Facturación

Manual de la API

Emite comprobantes electrónicos e intégralos con tu sistema. Compatible con el contrato api/v1 anterior.

Swagger UI (probar en vivo) Descargar colección Postman

Introducción

Esta API REST permite emitir factura, notas de crédito y débito, retención, guía de remisión y liquidación de compra. Si ya consumías api/v1, sigue funcionando.

URL base:

https://facturacion.disisot.com/facturacion/api/v1

Las peticiones y respuestas son application/json (UTF-8).

Autenticación

Cada petición se autentica con el token del emisor en la cabecera X-Key:

X-Key: <token del emisor>
Content-Type: application/json

El token de cada emisor está en el panel (sección Emisores). A diferencia del sistema anterior, ya no se envía la clave del certificado (X-Password): el .p12 nunca sale del servidor.

Proceso de emisión

La emisión es asíncrona:

  1. Envías el comprobante → respuesta inmediata con la clave de acceso y el estado inicial.
  2. El sistema firma (XAdES), envía al SRI y consulta autorización en segundo plano.
  3. Por cada cambio de estado se notifica a tu callback_url con el custom_uid que enviaste (ver Webhooks).

Estados: borrador → validado → firmado → enviado → autorizado → notificado (o rechazado / error).

Emitir factura

POST https://facturacion.disisot.com/facturacion/api/v1/invoices/issue

Cuerpo

{
  "ambiente": "1",                 // 1 pruebas, 2 producción
  "tipo_emision": "1",
  "custom_uid": "abc-123",         // tu id para idempotencia y callback
  "secuencial": "123",             // opcional; si se omite, lo asigna el sistema
  "fecha_emision": "2026-06-20 10:00:00",
  "emisor": {
    "ruc": "1790012345001",
    "razon_social": "MI EMPRESA S.A.",
    "establecimiento": { "codigo": "001", "punto_emision": "001" },
    "obligado_contabilidad": true
  },
  "comprador": {
    "tipo_identificacion": "05",   // ver tabla
    "identificacion": "1710034065001",
    "razon_social": "JUAN PEREZ",
    "direccion": "Av. Siempre Viva 123",
    "email": "cliente@correo.com"
  },
  "detalles": [
    {
      "codigo_principal": "P001",
      "descripcion": "SERVICIO PROFESIONAL",
      "cantidad": 1,
      "precio_unitario": 100.00,
      "descuento": 0.00,
      "impuestos": [
        { "codigo": "2", "codigo_porcentaje": "4", "tarifa": 15, "base_imponible": 100.00, "valor": 15.00 }
      ]
    }
  ],
  "pagos": [ { "forma_pago": "01", "total": 115.00 } ],
  "info_adicional": { "telefono": "099..." }
}

Respuesta

{
  "Code": 200,
  "Mensaje": "Comprobante recibido",
  "claveAcceso": "2006202601179001234500110010010000001231234567813",
  "numeroDocumento": "001-001-000000123",
  "estado": "borrador"
}

El XML firmado, la autorización y el RIDE se completan en segundo plano y se avisan por callback.

Ejemplo con curl

curl -X POST https://facturacion.disisot.com/facturacion/api/v1/invoices/issue \
  -H "X-Key: TU_TOKEN_DE_EMISOR" \
  -H "Content-Type: application/json" \
  -d '{ "ambiente":"1","custom_uid":"abc-123",
        "emisor":{"ruc":"1790012345001","establecimiento":{"codigo":"001","punto_emision":"001"}},
        "comprador":{"tipo_identificacion":"05","identificacion":"1710034065001","razon_social":"JUAN PEREZ","direccion":"Av. 123"},
        "detalles":[{"descripcion":"SERVICIO","cantidad":1,"precio_unitario":100,
          "impuestos":[{"codigo":"2","codigo_porcentaje":"4","tarifa":15}]}],
        "pagos":[{"forma_pago":"01","total":115}] }'

# Consultar y descargar
curl https://facturacion.disisot.com/facturacion/api/v1/invoices/{claveAcceso}   -H "X-Key: TU_TOKEN_DE_EMISOR"
curl https://facturacion.disisot.com/facturacion/api/v1/ver/{claveAcceso}/pdf -H "X-Key: TU_TOKEN_DE_EMISOR" -o ride.pdf

Emitir desde XML (solo clientes legacy)

POST https://facturacion.disisot.com/facturacion/api/v1/invoices/issue-xml

