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

# Factura

Emite una factura, el comprobante con el que cobras la venta de un bien o un servicio, con sus impuestos, totales y formas de pago.

La factura es el comprobante que más vas a emitir. Esta guía te da un ejemplo mínimo
listo para enviar, describe cada campo de su estructura con las reglas que
valida la API y reúne ejemplos con varias tarifas de IVA, descuento, pago a
crédito e ICE.

Las cabeceras, el [secuencial](/v1/guias/glosario) automático y las reglas
comunes a todos los tipos están en
[Comprobantes electrónicos](/v1/guias/emision). Aquí encuentras solo lo
propio de la factura.

> [!IMPORTANT]
> Ambiente de pruebas: sin validez fiscal. Los ejemplos usan
> `https://api-sandbox.mynexusapi.com` y los [datos de prueba](/v1/guias/datos-de-prueba).

Envías la factura a `POST /v1/contribuyentes/{identificacion}/facturas`. El tipo
de comprobante lo fija la ruta, así que el cuerpo no lleva
`infoTributaria.tipoDocumento`.

```
POST /v1/contribuyentes/{identificacion}/facturas
```

Para revisar el cuerpo sin emitir, usa
`POST /v1/contribuyentes/{identificacion}/facturas/validar`; aplica las mismas
reglas y su respuesta se describe en
[Validar sin emitir](/v1/guias/emision#validar-sin-emitir).

## Cuándo la emites

Emite una factura en situaciones como estas:

- Vendes un producto en tu tienda física o en línea.
- Prestas un servicio, como una consultoría, un mantenimiento o una suscripción
  mensual.
- Vendes a crédito. Emites la factura al momento de la venta e informas el
  plazo en `pagos`.
- Vendes a un consumidor que no da sus datos. En ese caso facturas a
  "consumidor final", pero solo hasta USD 50.00 de `importeTotal`.

Si necesitas devolver dinero o anular una factura ya autorizada, no la edites:
emite una [nota de crédito](/v1/guias/emision-04).

## Ejemplo mínimo

Este ejemplo factura una línea de servicio de 100.00 con IVA 15 %, pagada en
efectivo. Guarda el JSON como `comprobante.json`, porque lo usan los ejemplos de
[Envío](#envio).

```json
{
  "origenReferencia": "MiERP",
  "referenciaExterna": "FACTURA-2026-0002",
  "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": 100.00,
    "totalDescuento": 0,
    "totalConImpuestos": [
      {
        "codigo": "2",
        "codigoPorcentaje": "4",
        "tarifa": 15,
        "baseImponible": 100.00,
        "valor": 15.00
      }
    ],
    "propina": 0,
    "importeTotal": 115.00,
    "moneda": "DOLAR",
    "pagos": [
      {
        "formaPago": "01",
        "total": 115.00
      }
    ]
  },
  "detalles": [
    {
      "codigoPrincipal": "SERV-001",
      "descripcion": "SERVICIO DE MANTENIMIENTO",
      "cantidad": 1,
      "precioUnitario": 100.00,
      "descuento": 0,
      "precioTotalSinImpuesto": 100.00,
      "impuestos": [
        {
          "codigo": "2",
          "codigoPorcentaje": "4",
          "tarifa": 15,
          "baseImponible": 100.00,
          "valor": 15.00
        }
      ]
    }
  ],
  "infoAdicional": [
    {
      "nombre": "Orden",
      "valor": "OC-1001"
    }
  ]
}
```

La tabla muestra cómo se calcula cada total del ejemplo.

| Campo | Cálculo | Valor |
|---|---|---|
| `detalles[0].precioTotalSinImpuesto` | 1 x 100.00 - 0 | 100.00 |
| `detalles[0].impuestos[0].valor` | 100.00 x 15 / 100 | 15.00 |
| `totalConImpuestos[0]` | Suma de la única línea con IVA 15 % (`codigoPorcentaje` `4`) | base 100.00, valor 15.00 |
| `totalSinImpuestos` | Suma de `precioTotalSinImpuesto` | 100.00 |
| `importeTotal` | 100.00 + 15.00 + 0 de propina | 115.00 |
| `pagos[0].total` | Toda la factura en efectivo (`01`) | 115.00 |

Como el comprobante no lleva `secuencial`, te asignamos el siguiente número de
la serie 002-001. El paso a paso con descuentos, varias tarifas y
redondeo está en
[Cómo calcular los totales](/v1/guias/emision#como-calcular-los-totales).

## Envío

Envía el `comprobante.json` del ejemplo mínimo con cualquiera de estos
ejemplos. Todos usan como `Idempotency-Key` la misma `referenciaExterna`,
FACTURA-2026-0002, así que repetir el envío no emite otra factura.

```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-0002" \
  -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-0002");
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-0002",
    },
    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-0002',
      '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-0002',
        '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-0002")
    .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 factura de esta pagina
EmisionResultado resultado = await client.EmitirAsync("0123456789001", comprobante, "FACTURA-2026-0002");
Console.WriteLine($"Operacion {resultado.Admission.IdOperacion} / estado: {resultado.Admission.Estado}");
```

```python-sdk
from ecuafact import EcuafactClient

# client: EcuafactClient creado con tu API Key (ver SDK Python)
# comprobante: FacturaRequest con la factura de esta pagina
resultado = client.emitir_en("0123456789001", comprobante, "FACTURA-2026-0002")
print(f"Operacion {resultado.admission.id_operacion} / estado: {resultado.admission.estado}")
```

```javascript-sdk
import { EcuafactClient } from "@ecuafact/sdk";

// client: EcuafactClient creado con tu API Key (ver SDK Node.js)
// comprobante: FacturaRequest con la factura de esta pagina
const resultado = await client.emitirFacturaEn("0123456789001", comprobante, "FACTURA-2026-0002");
console.log(`Operacion ${resultado.admission.idOperacion} / estado: ${resultado.admission.estado}`);
```

```php-sdk
<?php
use Ecuafact\Sdk\EcuafactClient;

// $client: EcuafactClient creado con tu API Key (ver SDK PHP)
// $comprobante: FacturaRequest con la factura de esta pagina
$resultado = $client->emitirEn('0123456789001', $comprobante, 'FACTURA-2026-0002');
echo 'Operacion ' . $resultado->admission->idOperacion . ' / estado: ' . $resultado->admission->estado . 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 factura de esta pagina
EmisionResultado resultado = client.emitirEn("0123456789001", comprobante, "FACTURA-2026-0002");
System.out.println("Operacion " + resultado.admission().idOperacion() + " / estado: " + resultado.admission().estado());
```

```bash-cli
# Resultado esperado: una fila con el estado recibido y el idOperacion de la factura.
ecuafact emitir comprobante.json --entorno sandbox
```

**Resultado esperado.** La API responde 202 con `estado` en `recibido` y un
`idOperacion`. Si repites el mismo envío, la respuesta es la misma y trae el
mismo `idOperacion`, así que no se emite otra factura.

## Estructura del comprobante

El cuerpo de la factura se organiza en bloques, y cada tabla describe uno.

### Raíz

| Clave | Tipo | Obligatorio | Regla |
|---|---|---|---|
| `origenReferencia` | string | Sí | Nombre de tu sistema, de 1 a 64 caracteres entre letras y dígitos ASCII y `-` `_` `.` `:` `/`. |
| `referenciaExterna` | string | Sí | Tu número interno del documento, de 1 a 128 caracteres con el mismo alfabeto. |
| `infoTributaria` | object | Sí | Identidad del comprobante. Sus campos están en la tabla siguiente. |
| `info` | object | Sí | Cabecera de la factura, que se describe más abajo. |
| `detalles` | array | Sí | De 1 a 1000 líneas. |
| `infoAdicional` | array | No | Hasta 15 objetos `{ "nombre", "valor" }`. |

Para qué sirven `origenReferencia` y `referenciaExterna` se explica en
[Comprobantes electrónicos](/v1/guias/emision#origenreferencia-y-referenciaexterna).

### `infoTributaria`

| Campo | Tipo | Obligatorio | Regla |
|---|---|---|---|
| `ruc` | string | Sí | RUC completo del emisor, de 13 dígitos; en pruebas, `0123456789001`. |
| `estab` | string | Sí | Establecimiento, de hasta 3 dígitos. Se completa con ceros, así que `"2"` se toma como `"002"`. |
| `ptoEmi` | string | Sí | Punto de emisión, de hasta 3 dígitos. Se completa con ceros. |
| `secuencial` | string | No | Hasta 9 dígitos. Omítelo, o envía `"000000000"`, y te asignamos el siguiente, como se explica en [Secuencial automático](/v1/guias/emision#secuencial-automatico). |

No envíes `claveAcceso`: te la asignamos nosotros y la ves en el
[seguimiento](/v1/guias/consulta-operacion).

### `info`

| Campo | Tipo | Obligatorio | Regla |
|---|---|---|---|
| `fechaEmision` | string | Sí | `dd/MM/yyyy`. Envía la fecha de hoy, porque el comprobante autorizado lleva la fecha del día en que se procesa. |
| `dirEstablecimiento` | string | No | Dirección del establecimiento que vende, hasta 300 caracteres. |
| `tipoIdentificacionComprador` | string | Sí | `04` RUC, `05` cédula, `06` pasaporte, `07` consumidor final u `08` identificación del exterior. Los valores están en [Catálogos](/v1/guias/catalogos#tipos-de-identificacion). |
| `identificacionComprador` | string | Sí | Con `04`, 13 dígitos. Con `05`, 10 dígitos. Con `07`, exactamente `9999999999999`. Con `06` y `08`, hasta 20 caracteres. |
| `razonSocialComprador` | string | Sí | Nombre o razón social del comprador, hasta 300 caracteres. Para un consumidor final, envía `CONSUMIDOR FINAL`. |
| `direccionComprador` | string | No | Hasta 300 caracteres. |
| `telefono` | string | No | Teléfono del comprador, hasta 40 caracteres. |
| `correo` | string | No | Correo del comprador al que enviamos el comprobante, hasta 500 caracteres. Si lo omites, se toma el valor de un campo de `infoAdicional` llamado `email` o `correo`. |
| `totalSinImpuestos` | number | Sí | Suma de `detalles[].precioTotalSinImpuesto`, ya sin descuentos. |
| `totalDescuento` | number | Sí | Suma de `detalles[].descuento`. Envía `0` si no hay descuentos. |
| `totalConImpuestos` | array | Sí | Una o dos filas, una por cada pareja `codigo` + `codigoPorcentaje` de las líneas. Se describe más abajo. |
| `propina` | number | Sí | Propina, con 2 decimales como máximo. Envía `0` si no hay. Se suma al total y no paga IVA. |
| `importeTotal` | number | Sí | `totalSinImpuestos` + IVA + ICE + `propina`. |
| `moneda` | string | Sí | `DOLAR` o `USD`. |
| `pagos` | array | Sí | De 1 a 20 formas de pago, cuya suma es igual a `importeTotal`. Se describe más abajo. |
| `guiaRemision` | string | No | Número de la guía de remisión que acompaña la mercadería, con el formato `ddd-ddd-ddddddddd`; otro formato responde 422. |
| `placa` | string | No | Placa del vehículo, hasta 20 caracteres. Se usa, por ejemplo, en una venta de combustible. |
| `comercioExterior` | string | No | Valor fijo `EXPORTADOR` cuando la factura corresponde a comercio exterior. |
| `incoTermFactura` | string | No | Término de negociación internacional (Incoterm) de la factura de exportación, hasta 100 caracteres. |
| `lugarIncoTerm` | string | No | Lugar pactado para la entrega según el Incoterm, hasta 300 caracteres. |
| `paisOrigen` | string | No | Código del país de origen de la mercadería, según el catálogo de [Países](/v1/guias/catalogos#paises-comercio-exterior). |
| `puertoEmbarque` | string | No | Puerto de embarque de la mercadería, hasta 100 caracteres. |
| `puertoDestino` | string | No | Puerto de destino de la mercadería, hasta 100 caracteres. |
| `paisDestino` | string | No | Código del país de destino de la mercadería, según el catálogo de [Países](/v1/guias/catalogos#paises-comercio-exterior). |
| `paisAdquisicion` | string | No | Código del país donde el importador adquirió la mercadería, según el catálogo de [Países](/v1/guias/catalogos#paises-comercio-exterior). |
| `incoTermTotalSinImpuestos` | string | No | Incoterm aplicado sobre el total sin impuestos, cuando difiere del de los precios unitarios. |

La factura tampoco admite estos campos de `info`: `contribuyenteEspecial`,
`obligadoContabilidad`, `totalSubsidio`, `compensaciones`, `fleteInternacional`,
`seguroInternacional`, `gastosAduaneros`, `gastosTransporteOtros`,
`valorRetIva`, `valorRetRenta`, `retenciones`, `reembolsos`, `codDocReembolso`,
`totalComprobantesReembolso`, `totalBaseImponibleReembolso`,
`totalImpuestoReembolso`, `infoSustitutivaGuiaRemision`, `otrosRubrosTerceros`,
`tipoNegociable` y `maquinaFiscal`, ni los campos de otros tipos de
comprobante, como `...Proveedor` o `motivo`. Si envías alguno, la API responde
422 con `Campo no soportado en este contrato.`

La API tampoco procesa `unidadMedida` ni `precioSinSubsidio` en `detalles[]`, ni
`descuentoAdicional` ni `valorDevolucionIva` en `impuestos[]`. No los envíes,
porque la API los rechaza como campos desconocidos.

### `detalles[]`

| Campo | Tipo | Obligatorio | Regla |
|---|---|---|---|
| `codigoPrincipal` | string | Sí | Código del producto o servicio en tu sistema, hasta 25 caracteres. |
| `codigoAuxiliar` | string | No | Segundo código, como el código de barras, de hasta 25 caracteres. |
| `descripcion` | string | Sí | Hasta 300 caracteres. |
| `cantidad` | number | Sí | Mayor que 0, hasta 6 decimales. |
| `precioUnitario` | number | Sí | Mayor o igual a 0, hasta 6 decimales, sin IVA. |
| `descuento` | number | Sí | Importe del descuento de la línea en dólares, no en porcentaje, con 2 decimales como máximo. Envía `0` si no hay. |
| `precioTotalSinImpuesto` | number | Sí | `cantidad x precioUnitario - descuento`, redondeado a 2 decimales. |
| `impuestos` | array | Sí | Un IVA obligatorio y, como máximo, un ICE. Se describe más abajo. |
| `detallesAdicionales` | array | No | Hasta 3 objetos `{ "nombre", "valor" }`, como el color o el número de serie. |

No uses `codigoInterno` ni `codigoAdicional` en la factura, porque son de la
nota de crédito. Si los envías, la API responde 422 con
`Campo no soportado en este contrato.`

### `detalles[].impuestos[]`

| Campo | Tipo | Obligatorio | Regla |
|---|---|---|---|
| `codigo` | string | Sí | `"2"` para el IVA, exactamente uno por línea, o `"3"` para el ICE, como máximo uno. Otros impuestos, como el IRBPNR (`"5"`), no se admiten. |
| `codigoPorcentaje` | string | Sí | Código de la tarifa, de hasta 4 dígitos. En el IVA, `"4"` es 15 %, `"0"` es 0 %, `"6"` es no objeto y `"7"` es exento. La tabla completa está en [Catálogos: tarifas de IVA](/v1/guias/catalogos#tarifas-de-iva). |
| `tarifa` | number | Sí | Porcentaje, por ejemplo `15` y no `0.15`. Con `codigoPorcentaje` `0`, `6` o `7` debe ser `0`; con las demás tarifas de IVA, mayor que 0. |
| `baseImponible` | number | Sí | Igual a `precioTotalSinImpuesto` de la línea. En el IVA, más el ICE de la línea si lo hay. |
| `valor` | number | Sí | `(cantidad x precioUnitario - descuento) x tarifa / 100` con la base sin redondear, redondeado a 2 decimales. |

Envía la pareja exacta del catálogo, por ejemplo `"4"` con `15`. Para el IVA, la
API comprueba que el `codigoPorcentaje` exista en el catálogo del SRI y que la
`tarifa` sea la de ese código; si no coinciden, responde 422 con `La tarifa no
corresponde al codigoPorcentaje del catálogo del SRI.`

### `info.totalConImpuestos[]`

| Campo | Tipo | Obligatorio | Regla |
|---|---|---|---|
| `codigo` | string | Sí | Igual al de las líneas del grupo. |
| `codigoPorcentaje` | string | Sí | Igual al de las líneas del grupo. |
| `tarifa` | number | No | Si lo envías, debe ser igual a la `tarifa` de esas líneas. |
| `baseImponible` | number | Sí | Suma de `baseImponible` de las líneas del grupo. |
| `valor` | number | Sí | Suma de `valor` de las líneas del grupo, sin recalcularlo sobre la base sumada. |

Envía exactamente una fila por cada pareja `codigo` + `codigoPorcentaje` que
aparezca en las líneas, y como máximo dos filas.

### `info.pagos[]`

| Campo | Tipo | Obligatorio | Regla |
|---|---|---|---|
| `formaPago` | string | Sí | Código de 2 dígitos, como `"01"` sin utilización del sistema financiero (efectivo), `"19"` tarjeta de crédito o `"20"` otros con utilización del sistema financiero (transferencia). La tabla completa está en [Catálogos: formas de pago](/v1/guias/catalogos#formas-de-pago). |
| `total` | number | Sí | Monto pagado con esta forma, con 2 decimales como máximo. |
| `plazo` | number | No | Plazo de pago, como número entero mayor o igual a 0. Omítelo o envía `0` en los pagos de contado. |
| `unidadTiempo` | string | Condicional | Obligatoria si `plazo` es mayor que 0. Admite `dias`, `meses` o `anios`, de [Catálogos](/v1/guias/catalogos#unidades-de-tiempo), con hasta 20 caracteres. Si la omites con plazo 0, se asume `dias`. |

### `infoAdicional[]`

| Campo | Tipo | Obligatorio | Regla |
|---|---|---|---|
| `nombre` | string | Sí | Etiqueta que se imprime en el RIDE, hasta 300 caracteres. |
| `valor` | string | Sí | Valor, hasta 300 caracteres. |

## Reglas de cálculo y validaciones

Si la factura incumple una de estas reglas, la API responde 422 con el código
`comprobante_invalido` y el detalle en `errores`. Las reglas comunes de totales están en
[Cómo calcular los totales](/v1/guias/emision#como-calcular-los-totales).

| Regla | Mensaje (en `errores`) | Qué hacer |
|---|---|---|
| En cada línea, `precioTotalSinImpuesto` es `cantidad x precioUnitario - descuento` redondeado. | `Subtotal del detalle no coincide...` | Recalcula la línea. |
| El IVA de la línea se calcula sobre la base sin redondear. | `Valor de impuesto no coincide con base y tasa.` | Calcula `valor` antes de redondear la base. |
| La cabecera lleva una fila por grupo, con las sumas exactas. | `Base o valor de impuestos no coincide con detalles.` | Suma bases y valores por grupo. |
| `totalSinImpuestos`, `totalDescuento` y el IVA cuadran con las líneas. | `Totales no coinciden con detalles.` | Suma de nuevo las líneas. |
| `importeTotal` es subtotal + IVA + ICE + propina. | `total no coincide con subtotal + IVA + ICE + propina.` | Corrige `importeTotal`. |
| La suma de `pagos` es igual a `importeTotal`. | `Pagos no coinciden con total.` | Ajusta los pagos. |
| `unidadTiempo` es obligatoria cuando hay plazo. | `Obligatoria cuando hay plazo.` | Agrega `"unidadTiempo": "dias"`. |
| `plazo` es un número entero. | `Plazo entero fuera de rango.` | Envía `30`, no `30.5`. |
| Cada línea lleva un IVA y como máximo un ICE. | `Se admite un IVA y opcionalmente ICE porcentual.` | Deja un solo impuesto `"2"` por línea. |
| La tarifa es coherente con el tipo de IVA. | `IVA gravado requiere tasa positiva.` / `IVA 0 requiere tasa 0.` / `No objeto requiere tasa 0.` / `Exento requiere tasa 0.` | Usa la tarifa del catálogo. |
| La tarifa del IVA corresponde a su `codigoPorcentaje` del catálogo. | `La tarifa no corresponde al codigoPorcentaje del catálogo del SRI.` / `Código de porcentaje de IVA no existe en el catálogo del SRI.` | Usa una pareja de [Catálogos: tarifas de IVA](/v1/guias/catalogos#tarifas-de-iva). |
| Los importes llevan hasta 2 decimales, y la cantidad y el precio hasta 6. | `Precisión o importe no admitido; no se redondea silenciosamente.` | Redondea en tu sistema antes de enviar. |
| Solo se admiten los campos, las colecciones y los códigos de línea de la factura. | `Campo no soportado en este contrato.` | Quita el campo o usa `codigoPrincipal`. |
| `moneda` tiene un valor válido. | `Este adaptador admite DOLAR o USD.` | Envía `DOLAR`. |
| La factura a consumidor final llega hasta USD 50.00. | `Para una factura mayor a $50, seleccione un cliente con cedula, RUC o pasaporte...` | Pide la identificación del comprador. |
| El consumidor final lleva su identificación fija. | `Identificación de consumidor final inválida.` | Envía `9999999999999`. |
| La cédula tiene 10 dígitos y el RUC 13. | `Cédula tiene longitud o caracteres inválidos.` / `RUC tiene longitud o caracteres inválidos.` | Revisa `identificacionComprador`. |

## Más ejemplos

Cada ejemplo es un cuerpo completo. Antes de enviarlo, cambia su
`referenciaExterna` por una que no hayas usado y envía esa misma cadena como
`Idempotency-Key`. Si repites las de otro envío con un cuerpo distinto, la API
responde 409 con el `codEstado` 3005 (`conflicto_idempotencia`).

### Varias líneas con IVA 15 % y 0 %

Esta factura tiene dos líneas con tarifas distintas, así que la cabecera lleva
una fila por tarifa.

| Línea | Cálculo | Subtotal | IVA |
|---|---|---|---|
| Servicio (IVA 15 %, `4`) | 2 x 25.00 | 50.00 | 50.00 x 15 / 100 = 7.50 |
| Libro (IVA 0 %, `0`) | 1 x 10.00 | 10.00 | 0 |
| Totales | | `totalSinImpuestos` 60.00 | 7.50 -> `importeTotal` 67.50 |

```json
{
  "origenReferencia": "MiERP",
  "referenciaExterna": "FACTURA-2026-0003",
  "infoTributaria": {
    "ruc": "0123456789001",
    "estab": "002",
    "ptoEmi": "001"
  },
  "info": {
    "fechaEmision": "07/10/2026",
    "tipoIdentificacionComprador": "05",
    "identificacionComprador": "0123456789",
    "razonSocialComprador": "CONTRIBUYENTE DE PRUEBAS",
    "totalSinImpuestos": 60.00,
    "totalDescuento": 0,
    "totalConImpuestos": [
      {
        "codigo": "2",
        "codigoPorcentaje": "4",
        "tarifa": 15,
        "baseImponible": 50.00,
        "valor": 7.50
      },
      {
        "codigo": "2",
        "codigoPorcentaje": "0",
        "tarifa": 0,
        "baseImponible": 10.00,
        "valor": 0
      }
    ],
    "propina": 0,
    "importeTotal": 67.50,
    "moneda": "DOLAR",
    "pagos": [
      {
        "formaPago": "01",
        "total": 67.50
      }
    ]
  },
  "detalles": [
    {
      "codigoPrincipal": "SERV-010",
      "descripcion": "SOPORTE TECNICO POR HORA",
      "cantidad": 2,
      "precioUnitario": 25.00,
      "descuento": 0,
      "precioTotalSinImpuesto": 50.00,
      "impuestos": [
        {
          "codigo": "2",
          "codigoPorcentaje": "4",
          "tarifa": 15,
          "baseImponible": 50.00,
          "valor": 7.50
        }
      ]
    },
    {
      "codigoPrincipal": "LIB-020",
      "descripcion": "LIBRO TECNICO",
      "cantidad": 1,
      "precioUnitario": 10.00,
      "descuento": 0,
      "precioTotalSinImpuesto": 10.00,
      "impuestos": [
        {
          "codigo": "2",
          "codigoPorcentaje": "0",
          "tarifa": 0,
          "baseImponible": 10.00,
          "valor": 0
        }
      ]
    }
  ]
}
```

### Con descuento

Esta factura aplica un descuento del 10 % sobre la línea. Envía el descuento
como importe en dólares: si lo manejas en porcentaje, conviértelo antes de
enviarlo.

| Paso | Cálculo | Resultado |
|---|---|---|
| Bruto | 3 x 12.50 | 37.50 |
| `descuento` (10 %) | 37.50 x 10 / 100 | 3.75 |
| `precioTotalSinImpuesto` | 37.50 - 3.75 | 33.75 |
| IVA 15 % | 33.75 x 15 / 100 = 5.0625 | 5.06 |
| `importeTotal` | 33.75 + 5.06 | 38.81 |

```json
{
  "origenReferencia": "MiERP",
  "referenciaExterna": "FACTURA-2026-0004",
  "infoTributaria": {
    "ruc": "0123456789001",
    "estab": "002",
    "ptoEmi": "001"
  },
  "info": {
    "fechaEmision": "07/10/2026",
    "tipoIdentificacionComprador": "05",
    "identificacionComprador": "0123456789",
    "razonSocialComprador": "CONTRIBUYENTE DE PRUEBAS",
    "totalSinImpuestos": 33.75,
    "totalDescuento": 3.75,
    "totalConImpuestos": [
      {
        "codigo": "2",
        "codigoPorcentaje": "4",
        "tarifa": 15,
        "baseImponible": 33.75,
        "valor": 5.06
      }
    ],
    "propina": 0,
    "importeTotal": 38.81,
    "moneda": "DOLAR",
    "pagos": [
      {
        "formaPago": "19",
        "total": 38.81
      }
    ]
  },
  "detalles": [
    {
      "codigoPrincipal": "PROD-030",
      "descripcion": "CAJA DE PAPEL A4",
      "cantidad": 3,
      "precioUnitario": 12.50,
      "descuento": 3.75,
      "precioTotalSinImpuesto": 33.75,
      "impuestos": [
        {
          "codigo": "2",
          "codigoPorcentaje": "4",
          "tarifa": 15,
          "baseImponible": 33.75,
          "valor": 5.06
        }
      ]
    }
  ]
}
```

`totalSinImpuestos` es el valor **después** del descuento, 33.75, y
`totalDescuento` informa cuánto se descontó, 3.75.

### Pago a crédito con plazo

Esta venta de 230.00 se paga en dos partes: 50.00 con tarjeta de crédito el
mismo día y 180.00 a 30 días.

| Campo | Cálculo | Valor |
|---|---|---|
| `precioTotalSinImpuesto` | 1 x 200.00 | 200.00 |
| IVA 15 % | 200.00 x 15 / 100 | 30.00 |
| `importeTotal` | 200.00 + 30.00 | 230.00 |
| `pagos` | 50.00 (`19`) + 180.00 (`01`, 30 días) | 230.00 |

```json
{
  "origenReferencia": "MiERP",
  "referenciaExterna": "FACTURA-2026-0005",
  "infoTributaria": {
    "ruc": "0123456789001",
    "estab": "002",
    "ptoEmi": "001"
  },
  "info": {
    "fechaEmision": "07/10/2026",
    "tipoIdentificacionComprador": "05",
    "identificacionComprador": "0123456789",
    "razonSocialComprador": "CONTRIBUYENTE DE PRUEBAS",
    "totalSinImpuestos": 200.00,
    "totalDescuento": 0,
    "totalConImpuestos": [
      {
        "codigo": "2",
        "codigoPorcentaje": "4",
        "tarifa": 15,
        "baseImponible": 200.00,
        "valor": 30.00
      }
    ],
    "propina": 0,
    "importeTotal": 230.00,
    "moneda": "DOLAR",
    "pagos": [
      {
        "formaPago": "19",
        "total": 50.00
      },
      {
        "formaPago": "01",
        "total": 180.00,
        "plazo": 30,
        "unidadTiempo": "dias"
      }
    ]
  },
  "detalles": [
    {
      "codigoPrincipal": "EQ-040",
      "descripcion": "IMPRESORA LASER",
      "cantidad": 1,
      "precioUnitario": 200.00,
      "descuento": 0,
      "precioTotalSinImpuesto": 200.00,
      "impuestos": [
        {
          "codigo": "2",
          "codigoPorcentaje": "4",
          "tarifa": 15,
          "baseImponible": 200.00,
          "valor": 30.00
        }
      ]
    }
  ]
}
```

### Producto con ICE

Esta factura tiene una línea de 100.00 gravada con ICE porcentual del 10 % e
IVA 15 %. El ICE se calcula sobre el subtotal de la línea y **se suma a la base
del IVA**, y en la cabecera va una fila por impuesto.

| Campo | Cálculo | Valor |
|---|---|---|
| `precioTotalSinImpuesto` | 1 x 100.00 | 100.00 |
| ICE 10 % | 100.00 x 10 / 100 | 10.00 |
| Base del IVA | 100.00 + 10.00 (ICE) | 110.00 |
| IVA 15 % | 110.00 x 15 / 100 | 16.50 |
| `importeTotal` | 100.00 + 16.50 + 10.00 | 126.50 |

El `codigoPorcentaje` 3011 y la tarifa del 10 % son ilustrativos. Usa el código
y la tarifa que corresponden a tu producto según la tabla de
[Tarifas de ICE](/v1/guias/catalogos#tarifas-de-ice).

```json
{
  "origenReferencia": "MiERP",
  "referenciaExterna": "FACTURA-2026-0006",
  "infoTributaria": {
    "ruc": "0123456789001",
    "estab": "002",
    "ptoEmi": "001"
  },
  "info": {
    "fechaEmision": "07/10/2026",
    "tipoIdentificacionComprador": "05",
    "identificacionComprador": "0123456789",
    "razonSocialComprador": "CONTRIBUYENTE DE PRUEBAS",
    "totalSinImpuestos": 100.00,
    "totalDescuento": 0,
    "totalConImpuestos": [
      {
        "codigo": "2",
        "codigoPorcentaje": "4",
        "tarifa": 15,
        "baseImponible": 110.00,
        "valor": 16.50
      },
      {
        "codigo": "3",
        "codigoPorcentaje": "3011",
        "tarifa": 10,
        "baseImponible": 100.00,
        "valor": 10.00
      }
    ],
    "propina": 0,
    "importeTotal": 126.50,
    "moneda": "DOLAR",
    "pagos": [
      {
        "formaPago": "01",
        "total": 126.50
      }
    ]
  },
  "detalles": [
    {
      "codigoPrincipal": "PRD-ICE-01",
      "descripcion": "PRODUCTO GRAVADO CON ICE",
      "cantidad": 1,
      "precioUnitario": 100.00,
      "descuento": 0,
      "precioTotalSinImpuesto": 100.00,
      "impuestos": [
        {
          "codigo": "3",
          "codigoPorcentaje": "3011",
          "tarifa": 10,
          "baseImponible": 100.00,
          "valor": 10.00
        },
        {
          "codigo": "2",
          "codigoPorcentaje": "4",
          "tarifa": 15,
          "baseImponible": 110.00,
          "valor": 16.50
        }
      ]
    }
  ]
}
```

## Respuesta

La API responde 202 Accepted con este cuerpo:

```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-000000125",
  "referenciaExterna": "FACTURA-2026-0002",
  "claveAcceso": null,
  "fhRecibido": "2026-11-16T10:15:00-05:00",
  "fhAutorizacion": null
}
```

| Campo | Tipo | Descripción |
|---|---|---|
| `estado` | string | `recibido`: la factura pasó nuestras validaciones y la aceptamos. No es una autorización. Un reintento con la misma `Idempotency-Key` y el mismo cuerpo responde con el mismo `idOperacion` y el estado actual de la operación. Normalmente el 202 trae `recibido`, pero si el resultado ya se conoce al responder, trae directamente el estado final (`autorizado` con 2001, `rechazado` con 3xxx o `rechazo_configuracion` con 4xxx), con su `msgError` y su detalle en `errores`. Decide siempre por `estado` y `codEstado`. |
| `codEstado` | number | 1001 si el comprobante todavía no tiene clave de acceso, o 1002 si ya la tiene. Acepta los dos valores. |
| `errores` | array de string | Viene siempre; en una emisión recibida es una lista vacía, y con un resultado final trae su detalle. |
| `idOperacion` | string (UUID) | Identificador de la operación. Guárdalo para el seguimiento. |
| `urlEstado` | string | URL completa del seguimiento, igual a la cabecera `Location`. Puedes llamarla tal como viene. |
| `numeroDocumento` | string o `null` | Número del comprobante con la forma `estab-ptoEmi-secuencial`, incluido el secuencial que te asignamos si no lo enviaste. |
| `claveAcceso` | string o `null` | Clave de acceso de 49 dígitos. Es `null` con el `codEstado` 1001; en ese caso la obtienes en el seguimiento o en el webhook. Con 1002 o con un resultado final ya viene en la respuesta. |
| `fhRecibido` | string | Fecha y hora en que recibimos la emisión, en ISO 8601 con zona horaria. |

Los demás campos, `ambiente`, `tipoDocumento`, `referenciaExterna` y `fhAutorizacion`, tienen la misma forma del [seguimiento de una operación](/v1/guias/consulta-operacion#respuesta), y el campo `msgError` solo aparece cuando el 202 ya trae un resultado final con error.

Un reintento con la misma `Idempotency-Key` y el mismo cuerpo responde con el
mismo `idOperacion` y el estado actual de la operación, y no crea otra factura.

Un 202 significa que la factura quedó **recibida**, todavía no autorizada.
Sigue la operación con
[`GET /v1/operaciones/{idOperacion}`](/v1/guias/consulta-operacion) o espera el
[webhook](/v1/guias/webhooks). Cuando su `estado` sea `autorizado`, descarga el
[RIDE](/v1/guias/consulta-ride). Si es `rechazado`, lee el `codEstado` y el detalle de `errores`,
corrige la factura y reenvíala con una `Idempotency-Key` y una
`referenciaExterna` nuevas, como se explica en
[Reintentos y duplicados](/v1/guias/emision#reintentos-y-duplicados).

## Estados de este endpoint

Esta tabla reúne las respuestas que puedes recibir al emitir una factura.

| `codEstado` | HTTP | Cuándo ocurre | Qué hacer |
|---|---|---|---|
| 1001 o 1002 | 202 | La factura quedó recibida, o reintentaste con la misma `Idempotency-Key` y el mismo cuerpo. | Guarda `idOperacion` y sigue la operación; un reintento trae el estado actual. |
| 3003 (`solicitud_invalida`) | 400 | El JSON está mal formado, o la `Idempotency-Key` falta o no es válida. | Corrige la petición. |
| 3002 (`comprobante_invalido`) | 422 | La factura no cumple una regla; el detalle viene en `errores`. | Corrige según [Reglas de cálculo y validaciones](#reglas-de-calculo-y-validaciones). Consume 1 documento como intento. |
| 3004 (`comprobante_duplicado`) | 409 | Ya existe una factura con ese número (`estab`-`ptoEmi`-`secuencial`) autorizada, pendiente o rechazada 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` con otro cuerpo, o una `referenciaExterna` que ya usó otro comprobante. | No cambies el cuerpo de un reintento. Para un comprobante nuevo, incluida la corrección de un rechazo, usa otra `Idempotency-Key` y otra `referenciaExterna`. |
| 4004 (`cupo_agotado`) | 429 | Se agotó el cupo. | Compra un paquete de documentos en el Portal del Cliente y no reintentes en bucle. Revisa [Consumo](/v1/guias/consumo). |
| 3009 (`credenciales_invalidas`) | 401 | La API Key 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 llama sin proxies que oculten el origen. |
| 3011 (`acceso_denegado`) | 403 | El contribuyente o la factura no están habilitados, o el `ruc` no es el del contribuyente. | Revisa el contexto y el RUC enviado. |
| 5005 (`limite_solicitudes`) | 429 | Superaste el límite de solicitudes por minuto. | Espera los segundos que indica `Retry-After` y reintenta con la misma clave. |

Todos los errores traen la misma forma de la respuesta 202, con `msgError`, el detalle en `errores` y `idOperacion`, `urlEstado`, `numeroDocumento`, `claveAcceso` y las fechas en `null`. El catálogo completo está en [Errores](/v1/guias/errores#catalogo-de-codestado).

## Siguientes pasos

- [Seguimiento de una operación](/v1/guias/consulta-operacion): confirma si el SRI autorizó la factura.
- [Webhooks](/v1/guias/webhooks): recibe la autorización o el rechazo sin consultar.
- [Nota de crédito](/v1/guias/emision-04): revierte total o parcialmente una factura autorizada.
- [Descarga el ejemplo de solicitud](/downloads/v1/ejemplos/example-01.json): cuerpo de factura listo para ensayar.
