Skip to content
FlashpiFlashpiFlashpi Docs

Issuing documents

Flashpi issues the six base document types of the SRI, each in the latest XML version the SRI accepts. Flashpi picks the version; a request never names one.

Document Endpoint Events XML
Invoice (factura) POST /v1/invoices invoice.* 2.1.0
Credit note (nota de crédito) POST /v1/credit-notes credit_note.* 1.1.0
Debit note (nota de débito) POST /v1/debit-notes debit_note.* 1.0.0
Withholding receipt (comprobante de retención) POST /v1/withholdings withholding.* 2.0.0
Waybill (guía de remisión) POST /v1/waybills waybill.* 1.1.0
Purchase settlement (liquidación de compra) POST /v1/purchase-settlements purchase_settlement.* 1.1.0

Issuing needs a read_write key; an issuer-scoped key only issues for its issuer. Test keys issue in the SRI test environment and live keys in production.

Fields every request shares

Section titled “Fields every request shares”
Field Required Notes
issuerId Yes The issuer (taxpayer) that issues the document, or the shared demo issuer.
establishment, emissionPoint Yes Three-digit codes registered on the issuer ("001"). The document is numbered in that series.
issueDate No YYYY-MM-DD. Defaults to today in Ecuador; a later date is refused (future_date).
sequential No Choose the number yourself (1 to 999,999,999), for example when migrating. Otherwise Flashpi assigns the next one. See Sequentials.
additionalInfo No Additional fields printed on the document, name to value (1 to 300 characters each). At most 15 per document, counting the legends Flashpi adds (RUC Proveedor, and Gran Contribuyente for large taxpayers), so 13 or 14 of yours.
options.sendEmail No Email the authorized document to the buyer. Defaults to the issuer’s sendEmailByDefault. See RIDE and email.
options.waitForAuthorization, options.waitTimeoutSeconds No Sync mode: wait for the SRI’s answer, 15 seconds by default and 30 at most. See Sync and async modes.
expectedTotal No The total you expect (every type but waybills). See Totals.

Send an Idempotency-Key header with every issuing request, so a retried request never issues twice. See Idempotency.

Plain JSON, no SRI tags

Section titled “Plain JSON, no SRI tags”

Field names are English and values are readable words, never SRI codes: Flashpi maps them to the SRI’s tags and catalogs.

  • Identification (idType): ruc (13 digits ending in 001, format only), cedula (10 digits, check digit verified), passport, foreign_id (issued by another country’s tax authority) or final_consumer (invoices only; no number or name needed).
  • Taxes of a line: exactly one VAT, { "type": "vat", "rate": "15" }. VAT rates are 0, 5, 8, 12, 13, 14, 15, exempt and not_subject; use the one in force on the issue date. Invoices and credit notes also accept one ad valorem ICE: { "type": "ice", "code": "3031", "rate": "75" }.
  • Payments: { "method": "credit_card", "amount": "10.35" }, with method one of cash, debt_offset, debit_card, electronic_money, prepaid_card, credit_card, other_financial_system (bank transfers, checks and other payments through the financial system) or securities_endorsement. An optional term with termUnit (days or months) gives the payment term.

Decimal strings

Section titled “Decimal strings”

Money, quantities and rates are decimal strings with a dot: "4.50", "2.5", "15". A JSON number such as 4.5 is refused, because binary floating point cannot hold every amount exactly.

Value Decimals
Amounts: payments, discounts, tips, expectedTotal, debit note reasons Up to 2
quantity and unitPrice Up to 6
Withholding percentages Up to 2

Up to 12 digits before the dot. Extra trailing zeros are fine ("4.500").

Totals

Section titled “Totals”

You send quantities, prices, discounts and tax rates. Flashpi computes everything else with the SRI’s rounding rules (half up):

  • Each line’s subtotal: quantity × unit price − discount, rounded to 2 decimals.
  • The taxes, grouped by tax and rate, on the summed base of their lines (ICE is part of the VAT base).
  • The document’s subtotal, discount, tip and total. Withholding receipts compute each withheld amount and the total withheld.

The computed values come back in totals, as strings. Payments must add up to the total (amount_mismatch otherwise). Send expectedTotal with the total your own system computed: when it differs, Flashpi refuses the request with 422 total_mismatch and both values, and issues nothing.

