Modo síncrono y asíncrono

El SRI suele autorizar un comprobante en pocos segundos, pero puede tardar mucho más, y a veces sus servicios no están disponibles. Flashpi nunca te obliga a mantener una conexión abierta por eso: toda solicitud de emisión se responde rápido, y tú eliges cómo conocer el resultado.

Asíncrono (por defecto)

Una solicitud válida se responde de inmediato con 202 Accepted: el comprobante se numera, su XML se arma y se valida contra el esquema del SRI, y se guarda en estado processing, con un encabezado Location (/v1/documents/{id}). Luego Flashpi lo firma, lo envía al SRI y consulta su autorización en segundo plano.

Conoce el resultado con:

• Webhooks (recomendado): invoice.authorized e invoice.rejected, y lo mismo para cada tipo, enviados a tu endpoint apenas el SRI decide.
• GET /v1/documents/{id}: consulta el comprobante hasta que su estado sea final. Espera unos segundos entre lecturas.
• GET /v1/events: los mismos eventos que entregan los webhooks, para ponerte al día si tu receptor estuvo caído.

Esto le sirve a la mayoría de integraciones: un ERP, el backend de una tienda en línea, cualquier lote de comprobantes.

Síncrono (opcional)

Pon options.waitForAuthorization en true para esperar la decisión del SRI en la misma solicitud:

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

Opción	Por defecto	Notas
waitForAuthorization	false	Esperar al SRI antes de responder.
waitTimeoutSeconds	15	La espera máxima en segundos, de 1 a 30. Una espera mayor se rechaza con 422 validation_failed y el error de campo out_of_range, antes de crear nada.

La respuesta depende de lo que pase primero:

Resultado	Respuesta
El SRI lo autoriza o lo rechaza dentro de la espera, o falla	200 OK con el comprobante authorized, rejected o failed
La espera termina antes	202 Accepted con el comprobante tal como está en ese momento, normalmente pending_sri

En ambos casos la respuesta trae el encabezado Location. Después de un 202, el comprobante sigue exactamente como en el modo asíncrono: sus webhooks igual llegan, y GET /v1/documents/{id} muestra su avance.

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

Consejo

El modo síncrono es práctico en un punto de venta que imprime el RIDE en el momento, o en un script. Aun así, maneja la respuesta 202 (el SRI puede tardar) y mantén los webhooks: una solicitud síncrona solo espera, nunca cambia cómo se procesa el comprobante.

El RIDE después de una respuesta síncrona

Un 200 con authorized significa que el SRI autorizó el comprobante; el RIDE se genera justo después, normalmente en unos segundos. GET /v1/documents/{id}/pdf responde 409 ride_not_available hasta que ride.status sea generated. Vuelve a intentarlo en un momento, o espera el webhook document.ride.generated.

Reintentos y tiempos de espera

• Configura el tiempo de espera de tu cliente HTTP por encima de waitTimeoutSeconds, más unos segundos.
• Si la conexión se corta mientras esperas, envía la misma solicitud con la misma Idempotency-Key: mientras la primera siga en curso recibes 409 idempotency_key_in_progress (reintenta un poco después), y luego la primera respuesta otra vez, tal como era entonces (un 202 repetido sigue diciendo pending_sri). Consulta GET /v1/documents/{id} para ver el estado actual. Consulta Idempotencia.