Ctrl K⌘K
Actualizado: Markdown Abrir en Claude Abrir en ChatGPT
En esta página

Comprobantes electrónicos POST

Emite los seis comprobantes del SRI con una ruta por tipo y una estructura JSON común, y sigue después su autorización.

Puedes emitir todos los comprobantes electrónicos, desde la factura hasta el comprobante de retención, con el mismo flujo. Eliges la ruta según el tipo, envías el JSON del comprobante, la API lo valida y te responde 202 Accepted con un idOperacion; el resultado del SRI llega después, y puedes consultarlo o recibirlo por webhook.

En esta página encuentras lo que comparten los seis tipos: las rutas y sus cabeceras, la estructura del cuerpo, las reglas de formato, cómo cuadrar los totales, la respuesta, cómo validar un comprobante sin emitirlo, los mensajes de validación y cómo reintentar sin emitir dos veces. Los campos propios de cada tipo están en su guía, que encuentras en Cómo elegir el tipo de comprobante.

Importante

Ambiente de pruebas: sin validez fiscal. Todos los ejemplos de esta página usan https://api-sandbox.mynexusapi.com y los datos de prueba.

Para agentes#

Usa esta vía cuando quieras que un agente de programación haga esta tarea en tu entorno actual.

Pega este prompt en un agente de programación con acceso a la terminal:

Prompt para agentes

Construye en este proyecto la emisión de comprobantes con la API de Ecuafact y valida un comprobante de prueba antes de emitirlo. Solo ambiente de pruebas: usa https://api-sandbox.mynexusapi.com y no emitas nada real. Si tienes la skill de Ecuafact, úsala; si no, instálala con npx skills add Ecuanexus/ecuafact-skill. Lee https://docs.mynexusapi.com/llms.txt y la guía en Markdown https://docs.mynexusapi.com/v1/guias/emision.md antes de escribir código; no inventes campos. Reutiliza el lenguaje y el SDK de Ecuafact que el proyecto ya use; si no usa ninguno, recomiéndame el SDK de su lenguaje (o el CLI ecuafact para probar, o el MCP para operar mi cuenta), con una frase de motivo y espera mi respuesta; HTTP directo solo si lo prefiero. Averigua de dónde salen los datos en este proyecto y mapea cada dato a la guía, sin inventar campos: el tipo se elige con la guía de su comprobante, los importes se calculan con las reglas de la guía y el secuencial puede omitirse. Reutiliza ECUAFACT_API_KEY sin mostrarla. Si falta, pídeme que la cree en el Portal del Cliente (Cuenta > API Keys) y la configure yo mismo en mi entorno; nunca la pegues en el chat ni la imprimas. Valida con POST /v1/contribuyentes/{identificacion}/{tipo}/validar antes de emitir, donde {tipo} es la ruta del comprobante (facturas, liquidaciones-compra, notas-credito, notas-debito, guias-remision, retenciones), y no envíes infoTributaria.tipoDocumento en el cuerpo; solo si valida, emite con POST /v1/contribuyentes/{identificacion}/{tipo}, una Idempotency-Key estable y una referenciaExterna propia. La respuesta 202 puede traer codEstado 1001 o 1002 (recibido) o ya un estado final: decide siempre por estado y codEstado, usa urlEstado tal cual y lee errores como arreglo. Ejecuta una validación y una emisión de prueba e informa solo el resultado de la validación, el estado y el codEstado de la emisión, y cualquier acción que yo deba hacer.

Conceptos#

Si ya emitiste comprobantes electrónicos, puedes pasar directamente al Endpoint. Si no, estos son los conceptos que usa el resto de la página.

  • Un comprobante electrónico es el documento fiscal que el SRI, la autoridad tributaria del Ecuador, debe autorizar para que tenga validez. Puede ser una factura, una liquidación de compra, una nota de crédito, una nota de débito, una guía de remisión o un comprobante de retención.
  • La emisión es asíncrona. Tú envías el comprobante, la API lo valida y responde 202 Accepted, con lo que el comprobante queda recibido, todavía no autorizado. El resultado del SRI llega segundos o minutos después, y lo conoces por seguimiento o por webhook.
  • Cada comprobante tiene un número con la forma estab-ptoEmi-secuencial, por ejemplo 002-001-000000124. Se compone del establecimiento y el punto de emisión, de 3 dígitos cada uno, y del secuencial, un consecutivo de 9 dígitos dentro de esa serie.
  • La clave de acceso es el número de 49 dígitos que identifica al comprobante ante el SRI. No la envías: te la asignamos nosotros y la ves en el seguimiento o en el webhook.
  • El RIDE, el PDF del comprobante, se descarga cuando el comprobante ya está autorizado.

Endpoint#

La emisión tiene una ruta por tipo de comprobante. El tipo lo fija la ruta y no el cuerpo: no envíes infoTributaria.tipoDocumento, y info solo lleva los campos de ese tipo. Elige la ruta según el comprobante que emites.

Tipo Código Ruta de emisión Ruta de validación
Factura 01 POST /v1/contribuyentes/{identificacion}/facturas POST /v1/contribuyentes/{identificacion}/facturas/validar
Liquidación de compra 03 POST /v1/contribuyentes/{identificacion}/liquidaciones-compra POST /v1/contribuyentes/{identificacion}/liquidaciones-compra/validar
Nota de crédito 04 POST /v1/contribuyentes/{identificacion}/notas-credito POST /v1/contribuyentes/{identificacion}/notas-credito/validar
Nota de débito 05 POST /v1/contribuyentes/{identificacion}/notas-debito POST /v1/contribuyentes/{identificacion}/notas-debito/validar
Guía de remisión 06 POST /v1/contribuyentes/{identificacion}/guias-remision POST /v1/contribuyentes/{identificacion}/guias-remision/validar
Comprobante de retención 07 POST /v1/contribuyentes/{identificacion}/retenciones POST /v1/contribuyentes/{identificacion}/retenciones/validar

Todas las rutas usan las mismas cabeceras. El siguiente es el ejemplo de una factura; cambia facturas por el segmento del tipo que emites.

POST /v1/contribuyentes/{identificacion}/facturas
X-Api-Key: <API Key>
Idempotency-Key: <valor estable por intencion>
Content-Type: application/json
Nombre Dónde Tipo Obligatorio Descripción
identificacion Ruta string Sí El valor contribuyentes[].identificacion de GET /v1/contexto. Es la identificación completa del contribuyente, la misma que envías en infoTributaria.ruc; en pruebas, 0123456789001.
X-Api-Key Cabecera string Sí Tu API Key.
Idempotency-Key Cabecera string Sí Identifica la intención de emitir este comprobante. Admite hasta 128 caracteres entre letras y dígitos ASCII y - _ . : /. Su uso se explica en Reintentos y duplicados.
Content-Type Cabecera string Sí application/json, o application/xml / text/xml si envías el XML del SRI.
X-Additional-Info Cabecera string No Texto tuyo que identifica la solicitud cuando pides soporte. Sus reglas están en Límites.

