Introducción

Base URL

Todas las rutas se consumen sobre la siguiente base URL:

https://api.faktur.com.ec

Headers obligatorios

Sin estos headers, las peticiones devuelven 401 Unauthorized.

API Key por punto de emisión vs por company

Debes saber qué tipo de API Key estás usando, porque cambia qué campos envías en el body en cada petición de emisión (factura, nota de crédito, full-refund, partial-refund).

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.

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. Sin el scope adecuado, la API responde 403 (INSUFFICIENT_SCOPE o similar).