AtriumsAtriums
CorsiCome funzionaSei un ProBlog
Sei un Pro?
Accedi
HomeMessaggiPrenotazioniProfilo
AtriumsAtriums
CorsiCome funzionaSei un ProBlog
Sei un Pro?
Accedi

ATRIUMS PER I PARTNER · API

One Place. A World of Services.

Pulizie, tuttofare, babysitter, personal trainer e gli altri servizi dei professionisti di Atriums, e se il tuo contratto li comprende le esperienze e i transfer dall'aeroporto, prenotabili dal tuo sito o dalla tua app. Tu vendi al tuo prezzo; noi portiamo chi fa il servizio, la chat, le recensioni e il pagamento a lavoro fatto.

Prova sul testLeggi la documentazione ↓
# gli orari liberi di un servizio
curl "https://app.atriumsmarketplace.com/api/partner/v1/services/{id}/availability?date=2026-11-04" \
  -H "Authorization: Bearer atr_live_…"

# → { "slots": [ { "start": "…T08:00:00Z" }, … ] }

Cosa offri ai tuoi clienti

Il catalogo di Atriums, come lo vedono i nostri clienti: stessi servizi, stessi prezzi, stesse regole.

Professionisti con le carte in regolaSi prenota solo dai Pro con il listino acceso: approvati, con i pagamenti attivi e i dati fiscali confermati. Le richieste di preventivo seguono le regole di Atriums.
Orari veriGli stessi orari liberi del calendario del Pro, compresi gli impegni del suo calendario Google collegato.
Arriva dove servePrima di vendere sai se il Pro raggiunge l'indirizzo del tuo cliente.
Prezzi chiariListino, varianti e minimi come sul sito, IVA inclusa. Se il prezzo cambia non si prenota: te lo diciamo.
Regole di disdetta scritte24 o 48 ore, o non rimborsabile: la regola di ogni servizio è nei dati, da mostrare al cliente.
Dopo la vendita ci siamo noiChat col Pro, recensione e reclami: il tuo cliente entra su Atriums col suo numero. I messaggi sulla prenotazione li mandiamo noi o tu, come dice il contratto; quelli sulle richieste di preventivo li mandiamo noi.

Come funziona

Quattro passi. Gli stessi del nostro sito, fatti dal tuo.

  1. 1Mostri il catalogoCategorie, servizi vicino al cliente, listino e orari liberi.
  2. 2PrenotiUna chiamata, con l'orario e il cliente. L'importo si blocca sul tuo deposito.
  3. 3Il Pro rispondeConferma subito o entro 24 ore. Te lo diciamo con un avviso firmato.
  4. 4Lavoro fattoAtriums paga il Pro e gli fattura la commissione. Tu non gestisci nessuno.

Come guadagni

Il prezzo pubblico è il nostro. Quello a cui vendi è il tuo.

Il tuo margine

Vendi al prezzo che decidi, sopra il prezzo pubblico. Incassi tu dal tuo cliente.

Il deposito

Ricarichi in anticipo. Ogni prenotazione blocca il prezzo pubblico; se il Pro rifiuta o non risponde, torna disponibile.

Il Pro non cambia

Riceve quello che riceverebbe da qualunque cliente. Mai sotto il prezzo pubblico.

Le condizioni le definiamo insieme, sul tuo volume e sui servizi che vuoi offrire.Parliamone
Indice
Per cominciareTutte le chiamateChiavi e ambientiRipetere una richiestaErroriGuideIl deposito e la ricaricaPrenotare, passo per passoSpostare e disdireQuando arriva un avvisoIl tuo cliente e i messaggiChiedere preventiviEsperienzeEsperienze di operatori esterniTransfer da e per l'aeroportoInterventi urgentiReclamiSe qualcosa si ferma a metà
CatalogoCategorieServizi vicino a un puntoUn servizioOrari liberiPartenze di un'esperienzaOfferte di un'esperienza esternaTransferCoperturaImprese della zona
PrenotazioniPrenotareLeggere una prenotazioneQuanto costa disdireDisdireSpostare
RichiesteChiedere preventiviLeggere una richiestaScegliere un preventivoAspettare o allargareAnnullare una richiesta
DepositoIl deposito
AvvisiAvvisi di ritornoAltroRegistro delle modificheOpenAPI (JSON)

Il riferimento qui sotto nasce dalla descrizione OpenAPI della API: chiamate, campi, errori e avvisi sono gli stessi che la API controlla. Nomi dei campi, codici ed eventi restano in inglese: sono il contratto tecnico, quello che scrivi nel tuo codice.

Tutte le chiamate

