<!-- source_url: https://docs.mynexusapi.com/v1/guias/emision | last_updated: 2026-11-19 -->

# Comprobantes electrónicos

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](#como-elegir-el-tipo-de-comprobante).

> [!IMPORTANT]
> Ambiente de pruebas: sin validez fiscal. Todos los ejemplos de esta página usan
> `https://api-sandbox.mynexusapi.com` y los [datos de prueba](/v1/guias/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:

```text
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](#endpoint). Si no, estos son los conceptos que usa el resto de la
página.

- Un [comprobante electrónico](/v1/guias/glosario) es el documento fiscal que el
  [SRI](/v1/guias/glosario), 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](/v1/guias/consulta-operacion) o por
  [webhook](/v1/guias/webhooks).
- Cada comprobante tiene un **número** con la forma `estab-ptoEmi-secuencial`,
  por ejemplo `002-001-000000124`. Se compone del
  [establecimiento](/v1/guias/glosario) y el
  [punto de emisión](/v1/guias/glosario), de 3 dígitos cada uno, y del
  [secuencial](/v1/guias/glosario), un consecutivo de 9 dígitos dentro de esa
  serie.
- La [clave de acceso](/v1/guias/glosario) 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](/v1/guias/glosario), 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`](/v1/guias/consulta-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](/v1/guias/autenticacion). |
| `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](#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](/v1/guias/limites#cabeceras). |

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`).

```bash
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](/v1/guias/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`](/v1/guias/consulta-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](/v1/guias/emision-01) |
| 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](/v1/guias/emision-03) |
| Devolver dinero, aplicar un descuento posterior o anular total o parcialmente una factura ya autorizada | Nota de crédito | `04` | [Nota de crédito](/v1/guias/emision-04) |
| 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](/v1/guias/emision-05) |
| Acompañar el traslado de mercadería de un lugar a otro | Guía de remisión | `06` | [Guía de remisión](/v1/guias/emision-06) |
| Dejar constancia de los impuestos que retienes al pagar a un proveedor | Comprobante de retención | `07` | [Comprobante de retención](/v1/guias/emision-07) |

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](#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](#secuencial-automatico). |

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.

> [!NOTE]
> 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.

```json
{
  "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](/v1/guias/catalogos#tarifas-de-iva) y los de pago en
[Catálogos: formas de pago](/v1/guias/catalogos#formas-de-pago).

## Ejemplo de emisión

Con el JSON de [El comprobante completo](#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.

```bash
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}
```

```csharp
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()}");
```

```python
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)
```

```javascript
// 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
<?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;
```

```java
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());
```

```csharp-sdk
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}");
```

```python-sdk
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}")
```

```javascript-sdk
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-sdk
<?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;
```

```java-sdk
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());
```

```bash-cli
# 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](/v1/guias/consulta-operacion#respuesta):

```json
{
  "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](/v1/guias/webhooks) (`document.authorized`,
   `document.rejected` o `document.failed`) o consulta
   [`GET /v1/operaciones/{idOperacion}`](/v1/guias/consulta-operacion) mientras
   su `estado` sea `recibido`.
3. Con `autorizado`, descarga el [RIDE](/v1/guias/consulta-ride) o el
   [XML](/v1/guias/consulta-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](#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](/v1/guias/consumo).

## 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](/v1/guias/limite-de-request) 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](#endpoint), sin la
cabecera `Idempotency-Key`. Si el comprobante cumple todas las reglas, la API
responde 200 OK con este cuerpo:

```json
{
  "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](#errores-de-validacion), 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](#ejemplo-de-emision):

```bash
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.
```

```csharp
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()}");
```

```python
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)
```

```javascript
// 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
<?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;
```

```java
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());
```

```bash-cli
# 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:

```json
{
  "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](#que-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](/v1/guias/consumo). | 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](/v1/guias/errores#como-pedir-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.

> [!WARNING]
> 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](#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](/v1/guias/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](/v1/guias/errores#catalogo-de-codestado).

## Siguientes pasos

- [Factura](/v1/guias/emision-01): campos de la factura y ejemplos con varias tarifas, descuento y pago a crédito.
- [Seguimiento de una operación](/v1/guias/consulta-operacion): consulta el resultado del SRI con tu `idOperacion`.
- [Webhooks](/v1/guias/webhooks): recibe el resultado sin consultar.
- [Errores](/v1/guias/errores#catalogo-de-codestado): catálogo de `codEstado` y si se reintenta o se corrige.
