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/core-proxy/invoices/submit — JSON TEIF

Nécessite le scope invoice:write et un token org-scoped.

Authorization: Bearer <token org-scoped>
Content-Type: application/json
X-Allow-Partner-Upsert: true      # optionnel, voir ci-dessous

Réponse — 201 Created — l'objet facture complet (même forme que le listing/détail), avec status: "VALIDATED" immédiatement : la soumission exécute une validation TEIF synchrone, une réponse 201 reflète donc déjà une facture validée, prête pour la signature.

En-tête X-Allow-Partner-Upsert

Si le document TEIF référence un partenaire commercial (acheteur/vendeur) qui n'existe pas encore dans le registre de l'organisation cliente, la soumission échoue sauf si cet en-tête est à true et que le bloc TEIF contient une adresse complète — Fatoora crée alors automatiquement la fiche partenaire manquante.

POST /api/core-proxy/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/core-proxy/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 et un token org-scoped.

Méthode	Chemin	Notes
GET	/api/core-proxy/invoices	Liste paginée, filtrable (direction, status, dates, matricules)
GET	/api/core-proxy/invoices/:id	Détail complet — réponse enveloppée (voir ci-dessous)
GET	/api/core-proxy/invoices/:id/generated-xml	XML TEIF généré
GET	/api/core-proxy/invoices/:id/pdf	PDF de la facture
GET	/api/core-proxy/invoices/stats	Statistiques agrégées

/invoices/:id/status indisponible

Cet endpoint renvoie systématiquement une erreur 500. Utilisez GET /api/core-proxy/invoices/:id et lisez invoice.status à la place.

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

{
  "invoice": { "id": "...", "status": "...", "...": "..." },
  "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.

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.

Devis (quotations)

La même surface d'API prend en charge des devis brouillons, convertibles ensuite en facture — utile pour un flux « en attente d'approbation » avant facturation :

Méthode	Chemin	Scope
POST	/api/core-proxy/quotations/draft	invoice:write
GET	/api/core-proxy/quotations / /:id	invoice:read
PATCH	/api/core-proxy/quotations/:id/status	invoice:write
POST	/api/core-proxy/quotations/:id/convert-to-invoice	invoice:write

La conversion en facture crée un nouvel objet facture (nouvel id), avec isQuotation: false et status: "DRAFT".

Étape suivante : Signature et suivi TTN.