GET/​v1/​categoriesCategorieGET/​v1/​servicesServizi vicino a un puntoGET/​v1/​services/​{id}Un servizioGET/​v1/​services/​{id}/​availabilityOrari liberiGET/​v1/​services/​{id}/​departuresPartenze di un'esperienzaGET/​v1/​services/​{id}/​offersOfferte di un'esperienza esternaGET/​v1/​transfersTransferGET/​v1/​coverageCoperturaPOST/​v1/​bookingsPrenotareGET/​v1/​bookings/​{id}Leggere una prenotazioneGET/​v1/​bookings/​{id}/​cancellationQuanto costa disdirePOST/​v1/​bookings/​{id}/​cancelDisdirePOST/​v1/​bookings/​{id}/​rescheduleSpostareGET/​v1/​businessesImprese della zonaPOST/​v1/​requestsChiedere preventiviGET/​v1/​requests/​{id}Leggere una richiestaPOST/​v1/​requests/​{id}/​quotes/​{quote_id}/​acceptScegliere un preventivoPOST/​v1/​requests/​{id}/​direct-choiceAspettare o allargarePOST/​v1/​requests/​{id}/​cancelAnnullare una richiestaGET/​v1/​depositIl depositoavvisobooking.confirmedIl professionista ha accettato. Il bloccato ora è scalato dal tuo deposito.avvisobooking.declinedIl professionista ha rifiutato. Il bloccato torna sul tuo deposito.avvisobooking.expiredIl professionista non ha risposto entro 24 ore. Il bloccato torna sul tuo deposito.avvisobooking.cancelledAnnullata dal professionista (torna tutto sul tuo deposito) o da te (POST /bookings/{id}/cancel).avvisobooking.rescheduledLa prenotazione è stata spostata dal professionista o da te (POST /bookings/{id}/reschedule): data.starts_at è il nuovo orario. Se l'ha spostata il professionista, avvisa il tuo cliente.avvisobooking.completedIl lavoro è fatto. Il professionista lo paga Atriums.avvisodispute.openedIl cliente o il professionista ha aperto un reclamo su Atriums: lo decide Atriums, e il pagamento al professionista resta fermo. Vedi data.disputes.avvisodispute.resolvedAtriums ha deciso un reclamo: vedi data.disputes (outcome, back_to_deposit_cents). Se c'è un rimborso è già tornato sul tuo deposito: rimborsa tu il tuo cliente.avvisorequest.quote_receivedÈ arrivato un preventivo: vedi data.quotes. Lo puoi scegliere (POST /requests/{id}/quotes/{quote_id}/accept); al cliente l'ha già scritto Atriums.avvisorequest.quote_withdrawnUn professionista ha ritirato il suo preventivo.avvisorequest.assignedUn professionista è stato scelto, da te o dal cliente su Atriums: è il preventivo con state: assigned.avvisorequest.provider_confirmedIl professionista scelto ha confermato l'incarico: da qui cliente e professionista si accordano sul lavoro.avvisorequest.reopenedLa richiesta è di nuovo aperta (il professionista scelto non ha confermato in tempo, o l'ha riaperta Atriums): se ne può scegliere un altro.avvisorequest.closedLa richiesta è chiusa senza un professionista scelto: vedi data.closed_reason.avvisorequest.provider_found«Cercalo per me»: abbiamo trovato qualcuno, e la richiesta è partita verso i professionisti della zona.avvisorequest.direct_no_answerIl destinatario non ha ancora risposto: chiedi al tuo cliente se aspettarlo o mandarla ad altri (POST /requests/{id}/direct-choice). Glielo chiede anche Atriums.avvisorequest.urgent_provider_availableUrgenza in ascolto: ora qualcuno può arrivare a quell'indirizzo. Se serve ancora, crea una richiesta nuova con urgent: true.avvisorequest.urgent_on_the_wayIl professionista è partito: vedi data.urgent.provider_on_the_way_at.avvisorequest.urgent_arrivedIl professionista ha segnato l'arrivo. Il cliente conferma o contesta su Atriums, entro la sua finestra.avvisorequest.urgent_disputedIl cliente ha contestato l'intervento: lo decide Atriums, e l'uscita resta bloccata sul tuo deposito.avvisorequest.urgent_chargedL'uscita è scalata dal tuo deposito: data.urgent.callout.charged_cents (ridotta se il professionista era in ritardo; il resto è tornato disponibile).avvisorequest.urgent_releasedL'uscita è tornata disponibile sul tuo deposito: il professionista non è arrivato in tempo, o la contestazione è accolta.

Chiavi e ambienti

Ogni chiamata porta la tua chiave in Authorization: Bearer …. Le chiavi di prova iniziano con atr_test_ e lavorano sul catalogo di test, con un deposito di prova: niente soldi veri. Quelle vere iniziano con atr_live_. L'indirizzo di questo ambiente è https://app.atriumsmarketplace.com/api/partner/v1.

Importi in centesimi di euro, IVA inclusa. Date e ore ISO 8601; i giorni sono quelli di Europe/Rome.

Ripetere una richiesta

Le chiamate che scrivono (prenotare, spostare, disdire) vogliono un Idempotency-Key, diverso per ogni operazione. Se la rete cade e ripeti la richiesta con la stessa chiave, ricevi la stessa risposta: niente seconda prenotazione, niente secondo blocco sul deposito. La stessa chiave con un corpo diverso risponde idempotency_key_reused.

Guida

Il deposito e la ricarica

  1. Prenoti scalando da un deposito che ricarichi tu. GET /deposit ti dà il disponibile, il bloccato, il tuo tetto, gli ultimi movimenti e in bank_transfer l'IBAN solo tuo su cui ricaricarlo. L'IBAN può essere di un altro paese dell'area SEPA: per la tua banca è un bonifico in euro come un altro.
  2. Ogni bonifico che arriva lo incassiamo per intero e diventa un movimento top_up, di solito entro pochi minuti dall'arrivo. Un bonifico SEPA impiega da 0 a 3 giorni lavorativi: ricarica prima di restare senza disponibile, perché con un disponibile insufficiente le prenotazioni rispondono insufficient_deposit.
Guida

Prenotare, passo per passo

  1. Se il servizio si fa a casa del cliente (delivery_modes contiene at_customer), chiedi prima GET /coverage con le sue coordinate: sai subito se il professionista ci arriva.
  2. Chiedi gli orari liberi con GET /services/{id}/availability?date=… e fai scegliere al cliente uno start.
  3. Prenota con POST /bookings, una Idempotency-Key nuova e in expected_total_cents il prezzo pubblico su cui hai fatto l'offerta. Se il nostro prezzo è cambiato non si prenota niente e ricevi price_changed con quello attuale.
  4. La risposta è la prenotazione. Con status awaiting_provider il professionista ha 24 ore per accettare e l'importo è bloccato sul tuo deposito; con confirmed è già fissata e l'importo è scalato.
  5. Poi ti arriva un avviso: booking.confirmed (accettata, il bloccato diventa scalato), booking.declined o booking.expired (il bloccato torna disponibile).
  6. Gli errori da gestire sempre: slot_unavailable (quell'orario non è più libero: richiedi gli orari), price_changed, insufficient_deposit ed exposure_limit_exceeded (il deposito non basta).
Guida

Spostare e disdire

  1. Per spostare usa POST /bookings/{id}/reschedule con il nuovo starts_at, preso da GET /services/{id}/availability. Vale la regola del cliente su Atriums: almeno 24 ore prima dell'orario attuale, senza costi; il deposito non si muove.
  2. Se lo stesso spostamento ti torna indietro (per esempio ripeti dopo un errore di rete), lo stesso orario di adesso risponde con la prenotazione com'è, senza rifare niente.
  3. Per disdire, prima GET /bookings/{id}/cancellation: ti dice quanto la regola del servizio trattiene adesso e quanto torna sul tuo deposito. Poi POST /bookings/{id}/cancel.
  4. Le tue disdette e i tuoi spostamenti generano comunque booking.cancelled e booking.rescheduled: il tuo codice può trattare tutti gli avvisi allo stesso modo.
Guida

Quando arriva un avviso

  1. Verifica la firma Atriums-Signature sul corpo così come arriva, poi rispondi 2xx subito e lavora dopo: oltre 10 secondi l'avviso si ritenta.
  2. Lo stesso avviso può arrivarti due volte con lo stesso id: tieni gli id già trattati e ignora i doppioni.
  3. data è la prenotazione com'era quando è nato l'avviso. Gli avvisi possono arrivarti in un ordine diverso da quello in cui sono nati, per esempio dopo un tentativo fallito: per sapere com'è adesso, rileggi GET /bookings/{id}.
  4. Se il tuo indirizzo non risponde ritentiamo 8 volte in circa 22 ore. Se ti sembra che un avviso tardi, rileggi la prenotazione: lo stato vero è sempre quello di GET /bookings/{id}.
Guida

Il tuo cliente e i messaggi

  1. Il cliente si riconosce dal cellulare: se ha già un account su Atriums è il suo, altrimenti nasce dal numero. Entra su Atriums con un codice mandato al cellulare; la prima volta finisce la registrazione.
  2. Metti atriums_url nei tuoi messaggi: porta il cliente alla prenotazione su Atriums, dove trova la chat con il professionista, il reclamo e la recensione.
  3. Chi scrive al cliente lo dice il tuo contratto. Se gli scrivi tu, Atriums non gli manda i messaggi sulla prenotazione (conferma, rifiuto, mancata risposta, annullo, spostamento): li scrivi tu dalla risposta di POST /bookings e dagli avvisi. Atriums gli scrive solo ciò che riguarda il rapporto col professionista: chat, recensione, reclami, servizio completato. E le richieste ai professionisti, sempre (vedi «Chiedere preventivi»).
  4. Se un avviso non ti arriva entro 60 minuti, quel messaggio al cliente lo scriviamo noi, e solo se è ancora vero. Può arrivargli due volte, mai nessuna.
Guida

Chiedere preventivi

  1. Per un professionista preciso: se il servizio ha quote fra i booking_modes chiedi POST /requests con kind: provider; se ha chat_available puoi usare kind: chat, e la conversazione parte subito su Atriums. Per più preventivi dalla zona usa kind: area col box; dove non c'è nessuno, kind: find_for_me e lo cerchiamo noi. Per un'impresa non ancora su Atriums prendi l'id da GET /businesses e usa kind: business.
  2. Le risposte vanno in answers, per id delle domande del servizio o del box: le obbligatorie vanno date, e per le domande a scelta solo i valori di options. Chiedi al cliente come vuole essere ricontattato (contact_preference): non c'è un valore predefinito.
  3. Da lì valgono le regole di Atriums: a chi arriva e quando, fino a quando arrivano i preventivi (quotes_until), entro quando sceglierne uno (choose_by). Non paghi niente e il deposito non si muove.
  4. Ogni preventivo arriva con request.quote_received: lo scegli con POST /requests/{id}/quotes/{quote_id}/accept. Lo può scegliere anche il cliente su Atriums, dopo averne parlato in chat col professionista: se ha già scelto lui ricevi already_assigned, e in ogni caso ti arriva request.assigned. Con chat, il professionista che accetta la conversazione non manda un preventivo: la cifra, se c'è, arriva dopo.
  5. Il professionista scelto conferma l'incarico (request.provider_confirmed); da lì lui e il cliente si accordano sul lavoro e sul prezzo. Se non conferma in tempo la richiesta si riapre (request.reopened) e se ne può scegliere un altro.
  6. Con un destinatario solo (provider, chat, business), se non risponde ti arriva request.direct_no_answer: da lì (o se il destinatario rinuncia) chiedi al cliente se aspettarlo o mandarla ad altri, con POST /requests/{id}/direct-choice.
  7. Puoi annullarla con POST /requests/{id}/cancel finché è aperta e nessuno è stato scelto. Se si chiude da sola ricevi request.closed, col motivo in closed_reason.
  8. Sulle richieste al cliente scrive sempre Atriums: preventivi arrivati, scadenze, chiusure. Metti atriums_url nei tuoi messaggi: lì il cliente parla con i professionisti.
Guida

Esperienze

  1. Un'esperienza (un tour, un'escursione) si vende a partenze. I box di esperienze in GET /categories hanno offers_nearby; GET /services con quel box dà le esperienze dei professionisti con il punto d'incontro vicino al punto e almeno una partenza prenotabile, come la vetrina di Atriums.
  2. La scheda (GET /services/{id}) ha booking_modes departure, il punto d'incontro e le etichette in experience, e la regola di disdetta. Niente orari a calendario né preventivo: sul sito l'esperienza si compra solo scegliendo una partenza.
  3. Le partenze sono in GET /services/{id}/departures: data, posti rimasti (seats_left, 0 se esaurita, null se senza limite) e prezzo a persona. Le prenotazioni chiudono 12 ore prima della partenza.
  4. Prenoti con POST /bookings mandando departure_id, people (da 1 a 20) ed expected_total_cents (prezzo a persona per le persone). È confermata subito e l'importo è scalato dal tuo deposito. Se nel frattempo i posti non bastano ricevi not_enough_seats, con quelli rimasti; se la partenza non si prenota più, departure_unavailable.
  5. Una prenotazione su una partenza non si sposta: ha la data della partenza (not_reschedulable, con motivo not_supported). Si disdice con POST /bookings/{id}/cancel, con la regola di disdetta dell'esperienza.
  6. Se il professionista annulla la partenza ricevi booking.cancelled e l'importo torna tutto sul tuo deposito.
  7. Il giorno prima Atriums manda al cliente il promemoria della partenza, tranne quando il tuo contratto dice che al cliente scrivi tu.
Guida

Esperienze di operatori esterni

  1. Accanto alle esperienze dei professionisti, Atriums vende esperienze di operatori esterni (biglietti, tour, escursioni). Le vedi solo se il tuo contratto le comprende: allora compaiono nei box di esperienze di GET /categories e GET /services, e la loro scheda ha booking_modes offer.
  2. Non hanno partenze né orari a calendario: il prezzo dipende dal giorno e dall'età di ciascuno. Chiedi GET /services/{id}/offers con il giorno e le età (per esempio ages=35,33,8) quando il tuo cliente sceglie: ricevi le offerte di quel giorno, con orario e lingua quando ci sono, il prezzo di ogni persona e il totale, le penali di disdetta, le cose da sapere e le domande dell'operatore. Un'offerta vale circa 30 minuti.
  3. Prenoti con POST /bookings mandando offer (l'id dell'offerta, il giorno, i partecipanti nello stesso ordine delle età, le risposte alle domande) ed expected_total_cents (il total_cents dell'offerta); customer.email è obbligatoria. Nella stessa chiamata blocchiamo l'importo sul tuo deposito, l'operatore conferma e lo scaliamo: ricevi la prenotazione confermata. Se l'operatore non conferma ricevi operator_declined e il disponibile torna com'era (un blocco e il suo rilascio); se l'offerta non c'è più, offer_unavailable. Se l'operatore non risponde ricevi un errore 5xx e l'importo resta bloccato finché non sappiamo com'è andata: ripeti con la stessa Idempotency-Key (request_in_progress finché non è deciso) e ricevi l'avviso booking.confirmed o booking.cancelled.
  4. La prenotazione ha il blocco voucher: l'operatore vuole che il tuo cliente riceva un voucher con tutti quei campi. Se l'operatore consegna il suo documento (voucher.documents) vale quello; altrimenti lo componi tu con i dati del blocco.
  5. Non si sposta (not_reschedulable, motivo not_supported). Si disdice con POST /bookings/{id}/cancel: chiediamo all'operatore la penale di quel momento (la vedi prima con GET /bookings/{id}/cancellation), che resta scalata per lui; il resto torna sul tuo deposito. Il tuo cliente la disdetta la fa da te, non su Atriums.
Guida

Transfer da e per l'aeroporto

  1. Atriums vende i transfer di un operatore esterno fra gli aeroporti italiani e un indirizzo: auto private e navette condivise. Li vedi solo se il tuo contratto li comprende; altrimenti GET /transfers risponde not_found.
  2. Non hanno un catalogo: si chiedono. GET /transfers con il verso (arrival dall'aeroporto, departure verso l'aeroporto), l'aeroporto, l'indirizzo (e le coordinate confermate, se le hai), l'ora, le persone e il numero del volo ti dà i transfer di quel momento, dal più economico, con il prezzo pubblico della tratta e le penali. Vuoto: a quell'ora non c'è niente; prova un'altra ora. Alla prenotazione richiediamo l'offerta all'operatore: se non c'è più o il prezzo è cambiato, te lo diciamo.
  3. Prenoti con POST /bookings mandando transfer (l'id dell'offerta), il service_id della risposta, customer.email ed expected_total_cents (il total_cents dell'offerta). Come per le esperienze di operatori esterni: blocchiamo l'importo sul tuo deposito, l'operatore conferma e lo scaliamo; se non conferma ricevi operator_declined; se l'offerta non c'è più, offer_unavailable; se non risponde, un errore 5xx, l'importo resta bloccato finché non sappiamo com'è andata e ricevi l'avviso booking.confirmed o booking.cancelled.
  4. La prenotazione ha il blocco voucher con voucher.transfer (tratta, ora, volo, persone, veicolo) e, in voucher.instructions, chi chiamare se l'autista non si trova, quando l'operatore lo dà. Se l'operatore consegna il suo documento (voucher.documents) vale quello. Si disdice come un'esperienza di un operatore esterno, con la sua penale di quel momento; non si sposta.
Guida

Interventi urgenti

  1. Un intervento adesso si chiede con urgent: true, come il «Pronto intervento» di Atriums: a un professionista (kind: provider, se il servizio ha urgent_available; gli chiediamo per primo e se tace passa agli altri) o a chi è reperibile in zona (kind: area, su un box con le urgenze). In description scrivi in due parole cosa succede: è la nota per chi parte. Le risposte obbligatorie, qui, non lo sono.
  2. Serve l'indirizzo, con le coordinate scelte dal cliente se le hai. Se lì adesso non arriva nessuno rispondiamo no_urgent_provider; con if_nobody_available: wait la richiesta resta in ascolto, e quando qualcuno si rende disponibile ricevi request.urgent_provider_available.
  3. Chi può venire si propone con la sua uscita (callout_cents) e i minuti in cui arriva (arrives_within_minutes): ti arriva request.quote_received. Il via va dato prima di urgent.expires_at (30 minuti dall'apertura, qualche minuto in più se l'hai chiesta a un professionista preciso): poi la richiesta si chiude, al massimo entro un minuto. Gli avvisi partono ogni minuto: rispondi subito. Senza un via in tempo la richiesta si chiude.
  4. Il via lo dai tu, con POST /requests/{id}/quotes/{quote_id}/accept: l'uscita si blocca sul tuo deposito e il professionista parte. Il cliente vede chi si propone ma non dà il via, e non vede le cifre. Dopo il via non si annulla: qualcuno si è mosso.
  5. Da lì è tutto su Atriums, e al cliente scriviamo noi: il professionista parte (request.urgent_on_the_way) e segna l'arrivo (request.urgent_arrived), il cliente conferma o contesta (request.urgent_disputed, lo decide Atriums). Se l'intervento è fatto l'uscita si scala dal deposito, ridotta se il professionista era in ritardo (request.urgent_charged); se non arriva in tempo, o la contestazione è accolta, torna disponibile (request.urgent_released).
  6. Il professionista lo paga Atriums. Quanto far pagare l'uscita al tuo cliente lo decidi tu: noi non gli mostriamo cifre.
Guida

Reclami

  1. Un reclamo lo apre il tuo cliente o il professionista su Atriums, dalla prenotazione o dalla chat, entro il termine dopo la fine dell'appuntamento. Lo decide Atriums; ti arriva dispute.opened, e finché è aperto il professionista non viene pagato.
  2. Quando Atriums decide ti arriva dispute.resolved. Se c'è un rimborso su un importo già scalato, back_to_deposit_cents è già tornato sul tuo deposito, sul prezzo pubblico; se l'importo era solo bloccato (il professionista non aveva ancora accettato), la prenotazione si annulla e il bloccato si libera. In ogni caso rimborsi tu il tuo cliente, con le tue regole e sul tuo prezzo.
  3. Sui reclami al cliente scrive sempre Atriums, anche se il tuo contratto dice che gli scrivi tu: è il rapporto col professionista. Il testo del reclamo resta su Atriums; nella prenotazione trovi chi l'ha aperto, quando e com'è finito.
Guida

Se qualcosa si ferma a metà

  1. Ogni chiamata che scrive porta una Idempotency-Key. Se la rete cade o ricevi un errore 5xx, ripeti la stessa richiesta con la stessa chiave: non nasce una seconda prenotazione né una seconda richiesta ai professionisti, e non si muovono soldi due volte.
  2. Se la prenotazione (o la richiesta) era nata ma la risposta si era persa, la ripetizione te la restituisce con 201 e l'intestazione Idempotent-Replayed: true.
  3. request_in_progress vuol dire che la prima richiesta con quella chiave sta ancora lavorando: riprova fra qualche secondo. Se si era interrotta dalla nostra parte, dopo 15 minuti la ripetizione la rifà.
  4. La stessa chiave con un corpo diverso risponde idempotency_key_reused: per un'operazione nuova usa una chiave nuova.
Catalogo

Categorie

GET/v1/categories

L'albero del catalogo: le categorie, ognuna con i suoi box (i tipi di servizio). Con lat/lng, solo i box con almeno un professionista che serve quel punto.

lat
number (query)
Latitudine (WGS84).
lng
number (query)
Longitudine (WGS84).
curl "https://app.atriumsmarketplace.com/api/partner/v1/categories?lat=44.6940&lng=7.8539" \
  -H "Authorization: Bearer atr_live_…"
Risposta 200
categories
array · obbligatorio
categories[].slug
string · obbligatorio
categories[].name
object · obbligatorio
Testo in italiano e, quando c'è, in inglese.
categories[].boxes
array · obbligatorio
Errori di questa chiamata
invalid_request400La richiesta non è valida. Vedi details.
missing_api_key401Manca la chiave. Mandala come Authorization: Bearer <chiave>.
invalid_api_key401La chiave non è valida o è stata revocata.
partner_disabled403Questo account partner non è acceso. Scrivi ad Atriums.
unavailable503Il servizio è momentaneamente non disponibile. Riprova più tardi.
internal_error500Qualcosa non ha funzionato dalla nostra parte. È stato registrato.
Catalogo

Servizi vicino a un punto

GET/v1/services

I servizi di un box il cui professionista serve il punto. Modi di prenotazione e prezzi sono nella scheda del servizio. In un box di esperienze (offers_nearby in GET /categories) sono le esperienze dei professionisti con il punto d'incontro vicino e almeno una partenza prenotabile.

box
string (query) · obbligatorio
Lo slug del box, da GET /categories.
lat
number (query) · obbligatorio
Latitudine (WGS84).
lng
number (query) · obbligatorio
Longitudine (WGS84).
curl "https://app.atriumsmarketplace.com/api/partner/v1/services?box=pulizie&lat=44.6940&lng=7.8539" \
  -H "Authorization: Bearer atr_live_…"
Risposta 200
services
array · obbligatorio
services[].id
string · obbligatorio
services[].name
object · obbligatorio
Testo in italiano e, quando c'è, in inglese.
services[].box
any · obbligatorio
services[].provider
object · obbligatorio
services[].delivery_modes
array · obbligatorio
Errori di questa chiamata
invalid_request400La richiesta non è valida. Vedi details.
missing_api_key401Manca la chiave. Mandala come Authorization: Bearer <chiave>.
invalid_api_key401La chiave non è valida o è stata revocata.
partner_disabled403Questo account partner non è acceso. Scrivi ad Atriums.
unavailable503Il servizio è momentaneamente non disponibile. Riprova più tardi.
internal_error500Qualcosa non ha funzionato dalla nostra parte. È stato registrato.
Catalogo

Un servizio

GET/v1/services/{id}

Tutto quello che serve per vendere il servizio: modi di prenotazione, listino, regola di disdetta, domande per un preventivo. Il listino è vuoto quando adesso non si può comprare da lì. Un'esperienza ha booking_modes departure e il blocco experience (punto d'incontro, etichette): si vende a partenza.

id
string (path) · obbligatorio
Id del servizio.
curl "https://app.atriumsmarketplace.com/api/partner/v1/services/9e503313-322c-4b30-b647-e6a737d456af" \
  -H "Authorization: Bearer atr_live_…"
Risposta 200
id
string · obbligatorio
name
object · obbligatorio
Testo in italiano e, quando c'è, in inglese.
name.it
string
name.en
string
description
any · obbligatorio
box
any · obbligatorio
provider
object · obbligatorio
provider.id
string · obbligatorio
provider.name
string · obbligatorio
provider.city
any · obbligatorio
provider.logo_url
any · obbligatorio
provider.is_individual
boolean · obbligatorio
provider.rating_avg
any · obbligatorio
provider.rating_count
any · obbligatorio
delivery_modes
array · obbligatorio
duration_min
any · obbligatorio
booking_modes
array · obbligatorio
Come si compra questo servizio. Vuoto: adesso non si può comprare.
chat_available
boolean · obbligatorio
Si può scrivere subito al professionista in chat su Atriums (POST /requests con kind: chat), come col tasto «Chatta ora» della scheda.
urgent_available
boolean · obbligatorio
Il professionista accetta interventi urgenti su questo servizio: gli si può chiedere un intervento adesso (POST /requests con urgent: true). Se adesso è reperibile e arriva all'indirizzo lo verifichiamo alla richiesta.
price_list
array · obbligatorio
Vuoto, se il servizio non si vende dal listino.
price_list[].id
string · obbligatorio
price_list[].name
any · obbligatorio
price_list[].description
any · obbligatorio
price_list[].group
any · obbligatorio
La famiglia dentro il box; null = altre voci.
price_list[].price_cents
integer · obbligatorio
price_list[].duration_min
any · obbligatorio
Null: vale la durata del servizio.
price_list[].mandatory
boolean · obbligatorio
Si aggiunge una volta a ogni prenotazione di questo servizio.
price_list[].variants
array · obbligatorio
rates
array · obbligatorio
Tariffe fisse alternative, quando il servizio si vende dal listino.
rates[].id
string · obbligatorio
rates[].name
object · obbligatorio
Testo in italiano e, quando c'è, in inglese.
rates[].price_cents
integer · obbligatorio
options
array · obbligatorio
Opzioni del servizio stesso (servizi più vecchi), quando si può comprare.
options[].id
string · obbligatorio
options[].name
object · obbligatorio
Testo in italiano e, quando c'è, in inglese.
options[].price_cents
integer · obbligatorio
options[].unit
any · obbligatorio
base_price_cents
any · obbligatorio
Prezzo unico del servizio. C'è solo quando si può comprare e non ha voci né tariffe: altrimenti si vendono le voci e le tariffe.
minimum_charge_cents
any · obbligatorio
cancellation
object · obbligatorio
cancellation.free_until_hours_before
any · obbligatorio
Disdetta gratuita fino a queste ore prima dell'inizio. Null: non rimborsabile; per un'esperienza a offerta la regola è dell'operatore e sta in ogni offerta (cancellation).
request_questions
array · obbligatorio
Le domande per chiedere un preventivo (modo quote) o per scrivere in chat (chat_available).
request_questions[].id
string · obbligatorio
request_questions[].label
object · obbligatorio
Testo in italiano e, quando c'è, in inglese.
request_questions[].type
string: single, multi, text, number · obbligatorio
request_questions[].options
array
request_questions[].required
boolean
request_questions[].help
object
Testo in italiano e, quando c'è, in inglese.
request_questions[].prefill
string: zone, when
La risposta che il contesto può già dare. zone: se non la mandi, in POST /requests vale location.label, come sul sito con la zona cercata.
prices_include_vat
boolean · obbligatorio
pickup_and_return
boolean · obbligatorio
True per i servizi in due tempi (il professionista ritira e riconsegna, o il cliente porta e ripassa). Per ora non si prenotano dalla API: POST /bookings risponde service_not_bookable con motivo pickup_and_return.
experience
any · obbligatorio
Solo per un'esperienza (booking_modes contiene departure): il punto d'incontro e le etichette. Null negli altri servizi.
Errori di questa chiamata
invalid_request400La richiesta non è valida. Vedi details.
not_found404Non trovato.
missing_api_key401Manca la chiave. Mandala come Authorization: Bearer <chiave>.
invalid_api_key401La chiave non è valida o è stata revocata.
partner_disabled403Questo account partner non è acceso. Scrivi ad Atriums.
unavailable503Il servizio è momentaneamente non disponibile. Riprova più tardi.
internal_error500Qualcosa non ha funzionato dalla nostra parte. È stato registrato.
Catalogo

Orari liberi

GET/v1/services/{id}/availability

Gli orari d'inizio liberi del servizio in un giorno (Europe/Rome). Con item gli orari di una voce precisa del listino: valgono la sua durata e le sue persone dedicate.

id
string (path) · obbligatorio
Id del servizio.
date
string (query) · obbligatorio
Il giorno, in Europe/Rome: YYYY-MM-DD.
item
string (query)
Id di una voce del listino: la sua durata e le sue persone dedicate decidono gli orari.
curl "https://app.atriumsmarketplace.com/api/partner/v1/services/9e503313-322c-4b30-b647-e6a737d456af/availability?date=2026-11-04" \
  -H "Authorization: Bearer atr_live_…"
Risposta 200
date
string · obbligatorio
timezone
string · obbligatorio
duration_min
integer · obbligatorio
slots
array · obbligatorio
slots[].start
string · obbligatorio
ISO 8601, in UTC.
slots[].end
string · obbligatorio
Errori di questa chiamata
invalid_request400La richiesta non è valida. Vedi details.
not_found404Non trovato.
missing_api_key401Manca la chiave. Mandala come Authorization: Bearer <chiave>.
invalid_api_key401La chiave non è valida o è stata revocata.
partner_disabled403Questo account partner non è acceso. Scrivi ad Atriums.
unavailable503Il servizio è momentaneamente non disponibile. Riprova più tardi.
internal_error500Qualcosa non ha funzionato dalla nostra parte. È stato registrato.
Catalogo

Partenze di un'esperienza

GET/v1/services/{id}/departures

Le partenze future di un'esperienza (booking_modes con departure), come il cliente le vede su Atriums: data, posti, prezzo a persona, comprese le esaurite (seats_left 0). Le prenotazioni chiudono 12 ore prima della partenza, e da lì la partenza non compare più.

id
string (path) · obbligatorio
Id dell'esperienza.
curl "https://app.atriumsmarketplace.com/api/partner/v1/services/9e503313-322c-4b30-b647-e6a737d456af/departures" \
  -H "Authorization: Bearer atr_live_…"
Risposta 200
service_id
string · obbligatorio
currency
string · obbligatorio
departures
array · obbligatorio
departures[].id
string · obbligatorio
Da mandare in POST /bookings come departure_id.
departures[].starts_at
string · obbligatorio
ISO 8601, in UTC.
departures[].ends_at
any · obbligatorio
departures[].seats_total
any · obbligatorio
I posti della partenza. Null: senza limite.
departures[].seats_left
any · obbligatorio
Le persone che ci stanno ancora. Null: senza limite. 0: esaurita.
departures[].price_per_person_cents
integer · obbligatorio
Prezzo pubblico a persona, IVA inclusa.
Errori di questa chiamata
invalid_request400La richiesta non è valida. Vedi details.
not_found404Non trovato.
missing_api_key401Manca la chiave. Mandala come Authorization: Bearer <chiave>.
invalid_api_key401La chiave non è valida o è stata revocata.
partner_disabled403Questo account partner non è acceso. Scrivi ad Atriums.
unavailable503Il servizio è momentaneamente non disponibile. Riprova più tardi.
internal_error500Qualcosa non ha funzionato dalla nostra parte. È stato registrato.
Catalogo

Offerte di un'esperienza esterna

GET/v1/services/{id}/offers

Per un'esperienza di un operatore esterno (booking_modes con offer): le offerte di quel giorno per quelle età, chieste all'operatore in quel momento, come il foglio date di Atriums. Ogni offerta ha modalità, orario e lingua quando ci sono, il prezzo pubblico per persona e in tutto, le penali di disdetta e le domande dell'operatore. Chiedile quando il tuo cliente sceglie, una volta per scelta: non in anticipo né per conservarle. Un'offerta vale circa 30 minuti.

id
string (path) · obbligatorio
Id dell'esperienza.
date
string (query) · obbligatorio
Il giorno dell'esperienza, in Europe/Rome: YYYY-MM-DD.
ages
string (query) · obbligatorio
Le età dei partecipanti, separate da virgola (da 1 a 9 persone): l'operatore dà prezzi e tariffe per le età vere, come il foglio date di Atriums.
curl "https://app.atriumsmarketplace.com/api/partner/v1/services/9e503313-322c-4b30-b647-e6a737d456af/offers" \
  -H "Authorization: Bearer atr_live_…"
Risposta 200
service_id
string · obbligatorio
date
string · obbligatorio
currency
string · obbligatorio
important_info
array · obbligatorio
Le cose da sapere scritte dall'operatore: mostrale al cliente prima che prenoti.
operator_notes
any · obbligatorio
Le indicazioni dell'operatore (testo libero), quando ci sono.
offers
array · obbligatorio
offers[].id
string · obbligatorio
Da mandare in POST /bookings come offer.id. Vale per questo giorno e queste età; scade in fretta (circa 30 minuti): se è passato più tempo chiedi di nuovo le offerte.
offers[].name
any · obbligatorio
La modalità, come la scrive l'operatore. Null: l'operatore non la nomina (allora vale il nome del servizio).
offers[].duration
any · obbligatorio
offers[].session
any · obbligatorio
L'orario o il turno. Null: l'operatore non ne ha.
offers[].language
any · obbligatorio
La lingua della guida. Null: non si sceglie.
offers[].participants
array · obbligatorio
Le persone dalla più grande, con la fascia e il prezzo pubblico di ciascuna, IVA inclusa. Nello stesso ordine mandi i nomi in offer.participants.
offers[].total_cents
integer · obbligatorio
Il prezzo pubblico per tutte le persone, IVA inclusa: va in expected_total_cents.
offers[].free_cancellation
any · obbligatorio
offers[].cancellation
array · obbligatorio
Le penali dell'operatore, dalla prima. Vuoto: nessuna penale indicata.
offers[].questions
array · obbligatorio
Le domande dell'operatore al cliente (per esempio l'hotel di partenza): le risposte vanno in offer.answers. Email, telefono e nomi non ci sono: si prendono da customer e da offer.participants.
offers[].names_required
boolean · obbligatorio
L'operatore vuole nome e cognome di ogni partecipante.
Errori di questa chiamata
invalid_request400La richiesta non è valida. Vedi details.
not_found404Non trovato.
missing_api_key401Manca la chiave. Mandala come Authorization: Bearer <chiave>.
invalid_api_key401La chiave non è valida o è stata revocata.
partner_disabled403Questo account partner non è acceso. Scrivi ad Atriums.
unavailable503Il servizio è momentaneamente non disponibile. Riprova più tardi.
internal_error500Qualcosa non ha funzionato dalla nostra parte. È stato registrato.
Catalogo

Transfer

GET/v1/transfers

I transfer fra un aeroporto italiano e un indirizzo, all'ora e per le persone del tuo cliente, chiesti all'operatore in quel momento, come la ricerca dei transfer di Atriums: privati o condivisi, veicolo, prezzo pubblico della tratta, minuti di viaggio, valigie, attesa compresa, come si trova l'autista e penali di disdetta. Servono anche il numero del volo e, se le hai, le coordinate confermate dell'indirizzo. Chiedili quando il tuo cliente sceglie, una volta per scelta: non in anticipo né per conservarli. Alla prenotazione richiediamo l'offerta all'operatore. Solo se il tuo contratto comprende i transfer: altrimenti not_found.

direction
string: arrival, departure (query) · obbligatorio
arrival: dall'aeroporto all'indirizzo (il cliente atterra). departure: dall'indirizzo all'aeroporto (il cliente parte).
airport
string: FCO, MXP, LIN, BGY, VCE, TSF, NAP, CTA, PMO, BLQ, FLR, PSA, TRN, GOA, VRN, BRI, BDS, CAG, OLB, AHO, CIA, TRS, SUF, PEG (query) · obbligatorio
Il codice IATA dell'aeroporto: uno di quelli italiani con traffico di linea serviti da Atriums.
address
string (query) · obbligatorio
L'altro capo della tratta, come lo scrive il cliente: via e città, o il nome dell'albergo.
lat
number (query)
Se le hai, le coordinate dell'indirizzo confermate dal cliente: si usano così come sono. Con lng.
lng
number (query)
at
string (query) · obbligatorio
In Europe/Rome, YYYY-MM-DDTHH:MM. Per arrival l'ora di atterraggio; per departure l'ora in cui l'autista passa all'indirizzo.
adults
integer (query)
Adulti, da 1 a 9.
children
integer (query)
Bambini, da 0 a 9.
infants
integer (query)
Neonati, da 0 a 9.
flight
string (query) · obbligatorio
Il numero del volo: per arrival quello con cui il cliente atterra (l'autista lo segue e lo aspetta se è in ritardo), per departure quello che deve prendere. L'operatore lo vuole per prenotare.
curl "https://app.atriumsmarketplace.com/api/partner/v1/transfers" \
  -H "Authorization: Bearer atr_live_…"
Risposta 200
service_id
string · obbligatorio
Da mandare in POST /bookings come service_id, con transfer.
direction
string: arrival, departure · obbligatorio
airport
object · obbligatorio
airport.code
string · obbligatorio
airport.name
string · obbligatorio
address
string · obbligatorio
L'altro capo come lo useremo: quello che hai mandato, o il nome del luogo trovato sulla mappa.
at
string · obbligatorio
Lo stesso at della domanda.
offers
array · obbligatorio
offers[].id
string · obbligatorio
Da mandare in POST /bookings come transfer.id. Vale per questa domanda: alla prenotazione la chiediamo di nuovo all'operatore, e se non c'è più o il prezzo è cambiato ricevi offer_unavailable o price_changed.
offers[].private
boolean · obbligatorio
Vero: solo per il tuo cliente. Falso: una navetta condivisa con altri.
offers[].vehicle
string · obbligatorio
Il tipo di veicolo, come lo scrive l'operatore.
offers[].category
string · obbligatorio
offers[].min_people
integer · obbligatorio
offers[].max_people
integer · obbligatorio
offers[].total_cents
integer · obbligatorio
Il prezzo pubblico per tutta la tratta, IVA inclusa: va in expected_total_cents.
offers[].currency
string · obbligatorio
offers[].duration_minutes
any · obbligatorio
I minuti di viaggio stimati dall'operatore, quando li dice.
offers[].luggage
any · obbligatorio
Le valigie comprese, quando l'operatore lo dice.
offers[].wait_minutes
any · obbligatorio
I minuti di attesa compresi dopo l'atterraggio, quando l'operatore lo dice.
offers[].instructions
any · obbligatorio
Come si trova l'autista, scritto dall'operatore: mostralo al cliente prima che prenoti.
offers[].cancellation
array · obbligatorio
Le penali dell'operatore, dalla prima. Vuoto: nessuna penale indicata.
Errori di questa chiamata
invalid_request400La richiesta non è valida. Vedi details.
not_found404Non trovato.
address_not_found422Non troviamo quell'indirizzo. Controllalo, o manda lat e lng.
missing_api_key401Manca la chiave. Mandala come Authorization: Bearer <chiave>.
invalid_api_key401La chiave non è valida o è stata revocata.
partner_disabled403Questo account partner non è acceso. Scrivi ad Atriums.
unavailable503Il servizio è momentaneamente non disponibile. Riprova più tardi.
internal_error500Qualcosa non ha funzionato dalla nostra parte. È stato registrato.
Catalogo

Copertura

GET/v1/coverage

Per i servizi a domicilio, se il professionista arriva in quel punto.

service
string (query) · obbligatorio
Id del servizio.
lat
number (query) · obbligatorio
Latitudine (WGS84).
lng
number (query) · obbligatorio
Longitudine (WGS84).
curl "https://app.atriumsmarketplace.com/api/partner/v1/coverage?service=9e503313-322c-4b30-b647-e6a737d456af&lat=44.6940&lng=7.8539" \
  -H "Authorization: Bearer atr_live_…"
Risposta 200
service_id
string · obbligatorio
delivery_mode
string: at_customer, at_provider, remote · obbligatorio
at_customer: il professionista va dal cliente. at_provider: dal professionista. remote: online.
covered
boolean · obbligatorio
Per at_customer: il professionista arriva in questo punto. Negli altri casi è sempre true.
Errori di questa chiamata
invalid_request400La richiesta non è valida. Vedi details.
not_found404Non trovato.
missing_api_key401Manca la chiave. Mandala come Authorization: Bearer <chiave>.
invalid_api_key401La chiave non è valida o è stata revocata.
partner_disabled403Questo account partner non è acceso. Scrivi ad Atriums.
unavailable503Il servizio è momentaneamente non disponibile. Riprova più tardi.
internal_error500Qualcosa non ha funzionato dalla nostra parte. È stato registrato.
Catalogo

Imprese della zona

GET/v1/businesses

Le imprese di un box che lavorano in quel punto ma non sono ancora su Atriums: le stesse che il cliente vede nei risultati, le più vicine prima (al massimo 20). Non si prenotano: mandi loro una richiesta con kind: business e le contattiamo noi. Entrano anche da sole nelle gare (kind: area) e in «Cercalo per me».

box
string (query) · obbligatorio
Lo slug di un box (GET /categories).
lat
number (query) · obbligatorio
Latitudine (WGS84).
lng
number (query) · obbligatorio
Longitudine (WGS84).
curl "https://app.atriumsmarketplace.com/api/partner/v1/businesses?box=pulizie&lat=44.6940&lng=7.8539" \
  -H "Authorization: Bearer atr_live_…"
Risposta 200
businesses
array · obbligatorio
businesses[].id
string · obbligatorio
businesses[].name
string · obbligatorio
businesses[].city
any · obbligatorio
businesses[].covers
any · obbligatorio
Dove lavora, in parole.
businesses[].distance_km
any · obbligatorio
total
integer · obbligatorio
Errori di questa chiamata
invalid_request400La richiesta non è valida. Vedi details.
not_found404Non trovato.
missing_api_key401Manca la chiave. Mandala come Authorization: Bearer <chiave>.
invalid_api_key401La chiave non è valida o è stata revocata.
partner_disabled403Questo account partner non è acceso. Scrivi ad Atriums.
unavailable503Il servizio è momentaneamente non disponibile. Riprova più tardi.
internal_error500Qualcosa non ha funzionato dalla nostra parte. È stato registrato.
Prenotazioni

Prenotare

POST/v1/bookings

Prenota un servizio per il tuo cliente e blocca il prezzo pubblico sul tuo deposito. Manda il prezzo che hai mostrato: se nel frattempo il nostro è cambiato, non si prenota niente e ricevi price_changed con quello attuale. L'orario dev'essere uno di quelli liberi di /services/{id}/availability; per un'esperienza si mandano invece departure_id e people, e la prenotazione è confermata subito; per un'esperienza di un operatore esterno si manda offer (un'offerta di GET /services/{id}/offers, le persone, le risposte) e customer.email: la prenotazione la conferma l'operatore nella stessa chiamata (blocco, conferma, poi scalato), e se non conferma ricevi operator_declined e il disponibile torna com'era (un blocco e il suo rilascio). Un transfer si prenota allo stesso modo con transfer (un'offerta di GET /transfers), il service_id di quella risposta e customer.email. Se l'operatore non risponde ricevi un errore 5xx e l'importo resta bloccato finché non sappiamo com'è andata: ripeti con la stessa Idempotency-Key (request_in_progress finché non è deciso), e ricevi anche l'avviso booking.confirmed o booking.cancelled. Il cliente si riconosce dal cellulare, o nasce da lì. L'orario si controlla un attimo prima di scriverlo, non si tiene: se nello stesso istante un altro lo prende, il professionista se ne accorge e sposta o annulla una delle due, e tu ricevi l'avviso.

Idempotency-Key
string (header) · obbligatorio
8-200 caratteri, una per operazione.
Corpo della richiesta
service_id
string · obbligatorio
lines
array
Obbligatorio, tranne per un'esperienza (departure_id o offer) o un transfer (transfer).
lines[].item_id
string
Una voce del listino (price_list[].id).
lines[].item_variant_id
string
Una variante di una voce del listino (price_list[].variants[].id), al posto della voce.
lines[].rate_id
string
Una tariffa fissa (rates[].id).
lines[].option_id
string
Un'opzione del servizio (options[].id).
lines[].quantity
integer
starts_at
string
Uno start restituito da GET /services/{id}/availability, ISO 8601 con il fuso. Obbligatorio, tranne per un'esperienza (departure_id o offer) o un transfer (transfer).
departure_id
string
Per un'esperienza: un id di GET /services/{id}/departures. Allora niente lines né starts_at.
people
integer
Con departure_id: quante persone (da 1 a 20). Il prezzo è quello a persona per le persone.
offer
object
Per un'esperienza a offerta (booking_modes contiene offer). Allora niente lines, starts_at, departure_id né people; customer.email è obbligatoria.
offer.id
string · obbligatorio
Un id di GET /services/{id}/offers.
offer.date
string · obbligatorio
Lo stesso giorno chiesto per le offerte.
offer.participants
array · obbligatorio
Le stesse età chieste per le offerte. Nome e cognome servono quando l'offerta ha names_required; il primo, se manca, è quello di customer.
offer.answers
array
Le risposte alle questions dell'offerta.
offer.country
string
Il paese di chi prenota (ISO 3166, due lettere). Se manca, quello del prefisso del cellulare.
transfer
object
Per un transfer da o per l'aeroporto, con service_id quello della risposta di GET /transfers. Allora niente lines, starts_at, departure_id, people, offer, address né note; customer.email è obbligatoria. Tratta, ora, persone e volo sono quelli della domanda; l'intestatario è customer.
transfer.id
string · obbligatorio
Un id di GET /transfers.
delivery_mode
string: at_customer, at_provider, remote
Uno dei delivery_modes del servizio. Se manca: il primo.
address
object
Obbligatorio quando il modo è at_customer.
address.line
string · obbligatorio
Via e numero civico.
address.postal_code
string
address.city
string · obbligatorio
address.lat
number
Se le hai, manda le coordinate confermate dal cliente: si usano così come sono.
address.lng
number
customer
object · obbligatorio
customer.phone
string · obbligatorio
Il cellulare in formato E.164, verificato da te. È la chiave del cliente su Atriums: con un codice mandato lì entra per scrivere al professionista e per recensire. Un numero sbagliato dà a un altro l'accesso a questa prenotazione.
customer.first_name
string · obbligatorio
customer.last_name
string · obbligatorio
customer.email
string
Dove scriviamo al cliente, se il suo account non ha ancora un'email. Non serve mai a riconoscere un account.
note
string
Per il professionista (citofono, parcheggio…).
partner_reference
string
Il tuo riferimento: torna in ogni risposta e in ogni avviso.
expected_total_cents
integer · obbligatorio
Il prezzo pubblico su cui hai fatto l'offerta. Se adesso il nostro è diverso, non si prenota niente e ricevi price_changed con quello attuale.
curl -X POST "https://app.atriumsmarketplace.com/api/partner/v1/bookings" \
  -H "Authorization: Bearer atr_live_…" \
  -H "Idempotency-Key: 6f1c2a90-5b1e-4f3a-9d2c-1e8b7a6c5d4e" \
  -H "Content-Type: application/json" \
  -d '{
  "service_id": "9e503313-322c-4b30-b647-e6a737d456af",
  "lines": [
    {
      "item_id": "e6e55ea9-01c3-4cf8-8eaa-4e03c62d3d41",
      "quantity": 1
    }
  ],
  "starts_at": "2026-11-04T09:00:00+01:00",
  "address": {
    "line": "Via Roma 12",
    "postal_code": "12042",
    "city": "Bra",
    "lat": 44.694,
    "lng": 7.8539
  },
  "customer": {
    "phone": "+393331234567",
    "first_name": "Giulia",
    "last_name": "Bianchi",
    "email": "giulia@example.com"
  },
  "note": "Citofono 3B",
  "partner_reference": "APT-88231",
  "expected_total_cents": 2500
}'
Risposta 201
id
string · obbligatorio
L'id della prenotazione: usalo per tutte le chiamate successive.
number
any · obbligatorio
Il numero che vedono cliente e professionista (R-…).
status
string: awaiting_provider, confirmed, declined, expired, cancelled, completed · obbligatorio
awaiting_provider: il professionista ha 24 ore per accettare; l'importo è bloccato sul tuo deposito. confirmed: accettata; l'importo è scalato dal tuo deposito. declined / expired / cancelled: il bloccato torna sul tuo deposito (dopo lo scalato, quello che lascia la regola di disdetta). completed: il lavoro è fatto.
confirm_by
any · obbligatorio
Durante awaiting_provider: quando scade il tempo del professionista (ISO 8601): 24 ore dalla prenotazione, e comunque non oltre starts_at.
starts_at
string · obbligatorio
total_cents
integer · obbligatorio
Prezzo pubblico, IVA inclusa. Il tuo margine sta sopra, dalla tua parte.
currency
string · obbligatorio
partner_reference
any · obbligatorio
deposit
object · obbligatorio
deposit.held_cents
integer · obbligatorio
deposit.charged_cents
integer · obbligatorio
deposit.available_cents
integer · obbligatorio
service
object · obbligatorio
service.id
string · obbligatorio
service.name
object · obbligatorio
Testo in italiano e, quando c'è, in inglese.
provider
object · obbligatorio
Chi fa il lavoro. Niente recapiti: cliente e professionista si scrivono nella chat di Atriums (atriums_url).
provider.id
string · obbligatorio
provider.name
string · obbligatorio
lines
array · obbligatorio
Quello che è stato comprato, riga per riga.
lines[].name
object · obbligatorio
Testo in italiano e, quando c'è, in inglese.
lines[].quantity
integer · obbligatorio
lines[].total_cents
integer · obbligatorio
Prezzo pubblico della riga, IVA inclusa.
ends_at
any · obbligatorio
La fine prevista (ISO 8601, in UTC).
delivery_mode
any · obbligatorio
place
any · obbligatorio
Dove si svolge. Null quando il cliente su Atriums non lo vedrebbe (il luogo privato di un professionista): vale delivery_mode, e il luogo si concorda in chat.
note
any · obbligatorio
La nota per il professionista mandata con la prenotazione.
cancellation_policy
object · obbligatorio
cancellation_policy.free_until_hours_before
any · obbligatorio
La regola del servizio. Null: non rimborsabile; per un'esperienza di un operatore esterno la regola è sua, e le penali sono in voucher.cancellation.
cancellation_policy.free_until
any · obbligatorio
Fino a quando la disdetta è gratuita (ISO 8601, in UTC). Null: non rimborsabile, o non più disdicibile; per un'esperienza di un operatore esterno è sempre null e valgono le penali di voucher.cancellation.
disputes
array · obbligatorio
I reclami sulla prenotazione, dal più vecchio. Li apre il cliente o il professionista su Atriums e li decide Atriums; il testo del reclamo resta su Atriums.
disputes[].id
string · obbligatorio
disputes[].opened_by
string: customer, provider · obbligatorio
Chi l'ha aperto: il tuo cliente o il professionista.
disputes[].opened_at
string · obbligatorio
disputes[].status
string: open, resolved · obbligatorio
open: lo sta decidendo Atriums, e il pagamento al professionista resta fermo. resolved: deciso.
disputes[].outcome
any · obbligatorio
Com'è stato deciso; null finché è aperto. full_refund: la prenotazione è annullata; se l'importo era scalato torna sul tuo deposito (back_to_deposit_cents), se era solo bloccato si libera (lo vedi in deposit, e ricevi anche booking.cancelled). partial_refund: back_to_deposit_cents è tornato sul tuo deposito. In entrambi i casi rimborsi tu il tuo cliente, con le tue regole. settled_outside: sistemato fuori dalla API con Atriums.
disputes[].back_to_deposit_cents
integer · obbligatorio
Quanto è tornato sul tuo deposito per questo reclamo.
disputes[].resolved_at
any · obbligatorio
atriums_url
string · obbligatorio
La prenotazione su Atriums. Mettilo nei messaggi al cliente: entra con un codice mandato al suo cellulare e trova la chat con il professionista, il reclamo e la recensione.
voucher
any · obbligatorio
Solo per un'esperienza a offerta o un transfer, a prenotazione confermata; null negli altri casi. L'operatore vuole che il cliente riceva un voucher con TUTTI questi campi (riferimento, intestatario, partecipanti con l'età dei minori, punto d'incontro, operatore con indirizzo e riferimento, indicazioni, «prenotabile e pagabile tramite», penali): se l'operatore consegna il suo documento (documents) vale quello, altrimenti lo componi tu con questi dati.
Errori di questa chiamata
invalid_request400La richiesta non è valida. Vedi details.
missing_idempotency_key400Manda l'intestazione Idempotency-Key (8-200 caratteri) a ogni richiesta che scrive.
idempotency_key_reused422Questa Idempotency-Key è già stata usata con un corpo diverso.
request_in_progress409Una richiesta con questa Idempotency-Key è ancora in corso. Riprova fra qualche secondo: se si era interrotta a metà, dopo 15 minuti la ripetizione la rifà.
partner_not_active403Il tuo account legge il catalogo ma non può ancora prenotare. Scrivi ad Atriums.
not_allowed403Il tuo contratto non permette questa prenotazione.
not_found404Non trovato.
service_not_bookable422Questo servizio adesso non si prenota dalla API. Vedi details.reason.
slot_unavailable409Quell'orario non è più libero. Chiedi di nuovo GET /services/{id}/availability.
departure_unavailable409Questa partenza non si prenota più (passata, spenta, o a meno di 12 ore). Vedi details.reason e chiedi di nuovo GET /services/{id}/departures.
not_enough_seats409Non ci sono abbastanza posti su questa partenza. Vedi details.seats_left.
outside_coverage422Il professionista non arriva a quell'indirizzo.
address_not_found422Non troviamo quell'indirizzo. Controllalo, o manda lat e lng.
customer_is_provider422Il cliente è il professionista di questo servizio.
price_changed409Il prezzo è diverso da expected_total_cents. Non è stato prenotato niente. Vedi details.total_cents.
insufficient_deposit402Il tuo disponibile è più basso del totale. Ricarica il deposito e riprova.
exposure_limit_exceeded402Il bloccato supererebbe il tuo tetto. Riprova quando qualche prenotazione è confermata o rilasciata.
offer_unavailable409Questa offerta non si prenota più per quel giorno e quelle età. Chiedi di nuovo GET /services/{id}/offers.
operator_declined409L'operatore non ha confermato la prenotazione: non è stato scalato niente. Puoi scegliere un'altra offerta.
missing_api_key401Manca la chiave. Mandala come Authorization: Bearer <chiave>.
invalid_api_key401La chiave non è valida o è stata revocata.
partner_disabled403Questo account partner non è acceso. Scrivi ad Atriums.
unavailable503Il servizio è momentaneamente non disponibile. Riprova più tardi.
internal_error500Qualcosa non ha funzionato dalla nostra parte. È stato registrato.
Prenotazioni

Leggere una prenotazione

GET/v1/bookings/{id}

La prenotazione com'è adesso: stato, servizio e professionista, cosa è stato comprato, quando e dove, la regola di disdetta, cosa è bloccato o scalato sul tuo deposito, e il link alla prenotazione su Atriums. Sono i dati che vede il cliente: usali per scrivergli.

id
string (path) · obbligatorio
Id della prenotazione, da POST /bookings.
curl "https://app.atriumsmarketplace.com/api/partner/v1/bookings/a67b2cff-e588-48bf-8782-05a3887b4866" \
  -H "Authorization: Bearer atr_live_…"
Risposta 200
id
string · obbligatorio
L'id della prenotazione: usalo per tutte le chiamate successive.
number
any · obbligatorio
Il numero che vedono cliente e professionista (R-…).
status
string: awaiting_provider, confirmed, declined, expired, cancelled, completed · obbligatorio
awaiting_provider: il professionista ha 24 ore per accettare; l'importo è bloccato sul tuo deposito. confirmed: accettata; l'importo è scalato dal tuo deposito. declined / expired / cancelled: il bloccato torna sul tuo deposito (dopo lo scalato, quello che lascia la regola di disdetta). completed: il lavoro è fatto.
confirm_by
any · obbligatorio
Durante awaiting_provider: quando scade il tempo del professionista (ISO 8601): 24 ore dalla prenotazione, e comunque non oltre starts_at.
starts_at
string · obbligatorio
total_cents
integer · obbligatorio
Prezzo pubblico, IVA inclusa. Il tuo margine sta sopra, dalla tua parte.
currency
string · obbligatorio
partner_reference
any · obbligatorio
deposit
object · obbligatorio
deposit.held_cents
integer · obbligatorio
deposit.charged_cents
integer · obbligatorio
deposit.available_cents
integer · obbligatorio
service
object · obbligatorio
service.id
string · obbligatorio
service.name
object · obbligatorio
Testo in italiano e, quando c'è, in inglese.
provider
object · obbligatorio
Chi fa il lavoro. Niente recapiti: cliente e professionista si scrivono nella chat di Atriums (atriums_url).
provider.id
string · obbligatorio
provider.name
string · obbligatorio
lines
array · obbligatorio
Quello che è stato comprato, riga per riga.
lines[].name
object · obbligatorio
Testo in italiano e, quando c'è, in inglese.
lines[].quantity
integer · obbligatorio
lines[].total_cents
integer · obbligatorio
Prezzo pubblico della riga, IVA inclusa.
ends_at
any · obbligatorio
La fine prevista (ISO 8601, in UTC).
delivery_mode
any · obbligatorio
place
any · obbligatorio
Dove si svolge. Null quando il cliente su Atriums non lo vedrebbe (il luogo privato di un professionista): vale delivery_mode, e il luogo si concorda in chat.
note
any · obbligatorio
La nota per il professionista mandata con la prenotazione.
cancellation_policy
object · obbligatorio
cancellation_policy.free_until_hours_before
any · obbligatorio
La regola del servizio. Null: non rimborsabile; per un'esperienza di un operatore esterno la regola è sua, e le penali sono in voucher.cancellation.
cancellation_policy.free_until
any · obbligatorio
Fino a quando la disdetta è gratuita (ISO 8601, in UTC). Null: non rimborsabile, o non più disdicibile; per un'esperienza di un operatore esterno è sempre null e valgono le penali di voucher.cancellation.
disputes
array · obbligatorio
I reclami sulla prenotazione, dal più vecchio. Li apre il cliente o il professionista su Atriums e li decide Atriums; il testo del reclamo resta su Atriums.
disputes[].id
string · obbligatorio
disputes[].opened_by
string: customer, provider · obbligatorio
Chi l'ha aperto: il tuo cliente o il professionista.
disputes[].opened_at
string · obbligatorio
disputes[].status
string: open, resolved · obbligatorio
open: lo sta decidendo Atriums, e il pagamento al professionista resta fermo. resolved: deciso.
disputes[].outcome
any · obbligatorio
Com'è stato deciso; null finché è aperto. full_refund: la prenotazione è annullata; se l'importo era scalato torna sul tuo deposito (back_to_deposit_cents), se era solo bloccato si libera (lo vedi in deposit, e ricevi anche booking.cancelled). partial_refund: back_to_deposit_cents è tornato sul tuo deposito. In entrambi i casi rimborsi tu il tuo cliente, con le tue regole. settled_outside: sistemato fuori dalla API con Atriums.
disputes[].back_to_deposit_cents
integer · obbligatorio
Quanto è tornato sul tuo deposito per questo reclamo.
disputes[].resolved_at
any · obbligatorio
atriums_url
string · obbligatorio
La prenotazione su Atriums. Mettilo nei messaggi al cliente: entra con un codice mandato al suo cellulare e trova la chat con il professionista, il reclamo e la recensione.
voucher
any · obbligatorio
Solo per un'esperienza a offerta o un transfer, a prenotazione confermata; null negli altri casi. L'operatore vuole che il cliente riceva un voucher con TUTTI questi campi (riferimento, intestatario, partecipanti con l'età dei minori, punto d'incontro, operatore con indirizzo e riferimento, indicazioni, «prenotabile e pagabile tramite», penali): se l'operatore consegna il suo documento (documents) vale quello, altrimenti lo componi tu con questi dati.
Errori di questa chiamata
invalid_request400La richiesta non è valida. Vedi details.
not_found404Non trovato.
missing_api_key401Manca la chiave. Mandala come Authorization: Bearer <chiave>.
invalid_api_key401La chiave non è valida o è stata revocata.
partner_disabled403Questo account partner non è acceso. Scrivi ad Atriums.
unavailable503Il servizio è momentaneamente non disponibile. Riprova più tardi.
internal_error500Qualcosa non ha funzionato dalla nostra parte. È stato registrato.
Prenotazioni

Quanto costa disdire

GET/v1/bookings/{id}/cancellation

La regola del servizio applicata adesso, la stessa che il cliente vede su Atriums (24 ore, 48 ore o non rimborsabile): cosa resta scalato e va al professionista, e cosa torna sul tuo deposito. Per un'esperienza di un operatore esterno la penale la chiediamo all'operatore in quel momento, e resta scalata per lui. Non cambia niente.

id
string (path) · obbligatorio
Id della prenotazione.
curl "https://app.atriumsmarketplace.com/api/partner/v1/bookings/a67b2cff-e588-48bf-8782-05a3887b4866/cancellation" \
  -H "Authorization: Bearer atr_live_…"
Risposta 200
id
string · obbligatorio
cancellable
boolean · obbligatorio
reason
any · obbligatorio
Perché non si può disdire: not_active = già annullata, in corso o completata.
free_until_hours_before
any · obbligatorio
La regola del servizio. Null: non rimborsabile, o un'esperienza di un operatore esterno (vale fee_cents, chiesto all'operatore adesso).
fee_cents
integer · obbligatorio
Quello che la regola trattiene se disdici adesso: resta scalato e va al professionista (all'operatore, per un'esperienza di un operatore esterno).
back_to_deposit_cents
integer · obbligatorio
Quello che torna sul tuo deposito se disdici adesso.
currency
string · obbligatorio
Errori di questa chiamata
invalid_request400La richiesta non è valida. Vedi details.
not_found404Non trovato.
missing_api_key401Manca la chiave. Mandala come Authorization: Bearer <chiave>.
invalid_api_key401La chiave non è valida o è stata revocata.
partner_disabled403Questo account partner non è acceso. Scrivi ad Atriums.
unavailable503Il servizio è momentaneamente non disponibile. Riprova più tardi.
internal_error500Qualcosa non ha funzionato dalla nostra parte. È stato registrato.
Prenotazioni

