RIDE y correo

Cuando el SRI autoriza un comprobante, Flashpi lo entrega: genera el RIDE y, si se pidió, lo envía por correo con el XML al comprador. La entrega tiene sus propios estados, separados del estado tributario: un RIDE o un correo que falla nunca cambia si el SRI autorizó el comprobante. Consulta Ciclo de vida del comprobante. El envío por correo todavía se está habilitando: mientras tanto, entregas tú el RIDE y el XML (ver El correo al comprador).

El RIDE

El RIDE (Representación Impresa del Documento Electrónico) es la versión imprimible de un comprobante autorizado: un archivo PDF/A-2b con todos los campos que exige el Anexo 2 del SRI y la clave de acceso como código de barras Code 128.

• Flashpi lo genera justo después de la autorización, normalmente en segundos. Solo los comprobantes autorizados reciben un RIDE.
• GET /v1/documents/{id}/pdf lo devuelve cuando ride.status es generated (Content-Type: application/pdf, con la clave de acceso como nombre). Antes, o si falló, la respuesta es 409 ride_not_available con el rideStatus actual.
• Los webhooks document.ride.generated y document.ride.failed te avisan cuando está listo, o que no se pudo generar.
• Los comprobantes de prueba llevan el aviso “Documento emitido en el ambiente de pruebas del SRI: no tiene validez tributaria.”

curl https://api.flashpi.com.ec/v1/documents/01a1412b-ae38-7c39-8c71-16d2b5dfc472/pdf \
  -H "Authorization: Bearer $FLASHPI_API_KEY" \
  -o factura-001-001-000000123.pdf

Tres plantillas

Cada cuenta usa una de tres plantillas base, todas conformes al Anexo 2. La plantilla por defecto es moderna (modern); un propietario de la cuenta elige otra en la consola, en Configuración, Cuenta.

Moderna (modern, por defecto): encabezado con el color de marca del emisor, tipografía limpia y una tabla amplia.

Clásica (classic): recuadros de borde fino, como el RIDE tradicional.

Minimalista (minimal): blanco y negro, mucho espacio en blanco, ideal para imprimir.

Las vistas previas usan datos de ejemplo. Hoy la marca de un emisor es su color de marca (branding.brandColor, consulta Emisores); el logo y las notas de los ejemplos todavía no se pueden configurar.

• Un comprobante se genera una sola vez, con la plantilla que tiene la cuenta en ese momento. Cambiar la plantilla aplica a los RIDE que se generen después, no a los ya generados.
• ride.template indica qué plantilla usó un RIDE.
• Un RIDE que falló se vuelve a generar cuando reenvías el comprobante por correo (ver abajo). Por ahora no se puede pedir de otra forma un RIDE nuevo de un comprobante.

El correo al comprador

El envío por correo se está habilitando

Por ahora Flashpi no envía los correos a los compradores, así que es normal que el correo de un comprobante no llegue y su entrega quede failed. Mientras lo habilitamos, descarga el RIDE (GET /v1/documents/{id}/pdf) y el XML autorizado (GET /v1/documents/{id}/xml), o desde la consola, y envíaselos tú al correo que te dio el comprador: esa es la entrega que define el SRI (Resolución NAC-DGERCGC18-00000233, art. 6). Lo que sigue describe el envío tal como funcionará cuando esté activo.

Cuando un comprobante se autoriza, Flashpi envía su RIDE (PDF) y su XML autorizado a la dirección de correo de la solicitud:

Comprobante	Dirección que se usa
Factura, nota de crédito, nota de débito	customer.email
Liquidación de compra	supplier.email
Comprobante de retención	subject.email
Guía de remisión	Ninguna: una guía de remisión nunca se envía por correo

El correo solo sale cuando se cumplen las tres condiciones: el comprobante está autorizado, el correo se pidió y hay una dirección. En un comprobante de prueba, además, la dirección debe ser la de un miembro de tu equipo (ver Destinatarios de los comprobantes de prueba).

