Skip to main content

Soumettre et consulter des factures

TEIF (Tunisian Electronic Invoicing Format) est un standard XML, actuellement en version 1.8.8. Vous pouvez soumettre du JSON structuré (converti en TEIF XML par Fatoora) ou directement un document TEIF XML.

Soumettre une facture​

POST /api/v2/invoices/submit — JSON TEIF​

Nécessite le scope invoice:write.

Réponse — 201 Created — l'objet facture complet, avec status: "VALIDATED" immédiatement : la soumission exécute une validation TEIF synchrone, prête pour la signature.

POST /api/v2/invoices/submit-xml — TEIF XML brut​

Même authentification et même forme de réponse, avec Content-Type: application/xml et le document TEIF brut en corps de requête.

POST /api/v2/teif/validate — validation seule​

Corps { "xml": "<TEIF>...</TEIF>" } → exécute la validation XSD contre le schéma TEIF 1.8.8 sans créer de facture. Utile en pré-vol. Réponse : { "valid": true, "issues": [] }, ou une liste issues[] détaillée en cas d'échec.

Lister et récupérer des factures​

Toutes ces routes nécessitent invoice:read.

MéthodeCheminNotes
GET/api/v2/invoicesListe paginée, filtrable (direction, status, dates)
GET/api/v2/invoices/:idDétail complet — réponse enveloppée (voir ci-dessous)
GET/api/v2/invoices/:id/pdfPDF de la facture, quel que soit son statut (brouillon inclus)
GET/api/v2/invoices/:id/generated-xmlXML TEIF généré — voir avertissement ci-dessous
GET/api/v2/invoices/statsStatistiques agrégées du tableau de bord
GET/api/v2/invoices/api-key-statsStatistiques d'utilisation détaillées par clé API

Le détail d'une facture (GET /invoices/:id) enveloppe l'objet facture :

{
  "invoice": { "id": "...", "status": "ACCEPTED_TTN", "...": "..." },
  "teifJson": "...",
  "teifXml": "<TEIF ...>...</TEIF>",
  "ttnQrCodeBase64": null,
  "localSignedXml": null,
  "validationErrors": null,
  "ttnAcknowledgments": null
}

teifJson et teifXml sont déjà disponibles ici, sans appel séparé à generated-xml.

Télécharger le PDF​

curl -X GET "https://<base_url>/api/v2/invoices/INVOICE_ID/pdf" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -o facture.pdf

Fonctionne quel que soit le statut de la facture (brouillon inclus) — pas besoin d'attendre la signature.

generated-xml ne renvoie pas toujours le document signé

Au-delà du statut SIGNED, GET /invoices/:id/generated-xml régénère un XML non signé à la volée (il perd la signature et le QR code TTN). Pour l'artefact final réellement signé et horodaté par TTN, lisez plutôt le champ teifXml ci-dessus, renvoyé par GET /invoices/:id — c'est le seul qui reflète l'état persisté réel de la facture.

Étape suivante​

Passez à Signature et suivi TTN pour signer et envoyer votre facture, ou pour recevoir des webhooks à chaque changement de statut.