Disdire

POST/v1/bookings/{id}/cancel

Disdice per conto del tuo cliente, con la regola del servizio. Quello che la regola trattiene resta scalato e va al professionista; il resto torna sul tuo deposito. Per un'esperienza di un operatore esterno disdiciamo presso l'operatore con la sua penale di quel momento (che resta scalata per lui); se l'operatore la rifiuta ricevi unavailable e non cambia niente; se non risponde ricevi unavailable, la disdetta resta in sospeso e, se l'operatore l'ha fatta, la completiamo noi e ricevi booking.cancelled. Senza corpo.

id
string (path) · obbligatorio
Id della prenotazione.
Idempotency-Key
string (header) · obbligatorio
8-200 caratteri, una per operazione.
curl -X POST "https://app.atriumsmarketplace.com/api/partner/v1/bookings/a67b2cff-e588-48bf-8782-05a3887b4866/cancel" \
  -H "Authorization: Bearer atr_live_…" \
  -H "Idempotency-Key: 6f1c2a90-5b1e-4f3a-9d2c-1e8b7a6c5d4e"
Risposta 200
id
string · obbligatorio
L'id della prenotazione: usalo per tutte le chiamate successive.
number
any · obbligatorio
Il numero che vedono cliente e professionista (R-…).
status
string: awaiting_provider, confirmed, declined, expired, cancelled, completed · obbligatorio
awaiting_provider: il professionista ha 24 ore per accettare; l'importo è bloccato sul tuo deposito. confirmed: accettata; l'importo è scalato dal tuo deposito. declined / expired / cancelled: il bloccato torna sul tuo deposito (dopo lo scalato, quello che lascia la regola di disdetta). completed: il lavoro è fatto.
confirm_by
any · obbligatorio
Durante awaiting_provider: quando scade il tempo del professionista (ISO 8601): 24 ore dalla prenotazione, e comunque non oltre starts_at.
starts_at
string · obbligatorio
total_cents
integer · obbligatorio
Prezzo pubblico, IVA inclusa. Il tuo margine sta sopra, dalla tua parte.
currency
string · obbligatorio
partner_reference
any · obbligatorio
deposit
object · obbligatorio
deposit.held_cents
integer · obbligatorio
deposit.charged_cents
integer · obbligatorio
deposit.available_cents
integer · obbligatorio
service
object · obbligatorio
service.id
string · obbligatorio
service.name
object · obbligatorio
Testo in italiano e, quando c'è, in inglese.
provider
object · obbligatorio
Chi fa il lavoro. Niente recapiti: cliente e professionista si scrivono nella chat di Atriums (atriums_url).
provider.id
string · obbligatorio
provider.name
string · obbligatorio
lines
array · obbligatorio
Quello che è stato comprato, riga per riga.
lines[].name
object · obbligatorio
Testo in italiano e, quando c'è, in inglese.
lines[].quantity
integer · obbligatorio
lines[].total_cents
integer · obbligatorio
Prezzo pubblico della riga, IVA inclusa.
ends_at
any · obbligatorio
La fine prevista (ISO 8601, in UTC).
delivery_mode
any · obbligatorio
place
any · obbligatorio
Dove si svolge. Null quando il cliente su Atriums non lo vedrebbe (il luogo privato di un professionista): vale delivery_mode, e il luogo si concorda in chat.
note
any · obbligatorio
La nota per il professionista mandata con la prenotazione.
cancellation_policy
object · obbligatorio
cancellation_policy.free_until_hours_before
any · obbligatorio
La regola del servizio. Null: non rimborsabile; per un'esperienza di un operatore esterno la regola è sua, e le penali sono in voucher.cancellation.
cancellation_policy.free_until
any · obbligatorio
Fino a quando la disdetta è gratuita (ISO 8601, in UTC). Null: non rimborsabile, o non più disdicibile; per un'esperienza di un operatore esterno è sempre null e valgono le penali di voucher.cancellation.
disputes
array · obbligatorio
I reclami sulla prenotazione, dal più vecchio. Li apre il cliente o il professionista su Atriums e li decide Atriums; il testo del reclamo resta su Atriums.
disputes[].id
string · obbligatorio
disputes[].opened_by
string: customer, provider · obbligatorio
Chi l'ha aperto: il tuo cliente o il professionista.
disputes[].opened_at
string · obbligatorio
disputes[].status
string: open, resolved · obbligatorio
open: lo sta decidendo Atriums, e il pagamento al professionista resta fermo. resolved: deciso.
disputes[].outcome
any · obbligatorio
Com'è stato deciso; null finché è aperto. full_refund: la prenotazione è annullata; se l'importo era scalato torna sul tuo deposito (back_to_deposit_cents), se era solo bloccato si libera (lo vedi in deposit, e ricevi anche booking.cancelled). partial_refund: back_to_deposit_cents è tornato sul tuo deposito. In entrambi i casi rimborsi tu il tuo cliente, con le tue regole. settled_outside: sistemato fuori dalla API con Atriums.
disputes[].back_to_deposit_cents
integer · obbligatorio
Quanto è tornato sul tuo deposito per questo reclamo.
disputes[].resolved_at
any · obbligatorio
atriums_url
string · obbligatorio
La prenotazione su Atriums. Mettilo nei messaggi al cliente: entra con un codice mandato al suo cellulare e trova la chat con il professionista, il reclamo e la recensione.
voucher
any · obbligatorio
Solo per un'esperienza a offerta o un transfer, a prenotazione confermata; null negli altri casi. L'operatore vuole che il cliente riceva un voucher con TUTTI questi campi (riferimento, intestatario, partecipanti con l'età dei minori, punto d'incontro, operatore con indirizzo e riferimento, indicazioni, «prenotabile e pagabile tramite», penali): se l'operatore consegna il suo documento (documents) vale quello, altrimenti lo componi tu con questi dati.
cancellation
object · obbligatorio
cancellation.fee_cents
integer · obbligatorio
cancellation.back_to_deposit_cents
integer · obbligatorio
Errori di questa chiamata
invalid_request400La richiesta non è valida. Vedi details.
missing_idempotency_key400Manda l'intestazione Idempotency-Key (8-200 caratteri) a ogni richiesta che scrive.
idempotency_key_reused422Questa Idempotency-Key è già stata usata con un corpo diverso.
request_in_progress409Una richiesta con questa Idempotency-Key è ancora in corso. Riprova fra qualche secondo: se si era interrotta a metà, dopo 15 minuti la ripetizione la rifà.
not_found404Non trovato.
not_cancellable409Questa prenotazione non si può più disdire. Vedi details.status.
missing_api_key401Manca la chiave. Mandala come Authorization: Bearer <chiave>.
invalid_api_key401La chiave non è valida o è stata revocata.
partner_disabled403Questo account partner non è acceso. Scrivi ad Atriums.
unavailable503Il servizio è momentaneamente non disponibile. Riprova più tardi.
internal_error500Qualcosa non ha funzionato dalla nostra parte. È stato registrato.
Prenotazioni