• Pedido: options.sendEmail en la solicitud decide para ese comprobante, true o false. Sin él, aplica el sendEmailByDefault del emisor (true, salvo que lo hayas desactivado en el emisor).
• email.requested, email.status y email.deliveries[] del comprobante muestran qué pasó: not_requested cuando se desactivó, skipped sin dirección, queued hasta que se envía, y luego sent, delivered, bounced, complained o failed.
• Cada cambio genera un webhook: document.email.sent, document.email.delivered, document.email.bounced, document.email.complained y document.email.failed.

Lo que recibe el comprador:

• Desde comprobantes@flashpi.com.ec, con el nombre comercial (o la razón social) del emisor como nombre del remitente.
• En español, con el color de marca del emisor: el tipo de comprobante, el número, la fecha, el total y la clave de acceso, con el RIDE y el XML adjuntos (factura-001-001-000000123.pdf y factura-001-001-000000123.xml).
• El asunto indica el comprobante y el emisor, por ejemplo Factura 001-001-000000123 de Café Andino. Los comprobantes de prueba agregan [PRUEBAS] al inicio del asunto y un aviso en el cuerpo.

Nota

Planificado: plantillas de correo que puedas editar (asunto y cuerpo), envío desde tu propio dominio verificado y el logo del emisor en el RIDE y en el correo.

Revisión de la dirección

Flashpi revisa la dirección del destinatario para que un correo mal escrito no rebote:

• Errores de tipeo. Cuando el dominio de la dirección parece un error de tipeo de un dominio de correo común (por ejemplo gmial.com en lugar de gmail.com), email.warnings[] del comprobante trae una advertencia recipient_domain_typo con un message y la dirección sugerida (suggestedRecipient). Es solo una advertencia: el correo se envía igual a la dirección tal como está. Corrígela en tu sistema para los próximos comprobantes; todavía no se puede cambiar la dirección de un comprobante emitido. email.warnings está vacío cuando nada parece estar mal.
• Dominios que no reciben correo. Justo antes de cada envío, Flashpi revisa que el dominio del destinatario exista y reciba correo (un registro MX o, si no tiene, un registro A o AAAA). Si no, el correo no se envía: su entrega queda failed con el error invalid_domain, y se genera document.email.failed.
• Direcciones suprimidas. Una dirección que antes rebotó o marcó un correo como spam puede estar en la lista de supresión del proveedor de correo de Flashpi, que ya no le envía mensajes: la entrega queda bounced con el error bounce_suppressed.

Destinatarios de los comprobantes de prueba

Cualquiera puede emitir comprobantes de prueba con compradores inventados, así que sus correos solo se envían a las direcciones de los usuarios de la consola que las verificaron y son miembros de la cuenta que emitió el comprobante (también con el emisor demo compartido). Para probar el correo, usa tu propio correo como correo del cliente.

• A cualquier otra dirección el correo no se envía y no cuenta para los límites diarios: su entrega queda failed con el error test_recipient_not_allowed, y se genera document.email.failed.
• POST /v1/documents/{id}/email responde 409 test_recipient_not_allowed.
• Flashpi vuelve a revisar la dirección justo antes del envío, así que un correo en cola para alguien que salió del equipo falla igual.
• Los comprobantes de producción no tienen esta restricción.

Reenviar un comprobante por correo

POST /v1/documents/{id}/email vuelve a enviar el correo de un comprobante autorizado, a la misma dirección, por ejemplo cuando el comprador lo perdió o después de que corrigió un rebote de su lado. Requiere una llave read_write, y funciona aunque el correo no se haya pedido al emitir. No envíes cuerpo, o envía un objeto vacío.

curl -X POST https://api.flashpi.com.ec/v1/documents/01a1412b-ae38-7c39-8c71-16d2b5dfc472/email \
  -H "Authorization: Bearer $FLASHPI_API_KEY"

La respuesta es 202 Accepted con el comprobante: una nueva entrada en email.deliveries y email.status en queued. Si su RIDE había fallado, primero se vuelve a generar.

