Sync and async modes

The SRI usually authorizes a document in a few seconds, but it can take much longer, and its services are sometimes down. Flashpi never makes you hold a connection open for that: every issuing request is answered quickly, and you choose how to learn the outcome.

Asynchronous (default)

A valid request is answered at once with 202 Accepted: the document is numbered, its XML is built and checked against the SRI schema, and it is stored in status processing, with a Location header (/v1/documents/{id}). Flashpi then signs it, submits it to the SRI and polls its authorization in the background.

Learn the outcome with:

• Webhooks (recommended): invoice.authorized and invoice.rejected, and the same for every type, pushed to your endpoint as soon as the SRI decides.
• GET /v1/documents/{id}: read the document until its status is final. Wait a few seconds between reads.
• GET /v1/events: the same events the webhooks deliver, to catch up after your receiver was down.

This suits most integrations: an ERP, an e-commerce backend, any batch of documents.

Synchronous (optional)

Set options.waitForAuthorization to true to wait for the SRI’s decision in the same request:

{
  "options": { "waitForAuthorization": true, "waitTimeoutSeconds": 20 }
}

Option	Default	Notes
waitForAuthorization	false	Wait for the SRI before answering.
waitTimeoutSeconds	15	The longest wait in seconds, from 1 to 30. A longer wait is refused with 422 validation_failed and the field error out_of_range, before anything is created.

The answer depends on what happens first:

Outcome	Answer
The SRI authorizes or rejects it within the wait, or it fails	200 OK with the document authorized, rejected or failed
The wait ends first	202 Accepted with the document as it is then, usually pending_sri

In both cases the answer carries the Location header. After a 202, the document continues exactly as in the asynchronous mode: its webhooks still arrive, and GET /v1/documents/{id} shows its progress.

curl -i https://api.flashpi.com.ec/v1/invoices \
  -H "Authorization: Bearer $FLASHPI_API_KEY" \
  -H "Idempotency-Key: pos-01-ticket-55120" \
  -H "Content-Type: application/json" \
  -d @invoice-with-wait.json

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Location: /v1/documents/01a14116-1c50-73e7-8aab-349c93e541da
x-request-id: 01a14116-1c4f-7a02-9e6b-0d3c8f5a2b71

Tip

The sync mode is handy at a point of sale that prints the RIDE right away, or in a script. Even then, handle a 202 answer (the SRI can be slow) and keep the webhooks: a sync request only waits, it never changes how the document is processed.

The RIDE after a sync answer

A 200 with authorized means the SRI authorized the document; the RIDE is rendered right after, usually within a few seconds. GET /v1/documents/{id}/pdf answers 409 ride_not_available until ride.status is generated. Retry after a moment, or wait for the document.ride.generated webhook.

Retries and timeouts

• Set your HTTP client’s timeout above waitTimeoutSeconds, plus a few seconds.
• If the connection drops while you wait, send the same request again with the same Idempotency-Key: while the first request still runs you get 409 idempotency_key_in_progress (retry a little later), and afterwards the first answer again, as it was then (a replayed 202 still says pending_sri). Read GET /v1/documents/{id} for the current status. See Idempotency.