El cuerpo admite hasta 2 MiB y 32 niveles de anidamiento JSON. Si es mayor, la API responde 413 con el codEstado 3006 (cuerpo_excedido).

Cuerpo JSON o XML#

Los seis endpoints de emisión y sus seis validaciones aceptan el mismo comprobante en JSON o en el XML del SRI. En los dos casos la ruta fija el tipo, y el Content-Type de tu petición indica el formato del cuerpo.

Regla JSON XML
Content-Type application/json application/xml o text/xml
Tipo de comprobante Lo fija la ruta La raíz y infoTributaria.codDoc deben coincidir con la ruta
Tamaño máximo 2 MiB 2 MiB
Validación, cupo e idempotencia Sí Sí, con las mismas reglas
Firma La hace la plataforma Se ignora la firma del XML; la plataforma vuelve a firmar
origenReferencia Lo envías tú xml-sri
referenciaExterna La envías tú La claveAcceso si no es cero; si no, codDoc-estab-ptoEmi-secuencial

El XML puede estar firmado o sin firmar, porque la API descarta <ds:Signature>. En infoTributaria puedes dejar los elementos propios del XML del SRI (ambiente, tipoEmision, razonSocial, nombreComercial, claveAcceso, codDoc, dirMatriz, agenteRetencion, contribuyenteRimpe y regimenMicroempresas), que se ignoran. Cualquier otro elemento que no pertenezca al contrato se rechaza con un 400 y el codEstado 3003 (solicitud_invalida). La retención debe usar el XML 2.0 con docsSustento; el XML 1.0 que trae impuestos en la raíz responde 422 con el codEstado 3002 (comprobante_invalido).

curl -X POST "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas" \
  -H "X-Api-Key: $ECUAFACT_API_KEY" \
  -H "Idempotency-Key: factura-xml-001" \
  -H "Content-Type: application/xml" \
  --data-binary @factura.xml

La respuesta es la misma que con JSON: un 202 con el estado recibido o el rechazo con su codEstado. En las rutas /validar el XML se envía igual y la Idempotency-Key se ignora.

Antes de empezar#

  • Una API Key de pruebas. Si todavía no tienes una, crea tu sandbox.
  • En el ambiente de pruebas puedes llamar desde cualquier IP. En producción, la IP desde la que llamas debe estar registrada para tu API Key; si no lo está, la API responde 403 con el codEstado 3010 (ip_no_autorizada).
  • La identificacion del contribuyente, que obtienes de GET /v1/contexto.
  • El tipo de comprobante habilitado, es decir, que aparezca en contribuyentes[].tiposComprobante del contexto.
  • La variable de entorno ECUAFACT_API_KEY con tu API Key, para ejecutar los ejemplos.

Cómo elegir el tipo de comprobante#

Elige el tipo según lo que necesitas documentar. Cada uno tiene su guía, con sus campos propios y un ejemplo completo listo para copiar.

Si quieres... Emite Código SRI Guía
Cobrar una venta de bienes o servicios Factura 01 Factura
Documentar una compra a quien no puede emitirte factura (persona natural sin RUC, proveedor del exterior sin domicilio en Ecuador) Liquidación de compra 03 Liquidación de compra
Devolver dinero, aplicar un descuento posterior o anular total o parcialmente una factura ya autorizada Nota de crédito 04 Nota de crédito
Cobrar un valor adicional sobre una factura ya emitida (intereses por mora, recargos, gastos de cobranza) Nota de débito 05 Nota de débito
Acompañar el traslado de mercadería de un lugar a otro Guía de remisión 06 Guía de remisión
Dejar constancia de los impuestos que retienes al pagar a un proveedor Comprobante de retención 07 Comprobante de retención

Un comprobante autorizado no se edita. Si una factura autorizada tiene un error, revierte su efecto con una nota de crédito y, si corresponde, emite una factura nueva y correcta.

Estructura del comprobante#

Todos los tipos usan la misma estructura JSON. El tipo lo fija la ruta que llamas, así que el cuerpo no lleva infoTributaria.tipoDocumento. Lo que cambia de un tipo a otro son los campos que admite info y la colección de líneas.

Clave Tipo Obligatorio Contenido
origenReferencia string Sí Nombre estable del sistema que emite, por ejemplo MiERP. Se explica en origenReferencia y referenciaExterna.
referenciaExterna string Sí Identificador del documento en tu sistema, por ejemplo FACTURA-2026-0001.
infoTributaria object Sí Identidad del comprobante: emisor y serie. Sus campos están en la tabla siguiente.
info object Sí Cabecera del comprobante. Solo admite los campos del tipo de la ruta; con un campo de otro tipo, la API responde 422.
detalles array Según tipo Líneas de factura (01), liquidación de compra (03) y nota de crédito (04).
motivos array Según tipo Motivos de la nota de débito (05).
destinatarios array Según tipo Destinatario y mercadería de la guía de remisión (06).
docsSustento array Según tipo Documento sustento y retenciones del comprobante de retención (07).
infoAdicional array No Hasta 15 objetos { "nombre", "valor" } (cada uno de 1 a 300 caracteres) que se imprimen en el RIDE.

Si envías una colección que no corresponde al tipo, por ejemplo motivos en una factura, la API responde 422 con el codEstado 3002 (comprobante_invalido) y el mensaje $.motivos: Campo no soportado en este contrato.

infoTributaria#

El tipo de comprobante no va en este objeto: lo fija la ruta. Envía solo el RUC del emisor y la serie del documento.

Campo Tipo Obligatorio Regla
ruc string Sí RUC del emisor, de 5 a 13 dígitos. Envía la misma identificacion de la ruta, que es la identificación completa del contexto; en pruebas, 0123456789001. Si es distinto de la identificación de la ruta, la API responde 422 con el codEstado 3002 (comprobante_invalido).
estab string Sí Establecimiento, de hasta 3 dígitos. Se completa con ceros a la izquierda, así que 2 se toma como 002.
ptoEmi string Sí Punto de emisión, de hasta 3 dígitos. Se completa con ceros a la izquierda.
secuencial string No Secuencial, de hasta 9 dígitos, entre 1 y 999999999. Omítelo y te asignamos el siguiente, como se explica en Secuencial automático.

