Flussi API guidati

Questi esempi collegano gli endpoint in tre percorsi frequenti. Eseguili da un backend affidabile con una chiave dell'ambiente corretto. Nomi, indirizzi, ID e domini sono segnaposto fittizi. Sostituisci gli ID con quelli restituiti dalla tua company; gli ID di altre company o ambienti non sono riutilizzabili.

Usa l'URL versionato https://api.hub.donutwork.com/2026-02-01 e l'header Authorization: Bearer YOUR_API_KEY. Conserva la chiave tra i segreti del server. Gli esempi presuppongono che DONUTWORK_API_KEY sia già disponibile nella shell; non inserire una chiave reale nella documentazione. Prima della produzione leggi autenticazione e fondamenti dell'integrazione.

Flusso 1: creare un cliente e associarlo a un piano

Obiettivo: collegare un cliente del CRM a un piano ricorrente. Servono customers:write, customer_subscriptions:write, customer_subscriptions:read, recurring_subscriptions:read e taxes:read.

1. Elenca piani e profili fiscali. Scegli un piano e un profilo fiscale della stessa company. Il profilo fiscale è richiesto per l'associazione.

curl 'https://api.hub.donutwork.com/2026-02-01/recurring-payments/subscriptions.json' \
  -H "Authorization: Bearer $DONUTWORK_API_KEY"
curl 'https://api.hub.donutwork.com/2026-02-01/taxes.json' \
  -H "Authorization: Bearer $DONUTWORK_API_KEY"

2. Crea il cliente e salva customer.id dalla risposta. externalId è l'identificativo stabile del tuo CRM: un secondo tentativo con lo stesso valore può restituire 409. Dopo un esito incerto, cerca il cliente esistente prima di ricrearlo.

curl -X POST 'https://api.hub.donutwork.com/2026-02-01/customers.json' \
  -H "Authorization: Bearer $DONUTWORK_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"customer":{"company_name":"Example Studio","first_name":"Alex","last_name":"Rossi","email":"alex@example.com","externalId":"CRM-EXAMPLE-001","address":{"country":"IT","city":"Milano","address":"Via Esempio 1"}}}'

3. Associa il piano scelto. Sostituisci CUSTOMER_ID, PLAN_ID e TAX_ID con gli ID ottenuti. Poi rileggi gli abbonamenti del cliente per verificarne lo stato.

curl -X POST 'https://api.hub.donutwork.com/2026-02-01/customers/CUSTOMER_ID/subscriptions.json' \
  -H "Authorization: Bearer $DONUTWORK_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"subscription":{"id":"PLAN_ID","taxes":"TAX_ID"}}'
curl 'https://api.hub.donutwork.com/2026-02-01/customers/CUSTOMER_ID/subscriptions.json' \
  -H "Authorization: Bearer $DONUTWORK_API_KEY"

Un 404 nell'associazione indica spesso che cliente, piano o profilo fiscale non appartengono alla company. Per campi e azioni sul ciclo di vita consulta clienti, pagamenti ricorrenti e imposte.

Flusso 2: ricevere eventi e riconciliare una charge

Obiettivo: ricevere gli eventi di pagamento e leggere lo stato attuale della charge. Servono webhooks:read, webhooks:write, charges:write e charges:read. Per acquisire il pagamento il cliente deve avere un metodo di pagamento e serve un profilo fiscale valido.

1. Leggi i nomi degli eventi supportati, poi registra un endpoint HTTPS con certificato valido. Sostituisci l'URL di esempio con un endpoint sotto il tuo controllo. Conserva privatamente il token webhook generato.

curl 'https://api.hub.donutwork.com/2026-02-01/webhooks/types.json' \
  -H "Authorization: Bearer $DONUTWORK_API_KEY"
curl -X POST 'https://api.hub.donutwork.com/2026-02-01/webhooks.json' \
  -H "Authorization: Bearer $DONUTWORK_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"webhook":{"name":"Billing updates","url":"https://example.com/webhooks/billing","events":["Charge.succeeded","Charge.failed"]}}'

2. Crea una charge per un cliente con metodo di pagamento già configurato. Sostituisci TAX_ID con un profilo della company. Salva l'id restituito anche se captured è false.

curl -X POST 'https://api.hub.donutwork.com/2026-02-01/customers/CUSTOMER_ID/charges.json' \
  -H "Authorization: Bearer $DONUTWORK_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"charge":{"capture":true,"services":[{"name":"Example service","amount":25.00,"taxProfile":"TAX_ID"}]}}'

3. Dopo un evento o un timeout incerto, rileggi la charge e riconcilia il suo stato con il tuo sistema. La riuscita della creazione non garantisce che il pagamento sia stato acquisito. Se manca il metodo di pagamento, la risposta è 412.

curl 'https://api.hub.donutwork.com/2026-02-01/customers/CUSTOMER_ID/charges/CHARGE_ID.json' \
  -H "Authorization: Bearer $DONUTWORK_API_KEY"

Consulta pagamenti ricorrenti e charge e webhook. Registra soltanto gli eventi restituiti da /webhooks/types.json.

Per un pagamento già incassato da un altro sistema segui la guida importare charge esterne. Registra il pagamento ed emette gli eventi charge senza un secondo incasso sul gateway; usa la chiave della transazione sorgente per retry idempotenti.

Flusso 3: inviare un'email transazionale

Obiettivo: usare un template della company con variabili di esempio. Servono email_templates:read e email_messages:write. L'Email Gateway deve essere configurato per la company.

1. Elenca i template e scegli l'ID di uno esistente. Il template deve contenere HTML e prevedere le variabili inviate.

curl 'https://api.hub.donutwork.com/2026-02-01/email-gateway/templates.json' \
  -H "Authorization: Bearer $DONUTWORK_API_KEY"

2. Invia usando il mittente configurato. Ometti from per usare quello predefinito; un valore esplicito deve essere un mittente alternativo configurato. Il destinatario qui è fittizio.

curl -X POST 'https://api.hub.donutwork.com/2026-02-01/email-gateway/TEMPLATE_ID/send.json' \
  -H "Authorization: Bearer $DONUTWORK_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"email":{"to":"recipient@example.com","subject":"Aggiornamento account","vars":{"first_name":"Alex"}}}'

Se il template non esiste o è vuoto, l'endpoint restituisce 404. Nella reference Email Gateway trovi validazione, anteprima e risposte di invio.

Per l'AI segui gli esempi guidati AI Gateway. Per operazioni più avanzate consulta workflow, AI Gateway e AI Agents. La pagina di ogni endpoint indica permission e contratto della richiesta.