Comprobantes | API de facturación electrónica

Los documentos son el corazón de la API: representan cada comprobante electrónico emitido o por emitir. Esta página cubre los seis tipos SRI, la emisión automática, la descarga y el envío por correo.

Tipos de comprobante soportados

document_type_id	Código SRI	Nombre
1	01	Factura
6	03	Liquidación de Compra
2	04	Nota de Crédito
3	05	Nota de Débito
4	06	Guía de Remisión
5	07	Comprobante de Retención

Resuelve siempre document_type_id consultando /catalogs/document-types a partir del código SRI. No hardcodees los IDs en tu integración.

Estados del documento

Un documento atraviesa, en orden, los siguientes estados:

draft — borrador, todavía no enviado al SRI.
signed — XML firmado con el certificado del emisor.
recepted — recibido por el SRI, en cola de autorización.
authorizated — autorizado. Solo aquí el comprobante es válido fiscalmente.
rejected — rechazado por el SRI. Revisa errors para conocer el motivo.

Listar y consultar

GET/documents API Key

Lista los documentos de un negocio.

Colección paginada: sin page ni perPage recibes la primera página de 25 registros y el bloque meta. Ver Paginación y filtros.

Campo	Tipo	Requerido	Descripción
businessId	int	Sí	ID del negocio.
page	int	No	Número de página. Por defecto 1.
perPage	int	No	Tamaño de página. Por defecto 25, máximo 100. Alias: limit.
sortBy	string	No	Campo de ordenamiento. Valores admitidos: id, date, number, subtotal, total, createdAt, documentType, documentState, entity. Por defecto date desc.
sortDir	string	No	Sentido del ordenamiento: asc o desc.
search	string	No	Búsqueda parcial sobre número, clave de acceso, razón social e identificación del cliente.
number	string	No	Coincidencia parcial por número.
accessKey	string(49)	No	Coincidencia exacta por clave de acceso.
documentTypeCode	string(2)	No	Código del tipo de comprobante (01, 03, 04, 05, 06, 07).
documentStateAcronym	string	No	Estado del comprobante (CRD, PPR, SND, REC, DVL, AUT, NAT).
establishmentId	int	No	Filtra por establecimiento.
emissionPointId	int	No	Filtra por punto de emisión.
entityId	int	No	Filtra por cliente.
dateFrom	date	No	Fecha de emisión desde, formato Y-m-d.
dateTo	date	No	Fecha de emisión hasta, formato Y-m-d.
view	string	No	Usa summary para recibir una proyección liviana sin items ni impuestos.

GET/documents/{id} API Key

Obtiene un documento con sus items y detalles de emisión.

Campo	Tipo	Requerido	Descripción
businessId	int	Sí	ID del negocio.

Crear un documento

POST/documents API Key

Crea un documento. Con `emit: true` ejecuta el flujo completo de emisión.

Campos comunes a todos los tipos

Campo	Tipo	Requerido	Descripción
business_id	int	Sí	ID del negocio emisor.
customer_id	int	Sí	ID del cliente receptor.
document_type_id	int	Sí	Tipo de comprobante (ver tabla arriba o /catalogs/document-types).
emission_type_id	int	Sí	Tipo de emisión (ver /catalogs/emission-types).
establishment_id	int	Sí	Establecimiento emisor.
emission_point_id	int	No	Punto de emisión (ver /emission-points). Si se omite, se usa el punto "001" del establecimiento. Define la serie y el secuencial del comprobante.
payment_method_id	int	Sí	Forma de pago (ver /catalogs/payment-methods).
date	string	Sí	Fecha de emisión (YYYY-MM-DD).
detail	string	No	Descripción general del documento.
items	array	Sí	Detalle de líneas (ver más abajo).
additional_info	array	No	Campos adicionales del comprobante, hasta 11. Cada uno es { "name", "value" } con máximo 300 caracteres. Se emiten como campoAdicional; el SRI admite 15 en total y el servicio reserva cuatro (correo, celular, detalle y RUC del proveedor del sistema de facturación).
emit	bool	No	true = emite al SRI inmediatamente. false / omitido = guarda como borrador.

Campos adicionales por tipo

Nota de Crédito (04) y Nota de Débito (05): modified_document_code, modified_document_number, modified_document_date, reason.

Liquidación de Compra (03): provider_entity_id.

Guía de Remisión (06): departure_address, carrier_entity_id, transport_start_date, transport_end_date, vehicle_plate, transfer_reason.

Factura de operadora de transporte terrestre comercial (01):vehicle_plate es obligatorio al emitir líneas cuyo producto utiliza codigoAuxiliar H492001. La placa se normaliza y se genera en el elemento XML dedicado <placa>; no debe enviarse en additional_info.

