API e integrazioni

Per chi collega un e-commerce, un gestionale o un pannello ordini a Fattorino.it: le consegne nascono all'ordine pagato, il prezzo lo calcoliamo noi dai fatti, e lo stato torna indietro con avvisi firmati. Qui c'è tutto quello che serve per scriverlo — e per non doverci chiamare alle undici di sera.

La chiave

Si crea nel gestionale dell'organizzazione, in Integrazioni, e si vede una volta sola. Va in ogni richiesta come Authorization: Bearer ft_…. Dietro ogni chiave c'è un account tecnico, membro dell'organizzazione e visibile in «Persone e accessi»: un'integrazione che può scrivere dev'essere visibile come una persona. Si revoca da lì.

Gli endpoint

Base: https://www.fattorino.it/api/v1/, JSON in entrata e in uscita. Al massimo 600 richieste ogni 60 secondi.

Endpoint	Cosa fa
`GET /api/v1/copertura`	Copertura. Dice se servi quel comune con quel servizio. Non crea niente. Parametri: servizio (la chiave), comune.
`POST /api/v1/preventivo`	Preventivo. Dai fatti — servizio, peso_kg, volume_l, distanza_km, urgente, quando — il prezzo calcolato da noi, col listino del tuo contratto se c'è. Il client non manda mai un prezzo: se lo manda, non viene letto. Con ogni preventivo riuscito torna anche la regola di ripiego.
`GET /api/v1/regola-checkout`	Regola di ripiego. Cosa fare al checkout se non rispondiamo: nascondere l'opzione, usare una tariffa concordata, o bloccare. Tienila da parte: serve proprio quando non ci puoi chiamare. Senza accordo si nasconde.
`POST /api/v1/commesse`	Crea una consegna. All'ordine pagato. Risponde 201 con la consegna, o 200 con quella che esisteva già. Manda sempre Idempotency-Key e id_esterno (per esempio wc-<ordine>): ripetere non ne crea due. Stessa chiave e corpo diverso: 409. Il prezzo lo ricalcola il server.
`GET /api/v1/commesse`	Riconciliazione. Cosa si è mosso da un certo momento in poi: ?aggiornate_dopo=<ISO 8601>. È il rimedio quando un webhook si è perso. Falla girare ogni ora: se è scomoda si smette di farla, ed è il momento in cui i due sistemi divergono.
`GET /api/v1/commesse/per-id-esterno/{id_esterno}`	Cerca per id esterno. «L'avevo già mandata?» — la domanda da fare dopo un errore di rete, prima di riprovare. 404 vuol dire che non è arrivata: si può creare.
`GET /api/v1/commesse/{consegna_id}`	Stato e prove. A che punto è la consegna, con la cronologia degli stati. Delle prove di consegna si dice che ci sono e di che tipo, non si servono i file.
`POST /api/v1/commesse/{consegna_id}/pronta`	La merce è pronta. Conferma la consegna: da qui qualcuno può partire a ritirarla. Ripeterla risponde uguale: è quello che fa una rete lenta.
`POST /api/v1/commesse/{consegna_id}/reso`	Torna al mittente. La merce non consegnata torna indietro (stato «in reso»). Si può solo dove la macchina degli stati lo permette: se da qui non si può, non si può.
`POST /api/v1/commesse/{consegna_id}/resi`	Organizza un reso. Un reso chiesto dal cliente del negozio: una consegna al contrario, dal cliente alla sede di partenza. Uno solo per consegna: chiederlo di nuovo risponde 200 con lo stesso.
`POST /api/v1/commesse/{consegna_id}/link`	Link di tracking. Il link da mettere nell'email d'ordine: chi aspetta il pacco lo segue da lì. Sempre lo stesso finché vale: chiederlo di nuovo non spegne quello che il cliente ha già.
`PATCH /api/v1/commesse/{consegna_id}`	Variazioni. Cambia i dati che si possono ancora cambiare: istruzioni, telefono e note fino all'ultimo; destinatario e indirizzo finché la consegna non è partita. Ogni correzione resta in cronologia con cosa c'era prima. Se non si può più: 409 con il perché.

Ripetere non raddoppia

Una rete che cade a metà è normale. Per questo ogni creazione porta due reti una sopra l'altra: l'intestazione Idempotency-Key (stessa chiave, stessa risposta; stessa chiave con un corpo diverso è un errore tuo, e rispondiamo 409 invece di perdere una consegna in silenzio) e id_esterno, il tuo identificativo dell'ordine, unico per organizzazione. Il riferimento invece è il filo fra più consegne dello stesso ordine, e si ripete.

Gli errori

