Facturación electrónica para Ecuador

01 · INICIO RÁPIDO

Convenciones de la API

La API no utiliza un prefijo de versión en sus rutas actuales. Sustituye el dominio de ejemplo por la URL entregada para tu ambiente.

URL base

https://api.tudominio.com

Contenido

application/json

Autenticación

HTTP Basic

Respuesta

JSON

curl --request POST "https://api.tudominio.com/invoice/validate" \
  --user "usuario:contraseña" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
    "companyCode": "6f1c0c41-0000-4000-8000-000000000000",
    "voucherNumber": "2007202601000000000000110010010000001251234567811"
  }'

02 · SEGURIDAD

Autenticación

Todas las rutas descritas en esta página requieren autenticación HTTP Basic. El servidor decodifica el encabezado Authorization, busca un usuario activo y verifica su contraseña cifrada.

Authorization: Basic base64(usuario:contraseña)
Content-Type: application/json
Accept: application/json

Credenciales inválidas

{
  "message": "Unauthorized"
}

03 · CICLO DEL COMPROBANTE

Flujo de procesamiento

1. 01
   Identificar la empresa

   Se consulta una empresa activa mediante companyCode.

2. 02
   Construir o recibir el XML

   La factura se genera desde JSON o se recibe como XML completo.

3. 03
   Guardar y firmar

   Se registra el comprobante y se aplica la firma electrónica configurada.

4. 04
   Enviar a recepción

   El XML firmado se envía al servicio de recepción del ambiente de la empresa.

5. 05
   Consultar autorización

   Después de RECIBIDA, se consulta el resultado con /invoice/validate.

Construye una factura XML versión 1.0.0 a partir de JSON. El servidor completa la fecha de emisión, genera la clave de acceso, rellena el secuencial a nueve dígitos, firma y envía.

Campos del comprobante

Colecciones requeridas

Ejemplo JSON completo

{
  "companyCode": "6f1c0c41-0000-4000-8000-000000000000",
  "docCode": "01",
  "sequential": "125",
  "establishment": "001",
  "emissionPoint": "001",
  "establishmentAddress": "Otavalo, Ecuador",
  "typeId": "05",
  "socialReasonClient": "Cliente de ejemplo",
  "identificationClient": "1000000000",
  "emailClient": "cliente@example.com",
  "addressClient": "Dirección del cliente",
  "totalWithoutTaxes": "100.00",
  "totalDiscount": "0.00",
  "tip": "0.00",
  "totalAmount": "115.00",
  "currency": "DOLAR",
  "totalWithTaxesDetail": [
    {
      "code": "2",
      "codePercentage": "4",
      "taxBase": "100.00",
      "rate": "15.00",
      "value": "15.00"
    }
  ],
  "paymentsDetail": [
    {
      "paymentMethod": "01",
      "total": "115.00"
    }
  ],
  "details": [
    {
      "principalCode": "PROD-001",
      "auxCode": "A-001",
      "description": "Servicio de ejemplo",
      "quantity": "1.00",
      "unitPrice": "100.00",
      "discount": "0.00",
      "totalPriceWithoutTax": "100.00",
      "tax": [
        {
          "code": "2",
          "codePercentage": "4",
          "rate": "15.00",
          "taxBase": "100.00",
          "value": "15.00"
        }
      ]
    }
  ],
  "additionalInfo": [
    {
      "name": "Email",
      "description": "cliente@example.com"
    }
  ]
}

Los códigos tributarios y valores son ilustrativos. La integración debe usar los catálogos y reglas vigentes aplicables al emisor.

Respuesta de recepción exitosa

{
  "message": "success",
  "responseSign": "RECIBIDA",
  "voucherNumber": "clave-de-acceso-de-49-digitos"
}

Recibe una factura XML completa, obtiene sus datos principales, guarda el comprobante, aplica la firma electrónica y lo envía a recepción.

{
  "companyCode": "6f1c0c41-0000-4000-8000-000000000000",
  "xml": "<?xml version=\"1.0\" encoding=\"utf-8\"?>..."
}

Estructura XML esperada

El XML debe ser parseable y contener, como mínimo, las secciones que la implementación utiliza para registrar y firmar la factura.