No envíes tipoDocumento, claveAcceso, ambiente, tipoEmision, version ni formato, ni en la raíz ni en infoTributaria. La API no admite esos campos y responde 422 con el codEstado 3002 (comprobante_invalido), con un detalle en errores como "$.infoTributaria.tipoDocumento: Campo no soportado en este contrato.". El tipo lo fija la ruta y el ambiente lo define la URL que llamas; la validación sin emitir aplica la misma regla.

Qué cambia por tipo#

Cada tipo usa una contraparte, una colección de líneas y una regla de pagos propias. La tabla resume esas diferencias.

Tipo Contraparte en info Colección Pagos (info.pagos)
01 Factura ...Comprador (quien te compra) detalles con codigoPrincipal Obligatorio
03 Liquidación de compra ...Proveedor (a quien compras) detalles con codigoPrincipal Obligatorio
04 Nota de crédito ...Comprador de la factura original detalles con codigoInterno No se envía
05 Nota de débito ...Comprador motivos Obligatorio
06 Guía de remisión Transportista destinatarios No se envía
07 Comprobante de retención ...SujetoRetenido docsSustento Dentro del sustento

Secuencial automático#

El secuencial es el contador del comprobante dentro de una serie, y puedes dejar que te lo asignemos o enviar el tuyo. Una serie es la combinación de RUC + estab + ptoEmi + tipo de comprobante + ambiente: cada serie lleva su propio contador, y el de pruebas es independiente del de producción.

Lo que envías en secuencial Qué número recibe el comprobante
Nada (omites el campo), "" o solo ceros ("000000000") Te asignamos el siguiente número libre de la serie. Te recomendamos esta opción, porque no necesitas llevar el contador en tu sistema.
Un número ("124" o "000000124") Usamos ese número, completado a 9 dígitos.

Para conocer el número asignado, búscalo en el seguimiento, que lo devuelve en numeroDocumento (002-001-000000124). La claveAcceso que trae el seguimiento, cuando el comprobante ya la tiene, también contiene el secuencial.

Nota

Te recomendamos usar un solo modo por serie. Si mezclas números propios con el automático, el automático continúa desde el mayor número usado y tus números propios pueden chocar con uno ya emitido; en ese caso la API responde 409 con el codEstado 3004 (comprobante_duplicado).

origenReferencia y referenciaExterna#

Son los identificadores de tu sistema. Con ellos puedes encontrar la operación desde tu ERP, evitar emitir dos veces el mismo documento y cruzar el comprobante con tu registro contable.

Campo Para qué sirve Formato Ejemplos
origenReferencia Nombra el sistema o módulo que emite. Usa siempre el mismo valor desde el mismo sistema. 1 a 64 caracteres: letras y dígitos ASCII y - _ . : /. Sin espacios. MiERP, tienda-web, pos.local-03
referenciaExterna Identifica el documento dentro de ese sistema, como tu número interno de factura, pedido o nota. 1 a 128 caracteres, con el mismo alfabeto. FACTURA-2026-0001, PED/2026/10/0457, NC-00031

La pareja origenReferencia + referenciaExterna es única por contribuyente emisor y por ambiente, y vale para todas las API Key de tu integración: dos RUC de tu integración pueden usar la misma referencia. Si envías la misma pareja con el mismo cuerpo, la API la trata como un reintento y responde 202 con la misma operación. Si la envías con otro cuerpo, responde 409 con el codEstado 3005 (conflicto_idempotencia). Por eso, para corregir un comprobante rechazado, usa una referenciaExterna nueva, por ejemplo FACTURA-2026-0001-R1.

Reglas de formato#

Cada dato del comprobante tiene un formato fijo, y la API responde 422 a cualquier valor que no lo cumpla.

Dato Formato Ejemplo correcto Error común
Importes (total, valor, baseImponible...) Número JSON con punto decimal y como máximo 2 decimales. 52.44 "52,44" o 52.444
cantidad, precioUnitario Número JSON, hasta 6 decimales. 1.0112 1.0112345
tarifa Número JSON de 0 a 99.99, hasta 2 decimales, igual a la tarifa del codigoPorcentaje en el catálogo del SRI. 15 0.15 (es porcentaje, no fracción)
Códigos (codigoPorcentaje, formaPago, tipos de identificación) Cadena JSON. "01" 1 (número)
Identificaciones (ruc, identificacionComprador) Cadena de dígitos. "0123456789" 123456789 (pierde el cero inicial)
Fechas fiscales (fechaEmision, fechaEmisionDocSustento) dd/MM/yyyy, del 01/01/2000 al 31/12/2099. Envía en fechaEmision la fecha de hoy, porque, salvo en la retención, el comprobante autorizado lleva la fecha del día en que se procesa aunque envíes otra. "07/10/2026" "2026-10-07"
Periodo fiscal (retención) MM/yyyy. "10/2026" "2026-10"
Número de un documento (numDocModificado) ddd-ddd-ddddddddd. "002-001-000000123" "123" (solo el secuencial)
Textos Sin caracteres de control, como saltos de línea o tabuladores, y dentro del máximo de cada campo, que indica la guía de cada tipo. Ningún texto supera 500 caracteres. "CONSULTORIA MENSUAL" Texto vacío o solo espacios en un campo obligatorio
Campos de cada objeto Exactamente los nombres documentados, una sola vez. "precioUnitario" Un campo desconocido o repetido, que la API rechaza con un 422

Un número obligatorio que omites no se toma como cero: la API responde 422 con Campo obligatorio. Por eso, cuando el valor es cero, envía 0 de forma explícita.

Cómo calcular los totales#

Esta sección cuadra paso a paso los totales de una factura con tres líneas: una con descuento, una con un precio de 4 decimales y una con IVA 0 %. Las reglas son las mismas para la liquidación de compra y, sin propina ni pagos, para la nota de crédito.

Reglas#

Valor Fórmula Redondeo
precioTotalSinImpuesto de la línea cantidad x precioUnitario - descuento A 2 decimales.
descuento de la línea Importe en dólares, no porcentaje. Un 10 % sobre 37.50 se envía como 3.75. Ya con 2 decimales.
baseImponible del IVA de la línea Igual a precioTotalSinImpuesto (más el ICE de la línea, si lo hay). 2 decimales.
valor del IVA de la línea (cantidad x precioUnitario - descuento) x tarifa / 100, calculado con la base sin redondear. A 2 decimales; el 5 sube (0.455 -> 0.46).
totalConImpuestos[] (cabecera) Una fila por cada pareja codigo + codigoPorcentaje: baseImponible = suma de las bases de esas líneas; valor = suma de los valor de esas líneas. Suma, sin recalcular. Máximo 2 filas.
totalSinImpuestos Suma de precioTotalSinImpuesto de todas las líneas (ya con el descuento restado). Suma.
totalDescuento Suma de descuento de todas las líneas. Suma.
importeTotal totalSinImpuestos + suma de los IVA + suma de los ICE + propina. Suma.
pagos[].total La suma de todos los pagos es igual a importeTotal. Suma.

