Ir al contenido
FlashpiFlashpiFlashpi Docs

Emitir comprobantes

Flashpi emite los seis tipos de comprobante base del SRI, cada uno en la versión de XML más reciente que acepta el SRI. La versión la elige Flashpi; una solicitud nunca la indica.

Comprobante Endpoint Eventos XML
Factura POST /v1/invoices invoice.* 2.1.0
Nota de crédito POST /v1/credit-notes credit_note.* 1.1.0
Nota de débito POST /v1/debit-notes debit_note.* 1.0.0
Comprobante de retención POST /v1/withholdings withholding.* 2.0.0
Guía de remisión POST /v1/waybills waybill.* 1.1.0
Liquidación de compra POST /v1/purchase-settlements purchase_settlement.* 1.1.0

Emitir requiere una llave read_write; una llave de un emisor solo emite para su emisor. Las llaves de prueba emiten en el ambiente de pruebas del SRI y las de producción en producción.

Campos que comparten todas las solicitudes

Sección titulada «Campos que comparten todas las solicitudes»
Campo Obligatorio Notas
issuerId Sí El emisor (contribuyente) que emite el comprobante, o el emisor demo compartido.
establishment, emissionPoint Sí Códigos de tres dígitos registrados en el emisor ("001"). El comprobante se numera en esa serie.
issueDate No AAAA-MM-DD. Por defecto, hoy en Ecuador; una fecha posterior se rechaza (future_date).
sequential No Elige tú el número (de 1 a 999.999.999), por ejemplo al migrar. Si no, Flashpi asigna el siguiente. Consulta Secuenciales.
additionalInfo No Campos adicionales impresos en el comprobante, nombre y valor (de 1 a 300 caracteres cada uno). Máximo 15 por comprobante, contando las leyendas que agrega Flashpi (RUC Proveedor, y Gran Contribuyente para los grandes contribuyentes), así que 13 o 14 tuyos.
options.sendEmail No Enviar por correo al comprador el comprobante autorizado. Por defecto, el sendEmailByDefault del emisor. Consulta RIDE y correo.
options.waitForAuthorization, options.waitTimeoutSeconds No Modo síncrono: esperar la respuesta del SRI, 15 segundos por defecto y 30 como máximo. Consulta Modo síncrono y asíncrono.
expectedTotal No El total que esperas (todos los tipos menos las guías de remisión). Consulta Totales.

Envía un encabezado Idempotency-Key en cada solicitud de emisión, para que una solicitud reintentada nunca emita dos veces. Consulta Idempotencia.

JSON simple, sin etiquetas del SRI

Sección titulada «JSON simple, sin etiquetas del SRI»

Los nombres de los campos están en inglés y los valores son palabras legibles, nunca códigos del SRI: Flashpi los traduce a las etiquetas y catálogos del SRI.

  • Identificación (idType): ruc (13 dígitos terminados en 001, solo formato), cedula (10 dígitos, con dígito verificador validado), passport, foreign_id (emitida por la administración tributaria de otro país) o final_consumer (solo facturas; no hace falta número ni nombre).
  • Impuestos de una línea: exactamente un IVA, { "type": "vat", "rate": "15" }. Las tarifas de IVA son 0, 5, 8, 12, 13, 14, 15, exempt y not_subject; usa la vigente en la fecha de emisión. Las facturas y las notas de crédito también aceptan un ICE ad valorem: { "type": "ice", "code": "3031", "rate": "75" }.
  • Pagos: { "method": "credit_card", "amount": "10.35" }, con method igual a cash, debt_offset, debit_card, electronic_money, prepaid_card, credit_card, other_financial_system (transferencias, cheques y otros pagos por el sistema financiero) o securities_endorsement. Un term opcional con su termUnit (days o months) indica el plazo.

Cadenas decimales

Sección titulada «Cadenas decimales»

Los montos, las cantidades y las tarifas son cadenas decimales con punto: "4.50", "2.5", "15". Un número JSON como 4.5 se rechaza, porque el punto flotante binario no puede representar exactamente todos los montos.

Valor Decimales
Montos: pagos, descuentos, propinas, expectedTotal, motivos de una nota de débito Hasta 2
quantity y unitPrice Hasta 6
Porcentajes de retención Hasta 2

Hasta 12 dígitos antes del punto. Los ceros finales de más están bien ("4.500").

Totales

Sección titulada «Totales»

Tú envías cantidades, precios, descuentos y tarifas. Flashpi calcula todo lo demás con las reglas de redondeo del SRI (mitad hacia arriba):

  • El subtotal de cada línea: cantidad × precio unitario − descuento, redondeado a 2 decimales.
  • Los impuestos, agrupados por impuesto y tarifa, sobre la base sumada de sus líneas (el ICE forma parte de la base del IVA).
  • El subtotal, el descuento, la propina y el total del comprobante. En los comprobantes de retención, cada valor retenido y el total retenido.