¿Cuándo usar esto? Solo si tu sistema ya genera el XML del comprobante (migración desde el script legacy FacturacionCliente.php). Las integraciones nuevas deben usar la emisión por JSON (/invoices/issue): es más simple y no debes armar ni validar el XML.

Envía el XML ya armado como archivo en el campo xml (multipart) o como cuerpo application/xml. El servicio lo firma, lo envía al SRI y lo autoriza (el certificado lo aporta el emisor del X-Key; el XML puede ir sin firmar).

Respuesta 201: { "Code":"200", "claveAcceso":"…", "numeroDocumento":"001-002-000000007", "estado":"RECIBIDA" }. Validaciones: el RUC del XML debe coincidir con el emisor, la clave de acceso debe tener 49 dígitos y no estar duplicada.

Ejemplo con curl

curl -X POST https://facturacion.disisot.com/facturacion/api/v1/invoices/issue-xml \
  -H "X-Key: TU_TOKEN_DE_EMISOR" \
  -H "X-Password: CLAVE_DEL_CERTIFICADO" \
  -F "xml=@factura.xml"

Notas de crédito / débito

POST https://facturacion.disisot.com/facturacion/api/v1/credit-notes/issue  ·  POST https://facturacion.disisot.com/facturacion/api/v1/debit-notes/issue

Mismo formato que la factura, más el documento que se modifica:

"documento_modificado": {
  "tipo": "01",                         // 01 = factura
  "numero": "001-001-000000050",
  "fecha_emision": "2026-05-10",
  "motivo": "DEVOLUCIÓN PARCIAL"
}

Retención

POST https://facturacion.disisot.com/facturacion/api/v1/retentions/issue

{
  "ambiente": "1", "custom_uid": "ret-1",
  "emisor": { "ruc": "1790012345001", "establecimiento": { "codigo":"001","punto_emision":"001" } },
  "sujeto_retenido": { "tipo_identificacion":"04", "identificacion":"1790...001", "razon_social":"PROVEEDOR" },
  "periodo_fiscal": "06/2026",
  "retenciones": [
    {
      "codigo": "1",                    // 1 renta, 2 IVA
      "codigo_porcentaje": "303",
      "base_imponible": 100.00, "porcentaje": 10, "valor_retenido": 10.00,
      "tipo_documento_sustento": "01",
      "numero_documento_sustento": "001001000000050",   // 15 dígitos, sin guiones
      "fecha_emision_documento_sustento": "2026-05-10"
    }
  ]
}

Guía de remisión

POST https://facturacion.disisot.com/facturacion/api/v1/waybills/issue

{
  "ambiente": "1", "custom_uid": "guia-1",
  "emisor": { "ruc": "1790012345001", "establecimiento": { "codigo":"001","punto_emision":"001" } },
  "transportista": { "razon_social":"TRANSPORTES X", "tipo_identificacion":"04", "identificacion":"1790...001", "placa":"PXY1234" },
  "fecha_inicio_transporte": "2026-06-20", "fecha_fin_transporte": "2026-06-21",
  "destinatarios": [
    {
      "identificacion": "1710034065001", "razon_social": "CLIENTE",
      "direccion": "Av. Destino 99", "motivo_traslado": "Venta",
      "items": [ { "codigo_principal":"P001", "descripcion":"PRODUCTO", "cantidad":3 } ]
    }
  ]
}

Liquidación de compra

POST https://facturacion.disisot.com/facturacion/api/v1/purchase-settlements/issue

Mismo formato que la factura; el comprador es el proveedor al que se le liquida.

Consultar comprobante

GET https://facturacion.disisot.com/facturacion/api/v1/invoices/{claveAcceso}

{
  "claveAcceso": "2006...813",
  "numeroDocumento": "001-001-000000123",
  "estado": "autorizado",
  "autorizado_en": "2026-06-20 10:05:00"
}

Descargar XML / RIDE

GET https://facturacion.disisot.com/facturacion/api/v1/ver/{claveAcceso}/xml — XML autorizado
GET https://facturacion.disisot.com/facturacion/api/v1/ver/{claveAcceso}/pdf — RIDE (PDF)

Reenviar / reprocesar

Reprocesar (re-firmar y reenviar al SRI)

Si un comprobante quedó en error o rechazado y ya corregiste la causa, puedes reprocesarlo (vuelve a pasar por firma → SRI → autorización):

POST https://facturacion.disisot.com/facturacion/api/v1/invoices/{claveAcceso}/reissue