Calcula todos los valores en tu sistema antes de enviarlos. La API no calcula ni corrige ninguno: compara lo que envías con estas fórmulas y, si algo no cuadra al centavo, responde 422.

Paso 1: cada línea#

Línea Cantidad x precio Descuento precioTotalSinImpuesto Tarifa IVA (valor)
1. Consultoría 3 x 12.50 = 37.50 2.50 37.50 - 2.50 = 35.00 15 % (codigoPorcentaje 4) 35.00 x 15 / 100 = 5.25
2. Repuesto 3 x 1.0112 = 3.0336 0 3.0336 -> 3.03 15 % (4) 3.0336 x 15 / 100 = 0.45504 -> 0.46
3. Libro 2 x 4.35 = 8.70 0 8.70 0 % (0) 0

En la línea 2, el IVA se calcula sobre 3.0336, la base sin redondear, y da 0.46. Si lo calcularas sobre 3.03 daría 0.45, y la API respondería Valor de impuesto no coincide con base y tasa.

Paso 2: impuestos de cabecera#

Agrupa las líneas por codigo + codigoPorcentaje y suma sus bases y sus valores.

Grupo baseImponible valor
IVA 15 % (2 + 4) 35.00 + 3.03 = 38.03 5.25 + 0.46 = 5.71
IVA 0 % (2 + 0) 8.70 0

El valor de cabecera es la suma de los valores de las líneas, 5.71, y no el 15 % de 38.03, que daría 5.70.

Paso 3: totales y pagos#

Campo Cálculo Valor
totalSinImpuestos 35.00 + 3.03 + 8.70 46.73
totalDescuento 2.50 + 0 + 0 2.50
propina Sin propina 0
importeTotal 46.73 + 5.71 + 0 52.44
pagos 20.00 en efectivo (01) + 32.44 con tarjeta de crédito (19) 52.44

El comprobante completo#

Este es el comprobante con los totales del ejemplo. Guárdalo como comprobante.json, porque lo usan los ejemplos de la sección siguiente.

{
  "origenReferencia": "MiERP",
  "referenciaExterna": "FACTURA-2026-0001",
  "infoTributaria": {
    "ruc": "0123456789001",
    "estab": "002",
    "ptoEmi": "001"
  },
  "info": {
    "fechaEmision": "07/10/2026",
    "tipoIdentificacionComprador": "05",
    "identificacionComprador": "0123456789",
    "razonSocialComprador": "CONTRIBUYENTE DE PRUEBAS",
    "direccionComprador": "DIRECCION DE PRUEBAS",
    "totalSinImpuestos": 46.73,
    "totalDescuento": 2.50,
    "totalConImpuestos": [
      {
        "codigo": "2",
        "codigoPorcentaje": "4",
        "tarifa": 15,
        "baseImponible": 38.03,
        "valor": 5.71
      },
      {
        "codigo": "2",
        "codigoPorcentaje": "0",
        "tarifa": 0,
        "baseImponible": 8.70,
        "valor": 0
      }
    ],
    "propina": 0,
    "importeTotal": 52.44,
    "moneda": "DOLAR",
    "pagos": [
      {
        "formaPago": "01",
        "total": 20.00
      },
      {
        "formaPago": "19",
        "total": 32.44
      }
    ]
  },
  "detalles": [
    {
      "codigoPrincipal": "SERV-001",
      "descripcion": "CONSULTORIA",
      "cantidad": 3,
      "precioUnitario": 12.50,
      "descuento": 2.50,
      "precioTotalSinImpuesto": 35.00,
      "impuestos": [
        {
          "codigo": "2",
          "codigoPorcentaje": "4",
          "tarifa": 15,
          "baseImponible": 35.00,
          "valor": 5.25
        }
      ]
    },
    {
      "codigoPrincipal": "REP-002",
      "descripcion": "REPUESTO",
      "cantidad": 3,
      "precioUnitario": 1.0112,
      "descuento": 0,
      "precioTotalSinImpuesto": 3.03,
      "impuestos": [
        {
          "codigo": "2",
          "codigoPorcentaje": "4",
          "tarifa": 15,
          "baseImponible": 3.03,
          "valor": 0.46
        }
      ]
    },
    {
      "codigoPrincipal": "LIB-003",
      "descripcion": "LIBRO",
      "cantidad": 2,
      "precioUnitario": 4.35,
      "descuento": 0,
      "precioTotalSinImpuesto": 8.70,
      "impuestos": [
        {
          "codigo": "2",
          "codigoPorcentaje": "0",
          "tarifa": 0,
          "baseImponible": 8.70,
          "valor": 0
        }
      ]
    }
  ],
  "infoAdicional": [
    {
      "nombre": "Pedido",
      "valor": "PED-2026-0457"
    }
  ]
}

El comprobante no lleva secuencial, así que te asignamos el siguiente número de la serie 002-001. Los códigos de tarifa están en Catálogos: tarifas de IVA y los de pago en Catálogos: formas de pago.

Ejemplo de emisión#

Con el JSON de El comprobante completo guardado como comprobante.json, ejecuta uno de estos ejemplos. Todos envían la misma Idempotency-Key, así que si repites la petición no se emite un segundo comprobante.

curl -s -i -X POST \
  "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas" \
  -H "X-Api-Key: $ECUAFACT_API_KEY" \
  -H "Idempotency-Key: FACTURA-2026-0001" \
  -H "Content-Type: application/json" \
  -d @comprobante.json
# 202 Accepted -> sigue con GET /v1/operaciones/{idOperacion}
using System.Net.Http;
using System.Text;

string apiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!;
using var http = new HttpClient { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com") };
http.DefaultRequestHeaders.Add("X-Api-Key", apiKey);

using var peticion = new HttpRequestMessage(HttpMethod.Post, "/v1/contribuyentes/0123456789001/facturas");
peticion.Headers.Add("Idempotency-Key", "FACTURA-2026-0001");
peticion.Content = new StringContent(
    await File.ReadAllTextAsync("comprobante.json"), Encoding.UTF8, "application/json");

using HttpResponseMessage respuesta = await http.SendAsync(peticion);
Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}");
import json
import os
import requests

with open("comprobante.json", encoding="utf-8") as archivo:
    cuerpo = json.load(archivo)

r = requests.post(
    "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas",
    headers={
        "X-Api-Key": os.environ["ECUAFACT_API_KEY"],
        "Idempotency-Key": "FACTURA-2026-0001",
    },
    json=cuerpo,
    timeout=30,
)
print(r.status_code, r.text)
// Node.js 18 o superior. Guarda como emitir.mjs y ejecuta: node emitir.mjs
import { readFile } from 'node:fs/promises';

