Introducción

Documentación de los endpoints que consumen API Key para emitir y consultar comprobantes electrónicos ante el SRI de Ecuador.

Base URL

Todas las rutas se consumen sobre la base donde esté desplegada la API:

https://live.faktur.com.ec (producción)
https://dev.faktur.com.ec (desarrollo)

Headers obligatorios

Header	Descripción
`X-API-Key`	API Key asociada a un punto de emisión (formato `sk_...`).
`X-API-Secret`	Secret correspondiente a la API Key.
`Content-Type`	`application/json` en todas las peticiones con body (POST/PATCH).

Sin estos headers, las peticiones devuelven 401 Unauthorized.

Formato de respuesta

Éxito (200/201):

{ "success": true, "data": { ... } }

Error (4xx/5xx):

{ "success": false, "error": { "code": "CODIGO", "message": "Descripción", "details": [...] } }

El campo details es opcional (array con campos afectados en errores de validación). En cada endpoint los errores posibles se documentan en tabla HTTP + error.code con ejemplos de respuesta en la sección correspondiente.

Entrega al comprador por correo

Si en el body de emisión (factura o nota de crédito) envías el campo buyerEmail con un correo válido del comprador, Faktur enviará al cliente una notificación por correo con el comprobante autorizado (RIDE en PDF y/o XML) una vez que el SRI lo autorice. No necesitas implementar el envío de emails en tu sistema; la plataforma se encarga de la entrega al comprador.

El campo buyerEmail es opcional. Si no lo envías, el documento se emite igual pero no se envía correo al comprador. Ver el detalle de campos en POST Facturas.

Modos de emisión: síncrono y asíncrono

Los endpoints de emisión (POST /v1/documents/invoices, POST /v1/documents/credit-notes y variantes) admiten dos modos:

Síncrono (por defecto): La petición no retorna hasta que el SRI responde. La respuesta incluye el estado final (AUTHORIZED, REJECTED o ERROR). No es necesario hacer polling.

Asíncrono: Se activa con el query param ?async=true o el header X-Emit-Async: true. La API valida el body, crea el documento en estado PENDING y responde 201 de inmediato. La firma y envío al SRI se procesan en background.

Si usas modo asíncrono, conviene que registres webhooks para recibir la notificación cuando el documento pase a estado final (document.authorized, document.rejected o document.error). Así tu sistema no depende solo de polling. Ver Webhooks.

Alternativamente puedes hacer polling a GET /v1/documents/:id o GET /v1/documents/detail?accessKey=... hasta que status sea AUTHORIZED, REJECTED o ERROR.

Reintentos automáticos

Faktur cuenta con reintentos automáticos ante el SRI. Para documentos en SUBMITTED, REJECTED (por timeout) o ERROR (con XML firmado), la plataforma reintenta la autorización sin que tengas que intervenir. Si usas webhooks, recibirás la notificación cuando el documento quede autorizado, rechazado o en error tras esos reintentos.

Además puedes disparar un reintento manual con:

POST /v1/documents/request-authorization/:accessKey

En la respuesta del documento verás retryCount, lastRetryAt y lastRetryError para saber cuántos intentos se han hecho y el último error, si aplica. Ver Reintentar autorización.

Scopes

Cada API Key tiene uno o más scopes:

Scope	Endpoints
`documents:write`	Emitir facturas, notas de crédito, reintentar autorización.
`documents:read`	Listar, obtener detalle, RIDE y XML.
`webhooks:manage`	Crear, listar, actualizar y eliminar webhook endpoints.