Comprobante de Retención (07): a nivel de documento — related_party (bool), payment_location_id (catálogo payment-locations). En cada item — retention_tax_type_id (catálogo retention-tax-types), retention_code_id (catálogo retention-codes), retention_percentage, retention_value, support_document_type_id (catálogo document-types), support_document_number, support_document_date, sustain_code_id (catálogo sustain-codes), support_document_subtotal, support_document_tax_id (catálogo taxes), support_document_tax_value. Los campos *_id referencian el id del elemento del catálogo correspondiente. Cuando el código indique requiresExplicitPercentage: true, debes enviar explícitamente uno de sus allowedPercentages. Los códigos de porcentaje fijo sí se autocompletan.

Cuerpo de cada ítem

Campo	Tipo	Requerido	Descripción
item_id	int	Sí	ID del producto/servicio.
amount	float	Sí	Cantidad.
price	float	Sí	Precio unitario (sin impuestos).
discount	float	No	Descuento en valor absoluto sobre la línea.
detail	string	No	Descripción específica de la línea (máx. 300 caracteres, sin saltos de línea).
additional_details	array	No	Detalles adicionales de la línea, hasta 3 por ítem. Cada uno es { "name", "value" } con máximo 300 caracteres cada campo. El SRI los emite como detallesAdicionales; solo los admiten factura, liquidación de compra, nota de crédito y guía de remisión.

Ejemplo: Factura (01) con emisión automática

json

{
  "business_id": 1,
  "customer_id": 1,
  "document_type_id": 1,
  "emission_type_id": 1,
  "establishment_id": 1,
  "emission_point_id": 2,
  "payment_method_id": 1,
  "date": "2026-02-20",
  "detail": "Factura de servicios profesionales",
  "items": [
    { "item_id": 1, "discount": 0, "amount": 2, "price": 500.00, "detail": "Servicio de consultoría mensual" }
  ],
  "emit": true
}

Ejemplo: Factura de transporte terrestre comercial

El producto utilizado debe tener auxCode: H492001 y el comercio emisor debe estar clasificado como OPERADORA_TRANSPORTE_COMERCIAL. Para la factura del socio a la operadora se utiliza H492002 y la placa no es obligatoria por esta regla.

json

{
  "business_id": 1,
  "customer_id": 1,
  "document_type_id": 1,
  "emission_type_id": 1,
  "establishment_id": 1,
  "payment_method_id": 1,
  "date": "2026-10-01",
  "vehicle_plate": "ABC0123",
  "items": [
    {
      "item_id": 25,
      "amount": 1,
      "price": 150.00,
      "detail": "Servicio de transporte terrestre comercial"
    }
  ],
  "emit": true
}

Ejemplo: Factura (01) de vehículo con detalles adicionales

Una unidad nueva se identifica por su RAMV (importada) o su CPN (ensamblada en el país): la placa todavía no existe, se asigna en la matriculación. Una unidad usada se identifica por su placa y suele llevar además el kilometraje. Los identificadores van en additional_details de la línea (máx. 3) y los atributos descriptivos en additional_info del comprobante.

json

{
  "business_id": 1,
  "customer_id": 1,
  "document_type_id": 1,
  "emission_type_id": 1,
  "establishment_id": 1,
  "payment_method_id": 1,
  "date": "2026-08-29",
  "detail": "Venta de vehículo nuevo",
  "additional_info": [
    { "name": "Marca",            "value": "Chevrolet" },
    { "name": "Modelo",           "value": "Sail LS 1.5" },
    { "name": "Año",              "value": "2026" },
    { "name": "Color",            "value": "Rojo" },
    { "name": "Tipo de vehículo", "value": "Automóvil" }
  ],
  "items": [
    {
      "item_id": 12,
      "amount": 1,
      "price": 23900.00,
      "detail": "CHEVROLET SAIL LS 1.5 2026",
      "additional_details": [
        { "name": "RAMV",   "value": "C00779766" },
        { "name": "Chasis", "value": "8LDMF6842R0000001" },
        { "name": "Motor",  "value": "LDE123456" }
      ]
    }
  ],
  "emit": true
}

Ejemplo: Factura (01) como borrador (sin emitir)

json

{
  "business_id": 1,
  "customer_id": 1,
  "document_type_id": 1,
  "emission_type_id": 1,
  "establishment_id": 1,
  "payment_method_id": 1,
  "date": "2026-02-20",
  "detail": "Factura borrador",
  "items": [
    { "item_id": 1, "amount": 1, "price": 500.00 }
  ],
  "emit": false
}

Ejemplo: Nota de Crédito (04)

json

{
  "business_id": 1,
  "customer_id": 1,
  "document_type_id": 2,
  "emission_type_id": 1,
  "establishment_id": 1,
  "payment_method_id": 1,
  "date": "2026-02-20",
  "detail": "Anulación parcial de factura",
  "modified_document_code": "01",
  "modified_document_number": "001-001-000000045",
  "modified_document_date": "2026-02-15",
  "reason": "Devolución de producto defectuoso",
  "items": [
    { "item_id": 1, "amount": 1, "price": 200.00, "detail": "Producto devuelto" }
  ],
  "emit": true
}

