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

Factura POST

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 automático y las reglas comunes a todos los tipos están en Comprobantes electrónicos. Aquí encuentras solo lo propio de la factura.

Importante

Ambiente de pruebas: sin validez fiscal. Los ejemplos usan https://api-sandbox.mynexusapi.com y los 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.

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.

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.

{
  "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.

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.

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}
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()}");
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)
// 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
$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;
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());
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}");
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}")
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
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;
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());
# 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.

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.

No envíes claveAcceso: te la asignamos nosotros y la ves en el seguimiento.

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.
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.
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.
paisAdquisicion string No Código del país donde el importador adquirió la mercadería, según el catálogo de Países.
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.
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.
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, 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.

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.
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
{
  "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
{
  "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
{
  "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.

{
  "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:

{
  "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, 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} o espera el webhook. Cuando su estado sea autorizado, descarga el 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.

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

Siguientes pasos#

No se pudo completar la operación. Recargar ✕

Conexión con el servidor

Restableciendo la conexión…

Intento 1 de 5.

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

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

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

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

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