Los valores calculados vuelven en totals, como cadenas. Los pagos deben sumar el total (amount_mismatch si no). Envía expectedTotal con el total que calculó tu propio sistema: si es distinto, Flashpi rechaza la solicitud con 422 total_mismatch y ambos valores, y no emite nada.

{
  "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"
}

Validación

Sección titulada «Validación»

Flashpi valida toda la solicitud antes de numerar nada, y responde 422 validation_failed con todos los errores de campo a la vez, cada uno con la ruta del campo (field, por ejemplo items[0].taxes[0].rate), su code y su message:

  • Campos obligatorios, formatos, longitudes y campos desconocidos (unknown_field).
  • Números de identificación: el dígito verificador de la cédula (invalid_check_digit) y el formato del RUC (invalid_identification); un consumidor final donde el tipo no lo permite (final_consumer_not_allowed).
  • Valores de catálogo que Flashpi sabe que no estaban vigentes en la fecha de emisión (not_in_force).
  • Texto que el SRI no admite: saltos de línea, caracteres de control y caracteres fuera del plano multilingüe básico, como los emojis (unsupported_character, indicando el carácter). Flashpi nunca los elimina en silencio.
  • Pagos que no cuadran (amount_mismatch), fechas en orden incorrecto, descuentos mayores que la línea (discount_exceeds_amount), demasiados campos adicionales.

Después se arma el XML y se valida contra el esquema oficial del SRI antes de firmarlo. Un fallo ahí significa un vacío de validación en Flashpi: 422 document_schema_invalid, y no se emite nada; escribe a soporte con el requestId. Un comprobante demasiado grande para el SRI una vez firmado (más de 304 KiB sin firmar) recibe 422 document_too_large.

La respuesta

Sección titulada «La respuesta»

Una solicitud válida se numera, se guarda y se responde de inmediato con 202 Accepted, el comprobante en estado processing y un encabezado Location (/v1/documents/{id}). Luego Flashpi lo firma, lo envía al SRI y sigue su autorización. Síguelo con webhooks o GET /v1/documents/{id}, o espera en la misma solicitud con el modo síncrono.

El objeto comprobante

Sección titulada «El objeto comprobante»

Todos los endpoints de emisión, GET /v1/documents/{id}, la lista de comprobantes y los eventos de comprobantes devuelven el mismo objeto:

Campo Descripción
id El ID del comprobante (UUIDv7).
type invoice, credit_note, debit_note, withholding, waybill o purchase_settlement.
environment test o live, según la llave que lo emitió.
status El estado tributario: processing, pending_sri, authorized, rejected, failed o voided. Consulta Ciclo de vida del comprobante.
issuerId, establishment, emissionPoint, sequential, number Quién lo emitió y su número (001-001-000000123).
accessKey La clave de acceso de 49 dígitos, que también es el número de autorización.
issueDate, xmlVersion La fecha de emisión y la versión del XML del SRI.
counterparty id y name del comprador, proveedor, sujeto retenido o transportista.
totals Lo que calculó Flashpi: subtotal, discount, taxes[], tip, total o withheld, según el tipo. null en las guías de remisión.
authorization number y authorizedAt, cuando el SRI lo autoriza.
ride El RIDE (PDF): status, template, generatedAt.
email El correo al comprador: requested, status y deliveries[].
sriMessages Los mensajes del SRI, traducidos a códigos de Flashpi: los motivos de un rechazo, o las advertencias de una autorización.
failure code y message cuando el estado es failed.
voidedAt, createdAt, updatedAt Fechas y horas (ISO 8601, UTC).

Los mensajes de sriMessages y failure siguen Accept-Language: en inglés por defecto, en español con Accept-Language: es.

Consultar comprobantes

Sección titulada «Consultar comprobantes»
Operación Endpoint
Listar, del más nuevo al más antiguo, con los filtros issuerId, type, status, issueDateFrom, issueDateTo, counterpartyId y accessKey GET /v1/documents
Leer uno GET /v1/documents/{id}
Su XML GET /v1/documents/{id}/xml
Su RIDE (PDF) GET /v1/documents/{id}/pdf
Reenviarlo por correo POST /v1/documents/{id}/email
Ventana de terminal
curl "https://api.flashpi.com.ec/v1/documents?type=invoice&status=authorized&issueDateFrom=2026-10-01&limit=50" \
  -H "Authorization: Bearer $FLASHPI_API_KEY"
  • Cualquier llave puede leer, incluidas las read_only. Las llaves de prueba leen comprobantes de prueba y las de producción los de producción; una llave de un emisor solo lee los comprobantes de su emisor.
  • GET .../xml devuelve el XML más avanzado disponible y lo indica en el encabezado Flashpi-Xml-Kind: authorized (el comprobante firmado tal como lo devolvió el SRI en su autorización), signed o unsigned.
  • GET .../pdf devuelve el RIDE como archivo PDF/A-2b una vez generado, y 409 ride_not_available antes.
  • Las listas usan paginación por cursor; consulta Paginación.