Submitting and retrieving invoices

TEIF (Tunisian Electronic Invoicing Format) is an XML-based standard, currently at version 1.8.8. You can submit structured JSON (converted to TEIF XML by Fatoora) or a pre-built TEIF XML document directly.

Submitting an invoice

POST /api/core-proxy/invoices/submit — JSON TEIF

Requires scope invoice:write and an org-scoped token.

Authorization: Bearer <org-scoped token>
Content-Type: application/json
X-Allow-Partner-Upsert: true      # optional, see below

Response — 201 Created — the full invoice object (same shape as list/detail), with status: "VALIDATED" immediately: submission runs synchronous TEIF validation, so a successful 201 already reflects a validated invoice, ready for signing.

X-Allow-Partner-Upsert header

If the TEIF document references a business partner (buyer/seller) that doesn't yet exist in the client organization's partner registry, submission fails unless this header is true and the TEIF block includes a full address — Fatoora then auto-creates the missing partner record.

POST /api/core-proxy/invoices/submit-xml — raw TEIF XML

Same auth, same response shape as above, with Content-Type: application/xml and the raw TEIF document as the body.

POST /api/core-proxy/teif/validate — validate only

Body { "xml": "<TEIF>...</TEIF>" } → runs XSD validation against the TEIF 1.8.8 schema without creating an invoice. Useful for pre-flight checks. Response: { "valid": true, "issues": [] }, or a detailed issues[] list on failure.

Listing and retrieving invoices

All require invoice:read and an org-scoped token.

Method	Path	Notes
GET	/api/core-proxy/invoices	Paginated list, filterable (direction, status, dates, tax IDs)
GET	/api/core-proxy/invoices/:id	Full detail — wrapped response (see below)
GET	/api/core-proxy/invoices/:id/generated-xml	Generated TEIF XML
GET	/api/core-proxy/invoices/:id/pdf	Invoice PDF
GET	/api/core-proxy/invoices/stats	Aggregate stats

/invoices/:id/status unavailable

This endpoint consistently returns a 500 error. Use GET /api/core-proxy/invoices/:id and read invoice.status instead.

Invoice detail (GET /invoices/:id) wraps the invoice object:

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

teifJson and teifXml are already available here, without a separate call to generated-xml.

Quotations

The same core-proxy surface supports draft quotations, convertible into an invoice later — useful for a "pending approval" stage before invoicing:

Method	Path	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

Converting to an invoice creates a new invoice object (a new id), with isQuotation: false and status: "DRAFT".

Next step: Signing and TTN filing.