Spostare

POST/v1/bookings/{id}/reschedule

Sposta la prenotazione per conto del tuo cliente, con la regola che vale per lui su Atriums: almeno 24 ore prima dell'orario attuale, senza costi; il deposito non si muove. Il nuovo orario dev'essere libero (chiedilo a GET /services/{id}/availability); la durata resta quella della prenotazione. Il professionista riceve l'avviso; tu ricevi booking.rescheduled; al cliente scriviamo noi, salvo che il tuo contratto dica che gli scrivi tu. Lo stesso orario di adesso non cambia niente e risponde con la prenotazione com'è (anche a meno di 24 ore: così una ripetizione dopo un guasto risponde giusto). Un orario che si sovrappone a quello attuale si può scegliere; di rado, se il professionista ha il suo calendario collegato con un impegno attaccato, risulta slot_unavailable: scegline un altro. not_reschedulable dice il motivo in details.reason: not_active (non è in attesa né confermata), too_late (mancano meno di 24 ore), not_supported (questo tipo di prenotazione non si sposta), changed (è stata spostata o cambiata nel frattempo: rileggila). Come per POST /bookings: l'orario si controlla un attimo prima di scriverlo, non si tiene; se nello stesso istante un altro lo prende, il professionista se ne accorge e sposta o annulla una delle due, e tu ricevi l'avviso.