Ejemplo: Nota de Débito (05)

json

{
  "business_id": 1,
  "customer_id": 1,
  "document_type_id": 3,
  "emission_type_id": 1,
  "establishment_id": 1,
  "payment_method_id": 1,
  "date": "2026-02-20",
  "detail": "Cobro adicional por intereses",
  "modified_document_code": "01",
  "modified_document_number": "001-001-000000045",
  "modified_document_date": "2026-02-15",
  "reason": "Cobro de intereses por mora",
  "items": [
    {
      "item_id": 1, "amount": 1, "price": 50.00,
      "detail": "Intereses por mora",
      "debit_reason": "Intereses por mora",
      "debit_value": 50.00
    }
  ],
  "emit": true
}

Ejemplo: Liquidación de Compra (03)

json

{
  "business_id": 1,
  "customer_id": 1,
  "document_type_id": 6,
  "emission_type_id": 1,
  "establishment_id": 1,
  "payment_method_id": 1,
  "date": "2026-02-20",
  "detail": "Compra a persona natural no obligada a llevar contabilidad",
  "provider_entity_id": 1,
  "items": [
    { "item_id": 1, "amount": 10, "price": 10.00, "detail": "Sacos de abono" }
  ],
  "emit": true
}

Ejemplo: Guía de Remisión (06)

json

{
  "business_id": 1,
  "customer_id": 1,
  "document_type_id": 4,
  "emission_type_id": 1,
  "establishment_id": 1,
  "payment_method_id": 1,
  "date": "2026-02-20",
  "detail": "Traslado de mercadería a sucursal Guayaquil",
  "departure_address": "Av. Amazonas N24-150, Quito",
  "carrier_entity_id": 1,
  "transport_start_date": "2026-02-21",
  "transport_end_date": "2026-02-22",
  "vehicle_plate": "ABC-1234",
  "transfer_reason": "Traslado entre sucursales",
  "items": [
    { "item_id": 1, "amount": 50, "price": 10.00, "detail": "Cajas de producto" }
  ],
  "emit": true
}

Ejemplo: Comprobante de Retención (07)

json

{
  "business_id": 1,
  "customer_id": 1,
  "document_type_id": 5,
  "emission_type_id": 1,
  "establishment_id": 1,
  "payment_method_id": 1,
  "date": "2026-02-20",
  "detail": "Retención en la fuente e IVA",
  "related_party": false,
  "payment_location_id": 1,
  "items": [
    {
      "item_id": 1, "amount": 1, "price": 1000,
      "detail": "Retención IR 1%",
      "retention_tax_type_id": 1,
      "retention_code_id": 15,
      "retention_percentage": 2.00,
      "retention_value": 20.00,
      "support_document_type_id": 1,
      "support_document_number": "001-001-000000045",
      "support_document_date": "2026-02-15",
      "sustain_code_id": 1,
      "support_document_subtotal": 1000.00,
      "support_document_tax_id": 4,
      "support_document_tax_value": 150.00
    }
  ],
  "emit": true
}

Actualizar, emitir y verificar

PUT/documents/{id} API Key

Actualiza o emite un documento existente.

El comportamiento depende del cuerpo:

Solo campos de datos → actualiza el borrador (no permitido si ya fue emitido).
{ "emit": true } → emite un borrador existente (XML → firma → SRI → autorización).
{ "verify": true } → vuelve a consultar al SRI el estado de autorización de un documento ya enviado.

json

{ "emit": true }

json

{ "verify": true }

DELETE/documents/{id} API Key

Elimina un documento. Solo se permite sobre borradores no emitidos.

Descarga y entrega

GET/documents/{id}/download API Key

Descarga el comprobante en PDF o XML.

Query string

Campo	Tipo	Requerido	Descripción
businessId	int	Sí	ID del negocio.
format	string	No	pdf (por defecto) o xml.

La respuesta tiene Content-Type: application/pdf o application/xml y un Content-Disposition: attachment con el nombre sugerido del archivo.

POST/documents/{id}/email:send API Key

Envía por correo electrónico el comprobante (PDF + XML) al cliente registrado en el documento.

Campo	Tipo	Requerido	Descripción
businessId	int	Sí	ID del negocio.

El destinatario es el email del cliente. Si el cliente no tiene email, la respuesta será 422.

Errores comunes al emitir

Causa	Cómo lo resuelves
Firma electrónica vencida o no cargada.	Sube una nueva firma en `POST /businesses/{id}/files`.
Secuencial duplicado.	Verifica con `GET /sequences` y, si hay desfase, alinea con `PUT /sequences/{id}`.
SRI no responde a tiempo.	Espera unos minutos y llama `PUT /documents/{id}` con `{ "verify": true }`.
RUC del cliente inválido.	Corrige el `identification` del cliente y vuelve a emitir.