También: credit-notes, debit-notes, retentions, ats-retentions, waybills, purchase-settlements con /{claveAcceso}/reissue.

{
  "Code": "200",
  "Mensaje": "Comprobante reenviado a procesar (firma/SRI/autorización)",
  "claveAcceso": "2006...813",
  "estado": "borrador"
}

Reenviar el correo al receptor

POST https://facturacion.disisot.com/facturacion/api/v1/edocs/send-email/{claveAcceso}

{ "Code": "200", "Mensaje": "Reenvío de correo encolado", "claveAcceso": "2006...813" }

Compras (SRI)

Consulta las compras (comprobantes recibidos) descargadas del SRI, con sus impuestos y el crédito tributario. Usa la API nueva con token Bearer (no X-Key):

GET https://facturacion.disisot.com/facturacion/api/v1/compras?periodo=YYYY-MM

Obtén el token con POST https://facturacion.disisot.com/facturacion/api/v1/auth/login. Parámetros opcionales: periodo (YYYY-MM), emisor_id.

curl "https://facturacion.disisot.com/facturacion/api/v1/compras?periodo=2026-06" \
  -H "Authorization: Bearer TU_TOKEN"

{
  "periodo": "2026-06",
  "totales": { "base": 100.00, "iva": 15.00, "total": 115.00, "credito_tributario": 15.00 },
  "compras": [
    {
      "codigo_comprobante": "...", "ruc_emisor": "1790...001", "razon_social_emisor": "PROVEEDOR",
      "fecha_emision": "2026-06-15", "numero": "001-001-000000005", "tipo_comprobante": "FACTURA",
      "base": 100.00, "iva": 15.00, "total": 115.00, "credito_tributario": true,
      "impuestos": [ { "nombre": "IVA", "porcentaje": 15, "base": 100.00, "valor": 15.00 } ]
    }
  ]
}

Webhooks (callback)

Configura la URL de callback del emisor (en el panel, al editar el emisor, o por API). Por cada cambio de estado, el sistema hace un POST con cuerpo JSON a esa URL:

POST https://tu-sistema.com/callback
Content-Type: application/json
X-Signature: sha256=<HMAC-SHA256 del cuerpo con tu secreto>

{
  "custom_uid": "abc-123",
  "estado": "autorizado",
  "mensaje": null,
  "clave_acceso": "2006...813",
  "numero_documento": "001-001-000000123"
}

Verificar la firma

Cada emisor tiene un secreto de webhook (visible y regenerable en el panel, al editar el emisor). Calcula el HMAC del cuerpo crudo y compáralo con la cabecera X-Signature:

# PHP
$firma = 'sha256=' . hash_hmac('sha256', $rawBody, $secreto);
if (! hash_equals($firma, $request->header('X-Signature'))) { http_response_code(401); exit; }

El custom_uid es la pieza de correlación: úsalo para casar el aviso con tu venta. Se reintenta hasta 3 veces ante fallos.

Alta de clientes (socios)

Para quien revende la facturación dentro de su propio producto: da de alta al cliente, le deja el emisor listo y le activa la licencia que ya cobró con sus pasarelas, sin que el cliente entre nunca a este panel.

Contrato completo de cada endpoint —campos, tipos, y el cuerpo exacto de cada respuesta y de cada error— en OpenAPI, en la colección de Postman (trae el flujo numerado del 1 al 7) y en docs/integracion-socios.md del repositorio.

La clave de socio

Cada socio tiene una clave que se configura en el servidor (PARTNER_KEYS) y viaja en la cabecera X-Partner-Key. Pídenosla: no se genera desde el panel.

Un socio solo alcanza a las cuentas que él mismo dio de alta. Si su clave se filtra, quien la tenga no puede tocar los clientes de nadie más.

1. Dar de alta al cliente

Es el registro de siempre, pero con la cabecera de socio: eso es lo que marca la cuenta como tuya. Sin la cabecera, la cuenta queda como cliente directo y después no podrás gestionarla.

curl -X POST https://facturacion.disisot.com/facturacion/api/v1/auth/register \
  -H "X-Partner-Key: TU_CLAVE_DE_SOCIO" \
  -H "Content-Type: application/json" \
  -d '{"empresa":"Restaurante Central","nombre":"Ana","email":"ana@central.ec",
       "password":"…","password_confirmation":"…"}'