Respuesta	Cuándo
409 document_not_authorized	Solo se envían por correo los comprobantes autorizados. El cuerpo trae el documentStatus.
409 email_recipient_missing	La solicitud no tenía dirección de correo. Por ahora no se puede enviar a otra dirección.
409 email_already_queued	Un correo del comprobante todavía espera ser enviado. Vuelve a intentarlo cuando se haya enviado o haya fallado.
409 email_sending_paused	Los correos de comprobantes de la cuenta están pausados en el ambiente del comprobante, ver Correos pausados. El cuerpo trae el environment.
409 test_recipient_not_allowed	El comprobante es de prueba y su dirección no es la de un miembro verificado del equipo de la cuenta, ver Destinatarios de los comprobantes de prueba.
429 email_resend_limit_reached, account_email_limit_reached, platform_email_limit_reached	Se alcanzó un límite diario, ver abajo.

Límites diarios

Para proteger la reputación del dominio de envío, y las bandejas de entrada de tus clientes, los correos al comprador tienen límites diarios:

Límite	Comprobantes de prueba	Comprobantes de producción
Reenvíos de un comprobante (POST .../email)	3 al día	10 al día
Correos por cuenta: envíos automáticos y reenvíos juntos	20 al día	200 al día

Además, los correos de comprobantes de todas las cuentas de Flashpi comparten un límite diario, de prueba y de producción, envíos automáticos y reenvíos juntos (platform_email_limit_reached). Su cifra no se publica.

• Los días siguen el calendario de Ecuador (UTC-5): los conteos se reinician a la medianoche de Ecuador.
• Los límites de producción por cuenta son valores por defecto; Flashpi puede fijar otros para una cuenta.
• Un reenvío por encima de un límite recibe 429 con Retry-After y resetsAt. Los límites del comprobante y de la cuenta también traen el limit; el de la plataforma no muestra su cifra.
• Un correo automático por encima del límite de la cuenta o de la plataforma no se envía: su entrega queda failed con el error account_email_limit_reached o platform_email_limit_reached, y se genera document.email.failed. Reenvíalo cuando se reinicie el límite.

{
  "type": "https://flashpi.com.ec/docs/en/errors/email_resend_limit_reached",
  "title": "Resend limit reached",
  "status": 429,
  "detail": "This document's email was already resent 3 times today. You can resend it again after 2026-10-16T05:00:00.000Z.",
  "instance": "/v1/documents/01a1412b-ae38-7c39-8c71-16d2b5dfc472/email",
  "code": "email_resend_limit_reached",
  "errors": [],
  "requestId": "01a14190-6c2e-7f41-8a07-3d9b2e5c1f68",
  "limit": 3,
  "resetsAt": "2026-10-16T05:00:00.000Z"
}

Correos pausados

Los correos de comprobantes de todos los clientes de Flashpi salen por la misma cuenta del proveedor de correo, cuya reputación depende de que pocos correos reboten o se marquen como spam. Para protegerla, Flashpi pausa los correos de comprobantes de una cuenta cuando, en los últimos 7 días:

• al menos 3 correos rebotaron de forma permanente (bounce_permanent: la dirección o el dominio no existe) y son al menos el 3 % de los correos enviados, o
• al menos 2 correos se marcaron como spam y son al menos el 0,05 % de los correos enviados.

Cada ambiente se mide y se pausa por separado: los correos de prueba solo pausan los de prueba, y los de producción solo los de producción. Solo cuentan los rebotes permanentes: no cuentan los rebotes temporales o indeterminados, bounce_suppressed ni invalid_domain (que nunca se envía).

Mientras los correos están pausados:

• Los comprobantes se siguen emitiendo y autorizando, y su RIDE se genera.
• Sus correos no se envían: cada entrega queda failed con el error email_sending_paused, y se genera document.email.failed. No cuentan para los límites diarios.
• POST /v1/documents/{id}/email responde 409 email_sending_paused, con el environment pausado.

Flashpi te avisa: los propietarios de la cuenta reciben un correo, la consola muestra un aviso arriba de cada página y se genera el webhook account.email_paused. El equipo de Flashpi también puede pausar los correos de una cuenta a mano, con los mismos avisos.

Solo el soporte de Flashpi puede reanudarlos: revisa las direcciones de los comprobantes cuyos correos rebotaron y escribe a soporte@flashpi.com.ec. Cuando se reanudan se genera account.email_resumed, y los 7 días se cuentan de nuevo desde ese momento. Los correos que fallaron durante la pausa no se envían solos: reenvía esos comprobantes con POST /v1/documents/{id}/email.