Intégration API publique : société, données financières et recette
Construire une intégration de factures avec contrat API vivant, clés par société, identités durables, règlements et transmission Peppol structurée.
- Mis à jour
- Responsable du contenu
- Équipe intégration
- Pour
- Ingénieurs intégration · Architectes solutions · Responsables finance techniques
L’essentiel
Vérifiez société et capacités de la clé, définissez les correspondances financières et prouvez création, reprise, livraison et rapprochement avant lancement.
Avant de commencer
- Un propriétaire de clé société autorisé
- Des données structurées et identités source stables
- Une correspondance des champs et des exemples financiers validés
Résultats attendus
- Un contrat d'intégration testé par société
- Une correspondance durable des identités source/produit
- Une recette des reprises, règlements et preuves de transmission
Sur cette page
L'API publique constitue une frontière d'intégration financière. Appuyez-vous sur son contrat vivant et préservez les identités source dès le prototype. Une réponse HTTP réussie ne suffit pas : l'intégration doit expliquer ce qu'elle a créé, pour quelle société et comment elle reprend sans doublon.
Découvrir contrat et société
Consultez GET /api/v1/openapi.json pour les routes réelles. Commencez les appels authentifiés par GET /api/v1/me et vérifiez société, espace d'intégration, opérations, moyens de paiement, devises et capacités fiscales. Conservez version du contrat et date de collecte.
Un propriétaire ou administrateur autorisé crée la clé dans Société → Clés API. Le secret est affiché une fois ; stockez-le dans votre gestionnaire de secrets approuvé. La clé est limitée à une société ; aucun en-tête ne permet de sélectionner une autre société. Les cookies de session de l'application n'authentifient pas cette API.
| Responsabilité | Propriétaire | Preuve |
|---|---|---|
| Société et permissions | Propriétaire de clé | Vérification /me expurgée |
| Données et identités | Ingénieur | Correspondance versionnée |
| Attentes financières | Contrôleur | Montants et cas fiscaux validés |
| Reprise et suivi | Exploitation intégration | Preuves de répétition et exceptions |
| Lancement | Responsable service | Décision de recette et transfert |
Limiter les permissions au besoin
Utilisez Authorization: Bearer … ou X-Api-Key. Consultez GET /api/v1/scopes. L'écriture de documents exige sa permission d'écriture ; mouvements et acomptes à la création exigent payments:write.
POST /api/v1/peppol/send crée et peut transmettre une facture : il exige invoices:write et peppol:send. La consultation exige séparément peppol:read. L'approbation d'enregistrement et le quota du plan sont distincts des permissions de clé.
Définir la correspondance financière
Pour chaque champ, notez source, champ API, type, transformation, autorité et traitement du refus. Une adresse exige rue, ville, code postal et pays. Les champs inconnus sont refusés ; n'envoyez pas l'objet source entier. Omettez number si la séquence société doit attribuer le numéro.
Utilisez des chaînes décimales pour l'argent avec la précision de devise acceptée. Fournissez devise et heure d'occurrence avec fuseau. Ne tronquez pas les valeurs, ne convertissez pas implicitement et n'inférez pas un mouvement depuis une simple étiquette « payé ».
La commande ERP order-4711 peut devenir external_id: order-4711 dans l'espace erp. L'acompte confirmé porte sa propre identité tender-4711-1. Ces valeurs restent stables après nouvelle tentative ou remplacement de clé.
Séparer création et échange
POST /api/v1/invoices crée le document. L'émission d'une facture existante passe par /peppol/invoices/{invoice_id}/send ; les notes de crédit ont leur route distincte. Devis et reçus n'ont pas de route Peppol.
La route combinée /peppol/send accepte les champs structurés et un PDF fourni facultatif. send: false crée sans transmettre : cela reste une facture réelle, pas un environnement de test.
Peppol transporte UBL. Le PDF est un complément, pas une source à extraire. Les spécifications BIS Billing publient les structures facture et note de crédit. Cette API ne propose pas de conversion OCR d'un PDF en facture.
Concevoir la reprise durable
Conservez external_id pour documents et mouvements, et Idempotency-Key pour répétitions HTTP. La protection HTTP dure 24 heures et dépend de la clé ; les identités financières durables survivent à cette durée et à la rotation.
Après réponse perdue, cherchez par identité externe ou rejouez le contenu identique. EXTERNAL_ID_REUSED signale un contenu de création ou de mouvement changé sous la même identité : examinez le contenu initial et la correction appropriée au lieu de choisir un identifiant arbitraire. Une transmission Peppol incertaine attend le rapprochement fournisseur.
Parcourez toutes les pages de liste. Branchez sur code, pas sur le texte de l'erreur. Respectez en-têtes de limitation et Retry-After pour les réponses 429.
Recetter et transférer
Testez facture, avoir, acompte, paiement partiel, remboursement réel, répétition de création/mouvement et réponse perdue. Comparez séparément montants, identités, numéro, règlement, livraison et archives.
Pour 121 € et 40 € d'acompte, les paiements valent 40 € et la dette 81 €. Après paiement de 81 €, rejouer l'acompte doit retrouver son mouvement, sans dépasser 121 € de paiements.
Choisissez volontairement les vues PDF : current est un état de règlement daté, issued/original conserve le rendu original. L'identifiant document Peppol récupère les XML/PDF échangés et diffère de l'identifiant facture ou fournisseur.
Transmettez correspondances, propriétaire de clé, registre d'identités, suivi et exemples expurgés. Aucun écart financier inexpliqué ne doit rester avant lancement. Poursuivez avec fiabilité des intégrations et rapprochement mensuel.