id
string (path) · obbligatorio
Id della prenotazione.
Idempotency-Key
string (header) · obbligatorio
8-200 caratteri, una per operazione.
Corpo della richiesta
starts_at
string · obbligatorio
Il nuovo orario: uno start restituito da GET /services/{id}/availability, ISO 8601 con il fuso.
curl -X POST "https://app.atriumsmarketplace.com/api/partner/v1/bookings/a67b2cff-e588-48bf-8782-05a3887b4866/reschedule" \
  -H "Authorization: Bearer atr_live_…" \
  -H "Idempotency-Key: 6f1c2a90-5b1e-4f3a-9d2c-1e8b7a6c5d4e" \
  -H "Content-Type: application/json" \
  -d '{
  "starts_at": "2026-11-05T15:00:00+01:00"
}'
Risposta 200
id
string · obbligatorio
L'id della prenotazione: usalo per tutte le chiamate successive.
number
any · obbligatorio
Il numero che vedono cliente e professionista (R-…).
status
string: awaiting_provider, confirmed, declined, expired, cancelled, completed · obbligatorio
awaiting_provider: il professionista ha 24 ore per accettare; l'importo è bloccato sul tuo deposito. confirmed: accettata; l'importo è scalato dal tuo deposito. declined / expired / cancelled: il bloccato torna sul tuo deposito (dopo lo scalato, quello che lascia la regola di disdetta). completed: il lavoro è fatto.
confirm_by
any · obbligatorio
Durante awaiting_provider: quando scade il tempo del professionista (ISO 8601): 24 ore dalla prenotazione, e comunque non oltre starts_at.
starts_at
string · obbligatorio
total_cents
integer · obbligatorio
Prezzo pubblico, IVA inclusa. Il tuo margine sta sopra, dalla tua parte.
currency
string · obbligatorio
partner_reference
any · obbligatorio
deposit
object · obbligatorio
deposit.held_cents
integer · obbligatorio
deposit.charged_cents
integer · obbligatorio
deposit.available_cents
integer · obbligatorio
service
object · obbligatorio
service.id
string · obbligatorio
service.name
object · obbligatorio
Testo in italiano e, quando c'è, in inglese.
provider
object · obbligatorio
Chi fa il lavoro. Niente recapiti: cliente e professionista si scrivono nella chat di Atriums (atriums_url).
provider.id
string · obbligatorio
provider.name
string · obbligatorio
lines
array · obbligatorio
Quello che è stato comprato, riga per riga.
lines[].name
object · obbligatorio
Testo in italiano e, quando c'è, in inglese.
lines[].quantity
integer · obbligatorio
lines[].total_cents
integer · obbligatorio
Prezzo pubblico della riga, IVA inclusa.
ends_at
any · obbligatorio
La fine prevista (ISO 8601, in UTC).
delivery_mode
any · obbligatorio
place
any · obbligatorio
Dove si svolge. Null quando il cliente su Atriums non lo vedrebbe (il luogo privato di un professionista): vale delivery_mode, e il luogo si concorda in chat.
note
any · obbligatorio
La nota per il professionista mandata con la prenotazione.
cancellation_policy
object · obbligatorio
cancellation_policy.free_until_hours_before
any · obbligatorio
La regola del servizio. Null: non rimborsabile; per un'esperienza di un operatore esterno la regola è sua, e le penali sono in voucher.cancellation.
cancellation_policy.free_until
any · obbligatorio
Fino a quando la disdetta è gratuita (ISO 8601, in UTC). Null: non rimborsabile, o non più disdicibile; per un'esperienza di un operatore esterno è sempre null e valgono le penali di voucher.cancellation.
disputes
array · obbligatorio
I reclami sulla prenotazione, dal più vecchio. Li apre il cliente o il professionista su Atriums e li decide Atriums; il testo del reclamo resta su Atriums.
disputes[].id
string · obbligatorio
disputes[].opened_by
string: customer, provider · obbligatorio
Chi l'ha aperto: il tuo cliente o il professionista.
disputes[].opened_at
string · obbligatorio
disputes[].status
string: open, resolved · obbligatorio
open: lo sta decidendo Atriums, e il pagamento al professionista resta fermo. resolved: deciso.
disputes[].outcome
any · obbligatorio
Com'è stato deciso; null finché è aperto. full_refund: la prenotazione è annullata; se l'importo era scalato torna sul tuo deposito (back_to_deposit_cents), se era solo bloccato si libera (lo vedi in deposit, e ricevi anche booking.cancelled). partial_refund: back_to_deposit_cents è tornato sul tuo deposito. In entrambi i casi rimborsi tu il tuo cliente, con le tue regole. settled_outside: sistemato fuori dalla API con Atriums.
disputes[].back_to_deposit_cents
integer · obbligatorio
Quanto è tornato sul tuo deposito per questo reclamo.
disputes[].resolved_at
any · obbligatorio
atriums_url
string · obbligatorio
La prenotazione su Atriums. Mettilo nei messaggi al cliente: entra con un codice mandato al suo cellulare e trova la chat con il professionista, il reclamo e la recensione.
voucher
any · obbligatorio
Solo per un'esperienza a offerta o un transfer, a prenotazione confermata; null negli altri casi. L'operatore vuole che il cliente riceva un voucher con TUTTI questi campi (riferimento, intestatario, partecipanti con l'età dei minori, punto d'incontro, operatore con indirizzo e riferimento, indicazioni, «prenotabile e pagabile tramite», penali): se l'operatore consegna il suo documento (documents) vale quello, altrimenti lo componi tu con questi dati.
Errori di questa chiamata
invalid_request400La richiesta non è valida. Vedi details.
missing_idempotency_key400Manda l'intestazione Idempotency-Key (8-200 caratteri) a ogni richiesta che scrive.
idempotency_key_reused422Questa Idempotency-Key è già stata usata con un corpo diverso.
request_in_progress409Una richiesta con questa Idempotency-Key è ancora in corso. Riprova fra qualche secondo: se si era interrotta a metà, dopo 15 minuti la ripetizione la rifà.
not_found404Non trovato.
slot_unavailable409Quell'orario non è più libero. Chiedi di nuovo GET /services/{id}/availability.
not_reschedulable409Questa prenotazione non si può spostare. Vedi details.reason.
missing_api_key401Manca la chiave. Mandala come Authorization: Bearer <chiave>.
invalid_api_key401La chiave non è valida o è stata revocata.
partner_disabled403Questo account partner non è acceso. Scrivi ad Atriums.
unavailable503Il servizio è momentaneamente non disponibile. Riprova più tardi.
internal_error500Qualcosa non ha funzionato dalla nostra parte. È stato registrato.
Richieste

Chiedere preventivi

POST/v1/requests

Manda una richiesta per il tuo cliente, come su Atriums: a un professionista (provider, o chat per scrivergli subito), ai professionisti della zona (area), a noi perché lo cerchiamo (find_for_me), o a un'impresa non ancora su Atriums (business). Le risposte sono quelle di request_questions. Valgono le regole di Atriums: a chi arriva e quando, quanto resta aperta, quanto tempo c'è per scegliere. Per un preventivo non paghi niente e il deposito non si muove: sceglierlo è un incarico, il lavoro e il prezzo li concordano cliente e professionista. Al cliente sulle richieste scrive Atriums (preventivi arrivati, scadenze): tu ricevi gli avvisi request.*. Con urgent: true (provider o area) è un intervento adesso: vedi la guida «Interventi urgenti».

