API REST v2 · documentación para desarrolladores

Integra la facturación del SRI en tu sistema

Emite facturas, notas, retenciones, guías y liquidaciones directamente desde tu e-commerce, ERP o app, con respuesta en segundos. Autenticación por api_key y secuenciales automáticos.

Obtener mi api_key Ver endpoints
Emisión Consulta de comprobantes Webhooks Referencia completa (todos los endpoints) SDK · n8n · IA (MCP) Factura con IA (MCP)
emitir-factura.sh 
curl -X POST https://tu-dominio/plataforma/api/v2/factura/emision \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "TU_API_KEY",
    "codigoDoc": "01",
    "emisor": { "fecha_emision": "2026/07/13", "manejo_interno_secuencia": "SI" },
    "comprador": { "tipo_identificacion": "07", "identificacion": "9999999999999", "razon_social": "CONSUMIDOR FINAL", "direccion": "Quito" },
    "items": [ { "codigo_principal": "P1", "descripcion": "Producto", "cantidad": 1, "precio_unitario": 100, "tipoproducto": 1, "tipo_iva": 4 } ]
  }'

# ← { "creado": true, "claveacceso": "..." }

Autenticación

El api_key va en el cuerpo del JSON o en la cabecera X-Api-Key (también Authorization: Bearer); si viene en los dos, vale el del cuerpo. Cada api_key identifica tu empresa, establecimiento, punto de emisión y ambiente.

Secuenciales

Envía manejo_interno_secuencia: "SI" y AZUR asigna el secuencial automáticamente, sin duplicados.

Ambientes

Tu api_key define si emites en Pruebas o Producción. El mismo código funciona en ambos.

Rate limit

Los endpoints de emisión aceptan 5 peticiones cada 60 segundos por comprobante.

Respuesta

Éxito: { "creado": true, "claveacceso": "…" }. Luego consulta el estado con la API de consulta o recibe el aviso por webhook.

Automático

Al emitir, se crean o actualizan solos el cliente y los productos que no existan.

Endpoints de emisión

Ejemplos completos, listos para copiar

Cada comprobante tiene su endpoint. Elige uno para ver el cuerpo JSON completo que acepta.

Request · JSON POST 
POST /plataforma/api/v2/factura/emision

{
  "api_key": "TU_API_KEY",
  "codigoDoc": "01",
  "emisor": {
    "fecha_emision": "2026/07/13",
    "secuencial": "000000123",
    "manejo_interno_secuencia": "SI"
  },
  "comprador": {
    "tipo_identificacion": "05",
    "identificacion": "1712345678",
    "razon_social": "JUAN PEREZ LOPEZ",
    "direccion": "Av. Amazonas N34-56, Quito",
    "telefono": "022345678",
    "celular": "0991234567",
    "correo": "juan.perez@ejemplo.com"
  },
  "items": [
    {
      "codigo_principal": "PROD-001",
      "codigo_auxiliar": "AUX-001",
      "descripcion": "Laptop HP 15 Core i5",
      "cantidad": 2,
      "precio_unitario": 850.00,
      "descuento": 50.00,
      "tipoproducto": 1,
      "tipo_iva": 4,
      "unidad_medida": 1,
      "detalles_adicionales": [
        { "nombre": "Marca", "detalle": "HP" },
        { "nombre": "Garantia", "detalle": "12 meses" }
      ]
    },
    {
      "codigo_principal": "SERV-010",
      "descripcion": "Servicio de instalacion",
      "cantidad": 1,
      "precio_unitario": 30.00,
      "tipoproducto": 2,
      "tipo_iva": 4
    }
  ],
  "pagos": [
    { "tipo": "20", "total": 1918.00, "tiempo": "dias", "plazo": 30 }
  ],
  "informacion_adicional": [
    { "nombre": "Vendedor", "detalle": "Maria Gomez" }
  ]
}
Respuesta · éxito
{ "creado": true,
  "claveacceso": "2607…49 dígitos" }