const res = await fetch(
  'https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': process.env.ECUAFACT_API_KEY,
      'Idempotency-Key': 'FACTURA-2026-0001',
      'Content-Type': 'application/json'
    },
    body: await readFile('comprobante.json', 'utf8')
  });
console.log(res.status, await res.text());
<?php
$ch = curl_init('https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'X-Api-Key: ' . getenv('ECUAFACT_API_KEY'),
        'Idempotency-Key: FACTURA-2026-0001',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => file_get_contents('comprobante.json'),
]);
$cuerpo = curl_exec($ch);
$estado = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $estado . ' ' . $cuerpo . PHP_EOL;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Files;
import java.nio.file.Path;

// Dentro de: public static void main(String[] args) throws Exception
HttpClient cliente = HttpClient.newHttpClient();
HttpRequest peticion = HttpRequest.newBuilder()
    .uri(URI.create("https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas"))
    .header("X-Api-Key", System.getenv("ECUAFACT_API_KEY"))
    .header("Idempotency-Key", "FACTURA-2026-0001")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(Files.readString(Path.of("comprobante.json"))))
    .build();
HttpResponse<String> respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofString());
System.out.println(respuesta.statusCode() + " " + respuesta.body());
using Ecuafact.Sdk;

// client: EcuafactClient creado con tu API Key (ver SDK .NET)
// comprobante: FacturaRequest con la Estructura del comprobante
EmisionResultado resultado = await client.EmitirAsync("0123456789001", comprobante, "FACTURA-2026-0001");
Console.WriteLine($"Operacion {resultado.Admission.IdOperacion} / estado: {resultado.Admission.Estado} / codEstado: {resultado.Admission.CodEstado}");
from ecuafact import EcuafactClient

# client: EcuafactClient creado con tu API Key (ver SDK Python)
# comprobante: FacturaRequest con la Estructura del comprobante
resultado = client.emitir_en("0123456789001", comprobante, "FACTURA-2026-0001")
print(f"Operacion {resultado.admission.id_operacion} / estado: {resultado.admission.estado} / codEstado: {resultado.admission.cod_estado}")
import { EcuafactClient } from "@ecuafact/sdk";

// client: EcuafactClient creado con tu API Key (ver SDK Node.js)
// comprobante: FacturaRequest con la Estructura del comprobante
const resultado = await client.emitirFacturaEn("0123456789001", comprobante, "FACTURA-2026-0001");
console.log(`Operacion ${resultado.admission.idOperacion} / estado: ${resultado.admission.estado} / codEstado: ${resultado.admission.codEstado}`);
<?php
use Ecuafact\Sdk\EcuafactClient;

// $client: EcuafactClient creado con tu API Key (ver SDK PHP)
// $comprobante: FacturaRequest con la Estructura del comprobante
$resultado = $client->emitirEn('0123456789001', $comprobante, 'FACTURA-2026-0001');
echo 'Operacion ' . $resultado->admission->idOperacion . ' / estado: ' . $resultado->admission->estado
    . ' / codEstado: ' . $resultado->admission->codEstado . PHP_EOL;
import com.ecuafact.sdk.EcuafactClient;
import com.ecuafact.sdk.EmisionResultado;

// client: EcuafactClient creado con tu API Key (ver SDK Java)
// comprobante: FacturaRequest con la Estructura del comprobante
EmisionResultado resultado = client.emitirEn("0123456789001", comprobante, "FACTURA-2026-0001");
System.out.println("Operacion " + resultado.admission().idOperacion() + " / estado: " + resultado.admission().estado()
    + " / codEstado: " + resultado.admission().codEstado());
# Resultado esperado: una fila con el estado recibido y el idOperacion de la emisión.
ecuafact emitir comprobante.json --entorno sandbox

Si no le pasas la Idempotency-Key, el SDK la genera por ti y la devuelve en EmisionResultado. Guárdala, porque debes reutilizarla en cualquier reintento.

Respuesta#

La API responde 202 Accepted con este cuerpo, que tiene la misma forma del seguimiento de la operación:

{
  "estado": "recibido",
  "codEstado": 1001,
  "errores": [],
  "idOperacion": "3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f",
  "urlEstado": "https://api-sandbox.mynexusapi.com/v1/operaciones/3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f",
  "ambiente": 1,
  "tipoDocumento": "01",
  "numeroDocumento": "002-001-000000124",
  "referenciaExterna": "FACTURA-2026-0001",
  "claveAcceso": null,
  "fhRecibido": "2026-11-16T10:15:00-05:00",
  "fhAutorizacion": null
}
Campo Tipo Descripción
estado string recibido: el comprobante pasó nuestras validaciones y lo aceptamos. No es una autorización del SRI.
codEstado number 1001 si el comprobante todavía no tiene clave de acceso, o 1002 si ya la tiene. Tu sistema debe aceptar los dos valores.
errores array de string Viene siempre; en una emisión recibida es una lista vacía.
idOperacion string (UUID) Identificador de la operación. Guárdalo junto a tu documento, porque lo necesitas para el seguimiento y llega en el webhook.
urlEstado string URL completa del seguimiento, https://<URL del ambiente>/v1/operaciones/{idOperacion}. Puedes llamarla tal como viene.
ambiente number 1 para pruebas y 2 para producción, según la URL que llamaste.
tipoDocumento string Tipo de comprobante: 01, 03, 04, 05, 06 o 07.
numeroDocumento string o null Número del comprobante con la forma estab-ptoEmi-secuencial. Si omitiste el secuencial, aquí ves el que te asignamos.
referenciaExterna string o null La referenciaExterna que enviaste.
claveAcceso string o null Clave de acceso de 49 dígitos. Es null con el codEstado 1001 y viene con el 1002. Si es null, la obtienes después en el seguimiento o en el webhook.
fhRecibido string Fecha y hora en que recibimos la emisión, en ISO 8601 con la zona horaria de Ecuador.
fhAutorizacion string o null Fecha y hora de autorización; en el 202 de una emisión nueva es null.

El campo msgError no aparece porque la emisión no tiene error. Te recomendamos leer el 202 con la misma lógica que el seguimiento: decide con estado y codEstado y trata la claveAcceso como opcional mientras el estado sea recibido.

Cabecera Descripción
Location La misma URL completa que urlEstado.
X-Correlation-Id Identificador de la petición. Inclúyelo si pides soporte.

Un reintento con la misma Idempotency-Key y el mismo cuerpo, o con la misma origenReferencia + referenciaExterna y el mismo cuerpo, responde un 202 con el mismo idOperacion y el estado actual de esa operación, sin crear otro comprobante. El resultado actual de esa operación lo ves siempre en el seguimiento.