Devuelve usuario.account_id y un token del cliente. Guarda los dos: el id identifica la cuenta en las llamadas de socio y el token es el que usarás para lo del punto 2.

2. Dejar el emisor listo

Con el token del cliente (cabecera Authorization: Bearer):

# Crear el emisor
POST https://facturacion.disisot.com/facturacion/api/v1/emisores
{"pais_codigo":"EC","identificacion":"1790000000001","razon_social":"…",
 "ambiente":"pruebas","moneda_codigo":"USD"}

# Subir su certificado de firma (multipart)
POST https://facturacion.disisot.com/facturacion/api/v1/emisores/{id}/certificado
  certificado=@firma.p12   clave=CLAVE_DEL_CERTIFICADO

# Rotar el token de emisión (el X-Key con el que se factura)
POST https://facturacion.disisot.com/facturacion/api/v1/emisores/{id}/token

El certificado se comprueba al subirlo: si la clave no abre el archivo o está vencido, responde 422 y no se guarda nada. El token de emisión solo se puede leer en la respuesta de /token; el anterior deja de servir en el acto.

3. Activar la licencia que ya cobraste

Con la cabecera de socio. Aquí no se cobra nada: refleja lo que ya pagó el cliente en tu casa.

POST https://facturacion.disisot.com/facturacion/api/v1/partner/suscripciones
  -H "X-Partner-Key: TU_CLAVE_DE_SOCIO"
{"account_id":42, "plan":"profesional",
 "referencia":"CARGO-2026-09",          // tu identificador del cobro, opcional
 "termina_en":"2026-12-31T23:59:59Z"}   // hasta cuándo está pagada, opcional

Sin termina_en se usa el intervalo del plan. En lugar de account_id puedes mandar email, el del contacto de la cuenta.

Consultar y cancelar

GET  https://facturacion.disisot.com/facturacion/api/v1/partner/suscripciones?account_id=42
POST https://facturacion.disisot.com/facturacion/api/v1/partner/suscripciones/cancelar   {"account_id":42}

Al cancelar, la cuenta deja de poder emitir. El cobro recurrente lo paras tú en tu sistema: aquí no hay ninguna pasarela nuestra de por medio.

Respuestas

CódigoQué significa
401Falta X-Partner-Key o no es de ningún socio.
404Esa cuenta no es tuya (o no existe). Es la misma respuesta a propósito.
422Datos inválidos: plan inexistente, certificado que no abre con esa clave…

Integraciones y conectores

Además de la API directa, hay conectores y kits listos para los sistemas más usados. Todos consumen los mismos endpoints de este manual, así que puedes partir de uno y adaptarlo. El código está en la carpeta integrations/ del proyecto y la guía completa en docs/integracion-terceros.md.

SDK y plataformas

SDK PHPCliente sin dependencias (cURL) con métodos para factura, NC/ND, retención, guía y liquidación.
WooCommercePlugin de WordPress: emite al cambiar el estado del pedido, con enlace al RIDE.
ZapierApp con acción “Emitir factura” para automatizar desde miles de apps.
Make (Integromat)App personalizada con el módulo de emisión.
Odoo 17Módulo que agrega el botón “Emitir al SRI” en las facturas de cliente.

ERP y CRM

SAP Business OneStarter C# (.NET): lee la factura del Service Layer y la emite.
Dynamics 365 Business CentralExtensión AL: emite al registrar (post) la factura de venta.
Sage (50 / 200 / Business Cloud)Middleware REST (Node.js) que recibe la factura de Sage y la emite.
Zoho (Books / CRM)Función Deluge (o Zoho Flow sin código) disparada al crear la factura.
EspoCRMExtensión (hook PHP) que emite al guardar la factura; alternativa no-code con Workflow.

Descargar las extensiones

¿Usas otro sistema? Con la API REST + webhooks puedes integrar cualquier ERP/CRM. Toma el conector más parecido como base o revisa la guía de integración.

Tablas de referencia

Tipo de identificación del comprador

04RUC
05Cédula
06Pasaporte
07Consumidor final
08Identificación del exterior

Códigos de IVA (codigo_porcentaje)

00%
415%
212%
55%
6No objeto de impuesto
7Exento

Formas de pago (forma_pago)

01Sin sistema financiero (efectivo)
19Tarjeta de crédito
20Otros con sistema financiero
17Dinero electrónico

Ambiente

1Pruebas (certificación)
2Producción

¿Listo para integrar? Crea tu cuenta y obtén el token de tu emisor.