Idempotency-Key
string (header) · obbligatorio
8-200 caratteri, una per operazione.
Corpo della richiesta
kind
string: provider, chat, area, find_for_me, business · obbligatorio
provider: un preventivo a un professionista (il servizio ha quote fra i booking_modes). chat: lo stesso, ma la conversazione parte subito in chat su Atriums (il servizio ha chat_available). area: più preventivi dai professionisti della zona («Non sai chi scegliere?»). find_for_me: «Cercalo per me», quando in zona non c'è nessuno: lo cerchiamo noi. business: a un'impresa della zona che non è ancora su Atriums (GET /businesses).
service_id
string
Obbligatorio per provider e chat.
box
string
Lo slug del box. Obbligatorio per area, find_for_me e business; per provider e chat vale quello del servizio.
business_id
string
Obbligatorio per business: un id di GET /businesses.
title
string · obbligatorio
In breve, cosa serve.
description
string
I dettagli. Con chat arriva al professionista nel primo messaggio.
answers
object
Le risposte alle request_questions del servizio o del box, per id: una stringa, o un elenco per le domande multi. Le obbligatorie vanno date; i valori delle domande a scelta sono quelli di options.
location
object · obbligatorio
location.label
string · obbligatorio
Dove serve, come lo scrive il cliente: un comune o un indirizzo.
location.lat
number
Con le coordinate confermate dal cliente si usano così come sono; senza, label si cerca sulla mappa.
location.lng
number
location.place_id
string
Il Google Place ID del comune, se il luogo è un comune intero: gli inviti contano chi lavora in qualche punto del comune.
delivery_mode
string: at_customer, at_provider, remote
Come lo vuole il cliente, se lo sa.
remote_ok
boolean
Con at_customer o at_provider: va bene anche online.
budget_cents
integer
contact_preference
object · obbligatorio
Chiedila al tuo cliente: non ha un valore predefinito.
contact_preference.expected
string: quote, talk
Cosa aspetta il cliente: un preventivo scritto (quote) o di parlarne (talk). Obbligatorio, tranne per chat.
contact_preference.channel
string: chat, call, email · obbligatorio
Come vuole essere ricontattato. call o email vogliono dire che il professionista vedrà quel recapito.
contact_preference.time_slot
string: anytime, morning, afternoon, evening
Solo con call: quando chiamarlo.
customer
object · obbligatorio
customer.phone
string · obbligatorio
Il cellulare in formato E.164, verificato da te. È la chiave del cliente su Atriums: con un codice mandato lì entra per scrivere al professionista e per recensire. Un numero sbagliato dà a un altro l'accesso a questa prenotazione.
customer.first_name
string · obbligatorio
customer.last_name
string · obbligatorio
customer.email
string
Dove scriviamo al cliente, se il suo account non ha ancora un'email. Non serve mai a riconoscere un account.
partner_reference
string
Il tuo riferimento: torna in ogni risposta e in ogni avviso.
urgent
boolean
Un intervento adesso, come il «Pronto intervento» di Atriums: con provider (il servizio ha urgent_available) o area (un box con le urgenze). Vedi la guida «Interventi urgenti».
if_nobody_available
string: error, wait
Solo con urgent: true: se a quell'indirizzo adesso non arriva nessuno. error (di base): rispondiamo no_urgent_provider. wait: la richiesta resta in ascolto, e quando qualcuno si rende disponibile ricevi request.urgent_provider_available (come «Avvisami» su Atriums).
curl -X POST "https://app.atriumsmarketplace.com/api/partner/v1/requests" \
  -H "Authorization: Bearer atr_live_…" \
  -H "Idempotency-Key: 6f1c2a90-5b1e-4f3a-9d2c-1e8b7a6c5d4e" \
  -H "Content-Type: application/json" \
  -d '{
  "kind": "provider",
  "service_id": "9e503313-322c-4b30-b647-e6a737d456af",
  "title": "Sistemare una porta e montare due mensole",
  "description": "La porta del bagno non chiude bene. Secondo piano, senza ascensore.",
  "answers": {
    "quando": "Questa settimana",
    "intervento_tf": "Piccole riparazioni",
    "dove_tf": "Appartamento",
    "dimensione_tf": "Un intervento singolo",
    "materiali": "Da valutare insieme",
    "sopralluogo": "Si può fare al volo"
  },
  "location": {
    "label": "Via Roma 12, Bra",
    "lat": 44.694,
    "lng": 7.8539
  },
  "contact_preference": {
    "expected": "quote",
    "channel": "chat"
  },
  "customer": {
    "phone": "+393331234567",
    "first_name": "Giulia",
    "last_name": "Bianchi",
    "email": "giulia@example.com"
  },
  "partner_reference": "APT-88232"
}'
Risposta 201
id
string · obbligatorio
number
any · obbligatorio
Il numero della richiesta su Atriums.
kind
string: provider, chat, area, find_for_me, business · obbligatorio
provider: un preventivo a un professionista (il servizio ha quote fra i booking_modes). chat: lo stesso, ma la conversazione parte subito in chat su Atriums (il servizio ha chat_available). area: più preventivi dai professionisti della zona («Non sai chi scegliere?»). find_for_me: «Cercalo per me», quando in zona non c'è nessuno: lo cerchiamo noi. business: a un'impresa della zona che non è ancora su Atriums (GET /businesses).
status
string: open, assigned, closed · obbligatorio
open: aperta, i preventivi arrivano qui. assigned: un professionista è stato scelto (da te o dal cliente su Atriums). closed: chiusa senza un professionista scelto, vedi closed_reason.
closed_reason
any · obbligatorio
box
any · obbligatorio
title
string · obbligatorio
description
any · obbligatorio
answers
object · obbligatorio
location
any · obbligatorio
delivery_mode
any · obbligatorio
Come lo vuole il cliente: lo stesso campo della richiesta. null se non l'ha detto.
remote_ok
any · obbligatorio
Con at_customer o at_provider: va bene anche online. null se la domanda non è stata fatta.
contact_preference
any · obbligatorio
Come il cliente vuole essere ricontattato, come l'hai mandata (contact_preference). null se la richiesta non ce l'ha.
direct
any · obbligatorio
Solo per le richieste a un destinatario (provider, chat, business).
quotes_until
any · obbligatorio
Fino a quando arrivano i preventivi (ISO 8601, in UTC).
choose_by
any · obbligatorio
Entro quando sceglierne uno, dopo la scadenza.
quotes
array · obbligatorio
quotes[].id
string · obbligatorio
quotes[].provider
object · obbligatorio
quotes[].price_cents
any · obbligatorio
La cifra del professionista. Null: la dirà in chat.
quotes[].price_max_cents
any · obbligatorio
Se c'è, la cifra è un intervallo da price_cents a questo.
quotes[].needs_inspection
boolean · obbligatorio
Cifra indicativa, da confermare con un sopralluogo.
quotes[].retainer_cents
any · obbligatorio
Un canone ricorrente, se il professionista lo propone.
quotes[].message
any · obbligatorio
quotes[].callout_cents
any · obbligatorio
Solo per un'urgenza: il diritto di chiamata del professionista (l'uscita, non il lavoro). È quello che si blocca sul tuo deposito al via.
quotes[].arrives_within_minutes
any · obbligatorio
Solo per un'urgenza: entro quanti minuti può essere sul posto.
quotes[].state
string: submitted, assigned · obbligatorio
assigned: è il preventivo scelto.
quotes[].provider_confirmed_at
any · obbligatorio
Quando il professionista scelto ha confermato l'incarico.
quotes[].created_at
string · obbligatorio
urgent
any · obbligatorio
Solo per un'urgenza: le sue tappe e l'uscita.
created_at
string · obbligatorio
partner_reference
any · obbligatorio
atriums_url
string · obbligatorio
La richiesta su Atriums (per chat, la conversazione). Mettilo nei messaggi al cliente: entra con un codice mandato al suo cellulare, parla con i professionisti e può scegliere anche lui.
Errori di questa chiamata
invalid_request400La richiesta non è valida. Vedi details.
missing_idempotency_key400Manda l'intestazione Idempotency-Key (8-200 caratteri) a ogni richiesta che scrive.
idempotency_key_reused422Questa Idempotency-Key è già stata usata con un corpo diverso.
request_in_progress409Una richiesta con questa Idempotency-Key è ancora in corso. Riprova fra qualche secondo: se si era interrotta a metà, dopo 15 minuti la ripetizione la rifà.
partner_not_active403Il tuo account legge il catalogo ma non può ancora prenotare. Scrivi ad Atriums.
not_allowed403Il tuo contratto non permette questa prenotazione.
not_found404Non trovato.
not_requestable422Qui adesso non si può mandare questa richiesta. Vedi details.reason.
urgent_not_supported422Un intervento urgente (urgent: true) si chiede a un professionista (provider) o ai professionisti della zona (area).
no_urgent_provider422A questo indirizzo adesso non arriva nessuno. Puoi restare in attesa (if_nobody_available: wait): ti avvisiamo appena qualcuno si rende disponibile.
address_not_found422Non troviamo quell'indirizzo. Controllalo, o manda lat e lng.
outside_coverage422Il professionista non arriva a quell'indirizzo.
customer_is_provider422Il cliente è il professionista di questo servizio.
business_unavailable422Questa impresa non riceve più richieste. Chiedi di nuovo GET /businesses.
request_rejected422Atriums non ha accettato questa richiesta. Il motivo è in message.
missing_api_key401Manca la chiave. Mandala come Authorization: Bearer <chiave>.
invalid_api_key401La chiave non è valida o è stata revocata.
partner_disabled403Questo account partner non è acceso. Scrivi ad Atriums.
unavailable503Il servizio è momentaneamente non disponibile. Riprova più tardi.
internal_error500Qualcosa non ha funzionato dalla nostra parte. È stato registrato.
Richieste

Leggere una richiesta

GET/v1/requests/{id}

La richiesta com'è adesso, come la vede il cliente su Atriums: stato, preventivi arrivati, scadenze e il link alla richiesta su Atriums.

id
string (path) · obbligatorio
Id della richiesta, da POST /requests.
curl "https://app.atriumsmarketplace.com/api/partner/v1/requests/a67b2cff-e588-48bf-8782-05a3887b4866" \
  -H "Authorization: Bearer atr_live_…"
Risposta 200
id
string · obbligatorio
number
any · obbligatorio
Il numero della richiesta su Atriums.
kind
string: provider, chat, area, find_for_me, business · obbligatorio
provider: un preventivo a un professionista (il servizio ha quote fra i booking_modes). chat: lo stesso, ma la conversazione parte subito in chat su Atriums (il servizio ha chat_available). area: più preventivi dai professionisti della zona («Non sai chi scegliere?»). find_for_me: «Cercalo per me», quando in zona non c'è nessuno: lo cerchiamo noi. business: a un'impresa della zona che non è ancora su Atriums (GET /businesses).
status
string: open, assigned, closed · obbligatorio
open: aperta, i preventivi arrivano qui. assigned: un professionista è stato scelto (da te o dal cliente su Atriums). closed: chiusa senza un professionista scelto, vedi closed_reason.
closed_reason
any · obbligatorio
box
any · obbligatorio
title
string · obbligatorio
description
any · obbligatorio
answers
object · obbligatorio
location
any · obbligatorio
delivery_mode
any · obbligatorio
Come lo vuole il cliente: lo stesso campo della richiesta. null se non l'ha detto.
remote_ok
any · obbligatorio
Con at_customer o at_provider: va bene anche online. null se la domanda non è stata fatta.
contact_preference
any · obbligatorio
Come il cliente vuole essere ricontattato, come l'hai mandata (contact_preference). null se la richiesta non ce l'ha.
direct
any · obbligatorio
Solo per le richieste a un destinatario (provider, chat, business).
quotes_until
any · obbligatorio
Fino a quando arrivano i preventivi (ISO 8601, in UTC).
choose_by
any · obbligatorio
Entro quando sceglierne uno, dopo la scadenza.
quotes
array · obbligatorio
quotes[].id
string · obbligatorio
quotes[].provider
object · obbligatorio
quotes[].price_cents
any · obbligatorio
La cifra del professionista. Null: la dirà in chat.
quotes[].price_max_cents
any · obbligatorio
Se c'è, la cifra è un intervallo da price_cents a questo.
quotes[].needs_inspection
boolean · obbligatorio
Cifra indicativa, da confermare con un sopralluogo.
quotes[].retainer_cents
any · obbligatorio
Un canone ricorrente, se il professionista lo propone.
quotes[].message
any · obbligatorio
quotes[].callout_cents
any · obbligatorio
Solo per un'urgenza: il diritto di chiamata del professionista (l'uscita, non il lavoro). È quello che si blocca sul tuo deposito al via.
quotes[].arrives_within_minutes
any · obbligatorio
Solo per un'urgenza: entro quanti minuti può essere sul posto.
quotes[].state
string: submitted, assigned · obbligatorio
assigned: è il preventivo scelto.
quotes[].provider_confirmed_at
any · obbligatorio
Quando il professionista scelto ha confermato l'incarico.
quotes[].created_at
string · obbligatorio
urgent
any · obbligatorio
Solo per un'urgenza: le sue tappe e l'uscita.
created_at
string · obbligatorio
partner_reference
any · obbligatorio
atriums_url
string · obbligatorio
La richiesta su Atriums (per chat, la conversazione). Mettilo nei messaggi al cliente: entra con un codice mandato al suo cellulare, parla con i professionisti e può scegliere anche lui.
Errori di questa chiamata
invalid_request400La richiesta non è valida. Vedi details.
not_found404Non trovato.
missing_api_key401Manca la chiave. Mandala come Authorization: Bearer <chiave>.
invalid_api_key401La chiave non è valida o è stata revocata.
partner_disabled403Questo account partner non è acceso. Scrivi ad Atriums.
unavailable503Il servizio è momentaneamente non disponibile. Riprova più tardi.
internal_error500Qualcosa non ha funzionato dalla nostra parte. È stato registrato.
Richieste

Scegliere un preventivo

POST/v1/requests/{id}/quotes/{quote_id}/accept

Sceglie il preventivo per conto del tuo cliente, come «Scegli questo pro» su Atriums. Per un preventivo non paghi niente: il professionista riceve l'incarico e lo conferma, e da lì cliente e professionista si accordano sul lavoro. Un preventivo lo può scegliere anche il cliente su Atriums (un'urgenza no): se ha già scelto lui, ricevi already_assigned; in ogni caso ti arriva request.assigned. Una chat accettata non è un preventivo e non si sceglie. Su un'urgenza è il via: l'uscita del professionista (callout_cents) si blocca sul tuo deposito e lui parte (vedi la guida «Interventi urgenti»). Senza corpo.

id
string (path) · obbligatorio
Id della richiesta.
quote_id
string (path) · obbligatorio
Id del preventivo (quotes[].id).
Idempotency-Key
string (header) · obbligatorio
8-200 caratteri, una per operazione.
curl -X POST "https://app.atriumsmarketplace.com/api/partner/v1/requests/a67b2cff-e588-48bf-8782-05a3887b4866/quotes/{quote_id}/accept" \
  -H "Authorization: Bearer atr_live_…" \
  -H "Idempotency-Key: 6f1c2a90-5b1e-4f3a-9d2c-1e8b7a6c5d4e"
