Integrazioni

Panoramica

Usa questa guida quando colleghi sistemi esterni a Numezis tramite webhook, job batch o middleware personalizzato. Le app browser dovrebbero partire dall'Autenticazione; i client machine combinano autenticazione, il Riferimento API e le regole seguenti.

Webhook

I webhook dei canali in entrata (per esempio Telegram o WhatsApp) sono registrati sull'API e convalidati con le firme del provider. Le notifiche in uscita verso i tuoi sistemi vanno trattate come at-least-once: implementa handler idempotenti con chiave sull'id dell'evento.

Flusso tipico:

1. Registra l'URL dell'endpoint e il segreto nelle impostazioni di azienda o tenant.
2. Ricevi payload JSON con tipo di evento, ambito tenant/azienda e id delle entità.
3. Verifica la firma o il segreto condiviso prima di elaborare.
4. Rispondi rapidamente con 2xx; rimanda il lavoro pesante alla tua coda.

Limiti di frequenza

Le API pubbliche e di portale applicano limiti di frequenza per tenant. Le risposte includono header standard di rate-limit dove applicabile. Le integrazioni dovrebbero usare backoff esponenziale su 429 ed evitare cicli di polling serrati: preferisci webhook o endpoint di sincronizzazione documentati.

Idempotenza

Per le operazioni POST che creano record aziendali (fatture, fatture passive, pagamenti), invia un header Idempotency-Key stabile quando la tua libreria client lo supporta. Ripetere la stessa chiave con lo stesso corpo restituisce il risultato originale invece di un documento duplicato.

Errori strutturati

Gli errori dell'API usano una busta JSON coerente: code leggibile dalla macchina, message localizzato per la visualizzazione e details opzionali per i campi di convalida. Mappa i codici nel tuo livello di integrazione; non analizzare il testo del messaggio in inglese.

Pagine correlate

• Autenticazione
• Riferimento API
• Strumenti MCP
• Panoramica per sviluppatori