API REST
Referencia de la API pública v1 de Factunexo: autenticación, URL base, versionado y endpoints para emitir comprobantes electrónicos del SRI desde sus propios sistemas.
La API REST v1 permite integrar Factunexo con sus propios sistemas: emitir comprobantes electrónicos, gestionar clientes y catálogo, y consultar el estado de autorización ante el SRI.
URL base
https://api.factunexo.com/v1/ecAutenticación
Todas las rutas requieren API Key y API Secret en cabeceras:
| Cabecera | Descripción |
|---|---|
X-API-Key | Identificador público de la credencial |
X-API-Secret | Secreto de la credencial (solo visible al crearla) |
Las credenciales se crean en la aplicación: Configuración → Credenciales API.
No comparta el X-API-Secret. Si se filtra, revoque la credencial y genere una nueva. El secreto se
guarda cifrado y no se puede volver a consultar.
Ambientes
Para probar sin emitir comprobantes con validez tributaria, use el ambiente de pruebas del SRI, que se configura por comercio en el perfil de facturación: los comprobantes se firman y se envían, pero el SRI los autoriza como pruebas y no tienen efecto fiscal.
Alcance actual
- Billing: facturas, notas de crédito y débito, retenciones, guías de remisión, liquidaciones de compra y bitácora de eventos
- Workflow: clientes y catálogo de ítems
- Setup: perfil tributario, establecimientos y puntos de venta
- Webhooks: avisos a su sistema con el resultado de cada comprobante ante el SRI
Emisión asíncrona
Emitir un comprobante implica enviarlo al SRI, y la respuesta del SRI puede tardar. Por eso los
endpoints de emisión no esperan ese resultado: responden 202 Accepted apenas el comprobante queda
firmado y en camino.
HTTP/1.1 202 Accepted
Location: /v1/ec/billing/invoices/5f0c2a1e-8b3d-4c1a-9e2f-7a6b5c4d3e2f
Retry-After: 5El cuerpo trae el comprobante con status: SENDING. Para conocer el resultado tiene dos caminos:
- Webhooks (recomendado): reciba un aviso en cuanto el SRI responde. Ver Webhooks.
- Consulta: haga
GETa la URL deLocation, esperando lo que indiqueRetry-Afterentre consultas.
status | Significado |
|---|---|
SENDING, SRI_SENT, PROCESSING | En curso. Consulte de nuevo más tarde. |
SIGNED | El SRI no respondió. Se reenvía automáticamente; no hace falta volver a emitirlo. |
SRI_AUTHORIZED | Autorizado: es un documento tributario válido. |
SRI_RETURNED, SRI_REJECTED, SRI_NOT_AUTHORIZED | El SRI no lo aceptó. Revise el motivo, corrija y emita de nuevo. |
No reenvíe una emisión porque la respuesta llegó en SENDING: ese estado es el esperado. Para reintentar
una llamada que falló por red, use la cabecera Idempotency-Key, que evita emitir el mismo comprobante
dos veces.
Empezar
Cree una credencial API en la aplicación.
Consulte sus puntos de venta con GET /v1/ec/setup/pos/catalog. Necesita un posId para emitir
comprobantes.
Emita su primera factura contra el ambiente de pruebas del SRI antes de pasar a producción.
Registre un webhook para enterarse del resultado de cada comprobante sin consultar la API.
En cada página de endpoint puede probar la llamada con el playground.