Raccordement API à une Plateforme Agréée : guide technique pour développeurs

Vous êtes développeur et devez intégrer un logiciel métier à une Plateforme Agréée via API ? Voici un guide pratique des patterns d'intégration observés sur les PA majeures (Pennylane, Esker, Generix, Yooz, Tradeshift).

Architecture cible

Schéma général

Logiciel métier ── REST/GraphQL ──> API PA ── Annuaire PPF ──> PA destinataire
        ↑                              │
        └─ Webhooks ─── statuts ◄──────┘

Trois rôles côté votre logiciel

1. Émetteur : pousser des factures structurées
2. Récepteur : recevoir des factures fournisseurs
3. Reporting : suivre les statuts (envoyée, livrée, refusée, etc.)

Authentification

OAuth2 client_credentials (standard)

La plupart des PA modernes exposent un endpoint /oauth/token avec client_id / client_secret :

curl -X POST https://api.pa.fr/oauth/token \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_ID" \
  -d "client_secret=YOUR_SECRET" \
  -d "scope=invoice:write invoice:read"

Retour :

{
  "access_token": "eyJhbGc...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Stocker le token en cache jusqu'à expiration, renouveler avant.

mTLS pour les ETI / grandes PA

Les PA mid-market (Esker, Generix, Sovos) exigent souvent un certificat client X.509 pour mTLS. Le secret n'est plus dans la requête, mais dans la handshake TLS.

Signature des payloads (cas avancé)

Certaines PA exigent une signature HMAC-SHA256 des payloads en plus du token, pour garantir l'intégrité de la facture.

Endpoint principal : émission de facture

POST /invoices

curl -X POST https://api.pa.fr/v1/invoices \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/xml" \
  -d @invoice.xml

Format Factur-X (PDF/A-3 + XML)

Pour le marché français, Factur-X est le format dominant. C'est un PDF/A-3 incluant un XML CII embarqué.

<rsm:CrossIndustryInvoice
  xmlns:rsm="urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100"
  xmlns:ram="urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100">
  <rsm:ExchangedDocument>
    <ram:ID>INV-2026-0042</ram:ID>
    <ram:TypeCode>380</ram:TypeCode>
    <ram:IssueDateTime>
      <udt:DateTimeString format="102">20260601</udt:DateTimeString>
    </ram:IssueDateTime>
  </rsm:ExchangedDocument>
  ...
</rsm:CrossIndustryInvoice>

Format UBL 2.1

Alternative, surtout pour les flux internationaux (PEPPOL).

Réponse synchrone

{
  "invoice_id": "pa-9f2b...",
  "status": "received",
  "client_message_id": "INV-2026-0042",
  "submitted_at": "2026-06-01T10:00:00Z"
}

ATTENTION : "received" par la PA ≠ "delivered" au destinataire. Suivre les statuts ultérieurs.

Suivi des statuts

Cycle de vie d'une facture (français)

Le ministère a défini 14 statuts au cycle de vie d'une facture. Les principaux :

1. emitted — facture émise par votre PA
2. submitted — soumise à l'annuaire
3. received_by_recipient_pa — PA destinataire l'a reçue
4. delivered — déposée au logiciel destinataire
5. approved — validée par le client
6. payment_pending — en attente de paiement
7. paid — payée
8. rejected — refusée (motif obligatoire)
9. disputed — contestée

(Voir notre article cycle de vie facture).

Récupérer les statuts

Méthode 1 — Webhooks (recommandée)

Configurer une URL webhook côté PA, qui appelle votre logiciel à chaque changement de statut :

POST https://yourapp.com/webhooks/pa
{
  "event": "invoice.status_changed",
  "invoice_id": "pa-9f2b...",
  "new_status": "delivered",
  "occurred_at": "2026-06-01T10:05:00Z"
}

Méthode 2 — Polling

Pour les PA qui ne proposent pas (encore) de webhooks, polling régulier :

GET https://api.pa.fr/v1/invoices/pa-9f2b.../status

Limiter à toutes les 5-15 minutes pour ne pas saturer.

Réception des factures fournisseurs

Endpoint /invoices?direction=inbound

GET https://api.pa.fr/v1/invoices?direction=inbound&since=2026-06-01T00:00:00Z

Recommandation : webhooks de réception

Beaucoup plus fiable que le polling :

POST https://yourapp.com/webhooks/pa
{
  "event": "invoice.received",
  "invoice_id": "pa-1f7c...",
  "supplier_siren": "552120222",
  "amount_total": 1200.00,
  "currency": "EUR",
  "format": "factur-x",
  "download_url": "https://api.pa.fr/v1/invoices/pa-1f7c.../download"
}

Téléchargement et vérification

Toujours télécharger la facture, vérifier la signature Factur-X, puis enregistrer en GED ou alimenter l'ERP.

Gestion des erreurs

Codes HTTP standards

Pattern de retry

def submit_with_retry(invoice, max_attempts=5):
    for attempt in range(max_attempts):
        try:
            resp = post(invoice)
            if resp.status_code < 500:
                return resp
        except NetworkError:
            pass
        time.sleep(2 ** attempt)  # 1s, 2s, 4s, 8s, 16s
    raise Exception("Max retries reached")

Idempotence

Toujours envoyer un header Idempotency-Key unique par facture :

Idempotency-Key: INV-2026-0042-v1

Si la PA reçoit deux fois la même clé, elle ne traite qu'une fois.

Bonnes pratiques sécurité

Stockage des secrets

• Jamais en dur dans le code
• Utiliser Secrets Manager (AWS, GCP), HashiCorp Vault, ou équivalent
• Rotation automatique trimestrielle

Logs

• Ne pas logguer les tokens d'accès en clair
• Masquer les SIRENs et données fiscales si log public
• Conserver 6 ans les logs d'émission pour audit fiscal

Limites de taille

La plupart des PA limitent les payloads à 10 Mo par facture. Au-delà, splitting ou compression nécessaire.

Environnements

Sandbox

Toutes les PA proposent un environnement sandbox :

• Pas d'envoi réel à l'annuaire ou aux destinataires
• Permet de tester les statuts avec des cas factices
• Souvent un endpoint https://sandbox-api.pa.fr/v1/...

Pre-prod

Certaines PA proposent un pre-prod synchronisé avec l'annuaire test de la DGFiP, pour tests d'interop réels.

Production

Activation après validation conformité (formats, statuts, sécurité).

Checklist avant mise en prod

• OAuth2 / mTLS configurés et tests OK
• Émission Factur-X validée (XML + PDF/A-3)
• Webhooks de statut configurés et testés
• Webhooks de réception fonctionnels
• Retry et idempotence en place
• Logs et monitoring déployés
• Tests de charge sur 1 000 factures
• Rotation des secrets configurée
• Documentation interne à jour

En résumé

• OAuth2 + mTLS sont les standards d'auth
• Factur-X est le format dominant en France ; UBL pour PEPPOL
• Webhooks sont nettement préférables au polling
• 14 statuts au cycle de vie, à mapper côté logiciel
• Idempotence indispensable (header dédié)
• Sandbox systématique avant prod
• 6 ans de logs à conserver pour conformité fiscale