Risposta 200
id
string · obbligatorio
number
any · obbligatorio
Il numero della richiesta su Atriums.
kind
string: provider, chat, area, find_for_me, business · obbligatorio
provider: un preventivo a un professionista (il servizio ha quote fra i booking_modes). chat: lo stesso, ma la conversazione parte subito in chat su Atriums (il servizio ha chat_available). area: più preventivi dai professionisti della zona («Non sai chi scegliere?»). find_for_me: «Cercalo per me», quando in zona non c'è nessuno: lo cerchiamo noi. business: a un'impresa della zona che non è ancora su Atriums (GET /businesses).
status
string: open, assigned, closed · obbligatorio
open: aperta, i preventivi arrivano qui. assigned: un professionista è stato scelto (da te o dal cliente su Atriums). closed: chiusa senza un professionista scelto, vedi closed_reason.
closed_reason
any · obbligatorio
box
any · obbligatorio
title
string · obbligatorio
description
any · obbligatorio
answers
object · obbligatorio
location
any · obbligatorio
delivery_mode
any · obbligatorio
Come lo vuole il cliente: lo stesso campo della richiesta. null se non l'ha detto.
remote_ok
any · obbligatorio
Con at_customer o at_provider: va bene anche online. null se la domanda non è stata fatta.
contact_preference
any · obbligatorio
Come il cliente vuole essere ricontattato, come l'hai mandata (contact_preference). null se la richiesta non ce l'ha.
direct
any · obbligatorio
Solo per le richieste a un destinatario (provider, chat, business).
quotes_until
any · obbligatorio
Fino a quando arrivano i preventivi (ISO 8601, in UTC).
choose_by
any · obbligatorio
Entro quando sceglierne uno, dopo la scadenza.
quotes
array · obbligatorio
quotes[].id
string · obbligatorio
quotes[].provider
object · obbligatorio
quotes[].price_cents
any · obbligatorio
La cifra del professionista. Null: la dirà in chat.
quotes[].price_max_cents
any · obbligatorio
Se c'è, la cifra è un intervallo da price_cents a questo.
quotes[].needs_inspection
boolean · obbligatorio
Cifra indicativa, da confermare con un sopralluogo.
quotes[].retainer_cents
any · obbligatorio
Un canone ricorrente, se il professionista lo propone.
quotes[].message
any · obbligatorio
quotes[].callout_cents
any · obbligatorio
Solo per un'urgenza: il diritto di chiamata del professionista (l'uscita, non il lavoro). È quello che si blocca sul tuo deposito al via.
quotes[].arrives_within_minutes
any · obbligatorio
Solo per un'urgenza: entro quanti minuti può essere sul posto.
quotes[].state
string: submitted, assigned · obbligatorio
assigned: è il preventivo scelto.
quotes[].provider_confirmed_at
any · obbligatorio
Quando il professionista scelto ha confermato l'incarico.
quotes[].created_at
string · obbligatorio
urgent
any · obbligatorio
Solo per un'urgenza: le sue tappe e l'uscita.
created_at
string · obbligatorio
partner_reference
any · obbligatorio
atriums_url
string · obbligatorio
La richiesta su Atriums (per chat, la conversazione). Mettilo nei messaggi al cliente: entra con un codice mandato al suo cellulare, parla con i professionisti e può scegliere anche lui.
Errori di questa chiamata
invalid_request400La richiesta non è valida. Vedi details.
missing_idempotency_key400Manda l'intestazione Idempotency-Key (8-200 caratteri) a ogni richiesta che scrive.
idempotency_key_reused422Questa Idempotency-Key è già stata usata con un corpo diverso.
request_in_progress409Una richiesta con questa Idempotency-Key è ancora in corso. Riprova fra qualche secondo: se si era interrotta a metà, dopo 15 minuti la ripetizione la rifà.
partner_not_active403Il tuo account legge il catalogo ma non può ancora prenotare. Scrivi ad Atriums.
not_allowed403Il tuo contratto non permette questa prenotazione.
not_found404Non trovato.
request_closed409La richiesta non è più aperta. Vedi details.status.
already_assigned409Un professionista è già stato scelto, da te o dal cliente su Atriums. Rileggi la richiesta.
quote_not_available409Questo preventivo non si può scegliere (ritirato o non ancora inviato). Vedi details.state.
insufficient_deposit402Il tuo disponibile è più basso del totale. Ricarica il deposito e riprova.
exposure_limit_exceeded402Il bloccato supererebbe il tuo tetto. Riprova quando qualche prenotazione è confermata o rilasciata.
missing_api_key401Manca la chiave. Mandala come Authorization: Bearer <chiave>.
invalid_api_key401La chiave non è valida o è stata revocata.
partner_disabled403Questo account partner non è acceso. Scrivi ad Atriums.
unavailable503Il servizio è momentaneamente non disponibile. Riprova più tardi.
internal_error500Qualcosa non ha funzionato dalla nostra parte. È stato registrato.
Richieste

Aspettare o allargare

POST/v1/requests/{id}/direct-choice

Per una richiesta a un destinatario (provider, chat, business), quando Atriums propone la scelta al cliente: dopo request.direct_no_answer, o se il destinatario ha rinunciato (prima risponde not_requestable). widen la manda ai professionisti della zona, wait lo aspetta ancora. Sono «Mandala ad altri» e «Aspetto ancora» di Atriums. Senza una scelta, dopo 24 ore la mandiamo ad altri noi. Ti avvisiamo con request.direct_no_answer.

id
string (path) · obbligatorio
Id della richiesta.
Idempotency-Key
string (header) · obbligatorio
8-200 caratteri, una per operazione.
Corpo della richiesta
choice
string: wait, widen · obbligatorio
widen: mandala ad altri professionisti della zona. wait: aspetta ancora il destinatario.
curl -X POST "https://app.atriumsmarketplace.com/api/partner/v1/requests/a67b2cff-e588-48bf-8782-05a3887b4866/direct-choice" \
  -H "Authorization: Bearer atr_live_…" \
  -H "Idempotency-Key: 6f1c2a90-5b1e-4f3a-9d2c-1e8b7a6c5d4e" \
  -H "Content-Type: application/json" \
  -d '{
  "choice": "wait"
}'
Risposta 200
id
string · obbligatorio
number
any · obbligatorio
Il numero della richiesta su Atriums.
kind
string: provider, chat, area, find_for_me, business · obbligatorio
provider: un preventivo a un professionista (il servizio ha quote fra i booking_modes). chat: lo stesso, ma la conversazione parte subito in chat su Atriums (il servizio ha chat_available). area: più preventivi dai professionisti della zona («Non sai chi scegliere?»). find_for_me: «Cercalo per me», quando in zona non c'è nessuno: lo cerchiamo noi. business: a un'impresa della zona che non è ancora su Atriums (GET /businesses).
status
string: open, assigned, closed · obbligatorio
open: aperta, i preventivi arrivano qui. assigned: un professionista è stato scelto (da te o dal cliente su Atriums). closed: chiusa senza un professionista scelto, vedi closed_reason.
closed_reason
any · obbligatorio
box
any · obbligatorio
title
string · obbligatorio
description
any · obbligatorio
answers
object · obbligatorio
location
any · obbligatorio
delivery_mode
any · obbligatorio
Come lo vuole il cliente: lo stesso campo della richiesta. null se non l'ha detto.
remote_ok
any · obbligatorio
Con at_customer o at_provider: va bene anche online. null se la domanda non è stata fatta.
contact_preference
any · obbligatorio
Come il cliente vuole essere ricontattato, come l'hai mandata (contact_preference). null se la richiesta non ce l'ha.
direct
any · obbligatorio
Solo per le richieste a un destinatario (provider, chat, business).
quotes_until
any · obbligatorio
Fino a quando arrivano i preventivi (ISO 8601, in UTC).
choose_by
any · obbligatorio
Entro quando sceglierne uno, dopo la scadenza.
quotes
array · obbligatorio
quotes[].id
string · obbligatorio
quotes[].provider
object · obbligatorio
quotes[].price_cents
any · obbligatorio
La cifra del professionista. Null: la dirà in chat.
quotes[].price_max_cents
any · obbligatorio
Se c'è, la cifra è un intervallo da price_cents a questo.
quotes[].needs_inspection
boolean · obbligatorio
Cifra indicativa, da confermare con un sopralluogo.
quotes[].retainer_cents
any · obbligatorio
Un canone ricorrente, se il professionista lo propone.
quotes[].message
any · obbligatorio
quotes[].callout_cents
any · obbligatorio
Solo per un'urgenza: il diritto di chiamata del professionista (l'uscita, non il lavoro). È quello che si blocca sul tuo deposito al via.
quotes[].arrives_within_minutes
any · obbligatorio
Solo per un'urgenza: entro quanti minuti può essere sul posto.
quotes[].state
string: submitted, assigned · obbligatorio
assigned: è il preventivo scelto.
quotes[].provider_confirmed_at
any · obbligatorio
Quando il professionista scelto ha confermato l'incarico.
quotes[].created_at
string · obbligatorio
urgent
any · obbligatorio
Solo per un'urgenza: le sue tappe e l'uscita.
created_at
string · obbligatorio
partner_reference
any · obbligatorio
atriums_url
string · obbligatorio
La richiesta su Atriums (per chat, la conversazione). Mettilo nei messaggi al cliente: entra con un codice mandato al suo cellulare, parla con i professionisti e può scegliere anche lui.
Errori di questa chiamata
invalid_request400La richiesta non è valida. Vedi details.
missing_idempotency_key400Manda l'intestazione Idempotency-Key (8-200 caratteri) a ogni richiesta che scrive.
idempotency_key_reused422Questa Idempotency-Key è già stata usata con un corpo diverso.
request_in_progress409Una richiesta con questa Idempotency-Key è ancora in corso. Riprova fra qualche secondo: se si era interrotta a metà, dopo 15 minuti la ripetizione la rifà.
not_found404Non trovato.
not_direct422Questa richiesta non è a un destinatario: la scelta vale solo per provider, chat e business.
not_requestable422Qui adesso non si può mandare questa richiesta. Vedi details.reason.
request_closed409La richiesta non è più aperta. Vedi details.status.
missing_api_key401Manca la chiave. Mandala come Authorization: Bearer <chiave>.
invalid_api_key401La chiave non è valida o è stata revocata.
partner_disabled403Questo account partner non è acceso. Scrivi ad Atriums.
unavailable503Il servizio è momentaneamente non disponibile. Riprova più tardi.
internal_error500Qualcosa non ha funzionato dalla nostra parte. È stato registrato.
Richieste

Annullare una richiesta

POST/v1/requests/{id}/cancel

Annulla la richiesta per conto del tuo cliente, alle condizioni di Atriums: solo se è ancora aperta e nessun professionista è stato scelto. Chi aveva risposto riceve l'avviso. Senza corpo.

id
string (path) · obbligatorio
Id della richiesta.
Idempotency-Key
string (header) · obbligatorio
8-200 caratteri, una per operazione.
curl -X POST "https://app.atriumsmarketplace.com/api/partner/v1/requests/a67b2cff-e588-48bf-8782-05a3887b4866/cancel" \
  -H "Authorization: Bearer atr_live_…" \
  -H "Idempotency-Key: 6f1c2a90-5b1e-4f3a-9d2c-1e8b7a6c5d4e"
Risposta 200
id
string · obbligatorio
number
any · obbligatorio
Il numero della richiesta su Atriums.
kind
string: provider, chat, area, find_for_me, business · obbligatorio
provider: un preventivo a un professionista (il servizio ha quote fra i booking_modes). chat: lo stesso, ma la conversazione parte subito in chat su Atriums (il servizio ha chat_available). area: più preventivi dai professionisti della zona («Non sai chi scegliere?»). find_for_me: «Cercalo per me», quando in zona non c'è nessuno: lo cerchiamo noi. business: a un'impresa della zona che non è ancora su Atriums (GET /businesses).
status
string: open, assigned, closed · obbligatorio
open: aperta, i preventivi arrivano qui. assigned: un professionista è stato scelto (da te o dal cliente su Atriums). closed: chiusa senza un professionista scelto, vedi closed_reason.
closed_reason
any · obbligatorio
box
any · obbligatorio
title
string · obbligatorio
description
any · obbligatorio
answers
object · obbligatorio
location
any · obbligatorio
delivery_mode
any · obbligatorio
Come lo vuole il cliente: lo stesso campo della richiesta. null se non l'ha detto.
remote_ok
any · obbligatorio
Con at_customer o at_provider: va bene anche online. null se la domanda non è stata fatta.
contact_preference
any · obbligatorio
Come il cliente vuole essere ricontattato, come l'hai mandata (contact_preference). null se la richiesta non ce l'ha.
direct
any · obbligatorio
Solo per le richieste a un destinatario (provider, chat, business).
quotes_until
any · obbligatorio
Fino a quando arrivano i preventivi (ISO 8601, in UTC).
choose_by
any · obbligatorio
Entro quando sceglierne uno, dopo la scadenza.
quotes
array · obbligatorio
quotes[].id
string · obbligatorio
quotes[].provider
object · obbligatorio
quotes[].price_cents
any · obbligatorio
La cifra del professionista. Null: la dirà in chat.
quotes[].price_max_cents
any · obbligatorio
Se c'è, la cifra è un intervallo da price_cents a questo.
quotes[].needs_inspection
boolean · obbligatorio
Cifra indicativa, da confermare con un sopralluogo.
quotes[].retainer_cents
any · obbligatorio
Un canone ricorrente, se il professionista lo propone.
quotes[].message
any · obbligatorio
quotes[].callout_cents
any · obbligatorio
Solo per un'urgenza: il diritto di chiamata del professionista (l'uscita, non il lavoro). È quello che si blocca sul tuo deposito al via.
quotes[].arrives_within_minutes
any · obbligatorio
Solo per un'urgenza: entro quanti minuti può essere sul posto.
quotes[].state
string: submitted, assigned · obbligatorio
assigned: è il preventivo scelto.
quotes[].provider_confirmed_at
any · obbligatorio
Quando il professionista scelto ha confermato l'incarico.
quotes[].created_at
string · obbligatorio
urgent
any · obbligatorio
Solo per un'urgenza: le sue tappe e l'uscita.
created_at
string · obbligatorio
partner_reference
any · obbligatorio
atriums_url
string · obbligatorio
La richiesta su Atriums (per chat, la conversazione). Mettilo nei messaggi al cliente: entra con un codice mandato al suo cellulare, parla con i professionisti e può scegliere anche lui.
Errori di questa chiamata
invalid_request400La richiesta non è valida. Vedi details.
missing_idempotency_key400Manda l'intestazione Idempotency-Key (8-200 caratteri) a ogni richiesta che scrive.
idempotency_key_reused422Questa Idempotency-Key è già stata usata con un corpo diverso.
request_in_progress409Una richiesta con questa Idempotency-Key è ancora in corso. Riprova fra qualche secondo: se si era interrotta a metà, dopo 15 minuti la ripetizione la rifà.
not_found404Non trovato.
request_closed409La richiesta non è più aperta. Vedi details.status.
missing_api_key401Manca la chiave. Mandala come Authorization: Bearer <chiave>.
invalid_api_key401La chiave non è valida o è stata revocata.
partner_disabled403Questo account partner non è acceso. Scrivi ad Atriums.
unavailable503Il servizio è momentaneamente non disponibile. Riprova più tardi.
internal_error500Qualcosa non ha funzionato dalla nostra parte. È stato registrato.
Deposito

Il deposito

GET/v1/deposit

Disponibile e bloccato, il tuo tetto, gli ultimi movimenti e l'IBAN su cui lo ricarichi con un bonifico (bank_transfer).

curl "https://app.atriumsmarketplace.com/api/partner/v1/deposit" \
  -H "Authorization: Bearer atr_live_…"
Risposta 200
available_cents
integer · obbligatorio
held_cents
integer · obbligatorio
Bloccato per prenotazioni che aspettano il professionista.
exposure_limit_cents
any · obbligatorio
Il massimo che puoi avere bloccato nello stesso momento.
low_balance_threshold_cents
any · obbligatorio
currency
string · obbligatorio
bank_transfer
any · obbligatorio
Dove ricarichi il deposito: un IBAN solo tuo. Ogni bonifico che arriva lo incassiamo per intero e diventa un movimento top_up, di solito entro pochi minuti dall'arrivo (un bonifico SEPA impiega da 0 a 3 giorni lavorativi). Null: il tuo deposito non è ancora su Stripe; chiedilo ad Atriums.
movements
array · obbligatorio
Gli ultimi 100, dal più recente.
movements[].type
string: top_up, hold, release, charge, credit_back · obbligatorio
movements[].amount_cents
integer · obbligatorio
movements[].available_change_cents
integer · obbligatorio
Di quanto ha cambiato il tuo disponibile (lo scalato muove soldi già bloccati, quindi 0).
movements[].booking_id
any · obbligatorio
movements[].request_id
any · obbligatorio
Per l'uscita di un intervento urgente: la richiesta (POST /requests). Allora booking_id è null.
movements[].partner_reference
any · obbligatorio
movements[].created_at
string · obbligatorio
Errori di questa chiamata
missing_api_key401Manca la chiave. Mandala come Authorization: Bearer <chiave>.
invalid_api_key401La chiave non è valida o è stata revocata.
partner_disabled403Questo account partner non è acceso. Scrivi ad Atriums.
unavailable503Il servizio è momentaneamente non disponibile. Riprova più tardi.
internal_error500Qualcosa non ha funzionato dalla nostra parte. È stato registrato.
Avvisi

Avvisi di ritorno

Quando qualcosa succede a una tua prenotazione te lo mandiamo noi, con un POST all'indirizzo che ci hai dato. Il corpo è { id, type, created_at, data }: data è la prenotazione com'era quando è nato l'avviso, con gli stessi campi di GET /v1/bookings/{id}; per sapere com'è adesso, rileggila lì. Rispondi 2xx entro 10 secondi; altrimenti ritentiamo, 8 volte in circa 22 ore. Lo stesso avviso consegnato due volte ha lo stesso id.

