# Facturation électronique : intégration

Lire les formats et les retours du canal de facturation électronique.

## Prérequis

L'organisation doit disposer du paramétrage métier et de l'adaptateur prévu pour ce canal. La présence d'une facture dans le CRM ne signifie pas qu'elle a été transmise à un opérateur externe.

## Document et cycle de vie

Le parcours produit peut générer un document Factur-X et suivre les statuts de transmission. Consultez les opérations et les schémas de votre instance pour les routes disponibles et les valeurs de statut admises. Les identifiants externes du prestataire doivent rester associés à la facture concernée.

## Retours depuis un tiers

Lorsqu'une plateforme ne dispose pas d'un adaptateur direct, un système tiers peut fermer la boucle via les opérations exposées. Validez l'authentification, l'identifiant de facture et le statut source avant de pousser un retour.

Un statut de dépôt, de réception ou de traitement n'est pas un paiement. Conservez la distinction dans votre mapping et dans les écrans que vous développez.

## Tester le raccordement

1. Utilisez l'environnement de test approprié et une facture de recette.
2. Vérifiez le document et les identifiants de l'émetteur et du destinataire.
3. Suivez l'envoi, puis le retour positif ou négatif du prestataire.
4. Vérifiez la lisibilité de l'erreur et la procédure de reprise.
5. Contrôlez qu'un retour rejoué ne crée pas une seconde opération.

Les exigences réglementaires et les engagements de l'opérateur ne sont pas définis par ce guide technique. Pour diagnostiquer un incident, conservez l'identifiant Cercla, l'identifiant externe, les dates et le code d'erreur en évitant d'exposer des données de facture inutiles.

## Routes du canal

Les chemins ci-dessous sont relatifs à `/api/v1`.

| Route | Scope d'app | Usage |
|---|---|---|
| GET /invoices/{id}/facturx | invoices:read | Télécharger le document archivé et son empreinte X-Cercla-Sha256 |
| GET /invoices/{id}/einvoicing | invoices:read | Lire les transmissions et leurs événements |
| POST /invoices/{id}/einvoicing/transmissions | invoices:write | Enregistrer le dépôt chez le prestataire |
| POST /invoices/{id}/einvoicing/events | invoices:write | Ajouter un retour de cycle de vie |

La création d'une transmission porte notamment `providerRef`, et éventuellement `provider`, `depositedAt` et `documentSha256`. Si vous fournissez l'empreinte, elle doit correspondre au document archivé par Cercla.

Un événement porte `code`, éventuellement `occurredAt`, `reason` et `transmissionId`. Les valeurs admises sont décrites dans [le contrat des factures](/documentation/reference-api-invoices/). Les répétitions connues sont dédupliquées selon le contrat. Aucun retour de transmission ne remplace à lui seul le geste de règlement de la facture.

Un brouillon ou une facture sans les identifiants métier requis peut répondre `409` avec un motif d'inéligibilité. Un module indisponible et un document momentanément non généré ne sont pas le même incident : examinez le type d'erreur.