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/api/v1/compras?periodo=YYYY-MM

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

curl "https://facturacion.disisot.com/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.

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.