<?xml version="1.0" encoding="utf-8"?>
<factura id="comprobante" version="1.0.0">
  <infoTributaria>
    <ambiente>1</ambiente>
    <tipoEmision>1</tipoEmision>
    <razonSocial>Empresa de ejemplo</razonSocial>
    <nombreComercial>Empresa de ejemplo</nombreComercial>
    <ruc>0000000000001</ruc>
    <claveAcceso>...49 dígitos...</claveAcceso>
    <codDoc>01</codDoc>
    <estab>001</estab>
    <ptoEmi>001</ptoEmi>
    <secuencial>000000125</secuencial>
    <dirMatriz>Dirección matriz</dirMatriz>
  </infoTributaria>
  <infoFactura>
    <fechaEmision>20/07/2026</fechaEmision>
    <dirEstablecimiento>Dirección del establecimiento</dirEstablecimiento>
    <tipoIdentificacionComprador>05</tipoIdentificacionComprador>
    <razonSocialComprador>Cliente de ejemplo</razonSocialComprador>
    <identificacionComprador>1000000000</identificacionComprador>
    <direccionComprador>Dirección del cliente</direccionComprador>
    <totalSinImpuestos>100.00</totalSinImpuestos>
    <totalDescuento>0.00</totalDescuento>
    <totalConImpuestos>...</totalConImpuestos>
    <propina>0.00</propina>
    <importeTotal>115.00</importeTotal>
    <moneda>DOLAR</moneda>
    <pagos>...</pagos>
  </infoFactura>
  <detalles>...</detalles>
  <infoAdicional>...</infoAdicional>
</factura>

Recupera el XML guardado, vuelve a firmarlo y lo envía al servicio de recepción. Úsalo para un comprobante existente; no crea una nueva clave de acceso.

{
  "companyCode": "6f1c0c41-0000-4000-8000-000000000000",
  "voucherNumber": "clave-de-acceso-de-49-digitos"
}

La factura debe pertenecer a la empresa indicada y encontrarse en un estado recuperable por la implementación: r, s o d.

Consulta el servicio de autorización usando la clave de acceso del comprobante guardado y el ambiente configurado para la empresa.

{
  "companyCode": "6f1c0c41-0000-4000-8000-000000000000",
  "voucherNumber": "clave-de-acceso-de-49-digitos"
}

Autorización encontrada

{
  "message": "success",
  "validateSign": "AUTORIZADO"
}

Sin comprobante en la consulta

{
  "message": "We're sorry, dont have a document in the SRI data, please contact the system administrator.",
  "result": "none"
}

04 · CONTRATO DE RESPUESTAS

Respuestas y errores

La respuesta se entrega con Content-Type: application/json. La implementación actual combina códigos HTTP con campos de negocio, por lo que el cliente debe evaluar ambos.

Comprobante devuelto por recepción

{
  "message": "We're sorry, but there was a problem with the xml SRI",
  "responseSign": {
    "RespuestaRecepcionComprobante": {
      "estado": "DEVUELTA",
      "comprobantes": {
        "...": "Detalle retornado por el SRI"
      }
    }
  },
  "voucherNumber": "clave-de-acceso-de-49-digitos"
}

Empresa no encontrada

{
  "message": "We're sorry, We did not find your company, please verify the company code.",
  "result": "none"
}

05 · PERSISTENCIA

Estados internos del comprobante

06 · CHECKLIST

Recomendaciones de integración

• Usa HTTPS. HTTP Basic solo protege credenciales cuando el transporte está cifrado.
• Separa ambientes. Verifica que la empresa esté configurada para pruebas o producción antes de emitir.
• Valida antes de enviar. Comprueba campos, decimales, totales y catálogos tributarios en tu sistema.
• Conserva la clave de acceso. El valor de voucherNumber identifica las operaciones posteriores.
• Trata recepción y autorización por separado. Después de RECIBIDA, consulta /invoice/validate.
• Controla reintentos. /invoice/create genera una nueva clave; usa /invoice/resend para el comprobante existente.
• Registra la respuesta completa. Los detalles del SRI son necesarios para diagnosticar devoluciones.
• No expongas secretos. Mantén credenciales, certificados y contraseñas fuera del navegador y de los repositorios públicos.