Document lifecycle

A document has one tax status (status), driven by the SRI, and two delivery statuses, ride.status and email.status. A RIDE or an email that fails never changes whether the SRI authorized the document.

Tax status

processing ──► pending_sri ──► authorized
     │              │      └──► rejected
     └──────────────┴─────────► failed

Status	Final	Meaning
processing	No	Flashpi accepted the request: the document is numbered, its XML is built and checked against the SRI schema. It is being signed and submitted.
pending_sri	No	The SRI has the document, or must get it again, and Flashpi is waiting for its decision. While the SRI is slow or unreachable, Flashpi keeps retrying on its own.
authorized	Yes	The SRI authorized it. authorization.number (the access key) and authorization.authorizedAt are set. It is valid for tax purposes (in the live environment).
rejected	Yes	The SRI refused it. sriMessages lists why.
failed	Yes	Flashpi could not get an answer from the SRI for it. failure.code says why.
voided	Yes	Reserved for voided documents. Voiding is planned; no document reaches this status today.

Caution

Never send a document again because it is still processing or pending_sri: it already has its number and access key, and the SRI may already hold it. Flashpi retries for you, and a duplicate request would issue a second document. Use an Idempotency-Key so retrying the HTTP request itself is safe.

Rejected

A rejection is final for that document: its sequential is used. Fix the cause and issue a new document (a new request, which gets a new sequential). Each entry of sriMessages has a Flashpi code, a message (English, or Spanish with Accept-Language: es) and a severity (error, or warning):

"sriMessages": [
  {
    "code": "issuer_not_authorized",
    "message": "The issuer's RUC has no approved request to issue electronic documents in this SRI environment.",
    "severity": "error"
  }
]

Flashpi never passes the SRI’s answer through as it is: it maps every SRI message to a stable code, such as calculation_mismatch, issuer_not_authorized, issuer_ruc_inactive, establishment_closed, sequential_already_registered or late_submission. An authorized document can also carry SRI warnings in sriMessages, with severity warning: in the test environment, every authorized document carries test_environment.

Failed

failure.code	Meaning
certificate_required	The issuer has no accepted signing certificate for the document’s environment.
certificate_expired, certificate_not_yet_valid	The certificate is outside its validity dates.
certificate_blocked	Its revocation status could not be verified in time, or its chain is no longer trusted. See Certificates.
certificate_revoked	Its certification authority revoked it.
certificate_unusable, signing_failed, document_invalid	The signature could not be produced. Flashpi is alerted.
document_too_large	The signed document exceeds the SRI’s limit of 320 KB.
sri_unavailable	The SRI could not be reached during the whole submission window.
sri_authorization_timeout	The SRI gave no authorization or rejection within the waiting window.
sri_request_refused, sri_environment_mismatch	The SRI refused Flashpi’s request, or answered from the other environment. Flashpi is alerted.

The submission window and the waiting window are 72 hours each today, counted from the document’s creation and from its submission. A failed document’s sequential is used too: issue a new document once the cause is fixed. A failed document raises no webhook event yet, so also watch for it with GET /v1/documents?status=failed.

How to follow a document

• Webhooks (recommended): invoice.authorized, invoice.rejected, and the same for every type. See Webhooks.
• The sync mode: wait for the answer in the issuing request itself. See Sync and async modes.
• Reading it: GET /v1/documents/{id}, or a list filtered by status. If you poll, wait a few seconds between reads and longer while it is pending_sri.
• Events: GET /v1/events?documentId=... lists what happened to a document.

RIDE status

Once a document is authorized, Flashpi renders its RIDE (the printable PDF). See RIDE and email.

ride.status	Meaning
pending	Not rendered yet. Every document starts here; only authorized documents get a RIDE.
generated	Ready: GET /v1/documents/{id}/pdf returns it. ride.template and ride.generatedAt are set. Event document.ride.generated.
failed	It could not be rendered after a few attempts. Event document.ride.failed. Emailing the document again renders it again.

Email status

email.requested says whether the email was asked for (options.sendEmail, or the issuer’s default). email.status is the status of the latest delivery, and email.deliveries[] has one entry per email sent, with its recipient, status, sentAt, lastEventAt and error. email.warnings[] lists what looks wrong in the address, such as a recipient_domain_typo (see address checks).

email.status	Meaning
not_requested	The request or the issuer opted out.
skipped	There is no address to send it to (the request had no email).
queued	It goes out once the document is authorized and its RIDE is ready. A rejected or failed document keeps queued, since it is never emailed.
sent	The email provider accepted it. Event document.email.sent.
delivered	The recipient’s mail server accepted it. Event document.email.delivered.
bounced	It bounced (error says bounce_permanent, bounce_transient, bounce_undetermined or bounce_suppressed, an address the email provider no longer sends to after an earlier bounce or complaint). Event document.email.bounced.
complained	The recipient marked it as spam. Event document.email.complained.
failed	It could not be sent, for example when the recipient’s domain receives no mail (invalid_domain), the account’s or the platform’s daily email limit was reached (account_email_limit_reached, platform_email_limit_reached), the account’s emails are paused (email_sending_paused) or a test document goes to someone who is not a verified team member (test_recipient_not_allowed). Event document.email.failed.