booking.confirmedIl professionista ha accettato. Il bloccato ora è scalato dal tuo deposito.
booking.declinedIl professionista ha rifiutato. Il bloccato torna sul tuo deposito.
booking.expiredIl professionista non ha risposto entro 24 ore. Il bloccato torna sul tuo deposito.
booking.cancelledAnnullata dal professionista (torna tutto sul tuo deposito) o da te (POST /bookings/{id}/cancel).
booking.rescheduledLa prenotazione è stata spostata dal professionista o da te (POST /bookings/{id}/reschedule): data.starts_at è il nuovo orario. Se l'ha spostata il professionista, avvisa il tuo cliente.
booking.completedIl lavoro è fatto. Il professionista lo paga Atriums.
dispute.openedIl cliente o il professionista ha aperto un reclamo su Atriums: lo decide Atriums, e il pagamento al professionista resta fermo. Vedi data.disputes.
dispute.resolvedAtriums ha deciso un reclamo: vedi data.disputes (outcome, back_to_deposit_cents). Se c'è un rimborso è già tornato sul tuo deposito: rimborsa tu il tuo cliente.
request.quote_receivedÈ arrivato un preventivo: vedi data.quotes. Lo puoi scegliere (POST /requests/{id}/quotes/{quote_id}/accept); al cliente l'ha già scritto Atriums.
request.quote_withdrawnUn professionista ha ritirato il suo preventivo.
request.assignedUn professionista è stato scelto, da te o dal cliente su Atriums: è il preventivo con state: assigned.
request.provider_confirmedIl professionista scelto ha confermato l'incarico: da qui cliente e professionista si accordano sul lavoro.
request.reopenedLa richiesta è di nuovo aperta (il professionista scelto non ha confermato in tempo, o l'ha riaperta Atriums): se ne può scegliere un altro.
request.closedLa richiesta è chiusa senza un professionista scelto: vedi data.closed_reason.
request.provider_found«Cercalo per me»: abbiamo trovato qualcuno, e la richiesta è partita verso i professionisti della zona.
request.direct_no_answerIl destinatario non ha ancora risposto: chiedi al tuo cliente se aspettarlo o mandarla ad altri (POST /requests/{id}/direct-choice). Glielo chiede anche Atriums.
request.urgent_provider_availableUrgenza in ascolto: ora qualcuno può arrivare a quell'indirizzo. Se serve ancora, crea una richiesta nuova con urgent: true.
request.urgent_on_the_wayIl professionista è partito: vedi data.urgent.provider_on_the_way_at.
request.urgent_arrivedIl professionista ha segnato l'arrivo. Il cliente conferma o contesta su Atriums, entro la sua finestra.
request.urgent_disputedIl cliente ha contestato l'intervento: lo decide Atriums, e l'uscita resta bloccata sul tuo deposito.
request.urgent_chargedL'uscita è scalata dal tuo deposito: data.urgent.callout.charged_cents (ridotta se il professionista era in ritardo; il resto è tornato disponibile).
request.urgent_releasedL'uscita è tornata disponibile sul tuo deposito: il professionista non è arrivato in tempo, o la contestazione è accolta.

La firma. Ogni avviso porta Atriums-Signature: t=<secondi unix>,v1=<hex>. Calcola l'HMAC-SHA256 di <t>.<corpo così come arriva> col tuo segreto di firma e confrontalo con v1 a tempo costante. Scarta l'avviso se t è più vecchio di 5 minuti.

import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody: il corpo così come è arrivato, prima di JSON.parse
function firmaValida(rawBody, intestazione, segreto) {
  const [t, v1] = intestazione.split(",").map((p) => p.split("=")[1]);
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // più vecchia di 5 minuti
  const atteso = createHmac("sha256", segreto).update(`${t}.${rawBody}`).digest("hex");
  return v1.length === atteso.length && timingSafeEqual(Buffer.from(v1, "hex"), Buffer.from(atteso, "hex"));
}

Errori

Ogni errore ha un code stabile e un message leggibile; alcuni hanno details. I codici si aggiungono, non si cambiano.

missing_api_key401Manca la chiave. Mandala come Authorization: Bearer <chiave>.
invalid_api_key401La chiave non è valida o è stata revocata.
partner_disabled403Questo account partner non è acceso. Scrivi ad Atriums.
invalid_request400La richiesta non è valida. Vedi details.
not_found404Non trovato.
unavailable503Il servizio è momentaneamente non disponibile. Riprova più tardi.
internal_error500Qualcosa non ha funzionato dalla nostra parte. È stato registrato.
missing_idempotency_key400Manda l'intestazione Idempotency-Key (8-200 caratteri) a ogni richiesta che scrive.
idempotency_key_reused422Questa Idempotency-Key è già stata usata con un corpo diverso.
request_in_progress409Una richiesta con questa Idempotency-Key è ancora in corso. Riprova fra qualche secondo: se si era interrotta a metà, dopo 15 minuti la ripetizione la rifà.
partner_not_active403Il tuo account legge il catalogo ma non può ancora prenotare. Scrivi ad Atriums.
not_allowed403Il tuo contratto non permette questa prenotazione.
service_not_bookable422Questo servizio adesso non si prenota dalla API. Vedi details.reason.
slot_unavailable409Quell'orario non è più libero. Chiedi di nuovo GET /services/{id}/availability.
departure_unavailable409Questa partenza non si prenota più (passata, spenta, o a meno di 12 ore). Vedi details.reason e chiedi di nuovo GET /services/{id}/departures.
not_enough_seats409Non ci sono abbastanza posti su questa partenza. Vedi details.seats_left.
offer_unavailable409Questa offerta non si prenota più per quel giorno e quelle età. Chiedi di nuovo GET /services/{id}/offers.
operator_declined409L'operatore non ha confermato la prenotazione: non è stato scalato niente. Puoi scegliere un'altra offerta.
outside_coverage422Il professionista non arriva a quell'indirizzo.
address_not_found422Non troviamo quell'indirizzo. Controllalo, o manda lat e lng.
customer_is_provider422Il cliente è il professionista di questo servizio.
price_changed409Il prezzo è diverso da expected_total_cents. Non è stato prenotato niente. Vedi details.total_cents.
insufficient_deposit402Il tuo disponibile è più basso del totale. Ricarica il deposito e riprova.
exposure_limit_exceeded402Il bloccato supererebbe il tuo tetto. Riprova quando qualche prenotazione è confermata o rilasciata.
not_cancellable409Questa prenotazione non si può più disdire. Vedi details.status.
not_reschedulable409Questa prenotazione non si può spostare. Vedi details.reason.
not_requestable422Qui adesso non si può mandare questa richiesta. Vedi details.reason.
urgent_not_supported422Un intervento urgente (urgent: true) si chiede a un professionista (provider) o ai professionisti della zona (area).
no_urgent_provider422A questo indirizzo adesso non arriva nessuno. Puoi restare in attesa (if_nobody_available: wait): ti avvisiamo appena qualcuno si rende disponibile.
business_unavailable422Questa impresa non riceve più richieste. Chiedi di nuovo GET /businesses.
request_rejected422Atriums non ha accettato questa richiesta. Il motivo è in message.
request_closed409La richiesta non è più aperta. Vedi details.status.
already_assigned409Un professionista è già stato scelto, da te o dal cliente su Atriums. Rileggi la richiesta.
quote_not_available409Questo preventivo non si può scegliere (ritirato o non ancora inviato). Vedi details.state.
not_direct422Questa richiesta non è a un destinatario: la scelta vale solo per provider, chat e business.

Registro delle modifiche

In questa versione si aggiungono campi, valori ed eventi, ma non si tolgono né si cambiano quelli esistenti: il tuo codice deve ignorare ciò che non conosce.

21 novembre 2026
  • Le richieste (GET /requests/{id} e le altre risposte con una richiesta) hanno tre campi nuovi, letti dalla richiesta che hai mandato: delivery_mode, remote_ok e contact_preference. null quando il cliente non li ha dati. Gli stessi campi arrivano negli avvisi con una richiesta. Gli altri campi non cambiano.
13 novembre 2026
  • confirm_by ora non va mai oltre starts_at: il professionista ha 24 ore per accettare, e comunque fino all'inizio dell'appuntamento. Campo e formato non cambiano; per un appuntamento vicino il valore è più presto. Alla scadenza tutto resta come prima: lo stato expired e l'avviso booking.expired.
2 novembre 2026
  • GET /deposit ha il nuovo campo bank_transfer: l'IBAN solo tuo su cui ricarichi il deposito con un bonifico (null se il deposito non è ancora su Stripe). Ogni bonifico arrivato diventa un movimento top_up.
2 novembre 2026
  • Transfer da e per l'aeroporto, se il tuo contratto li comprende: nuova chiamata GET /transfers (tratta, ora, persone, volo) con le offerte dell'operatore di quel momento.
  • POST /bookings prenota un transfer con il nuovo campo transfer e il service_id della risposta di GET /transfers (con customer.email obbligatoria), con la stessa sequenza delle esperienze di operatori esterni.
  • Nel blocco voucher il nuovo campo transfer (null per un'esperienza): tratta, ora, volo, persone e veicolo. Per un transfer voucher.participants è vuoto.
2 novembre 2026
  • Esperienze di operatori esterni, se il tuo contratto le comprende: compaiono nei box di esperienze di GET /categories e GET /services; la loro scheda ha booking_modes offer (nuovo valore) e cancellation.free_until_hours_before null (la regola è dell'operatore).
  • Nuova chiamata GET /services/{id}/offers: le offerte di un giorno per le età dei partecipanti, con prezzi, penali e domande dell'operatore.
  • POST /bookings prenota un'offerta con il nuovo campo offer (con customer.email obbligatoria): l'operatore conferma nella stessa chiamata. Nuovi errori offer_unavailable e operator_declined. Se l'operatore non risponde: un 5xx, l'importo resta bloccato finché l'esito non è chiaro, poi l'avviso booking.confirmed o booking.cancelled.
  • Nella prenotazione il nuovo blocco voucher (null negli altri casi), con i campi che l'operatore vuole sul voucher del cliente. La disdetta di un'offerta usa la penale dell'operatore di quel momento.
1 novembre 2026
  • Il catalogo che vedi è quello del tuo contratto: se il contratto ti lascia vendere solo alcuni box, gli altri non compaiono in GET /categories, GET /services e GET /businesses non li danno, e le chiamate su un loro servizio rispondono not_found. Prima il catalogo era intero, e i box fuori contratto si fermavano solo in scrittura (not_allowed, box_not_in_contract), che resta.
1 novembre 2026
  • Esperienze dei professionisti: nei box di esperienze GET /categories dà offers_nearby e GET /services le esperienze con almeno una partenza; la scheda di un'esperienza ha booking_modes departure e il nuovo blocco experience (punto d'incontro, etichette). Gli altri servizi hanno experience: null.
  • Nuova chiamata GET /services/{id}/departures: le partenze con posti e prezzo a persona.
  • POST /bookings prenota una partenza con departure_id e people (al posto di lines e starts_at): confermata subito, scalata dal deposito. Nuovi errori departure_unavailable e not_enough_seats. Una prenotazione su una partenza non si sposta (not_reschedulable, motivo not_supported); se il professionista annulla la partenza ricevi booking.cancelled e torna tutto sul deposito.
  • Le voci del catalogo esterno nei box di esperienze non sono ancora nella API: GET /services/{id} risponde not_found (prima rispondeva come un servizio qualsiasi).
1 novembre 2026
  • Interventi urgenti: POST /requests con urgent: true (kind: provider o area) apre un intervento adesso, come il «Pronto intervento» di Atriums. Il via lo dai con POST /requests/{id}/quotes/{quote_id}/accept: l'uscita si blocca sul tuo deposito. Vedi la guida «Interventi urgenti».
  • GET /services/{id}: nuovo campo urgent_available.
  • Nuovi campi urgent e if_nobody_available in POST /requests; nuovi campi callout_cents e arrives_within_minutes nei preventivi e urgent nella richiesta. Nuovo errore no_urgent_provider; insufficient_deposit ed exposure_limit_exceeded anche sul via di un'urgenza. Nei movimenti di GET /deposit il nuovo campo request_id per l'uscita di un'urgenza (lì booking_id è null).
  • Nuovi avvisi request.urgent_provider_available, request.urgent_on_the_way, request.urgent_arrived, request.urgent_disputed, request.urgent_charged, request.urgent_released.
  • urgent_not_supported ora risponde a urgent: true con chat, find_for_me o business.
1 novembre 2026
  • Richieste ai professionisti: nuova chiamata POST /requests per chiedere preventivi per il tuo cliente, nei modi di Atriums: a un professionista (provider), in chat (chat), ai professionisti della zona (area), «Cercalo per me» (find_for_me) o a un'impresa non ancora su Atriums (business). Non paghi niente: scegliere è un incarico, il prezzo lo concordano cliente e professionista. Al cliente scrive Atriums.
  • Nuove chiamate GET /requests/{id}, POST /requests/{id}/quotes/{quote_id}/accept, POST /requests/{id}/direct-choice e POST /requests/{id}/cancel.
  • Nuova chiamata GET /businesses: le imprese della zona non ancora su Atriums, come nei risultati del sito.
  • Nuovi avvisi request.quote_received, request.quote_withdrawn, request.assigned, request.provider_confirmed, request.reopened, request.closed, request.provider_found, request.direct_no_answer: data è la richiesta. Gli avvisi di prima non cambiano.
  • Nuovi errori not_requestable, urgent_not_supported, business_unavailable, request_rejected, request_closed, already_assigned, quote_not_available, not_direct.
  • GET /services/{id}: nuovo campo chat_available; request_questions ora c'è anche quando il servizio si può solo chattare (prima era vuoto).
1 novembre 2026
  • Reclami: nuovi avvisi dispute.opened e dispute.resolved, e il campo disputes nella prenotazione (chi l'ha aperto, quando, com'è stato deciso, quanto è tornato sul tuo deposito). Il testo del reclamo resta su Atriums.
  • Un reclamo deciso con un rimborso ora torna sul tuo deposito (prima si chiudeva solo senza rimborso): rimborsi tu il tuo cliente.
  • Una disdetta interrotta a metà dalla nostra parte (POST /bookings/{id}/cancel) si completa da sola: i soldi tornano sul deposito senza doppioni.
1 novembre 2026
  • GET /bookings/{id} e gli avvisi portano la prenotazione per intero, come la vede il cliente su Atriums: service, provider, lines, ends_at, delivery_mode, place, note, cancellation_policy, atriums_url. Nessun campo di prima è cambiato.
  • Nuova chiamata POST /bookings/{id}/reschedule per spostare una prenotazione con la regola del cliente (24 ore prima, senza costi). Nuovo errore not_reschedulable, col motivo in details.reason.
  • booking.rescheduled arriva anche quando sposti tu, uno per ogni spostamento, anche tornando su un orario già avvisato.
  • Messaggi al cliente: se il tuo contratto dice che gli scrivi tu, Atriums non gli manda i messaggi sulla prenotazione. Se un avviso non ti arriva entro 60 minuti, quel messaggio glielo scriviamo noi.
  • POST /bookings accetta esattamente le partenze di GET /services/{id}/availability: prima, prenotando più unità, alcune venivano rifiutate con slot_unavailable.
  • request_in_progress: una richiesta interrotta a metà dalla nostra parte si rifà ripetendola dopo 15 minuti, invece di restare in corso per sempre.
31 ottobre 2026
  • Prima versione. Catalogo: GET /categories, GET /services, GET /services/{id}, GET /services/{id}/availability, GET /coverage.
  • Prenotazioni: POST /bookings, GET /bookings/{id}, GET /bookings/{id}/cancellation, POST /bookings/{id}/cancel. Deposito: GET /deposit.
  • Avvisi di ritorno firmati: booking.confirmed, booking.declined, booking.expired, booking.cancelled, booking.rescheduled, booking.completed.

Pronto a vendere?

Una chiave di prova e il catalogo di test, per provare tutto senza soldi veri.

  1. 1La tua azienda
  2. 2Chi richiamiamo

Dove i tuoi clienti prenoteranno i servizi.

AtriumsAtriums

Il marketplace più semplice per la prenotazione immediata di servizi.

App

  • Sei un Pro
  • Partner e API
  • Esplora i Servizi
  • Come funziona

In Atriums

  • Chi siamo
  • Finalità Sociali
  • Aiuto e assistenza
  • Blog

© 2026 Atriums S.r.l. — Tutti i diritti riservati.

Cookie PolicyInformativa PrivacyTermini e Condizioni