Respuesta · error
{ "creado": false,
  "errors": [ "El campo items es
  obligatorio." ] }
Consulta de comprobantes

Lista, sincroniza y descarga lo emitido

Para traer a tu sistema lo que se emitió (también desde el portal), saber en qué estado está cada documento y bajar su PDF y XML.

Ver la referencia completa (146 endpoints)

Autenticación de estos endpoints

Se autentican con la cabecera X-Api-Key: TU_CREDENCIAL_API_V2 (también vale Authorization: Bearer …). Es una credencial propia de la API v2 para tu punto de emisión: empieza con sk_live_ (producción) o sk_test_ (pruebas) —las creadas antes del 04/10/2026 empiezan por azur_live_ / azur_test_ y siguen valiendo—, se puede revocar y es distinta del api_key de la emisión. El dueño de la cuenta la crea en su menú de usuario → Credenciales API, eligiendo qué puede hacer (permisos), desde qué IP y hasta cuándo.

Todas responden en el mismo sobre: { "ok": true, "datos": { … }, "avisos": [ … ] } o { "ok": false, "error": { "codigo", "mensaje" } }. Base: https://tu-dominio/plataforma/api/v2

GET /comprobantes Todos los comprobantes electrónicos juntos (facturas, notas, retenciones, guías, liquidaciones), con filtros y sincronización.
GET /facturas Listado de un solo tipo. También /creditos, /debitos, /guias, /retenciones, /liquidaciones, /compras, /proformas y /notaventas.
GET /{recurso}/{id} Detalle completo de un documento (recurso: factura, credito, debito, guia, retencion, liquidacion…).
GET /{recurso}/{id}/estado Estado en el SRI con su código, si es final, si se puede reprocesar y qué hacer. Con ?sri=1 pregunta en vivo al SRI.
GET /{recurso}/{id}/pdf El RIDE en PDF (cuando ya está autorizado). Con ?base64=1 llega dentro del JSON.
GET /{recurso}/{id}/xml El XML autorizado. Con ?tipo=firmado, el XML firmado; con ?base64=1, dentro del JSON.
Sincronizar lo que cambió GET 
curl "https://tu-dominio/plataforma/api/v2/comprobantes?modificado_desde=2026-09-30&limite=100" \
  -H "X-Api-Key: TU_CREDENCIAL_API_V2"
{
  "ok": true,
  "datos": {
    "comprobantes": [
      {
        "id": 1520,
        "recurso": "factura",
        "tipo": "01",
        "tipo_nombre": "Factura",
        "secuencial": "000000152",
        "numero": "001-001-000000152",
        "fecha": "2026-09-30",
        "total": "115.00",
        "estado": "autorizado",
        "es_borrador": false,
        "actualizado": "2026-09-30 10:15:02",
        "claveacceso": "3009202601179...",
        "ambiente": 2,
        "vendedor": null,
        "cliente": {
          "tipo": "cliente",
          "id": 45,
          "identificacion": "0990012345001",
          "nombre": "DISTRIBUIDORA GUAYAS S.A."
        }
      }
    ],
    "total": 1,
    "pagina": 1,
    "paginas": 1,
    "ventana": { "aplicada": false, "dias": null, "desde": null },
    "siguiente_cursor": null
  },
  "avisos": [ "No hay más cambios: ya está al día. Guarde la hora de esta llamada y mándela como «modificado_desde» la próxima vez." ]
}
Parámetros de los listados
  • tipo Solo en /comprobantes. Uno o varios separados por coma: factura,retencion o 01,07.
  • desde · hasta Rango por fecha de emisión.
  • buscar Texto: número, nombre o identificación del cliente.
  • estado Solo en /comprobantes. Código de estado (por ejemplo 4 = autorizado).
  • global 1 = toda la empresa (solo el dueño). Sin él, solo el establecimiento de la credencial.
  • limite · pagina Hasta 100 por página (25 por defecto).
  • modificado_desde Sincronización: lo creado o cambiado desde esa fecha (aaaa-mm-dd o aaaa-mm-dd hh:mm:ss), incluidas las anulaciones.
  • cursor Sincronización: el «siguiente_cursor» de la respuesta anterior, sin modificarlo.
Cómo sincronizar sin perder nada

Llame con modificado_desde y, mientras la respuesta traiga siguiente_cursor, vuelva a llamar con cursor=…. Cuando venga vacío, ya está al día: guarde la hora y úsela la próxima vez. Sin fechas ni búsqueda, los listados devuelven solo los últimos 60 días.

Estado de un comprobante GET 
curl "https://tu-dominio/plataforma/api/v2/factura/1520/estado?sri=1" \
  -H "X-Api-Key: TU_CREDENCIAL_API_V2"
{
  "ok": true,
  "datos": {
    "codigo": 4,
    "estado": "autorizado",
    "es_final": true,
    "autorizado": true,
    "es_borrador": false,
    "reprocesable": false,
    "que_hacer": "Autorizado por el SRI. Ya tiene PDF y XML.",
    "id": 1520,
    "tipo": "Factura",
    "secuencial": "000000152",
    "numero": "001-001-000000152",
    "claveacceso": "3009202601179...",
    "ambiente": 2,
    "fecha_autorizacion": "2026-09-30 10:15:02",
    "errores": [],
    "anulado": false,
    "pendiente_en_sri": false,
    "actualizado": "2026-09-30 10:15:02",
    "sri": {
      "consultado": true,
      "estado_consulta": "EXISTE",
      "estado_autorizacion": "AUTORIZADO",
      "anulado": false
    }
  }
}
Códigos de estado (codigo)
-1 borrador
0 en proceso
3 recibido por el SRI
4 autorizado
5 no autorizado
6 error de secuencial
7 error al firmar
11 SRI no disponible (se reintenta solo)
15 establecimiento cerrado
17 corregir firma electrónica
18 corregir comprobante
9 anulado

El campo codigo no cambia nunca: ramifique por él, no por el texto.

Con el api_key de emisión

Si solo usa los endpoints de emisión, puede consultar un comprobante por su clave de acceso con el mismo api_key (en el cuerpo o en la cabecera X-Api-Key).

/consulta/comprobante POST 
{
  "api_key": "TU_API_KEY",
  "claveacceso": "3009202601179..."
}
Respuesta · autorizado
{
  "creado": true,
  "claveacceso": "3009202601179...",
  "estado": 4,
  "estado_texto": "Autorizado",
  "fecha_aprobado": "2026-09-30 10:15:02",
  "mensaje": "",
  "motivo": null,
  "enlace_pdf": "https://.../descargaryver/...",
  "enlace_xml": "https://.../descargar/..."
}
Otros endpoints con api_key (cuerpo o cabecera X-Api-Key)
POST /clientes/nuevo Crea o actualiza un cliente { "resultado": true, "id_cliente": 45, "id_sucursal": 12, "mensaje": "cliente creado o actualizado" }
POST /actualizar/productos Actualiza nombre/descripción de productos { "respuesta": true }
POST /crear/productos Crea productos con stock inicial { "creado": true }
POST /productos/obtenerstock Consulta stock de un producto { "respuesta": true, "producto": "Laptop HP", "precio": 850, "cantidad": 12, "bodega": "Principal" }
POST /consulta/comprobante Consulta estado y enlaces PDF/XML { "creado": true, "estado": 4, "estado_texto": "Autorizado", "enlace_pdf": "...", "enlace_xml": "..." }
POST /consultar/comprobantes Comprobantes usados y restantes del plan { "creado": true, "plan_actual": "Ilimitado", "comprobantes_utilizados": 340, "comprobantes_restantes": -1 }
POST /enviar/correo Reenvía el comprobante al cliente { "respuesta": true }
POST /factura/pagada Marca una factura como pagada { "modificado": true, "mensaje": "Correcto" }
Webhooks

Te avisamos cuando el SRI contesta

Registra una URL y recibe un POST firmado cada vez que un comprobante se autoriza, se rechaza o se anula. Sin preguntar cada minuto.

POST /webhooks Registra una URL https que recibirá los avisos. Devuelve el secreto para verificar la firma (solo esa vez).
GET /webhooks Lista sus webhooks: URL, eventos, si está activo, último envío y fallos seguidos.
DELETE /webhooks/{id} Borra un webhook.
GET /webhooks/{id}/envios Los últimos 50 envíos de ese webhook (evento, intento, código HTTP, respuesta) para depurar.
Registrar un webhook POST 
curl -X POST "https://tu-dominio/plataforma/api/v2/webhooks" \
  -H "X-Api-Key: TU_CREDENCIAL_API_V2" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://mi-sistema.com/avisos/sri",
    "eventos": ["comprobante.autorizado", "comprobante.rechazado"],
    "descripcion": "ERP principal"
  }'
{
  "ok": true,
  "datos": {
    "id": 12,
    "url": "https://mi-sistema.com/avisos/sri",
    "eventos": ["comprobante.autorizado", "comprobante.rechazado"],
    "secreto": "whsec_9fK2...",
    "como_verificar": "Cada aviso trae las cabeceras `X-Azur-Firma` y `X-Azur-Momento`. ..."
  },
  "avisos": [ "Guarde el secreto ahora: no se vuelve a mostrar." ]
}
Campos
  • url Obligatoria y https.
  • eventos Lista de eventos. Vacía = todos.
  • descripcion Opcional, hasta 160 caracteres.
Eventos
comprobante.autorizado El SRI autorizó el comprobante.
comprobante.rechazado El SRI no lo autorizó o hay que corregirlo (secuencial, firma, establecimiento). En «errores» está el motivo.
comprobante.anulado El comprobante se anuló (estado 9).
plan.cupo_bajo El plan llegó al 80 %, al 95 % o se agotó (nivel 80, 95 o 100), una vez por nivel y periodo.
Lo que recibe tu URL POST 
POST https://mi-sistema.com/avisos/sri
Content-Type: application/json
X-Azur-Evento: comprobante.autorizado
X-Azur-Momento: 1759245302
X-Azur-Intento: 1
X-Azur-Firma: 5b1f0c…(hmac sha256 en hexadecimal)

{
  "evento": "comprobante.autorizado",
  "momento": "1759245302",
  "datos": {
    "claveacceso": "3009202601179...",
    "tipo_comprobante": "01",
    "secuencial": "000000152",
    "id_comprobante": 1520,
    "estado": 4,
    "ambiente": 2,
    "fecha_emision": "2026-09-30",
    "valor": "115.00",
    "errores": null
  }
}
Verificar la firma HMAC SHA-256 
// PHP
$cuerpo  = file_get_contents('php://input');            // el cuerpo CRUDO, sin decodificar
$momento = $_SERVER['HTTP_X_AZUR_MOMENTO'] ?? '';
$firma   = $_SERVER['HTTP_X_AZUR_FIRMA'] ?? '';
$esperada = hash_hmac('sha256', $momento . '.' . $cuerpo, 'whsec_TU_SECRETO');

if (!hash_equals($esperada, $firma)) {
    http_response_code(401); exit;                       // no viene de nosotros
}
$aviso = json_decode($cuerpo, true);
http_response_code(200);                                 // responda 2xx rápido
// Node.js (Express)
const crypto = require('crypto');
app.post('/avisos/sri', express.raw({ type: 'application/json' }), (req, res) => {
  const momento = req.get('X-Azur-Momento');
  const esperada = crypto.createHmac('sha256', 'whsec_TU_SECRETO')
    .update(momento + '.' + req.body.toString('utf8')).digest('hex');
  if (esperada !== req.get('X-Azur-Firma')) return res.sendStatus(401);
  const aviso = JSON.parse(req.body);
  res.sendStatus(200);
});

Firma

Calcule hash_hmac('sha256', momento + '.' + cuerpo_crudo, secreto) con las cabeceras X-Azur-Momento y compárelo con X-Azur-Firma. Si no coincide, ignore el aviso.

Reintentos

Responda con un código 2xx. Si su servidor falla o no contesta en 20 s, reintentamos a 1, 5 y 15 minutos (4 intentos). Tras 20 fallos seguidos el webhook se desactiva.

Quién lo configura

Solo el dueño de la cuenta registra webhooks (no los vendedores). El secreto se muestra una sola vez al crearlo: guárdelo. Un aviso puede llegar repetido: use la clave de acceso para no procesarlo dos veces.

SDK e integraciones

Integra en minutos, en tu lenguaje o sin código

Todo funciona con una credencial sk_live_… (producción) o sk_test_… (pruebas) que el dueño de la cuenta crea en menú de usuario → Credenciales API, con permisos, IP autorizadas y vencimiento.

SDK de PHP

Para Laravel, WordPress/WooCommerce o PHP puro. Reintentos, protección contra duplicados, sincronización por cursor y verificación de webhooks ya resueltos.

composer require azur/sdk
Ver en GitHub

SDK de JavaScript / TypeScript

Para Node.js, Next.js, Bun o Deno. Tipado completo, sin dependencias, con los mismos reintentos y verificación de webhooks.

npm install @azur.com.ec/sdk
Ver en npm

Nodos para n8n

Automatiza sin programar: elige clientes, productos y comprobantes desde listas, y dispara flujos cuando el SRI autoriza, rechaza o se anula un comprobante.

Configuración → Community nodes → n8n-nodes-azur
Ver en npm

Asistentes de IA (MCP remoto)

Conecta Claude, Cursor, VS Code o tu agente a tu cuenta: busca clientes y productos, consulta comprobantes y prepara borradores. El envío al SRI queda en manos de una persona.

https://azur.com.ec/mcp  ·  Authorization: Bearer sk_live_…
Guía del servidor MCP

MCP local (Claude Desktop)

Para clientes de IA que se conectan por stdio. Solo necesita Node.js 18 y su credencial en AZUR_API_KEY.

npx -y @azur.com.ec/mcp
Ver en npm

OpenAPI 3.1 (Postman, Insomnia)

El contrato completo de la API, público y legible por máquina. Impórtalo en Postman o genera un cliente para cualquier otro lenguaje.

https://azur.com.ec/plataforma/api/v2/openapi
Descargar
Referencia SRI

Códigos que usa la API

Tipo de identificación
04 RUC (13 dígitos)
05 Cédula (10 dígitos)
06 Pasaporte
07 Consumidor final
08 Identificación del exterior
09 Placa
Tarifa de IVA (tipo_iva)
0 0%
4 15%
3 14%
5 5%
8 8% (turístico)
10 13%
6 No objeto de IVA
7 Exento de IVA
Formas de pago (tipo)
01 Efectivo / sin sistema financiero
16 Tarjeta de débito
17 Dinero electrónico
18 Tarjeta prepago
19 Tarjeta de crédito
20 Otros con sistema financiero
21 Endoso de títulos

Empieza a integrar hoy

Crea tu cuenta, obtén tu api_key y emite tu primer comprobante de prueba en minutos.

Crear cuenta gratis Hablar con un técnico