El 202 puede traer autorizado (2001) si la emisión directa ya conoce el resultado; en ese caso no sigas esperando. Si ya conoce un rechazo definitivo, rechazado (3xxx, con el detalle del SRI en errores) o rechazo_configuracion (4xxx), la respuesta no es un 202 sino un 422 con el mismo cuerpo de la operación: estado, codEstado, msgError, errores, idOperacion y urlEstado. Un reintento con la misma Idempotency-Key y el mismo cuerpo devuelve el mismo 422; corrige la causa y emite con una referenciaExterna nueva. Cuando el 202 trae recibido, el comprobante todavía no está autorizado; después de recibirlo, sigue estos pasos:

  1. Guarda idOperacion junto a tu documento.
  2. Espera el webhook (document.authorized, document.rejected o document.failed) o consulta GET /v1/operaciones/{idOperacion} mientras su estado sea recibido.
  3. Con autorizado, descarga el RIDE o el XML. Con cualquier otro estado final, lee el codEstado y el detalle de errores, corrige la causa y reenvía el comprobante como se explica en Reintentos y duplicados.

Cada comprobante que el SRI autoriza o rechaza consume un documento de tu cupo, y uno cancelado lo libera. Una solicitud mal formada (400) no consume cupo, y un 422 por validación consume 1 documento como intento. El detalle está en Consumo y cuotas.

Validar sin emitir#

Antes de emitir puedes comprobar que un comprobante está bien armado. La validación aplica las mismas reglas que la emisión: la estructura, los formatos, los totales, los impuestos y los pagos, que infoTributaria.ruc corresponda al contribuyente de la ruta y que el contribuyente y el tipo de comprobante estén habilitados para tu API Key. No emite nada, no consume cupo ni usa un número de la serie, y no necesita Idempotency-Key. Si tu cliente la envía siempre, la validación la ignora: no la valida ni la guarda, y reutilizarla con otro cuerpo no produce un 409. Cada validación cuenta para tu límite de solicitudes por minuto.

Te sirve sobre todo cuando generas los comprobantes de forma automática, por ejemplo desde un archivo o con un asistente de IA: validas el lote completo, corriges lo que falle y emites después solo lo que pasó.

La ruta de validación es la de emisión del tipo con /validar al final. Para una factura:

POST /v1/contribuyentes/{identificacion}/facturas/validar
X-Api-Key: <API Key>
Content-Type: application/json

El cuerpo y sus límites son los mismos de Endpoint, sin la cabecera Idempotency-Key. Si el comprobante cumple todas las reglas, la API responde 200 OK con este cuerpo:

{
  "valido": true,
  "errores": []
}
Campo Tipo Descripción
valido boolean true cuando el comprobante cumple todas las reglas de la emisión.
errores array de string Viene siempre y, en una validación correcta, es una lista vacía.

Si no las cumple, responde el mismo código que daría la emisión, con la forma de error de toda la API (estado, codEstado, msgError y errores): un 422 con el codEstado 3002 (comprobante_invalido) y hasta 20 problemas en errores, como se explica en Errores de validación, o un 403 con el codEstado 3011 (acceso_denegado) si el contribuyente, su RUC o el tipo de comprobante no están habilitados para tu API Key.

Un 200 significa que, con el contenido que enviaste, la emisión no tendrá errores de validación. La validación no comprueba tu cupo ni si ya emitiste ese comprobante, así que al emitir todavía puedes recibir un 429 con el codEstado 4004 si no tienes un paquete vigente con saldo, o la respuesta de un reintento si ya usaste esa Idempotency-Key. Tampoco es una autorización del SRI: el resultado fiscal llega solo después de emitir.

Estos ejemplos validan el comprobante.json de Ejemplo de emisión:

curl -s -X POST   "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas/validar"   -H "X-Api-Key: $ECUAFACT_API_KEY"   -H "Content-Type: application/json"   -d @comprobante.json
# 200 OK con valido en true si cumple todas las reglas; si no, el error de la emisión.
using System.Net.Http;
using System.Text;

string apiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!;
using var http = new HttpClient { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com") };
http.DefaultRequestHeaders.Add("X-Api-Key", apiKey);

using var contenido = new StringContent(
    await File.ReadAllTextAsync("comprobante.json"), Encoding.UTF8, "application/json");
using HttpResponseMessage respuesta = await http.PostAsync("/v1/contribuyentes/0123456789001/facturas/validar", contenido);
Console.WriteLine($"{(int)respuesta.StatusCode} {await respuesta.Content.ReadAsStringAsync()}");
import json
import os
import requests

with open("comprobante.json", encoding="utf-8") as archivo:
    cuerpo = json.load(archivo)

r = requests.post(
    "https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas/validar",
    headers={"X-Api-Key": os.environ["ECUAFACT_API_KEY"]},
    json=cuerpo,
    timeout=30,
)
print(r.status_code, r.text)
// Node.js 18 o superior. Guarda como validar.mjs y ejecuta: node validar.mjs
import { readFile } from 'node:fs/promises';

const res = await fetch(
  'https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas/validar',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': process.env.ECUAFACT_API_KEY,
      'Content-Type': 'application/json'
    },
    body: await readFile('comprobante.json', 'utf8')
  });
console.log(res.status, await res.text());
<?php
$ch = curl_init('https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas/validar');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'X-Api-Key: ' . getenv('ECUAFACT_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => file_get_contents('comprobante.json'),
]);
$cuerpo = curl_exec($ch);
$estado = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $estado . ' ' . $cuerpo . PHP_EOL;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Files;
import java.nio.file.Path;

