ASP and FTA lifecycle

What happens between 'submit' and 'accepted', and how it shows in the API.

View as Markdown Open in Claude Open in ChatGPT

The UAE model has five corners: the seller (C1), the seller's accredited service provider (C2), the buyer's ASP (C3), the buyer (C4) and the FTA (C5). Alya Books is the seller's software; Taxilla is the ASP it submits through.

Diagram

sequenceDiagram
  participant App as Your system
  participant F as Alya Books API
  participant ASP as Taxilla (C2)
  participant B as Buyer ASP (C3)
  participant FTA as FTA (C5)
  App->>F: POST /invoices { submit: true }
  F->>F: validate PINT AE, allocate number, build UBL
  F->>ASP: submit XML
  ASP-->>F: requestId (status processing)
  Note over F: invoice.status = submitted (locked)
  ASP->>B: deliver document
  ASP->>FTA: report tax data
  F->>ASP: poll status (app, scheduler)
  ASP-->>F: delivered / accepted / rejected + stage
  Note over F: invoice.status = delivered → accepted | rejected
  F-->>App: webhook invoice.delivered / invoice.reported / invoice.rejected

Statuses

`invoiceStatus`	Meaning	Locked
`draft`	Stored, not validated or failed validation	no
`validated`	Passed PINT AE; can be submitted	no
`submitted`	Accepted by the ASP for processing	yes
`delivered`	The buyer's access point accepted the document	yes
`accepted`	The FTA accepted the tax data ("reported")	yes
`rejected`	Rejected by the ASP (`stage: taxilla`), the buyer access point (`buyer`) or the FTA (`fta`)	no; fix and resubmit, or credit

GET /invoices/{id}/status returns authority[], newest first:

{
  "type": "fta", "provider": "taxilla", "mode": "live",
  "status": "rejected", "stage": "fta", "documentKind": "invoice",
  "referenceNumber": "INV-0042", "requestId": "TX-…",
  "submittedAt": "2026-09-23T10:00:05Z", "completedAt": "2026-09-23T10:00:41Z",
  "error": "Buyer TRN not registered"
}

jobStatus summarises it: ready (validated), processing (submitted/delivered), done (accepted), failed (rejected); it is omitted for drafts.

Modes

The organization's e-invoicing connection has three modes (Settings → E-invoicing):

Mode	Behaviour
`mock` (Test, simulated)	No network; a simulated ASP answers with configurable scenarios (accept, reject at each stage, slow). Test documents can only be submitted here.
`uat`	Taxilla's acceptance environment with your UAT credentials.
`live`	Production. Test documents (`isTest: true`) are refused.

GET /me reports the current mode under einvoicing.mode.

Resubmission and correction

A rejected invoice can be edited (it is unlocked) and submitted again; the number stays the same and the new attempt appears as another authority[] entry.
An accepted invoice cannot change. Issue a credit note (381) to cancel or reduce it, or a debit note (383) to increase it, both with precedingInvoice: { id }. Credit notes are checked against the original (currency, remaining creditable amount).
Payments, categories, archiving and custom fields are not part of the reported document and remain editable.

Timing

Submission returns after the ASP acknowledged the request and one status poll (about two seconds in UAT and live). Later stages arrive through the status checks the app and the scheduler run (every 5 minutes, less often as a submission ages, stopping after 7 days), and reach you through webhooks: invoice.submitted, invoice.delivered, invoice.reported, invoice.rejected.