Intégrations
Webhooks, limites de débit, idempotence et erreurs structurées pour les intégrations serveur à serveur.
Vue d'ensemble
Utilisez ce guide pour connecter des systèmes externes à Numezis via des webhooks, des traitements par lot ou votre propre middleware. Les applications navigateur commencent par l'Authentification ; les clients machine combinent l'authentification, la Référence API et les règles ci-dessous.
Webhooks
Les webhooks de canaux entrants (par exemple Telegram ou WhatsApp) sont enregistrés sur l'API et validés avec les signatures du fournisseur. Les notifications sortantes vers vos systèmes doivent être traitées comme at-least-once : implémentez des gestionnaires idempotents avec clé sur l'ID d'événement.
Flux typique :
- Enregistrez l'URL de l'endpoint et le secret dans les paramètres entreprise ou locataire.
- Recevez des charges utiles JSON avec type d'événement, périmètre locataire/entreprise et IDs d'entités.
- Vérifiez la signature ou le secret partagé avant traitement.
- Répondez rapidement par
2xx; reportez le travail lourd vers votre propre file.
Limites de débit
Les API publiques et de portail appliquent des limites de débit par locataire.
Les réponses incluent les en-têtes standard de rate-limit le cas échéant. Les
intégrations doivent utiliser un backoff exponentiel sur 429 et éviter les
boucles de polling serrées — privilégiez les webhooks ou les endpoints de
synchronisation documentés.
Idempotence
Pour les opérations POST qui créent des enregistrements métier (factures,
factures fournisseurs, paiements), envoyez un en-tête Idempotency-Key stable
lorsque votre bibliothèque cliente le permet. Répéter la même clé avec le même
corps renvoie le résultat original au lieu d'un document en double.
Erreurs structurées
Les erreurs de l'API utilisent une enveloppe JSON cohérente : code lisible par
la machine, message localisé pour l'affichage et details optionnels pour les
champs de validation. Mappez les codes dans votre couche d'intégration ;
n'analysez pas le texte du message en anglais.
| HTTP | Code typique | Action |
|---|---|---|
| 401 | UNAUTHORIZED | Rafraîchir la session ou se réauthentifier |
| 403 | FORBIDDEN | Vérifier l'en-tête de portail et les permissions |
| 422 | VALIDATION_ERROR | Corriger la charge utile ; lire details |
| 429 | RATE_LIMITED | Appliquer un backoff et réessayer |