// Dentro de: public static void main(String[] args) throws Exception
HttpClient cliente = HttpClient.newHttpClient();
HttpRequest peticion = HttpRequest.newBuilder()
    .uri(URI.create("https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas/validar"))
    .header("X-Api-Key", System.getenv("ECUAFACT_API_KEY"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(Files.readString(Path.of("comprobante.json"))))
    .build();
HttpResponse<String> respuesta = cliente.send(peticion, HttpResponse.BodyHandlers.ofString());
System.out.println(respuesta.statusCode() + " " + respuesta.body());
# Resultado esperado: una fila con el estado valido, o invalido con el error de la API.
ecuafact validar comprobante.json --entorno sandbox

Errores de validación#

Cuando una emisión no pasa la validación, la API responde con el primer problema que encontró, así que cada respuesta te dice qué corregir. Si el cuerpo tiene errores y además falta la cabecera Idempotency-Key, primero recibes el error del cuerpo.

Un 400 con el codEstado 3003 (solicitud_invalida) significa que la petición está mal formada, porque el JSON está roto o la cabecera Idempotency-Key falta o no es válida. Un 422 con el codEstado 3002 (comprobante_invalido) significa que la API entendió la petición, pero el comprobante no cumple una regla.

Un 400 no consume cupo; un 422 consume 1 documento como intento. Ninguno de los dos usa un número de la serie. Corrige el dato y reenvía con la misma Idempotency-Key.

Así se ve un error de validación. Tiene la misma forma de la respuesta 202, con idOperacion, urlEstado, numeroDocumento, claveAcceso y las fechas en null, porque no se creó ninguna operación:

{
  "estado": "rechazado",
  "codEstado": 3002,
  "msgError": "El comprobante no cumple las validaciones.",
  "errores": [
    "$.info.pagos[0].unidadTiempo: Obligatoria cuando hay plazo."
  ],
  "idOperacion": null,
  "urlEstado": null,
  "ambiente": 1,
  "tipoDocumento": "01",
  "numeroDocumento": null,
  "referenciaExterna": "FACTURA-2026-0001",
  "claveAcceso": null,
  "fhRecibido": null,
  "fhAutorizacion": null
}
Campo Tipo Descripción
estado string rechazado en los errores de validación.
codEstado number Código estable para programar, como 3003 (solicitud_invalida) o 3002 (comprobante_invalido).
msgError string Descripción general y fija del código. Puedes mostrarla, pero no decidas con ella.
errores array de string Viene siempre. En 3002 (comprobante_invalido) trae hasta 20 mensajes, uno por problema, cada uno con la ruta del campo y, cuando corresponde, la posición de la línea o del impuesto ($.info.pagos[0].unidadTiempo, $.detalles[3].impuestos[0].valor). En 3003 (solicitud_invalida) trae el detalle de los parámetros o del cuerpo que no se pudo leer; puede ser más de uno. En los demás errores es una lista vacía. Corrige todos los que puedas y reenvía; los que no se hayan podido validar aparecerán en la siguiente respuesta.
ambiente, tipoDocumento y referenciaExterna Vienen con el valor de tu petición cuando la API pudo leerlo; si no, son null.

Mensajes de validación frecuentes#

Estos son los mensajes de errores que aparecen con más frecuencia al emitir cualquier tipo de comprobante.

Mensaje (en errores) Causa Qué hacer
Campo no soportado en este contrato. Un campo que la API no conoce en ese objeto, como claveAcceso, ambiente, un campo de info, una colección o un código de línea de otro tipo (motivos o codigoInterno en una factura), o un nombre mal escrito. Quita el campo o corrige su nombre; envía solo los campos y la colección de la guía del tipo, según Qué cambia por tipo.
Valor o tipo inválido. Un tipo JSON incorrecto: un número donde va una cadena ("estab": 2) o un texto donde va un número. A veces añade qué se esperaba, por ejemplo Valor o tipo inválido: se esperaba texto. Envía los códigos como cadena y los importes como número.
Campo obligatorio. / Texto vacio o longitud excedida. Falta un campo obligatorio, está vacío o supera su largo. Completa el campo indicado en la ruta.
Numero fuera de rango. Un número negativo o demasiado grande. Envía importes positivos: la nota de crédito y la retención también llevan valores positivos.
La creación de este tipo requiere un contribuyente identificado. Tipo de identificación 07 (consumidor final) en un tipo distinto de la factura. Identifica a la contraparte con RUC, cédula, pasaporte o identificación del exterior.
Para una factura mayor a $50, seleccione un cliente con cedula, RUC o pasaporte... Una factura a consumidor final (07) con importeTotal mayor que 50. Identifica al comprador con RUC, cédula o pasaporte.
Lista vacia, invalida o demasiado extensa. Falta una lista obligatoria (detalles, pagos, totalConImpuestos) o supera su máximo. Envía al menos un elemento y respeta el máximo.
Use dd/MM/yyyy, como el SRI. Fecha en otro formato. Usa 07/10/2026.
El RUC no corresponde al contribuyente del contexto. infoTributaria.ruc no corresponde a la identificacion de la ruta. Usa el RUC completo del contribuyente de la ruta.
Subtotal del detalle no coincide... precioTotalSinImpuesto distinto de cantidad x precioUnitario - descuento redondeado. Recalcula la línea.
Valor de impuesto no coincide con base y tasa. El IVA de una línea no es la base sin redondear por la tarifa, redondeado a 2 decimales. Calcula el IVA antes de redondear la base.
Base IVA debe incluir subtotal e ICE. La baseImponible del IVA es distinta de precioTotalSinImpuesto más el ICE de la línea. Usa el subtotal de la línea como base.
Base o valor de impuestos no coincide con detalles. Una fila de totalConImpuestos no es la suma de sus líneas. Suma bases y valores por codigo + codigoPorcentaje.
Los impuestos de cabecera no corresponden a los detalles. Falta o sobra una fila en totalConImpuestos, o hay dos filas con el mismo codigo + codigoPorcentaje. Envía exactamente una fila por grupo de las líneas.
Totales no coinciden con detalles. totalSinImpuestos, totalDescuento o la suma de IVA no cuadra con las líneas. Suma de nuevo las líneas.
total no coincide con subtotal + IVA + ICE + propina. El importeTotal, o el valorModificacion en la nota de crédito, está mal calculado. Aplica la fórmula del total.
Pagos no coinciden con total. La suma de pagos[].total es distinta de importeTotal. Ajusta los pagos al total.
...importe no admitido; no se redondea silenciosamente. Un importe con más de 2 decimales, o cantidad o precio con más de 6. Redondea en tu sistema antes de enviar.

Cada guía de tipo agrega los mensajes propios de ese comprobante.

Reintentos y duplicados#

Con la Idempotency-Key puedes reintentar un envío sin emitir dos veces el mismo comprobante. Usa un valor estable por intención, como tu número interno del documento (FACTURA-2026-0001) o un UUID v4 que guardas junto al documento antes de enviarlo. La API recuerda la clave durante 7 días, por integración y por ambiente.

Situación Qué envías Resultado Qué hacer
Timeout, error de red o 5xx sin respuesta clara La misma Idempotency-Key y el mismo cuerpo. 202 con el mismo idOperacion si el primer intento llegó, o con una operación nueva si nunca llegó. Continúa con el seguimiento de ese idOperacion.
Reenvío accidental del mismo documento La misma Idempotency-Key y el mismo cuerpo. 202 con el mismo idOperacion. No hagas nada; no se emitió otro comprobante.
Misma Idempotency-Key con un cuerpo distinto La clave repetida y el cuerpo cambiado. 409 con el codEstado 3005 (conflicto_idempotencia). Si es otro documento, usa otra clave. Si es una corrección, sigue la fila del rechazo que corresponda.
Misma origenReferencia + referenciaExterna con un cuerpo distinto, o con otro tipo de comprobante Una clave nueva y una referencia que ya usó otro comprobante. 409 con el codEstado 3005 (conflicto_idempotencia). Usa una referenciaExterna nueva para el documento corregido.
Número (estab-ptoEmi-secuencial) de un comprobante autorizado, pendiente o rechazado por el SRI Un secuencial propio que ya se usó. 409 con el codEstado 3004 (comprobante_duplicado). No reenvíes, porque ese número ya existe. Si el comprobante anterior fue rechazado por el SRI, emite con un secuencial nuevo; omite secuencial para que se asigne el siguiente.
Corregir un comprobante que no se emitió: estado rechazado con el codEstado 3002, rechazo_configuracion con cualquier código 4xxx, o error con el 5006 (entrega_no_posible) El cuerpo corregido, una nueva Idempotency-Key, una nueva referenciaExterna y, para conservar el número, el mismo estab, ptoEmi y secuencial en infoTributaria. 202, que puede traer el mismo idOperacion. Si corriges el contenido tras un rechazo, cuenta como otro envío y consume 1 documento; si reenvías con el mismo número tras un error 5006, no consume otro, como se explica en Consumo y cuotas. Sigue la operación como siempre.
Reenviar una operación cancelado Una nueva Idempotency-Key y una nueva referenciaExterna; puedes usar el mismo número. 202 con estado en recibido y el codEstado 1001 o 1002. Sigue la operación. Si envías la misma referenciaExterna y el mismo cuerpo, la API devuelve la operación cancelada y no emite.
Corregir un comprobante rechazado por el SRI (estado rechazado con el codEstado 3001) El cuerpo corregido, una nueva Idempotency-Key y una nueva referenciaExterna, sin secuencial para que se asigne automáticamente. 202 con una operación nueva. Emite con un secuencial nuevo, porque si reutilizas el mismo número la API responde 409 con el codEstado 3004 (comprobante_duplicado).
estado error con el codEstado 5007 (resultado_no_confirmado) o 5001 (error_interno) Nada todavía. - No reemitas, porque el comprobante podría existir. Búscalo en el seguimiento y escribe a soporte con el idOperacion.

Si omitiste el secuencial y quieres conservar el número al reenviar, búscalo en el numeroDocumento de la respuesta 202 o del seguimiento; si no lo necesitas, deja que se asigne el siguiente.

Atención

No generes una Idempotency-Key nueva para reintentar un envío cuyo resultado no conoces (timeout). Si el primer intento llegó, la clave nueva emite un segundo comprobante, con otro número y otro cupo consumido.

Estados de este endpoint#

Esta tabla reúne todas las respuestas posibles de la emisión. Todas, incluidos los errores, traen la forma de la respuesta 202 que se explica en Respuesta.

codEstado HTTP Cuándo ocurre Qué hacer
1001, 1002 o 2001 202 La API recibió el comprobante, o reintentaste con la misma Idempotency-Key o la misma referencia y el mismo cuerpo. El 2001 indica que la autorización ya se conoce. Guarda idOperacion y sigue la operación; un reintento no emite otro comprobante y trae el estado actual.
3003 (solicitud_invalida) 400 El JSON o el XML está mal formado, o la Idempotency-Key falta o no es válida. Corrige la petición y reenvía.
3002 (comprobante_invalido) 422 El comprobante no cumple una regla de estructura o fiscal; el detalle viene en errores. Corrige el campo indicado. Consume 1 documento como intento.
3xxx o 4xxx 422 La emisión directa ya conoce un rechazo definitivo (rechazado o rechazo_configuracion); el cuerpo trae el codEstado, el msgError y el detalle en errores. Corrige la causa según el codEstado y emite con una referenciaExterna nueva.
3006 (cuerpo_excedido) 413 El cuerpo supera 2 MiB. Reduce el cuerpo, con menos líneas o textos más cortos.
3004 (comprobante_duplicado) 409 Ya existe un comprobante con ese número (estab-ptoEmi-secuencial) autorizado, pendiente o rechazado por el SRI. Consulta la existente. Si la anterior no se emitió (document.failed), puedes reenviar el mismo número con nueva Idempotency-Key y referenciaExterna; si la rechazó el SRI, emite con un secuencial nuevo (omite secuencial para que se asigne el siguiente).
3005 (conflicto_idempotencia) 409 Usaste la misma Idempotency-Key, o la misma origenReferencia + referenciaExterna, con otro cuerpo. Reutiliza el cuerpo original o usa una clave y referencia nuevas para el documento nuevo.
4004 (cupo_agotado) 429 No quedan documentos en tus paquetes vigentes. Compra un paquete en el portal y no reintentes en bucle. Revisa Consumo.
3009 (credenciales_invalidas) 401 La API Key falta o no es válida. Revisa la API Key.
3010 (ip_no_autorizada) 403 En producción, la IP no está registrada para tu API Key o no se pudo identificar. El ambiente de pruebas acepta cualquier IP. Registra tu IP en Cuenta > IP permitidas o revisa proxies o balanceadores entre tu sistema y la API.
3011 (acceso_denegado) 403 El contribuyente o el tipo de comprobante no están habilitados para tu integración. Revisa la identificacion y los tiposComprobante del contexto.
5005 (limite_solicitudes) 429 Superaste el límite de solicitudes por minuto. Espera lo que indica Retry-After y reintenta con la misma Idempotency-Key. Es el único 429 que se reintenta; el 4004 no.
3003 (solicitud_invalida) 415 El Content-Type no es application/json, application/xml ni text/xml, por ejemplo porque falta la cabecera. Envía el Content-Type que corresponda al cuerpo.
5001 (error_interno) / 5002 (servicio_no_disponible) 500 / 503 Ocurrió un error interno o el servicio no está disponible. Reintenta con la misma Idempotency-Key y el mismo cuerpo.

El catálogo completo está en Errores.

Siguientes pasos#

  • Factura: campos de la factura y ejemplos con varias tarifas, descuento y pago a crédito.
  • Seguimiento de una operación: consulta el resultado del SRI con tu idOperacion.
  • Webhooks: recibe el resultado sin consultar.
  • Errores: catálogo de codEstado y si se reintenta o se corrige.
No se pudo completar la operación. Recargar ✕

Conexión con el servidor

Restableciendo la conexión…

Intento 1 de 5.

No se pudo conectar. Revisa tu conexión y vuelve a intentarlo.

La sesión ya no está disponible. Recarga la página para continuar.

La sesión está en pausa. Puedes reanudarla para continuar.

No se pudo reanudar la sesión. Vuelve a intentarlo o recarga la página.

Al recargar se perderán los cambios que no hayas guardado.