Specifica di integrazione API
Integrazione: Ordini del negozio online alla contabilità
Versione: 1.0
Redatta da: Hamza Idrissi
Data: 5 aprile 2029
1. Scopo
Inviare ogni ordine pagato del negozio online al sistema di contabilità come fattura di vendita, così che l'ufficio finanziario non debba reinserirlo.
2. Sistemi
- Invia dati: Negozio online (API v2)
- Riceve dati: Sistema di contabilità (API REST)
3. Flusso dei dati
1. Un cliente paga un ordine.
2. Il negozio invia un webhook al servizio di integrazione.
3. Il servizio trasforma l'ordine in una fattura e chiama l'API di contabilità.
4. Il sistema di contabilità restituisce un numero di fattura, che il servizio salva sull'ordine.
4. Endpoint e messaggi
| Metodo e percorso | Cosa fa | Campi principali | Cosa restituisce |
|---|---|---|---|
| POST /invoices | Crea una fattura | Corpo: cliente, righe, imposta, totale | Restituisce: id e numero fattura |
| GET /customers?email= | Trova un cliente | Restituisce: id cliente o vuoto | |
| POST /customers | Crea un cliente | Corpo: nome, email, indirizzo |
5. Mappatura dei campi
order.total_paid → invoice.total
order.billing_email → customer.email
order.items[].sku → line.product_code
6. Autenticazione e sicurezza
OAuth 2.0 client credentials. I token durano un'ora. I segreti sono conservati nel vault, mai nel codice. Tutte le chiamate usano HTTPS. I webhook sono firmati e la firma viene verificata.
I dati personali vengono inviati solo quando necessario, non vengono scritti nei log e sono coperti dalle condizioni sulla privacy di entrambi i sistemi.
7. Errori e nuovi tentativi
Riprova su 429 e 5xx fino a 5 volte con ritardi crescenti. Non riprovare gli errori 4xx: registrali e avvisa l'ufficio finanziario. Ogni fattura ha una chiave unica, così un nuovo tentativo non può creare un duplicato.
8. Limiti e volumi
L'API di contabilità consente 60 chiamate al minuto. Previsione: 400 ordini al giorno, fino a 2.000 nei giorni di saldi.
9. Test
Usa la sandbox di contabilità. Prova un ordine normale, un ordine con sconto, un rimborso, un cliente già esistente e un'interruzione dell'API.
10. Responsabili e supporto
Responsabile: team E-commerce. Supporto: Hamza Idrissi. Escalation: help desk del fornitore di contabilità.
11. Modifiche e versionamento
Ciascuna parte dà 30 giorni di preavviso per una modifica incompatibile.