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#
- Seguimiento de una operación: confirma si el SRI autorizó la factura.
- Webhooks: recibe la autorización o el rechazo sin consultar.
- Nota de crédito: revierte total o parcialmente una factura autorizada.
- Descarga el ejemplo de solicitud: cuerpo de factura listo para ensayar.