Ogni errore dice cosa fare, con un codice da leggere e una frase da mostrare (le frasi dell'API sono in italiano):

{
  "come_fare": "crea una chiave nel gestionale, in Integrazioni, e mandala come Authorization: Bearer ft_\u2026",
  "errore": "chiave_non_valida"
}

Gli avvisi (webhook)

Si configurano in Integrazioni, solo verso https://. Partono dopo il cambio di stato, con sei ritentativi a pause crescenti; se uno si perde, la riconciliazione (GET /api/v1/commesse?aggiornate_dopo=…) rimette in pari. Da Integrazioni si manda anche un evento di prova: provalo prima che arrivi il primo pacco vero.

Evento	Quando
`commessa.creata`	La consegna è stata creata
`commessa.confermata`	La merce è pronta e la consegna è confermata
`commessa.assegnata`	Qualcuno la porta
`commessa.ritirata`	Ritirata
`commessa.consegnata`	Consegnata
`commessa.non_riuscita`	Tentativo non riuscito
`commessa.annullata`	Annullata
`prova.raccolta`	È stata raccolta una prova di consegna

Ogni avviso porta X-Fattorino-Evento, X-Fattorino-Invio (lo stesso nei ritentativi: usalo per non elaborarlo due volte) e X-Fattorino-Signature nella forma t=<secondi>,v1=<hmac>, dove l'HMAC-SHA256 si calcola col segreto del webhook su <t>.<corpo>. Scarta gli avvisi con un t più vecchio di cinque minuti: una firma valida su un avviso catturato mesi fa resta valida.

Per provare il tuo codice: con il segreto segreto-di-esempio, il corpo {"evento":"commessa.consegnata","consegna":{"id":1042,"stato":"consegnata"}} e t=1790000000, l'intestazione dev'essere:

t=1790000000,v1=95ba4bb6ac885d42ffaab79aec7f65f652aa2ea2cc0a328b6d0e9f5dcf070ff9

Quando non rispondiamo

Il tuo checkout non deve restare appeso. La regola di ripiego — nascondere l'opzione, una tariffa concordata, o bloccare — la concordiamo prima, viaggia con ogni preventivo e si legge da GET /api/v1/regola-checkout: tienila da parte, serve proprio quando non ci raggiungi. Senza un accordo si nasconde.

WooCommerce, PrestaShop e Magento

Ci sono i plugin: preventivo al checkout, consegna all'ordine pagato, link di tracking nelle email del negozio, stato aggiornato dagli avvisi firmati più una riconciliazione oraria. Nel pilota li installiamo insieme a te. I plugin.

Assistenti AI (MCP)

La stessa chiave apre un server MCP su https://www.fattorino.it/mcp: un assistente vede solo gli strumenti che può usare, e per scrivere serve una delega che dice cosa, dove, fino a quando e fino a quanto. Ogni chiamata resta nel registro che vedi in Integrazioni. Gli strumenti:

copertura — Copriamo questa zona?
preventivo — Quanto costa
sedi — Le nostre sedi
rubrica — Cerca un destinatario abituale
commesse_aggiornate — Cosa si è mosso
commessa — A che punto è una commessa
attivazione — A che punto è la nostra attivazione
report — Come sta andando: consegne e costi
scadenze_documenti — Documenti e scadenze
ticket — I nostri ticket
crea_commessa — Crea una consegna (scrive: serve una delega)
merce_pronta — La merce è pronta (scrive: serve una delega)

A un assistente dai una chiave da assistente (si sceglie quando la crei): dall'API legge e basta — a ogni scrittura risponde chiave_assistente — e quando il titolare spegne gli assistenti si ferma anche nelle letture, con assistenti_sospesi. Una chiave d'integrazione dall'API scrive senza delega: non darla a un assistente.

L'ambiente di prova

Per sviluppare senza toccare niente di vero: apri il gestionale, e chiedi all'assistenza di segnare l'organizzazione come di prova. Ti carichiamo sedi, rubrica e consegne d'esempio in tutti gli stati; API, webhook e MCP funzionano come in produzione, ma le email ai destinatari non partono (restano registrate, così vedi che sarebbero partite) e un'organizzazione di prova non entra nelle statistiche di nessuno.

Supporto

Dal gestionale, bottone Aiuto: scrivi a Fattorino.it e la risposta la trovi lì, con la tua organizzazione già attaccata. In Integrazioni vedi le chiavi, gli avvisi partiti con il loro esito e le chiamate degli assistenti: è la prima cosa da guardare quando «non arriva niente». Per tutto il resto: info@fattorino.it.

Apri il gestionale Plugin