Antes de empezar
Una API key de pruebas de Flashpi
Guárdala en una variable de entorno, nunca en el código ni en el repositorio.
Tu certificado de firma .p12
Cargado en la cuenta de pruebas.
Tus datos de emisor
RUC, establecimiento y punto de emisión configurados en tu cuenta.
Los datos del documento sustento
La factura del proveedor: tipo, número y fecha.
El catálogo vigente de códigos y porcentajes de retención del SRI
Paso 1 · Reúne los datos de la retención
| Dato | Qué es |
|---|---|
sujeto_retenido | El proveedor al que le retienes |
periodo_fiscal | Mes y año de la retención |
documento_sustento | La factura que origina la retención |
impuestos | Uno o varios: tipo (renta o IVA), código, base imponible y porcentaje |
Paso 2 · Emite la retención
curl -X POST https://api.flashpi.ec/v1/retenciones \
-H "Authorization: Bearer $FLASHPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sujeto_retenido": {
"tipo_identificacion": "ruc",
"identificacion": "1790000000001",
"razon_social": "Proveedor de ejemplo S.A."
},
"periodo_fiscal": "11/2026",
"documento_sustento": {
"tipo": "factura",
"numero": "001-001-000000123",
"fecha_emision": "2026-11-02"
},
"impuestos": [
{ "tipo": "RENTA", "codigo": "CODIGO_SRI", "base_imponible": 100.00, "porcentaje": "PORCENTAJE" },
{ "tipo": "IVA", "codigo": "CODIGO_SRI", "base_imponible": 12.00, "porcentaje": "PORCENTAJE" }
]
}'Reemplaza CODIGO_SRI y PORCENTAJE por los valores del catálogo vigente del SRI. No los dejes como están.
Paso 3 · Lee la respuesta
{
"estado": "AUTORIZADO",
"clave_acceso": "(49 dígitos)",
"numero_autorizacion": "(número de autorización del SRI)",
"fecha_autorizacion": "(fecha y hora)"
}Guarda la clave_acceso: es la referencia del comprobante para consultas y reportes.
Paso 4 · Corrige si te equivocaste
Si ya se autorizó una retención con un error, el proceso de corrección depende de la normativa vigente. Consulta con tu contador el procedimiento antes de intentar reemplazarla.
Errores frecuentes
| Síntoma | Causa probable | Qué hacer | Referencia |
|---|---|---|---|
401 Unauthorized | API key ausente, inválida o de otro ambiente. | Revisa el header Authorization y que uses la key del ambiente correcto. | Ver detalle |
422 Esquema XML | Algún campo no cumple la estructura esperada. | Lee el detalle del error y corrige el campo indicado. | Ver detalle |
SRI 35 | El archivo no cumple la estructura XML. | Revisa los campos obligatorios y sus formatos. | Ver detalle |
SRI 45 | Secuencial ya registrado. | Revisa tu control de secuenciales por establecimiento y punto de emisión. | Ver detalle |