{
  "type": "https://flashpi.com.ec/docs/en/errors/total_mismatch",
  "title": "Total mismatch",
  "status": 422,
  "detail": "The total Flashpi computed (68.94) does not match expectedTotal (68.95).",
  "instance": "/v1/invoices",
  "code": "total_mismatch",
  "errors": [],
  "requestId": "01a1412b-a9f1-7d20-8c3e-5b7a19d04e62",
  "expectedTotal": "68.95",
  "computedTotal": "68.94"
}

Validation

Section titled “Validation”

Flashpi validates the whole request before it numbers anything, and answers 422 validation_failed with every field error at once, each with its field path (items[0].taxes[0].rate), code and message:

  • Required fields, formats, lengths and unknown fields (unknown_field).
  • Identification numbers: the cédula check digit (invalid_check_digit) and the RUC format (invalid_identification); a final consumer where the type does not allow one (final_consumer_not_allowed).
  • Catalog values Flashpi knows were not in force on the issue date (not_in_force).
  • Text the SRI cannot carry: line breaks, control characters and characters outside the Basic Multilingual Plane, such as emoji (unsupported_character, naming the character). Flashpi never strips them silently.
  • Payments that do not add up (amount_mismatch), dates in the wrong order, discounts larger than the line (discount_exceeds_amount), too many additional fields.

Then the XML is built and checked against the official SRI schema before it is signed. A failure there means a validation gap in Flashpi: 422 document_schema_invalid, and nothing is issued; write to support with the requestId. A document too large for the SRI once signed (over 304 KiB unsigned) gets 422 document_too_large.

The answer

Section titled “The answer”

A valid request is numbered, stored and answered at once with 202 Accepted, the document in status processing and a Location header (/v1/documents/{id}). Flashpi then signs it, submits it to the SRI and follows its authorization. Follow it with webhooks or GET /v1/documents/{id}, or wait in the same request with the sync mode.

The document object

Section titled “The document object”

Every issuing endpoint, GET /v1/documents/{id}, the document list and the document events return the same object:

Field Description
id The document’s ID (UUIDv7).
type invoice, credit_note, debit_note, withholding, waybill or purchase_settlement.
environment test or live, from the key that issued it.
status The tax status: processing, pending_sri, authorized, rejected, failed or voided. See Document lifecycle.
issuerId, establishment, emissionPoint, sequential, number Who issued it and its number (001-001-000000123).
accessKey The 49-digit access key (clave de acceso), also the authorization number.
issueDate, xmlVersion The issue date and the SRI XML version.
counterparty id and name of the buyer, supplier, withheld subject or carrier.
totals What Flashpi computed: subtotal, discount, taxes[], tip, total, or withheld, depending on the type. null for waybills.
authorization number and authorizedAt, once the SRI authorizes it.
ride The RIDE (PDF): status, template, generatedAt.
email The email to the buyer: requested, status and deliveries[].
sriMessages The SRI’s messages, mapped to Flashpi codes: the reasons of a rejection, or warnings of an authorization.
failure code and message when the status is failed.
voidedAt, createdAt, updatedAt Timestamps (ISO 8601, UTC).

Messages in sriMessages and failure follow Accept-Language: English by default, Spanish with Accept-Language: es.

Reading documents

Section titled “Reading documents”
Operation Endpoint
List, newest first, with filters issuerId, type, status, issueDateFrom, issueDateTo, counterpartyId and accessKey GET /v1/documents
Read one GET /v1/documents/{id}
Its XML GET /v1/documents/{id}/xml
Its RIDE (PDF) GET /v1/documents/{id}/pdf
Email it again POST /v1/documents/{id}/email
Terminal window
curl "https://api.flashpi.com.ec/v1/documents?type=invoice&status=authorized&issueDateFrom=2026-10-01&limit=50" \
  -H "Authorization: Bearer $FLASHPI_API_KEY"
  • Any key reads, read_only included. Test keys read test documents and live keys live ones; an issuer-scoped key only reads its issuer’s documents.
  • GET .../xml returns the most advanced XML available and names it in the Flashpi-Xml-Kind header: authorized (the signed document as the SRI returned it in its authorization), signed or unsigned.
  • GET .../pdf returns the RIDE as a PDF/A-2b file once it is generated, and 409 ride_not_available before.
  • Lists use cursor pagination; see Pagination.