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

Liquidación de compra POST

Emite una liquidación de compra cuando compras bienes o servicios a alguien que no puede entregarte una factura.

Algunos proveedores no pueden emitir comprobantes, como un agricultor sin RUC o una empresa del exterior sin domicilio en Ecuador. Cuando les compras, eres tú quien emite el comprobante que respalda la compra, y ese comprobante es la liquidación de compra.

Esta guía explica en qué se diferencia de la factura, te da un ejemplo mínimo listo para enviar y describe cada campo de su estructura con las reglas que valida la API. El endpoint, las cabeceras, el secuencial automático y las reglas comunes a todos los tipos están en Comprobantes electrónicos.

Importante

Ambiente de pruebas: sin validez fiscal. Los ejemplos usan https://api-sandbox.mynexusapi.com y los datos de prueba.

Envías la liquidación de compra a la ruta del tipo 03. El tipo lo fija la ruta, así que el cuerpo no lleva infoTributaria.tipoDocumento.

POST /v1/contribuyentes/{identificacion}/liquidaciones-compra

Conceptos#

En una factura, el vendedor emite el comprobante. En una liquidación de compra es al revés: tú, el comprador, emites el comprobante en nombre del proveedor. Por eso info describe al proveedor, con los campos que terminan en Proveedor, y no a un comprador. Las líneas, los impuestos, los totales y los pagos se calculan como en la factura, con dos diferencias: la liquidación de compra solo admite IVA, sin ICE, y no lleva propina.

Cuándo la emites#

Emite una liquidación de compra en situaciones como estas:

  • Compras productos a una persona natural sin RUC que no puede emitir comprobantes, como un agricultor que te vende su cosecha, un pescador artesanal o un recolector de material reciclable.
  • Contratas un servicio ocasional a una persona sin RUC, como un trabajo puntual de reparación.
  • Pagas un servicio prestado por una persona o empresa del exterior sin domicilio en Ecuador. En ese caso la identificas con el tipo 06, pasaporte, o 08, identificación del exterior.

Si tu proveedor tiene RUC y emite facturas, pídele su factura en lugar de emitir una liquidación de compra. Si además te corresponde retener impuestos sobre esta compra, emite un comprobante de retención con esta liquidación como documento sustento, es decir, con codDocSustento 03.

Ejemplo mínimo#

Este ejemplo documenta la compra de 50 kg de maíz, con IVA 0 %, y de un servicio de secado, con IVA 15 %, a un agricultor identificado con cédula, que cobra en efectivo. Guarda el JSON como comprobante.json, porque lo usan los ejemplos de Envío.

{
  "origenReferencia": "MiERP",
  "referenciaExterna": "LIQUIDACION-2026-0001",
  "infoTributaria": {
    "ruc": "0123456789001",
    "estab": "002",
    "ptoEmi": "001"
  },
  "info": {
    "fechaEmision": "07/10/2026",
    "tipoIdentificacionProveedor": "05",
    "identificacionProveedor": "0123456789",
    "razonSocialProveedor": "PROVEEDOR DE PRUEBAS",
    "direccionProveedor": "DIRECCION DE PRUEBAS",
    "totalSinImpuestos": 80.00,
    "totalDescuento": 0,
    "totalConImpuestos": [
      {
        "codigo": "2",
        "codigoPorcentaje": "0",
        "tarifa": 0,
        "baseImponible": 60.00,
        "valor": 0
      },
      {
        "codigo": "2",
        "codigoPorcentaje": "4",
        "tarifa": 15,
        "baseImponible": 20.00,
        "valor": 3.00
      }
    ],
    "importeTotal": 83.00,
    "moneda": "DOLAR",
    "pagos": [
      {
        "formaPago": "01",
        "total": 83.00
      }
    ]
  },
  "detalles": [
    {
      "codigoPrincipal": "MAIZ-001",
      "descripcion": "MAIZ EN GRANO (KG)",
      "cantidad": 50,
      "precioUnitario": 1.20,
      "descuento": 0,
      "precioTotalSinImpuesto": 60.00,
      "impuestos": [
        {
          "codigo": "2",
          "codigoPorcentaje": "0",
          "tarifa": 0,
          "baseImponible": 60.00,
          "valor": 0
        }
      ]
    },
    {
      "codigoPrincipal": "SERV-002",
      "descripcion": "SERVICIO DE SECADO DE GRANO",
      "cantidad": 1,
      "precioUnitario": 20.00,
      "descuento": 0,
      "precioTotalSinImpuesto": 20.00,
      "impuestos": [
        {
          "codigo": "2",
          "codigoPorcentaje": "4",
          "tarifa": 15,
          "baseImponible": 20.00,
          "valor": 3.00
        }
      ]
    }
  ],
  "infoAdicional": [
    {
      "nombre": "Lote",
      "valor": "COSECHA-2026-10"
    }
  ]
}

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

Campo Cálculo Valor
Línea 1 (precioTotalSinImpuesto) 50 x 1.20 - 0 60.00, IVA 0 % = 0
Línea 2 (precioTotalSinImpuesto) 1 x 20.00 - 0 20.00, IVA 15 % = 3.00
totalConImpuestos Una fila por tarifa: IVA 0 % (0) y IVA 15 % (4) 60.00 / 0 y 20.00 / 3.00
totalSinImpuestos 60.00 + 20.00 80.00
importeTotal 80.00 + 3.00 83.00
pagos[0].total Todo en efectivo (01) 83.00

La liquidación de compra no lleva propina. El paso a paso con descuentos 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, LIQUIDACION-2026-0001, así que repetir el envío no emite otra liquidación.

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

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

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

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

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

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

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

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

// client: EcuafactClient creado con tu API Key (ver SDK .NET)
// comprobante: LiquidacionCompraRequest con la liquidacion de esta pagina
EmisionResultado resultado = await client.EmitirAsync("0123456789001", comprobante, "LIQUIDACION-2026-0001");
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: LiquidacionCompraRequest con la liquidacion de esta pagina
resultado = client.emitir_en("0123456789001", comprobante, "LIQUIDACION-2026-0001")
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: LiquidacionCompraRequest con la liquidacion de esta pagina
const resultado = await client.emitirEn("0123456789001", comprobante, "LIQUIDACION-2026-0001");
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: LiquidacionCompraRequest con la liquidacion de esta pagina
$resultado = $client->emitirEn('0123456789001', $comprobante, 'LIQUIDACION-2026-0001');
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: LiquidacionCompraRequest con la liquidacion de esta pagina
EmisionResultado resultado = client.emitirEn("0123456789001", comprobante, "LIQUIDACION-2026-0001");
System.out.println("Operacion " + resultado.admission().idOperacion() + " / estado: " + resultado.admission().estado());
# Resultado esperado: una fila con el estado recibido y el idOperacion de la emisión.
ecuafact emitir comprobante.json --entorno sandbox

Resultado esperado. La API responde 202 con estado en recibido, el codEstado 1001 o 1002 y un idOperacion.

Validar sin emitir#

Antes de emitir puedes comprobar que la liquidación está bien armada. Envía el mismo cuerpo a la ruta de validación del tipo:

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

La validación aplica las mismas reglas que la emisión, sin Idempotency-Key, sin consumir cupo y sin usar un número de la serie. Si la liquidación cumple todas las reglas, responde 200 con valido en true y errores vacío; si no, responde el mismo error que daría la emisión. Los detalles están en Validar sin emitir.

Estructura del comprobante#

El cuerpo de la liquidación de compra 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 de la compra, 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 liquidación, que se describe más abajo.
detalles array Sí De 1 a 1000 líneas.
infoAdicional array No Hasta 15 objetos { "nombre", "valor" }, cada uno de 1 a 300 caracteres.

infoTributaria#

Campo Tipo Obligatorio Regla
ruc string Sí Tu RUC completo, el del comprador que emite, de 13 dígitos; en pruebas, 0123456789001.
estab string Sí Establecimiento, de hasta 3 dígitos. Se completa con ceros.
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 y te asignamos el siguiente de la serie de liquidaciones, como se explica en Secuencial automático.

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 de tu establecimiento, hasta 300 caracteres.
tipoIdentificacionProveedor string Sí 05 cédula, 06 pasaporte, 08 identificación del exterior o 04 RUC. Los valores están en Catálogos. 07, consumidor final, no se admite.
identificacionProveedor string Sí Con 04, 13 dígitos. Con 05, 10 dígitos. Con 06 y 08, hasta 20 caracteres.
razonSocialProveedor string Sí Nombre del proveedor, hasta 300 caracteres.
direccionProveedor string No Hasta 300 caracteres.
telefono string No Teléfono del proveedor, hasta 40 caracteres.
correo string No Correo del proveedor al que enviamos el comprobante, hasta 500 caracteres. Si lo omites, se toma un campo de infoAdicional llamado email o correo.
totalSinImpuestos number Sí Suma de detalles[].precioTotalSinImpuesto.
totalDescuento number Sí Suma de detalles[].descuento. Envía 0 si no hay.
totalConImpuestos array Sí Una o dos filas, una por cada pareja codigo + codigoPorcentaje de las líneas, con la suma de sus bases y valores. tarifa es opcional y, si la envías, debe ser igual a la de las líneas.
importeTotal number Sí totalSinImpuestos + IVA.
moneda string Sí DOLAR o USD.
pagos array Sí De 1 a 20 formas de pago, cuya suma es igual a importeTotal. Llevan los mismos campos que en la factura (formaPago, total, plazo y unidadTiempo), y sus códigos están en Catálogos: formas de pago.

No envíes propina, ni siquiera con 0, ni guiaRemision, placa o los campos ...Comprador. Si los envías, la API responde 422 con Campo no soportado en este contrato.

detalles[] e impuestos#

Las líneas y sus impuestos son iguales a los de la factura.

Campo Tipo Obligatorio Regla
codigoPrincipal string Sí Código del bien o servicio, hasta 25 caracteres.
codigoAuxiliar string No 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 en dólares, con 2 decimales como máximo.
precioTotalSinImpuesto number Sí cantidad x precioUnitario - descuento, redondeado a 2 decimales.
impuestos array Sí Un solo IVA, con codigo "2". El ICE no se admite en la liquidación de compra. Lleva codigoPorcentaje, tarifa, baseImponible y valor, y sus reglas completas están en Factura.
detallesAdicionales array No Hasta 3 objetos { "nombre", "valor" }.

No uses codigoInterno ni codigoAdicional, porque la API responde 422 con Campo no soportado en este contrato.

Tampoco envíes unidadMedida ni precioSinSubsidio, porque la API no los procesa y los rechaza como campos desconocidos.

Reglas de cálculo y validaciones#

Las fórmulas de líneas, impuestos, totales y pagos son las de Cómo calcular los totales. Si una regla no se cumple, la API responde 422 con el codEstado 3002 (comprobante_invalido). Estos son los errores típicos de la liquidación de compra:

Error típico Mensaje (en errores) Qué hacer
Enviar propina, aunque sea 0. $.info.propina: Campo no soportado en este contrato. Quita propina.
Usar los campos de la factura, como tipoIdentificacionComprador. $.info.tipoIdentificacionComprador: Campo no soportado en este contrato. Usa tipoIdentificacionProveedor, identificacionProveedor y razonSocialProveedor.
Identificar al proveedor como consumidor final (07). ...requiere un contribuyente identificado. Identifica al proveedor con cédula, pasaporte o identificación del exterior.
Enviar una cédula que no tiene 10 dígitos o un RUC que no tiene 13. Cédula tiene longitud o caracteres inválidos. / RUC tiene longitud o caracteres inválidos. Revisa la identificación del proveedor.
Omitir pagos. $.info.pagos: Lista vacia, invalida o demasiado extensa. Informa cómo pagas al proveedor.
Usar codigoInterno en las líneas. Campo no soportado en este contrato. Usa codigoPrincipal.
Enviar un ICE (codigo "3") en una línea. La liquidación de compra solo admite IVA. Deja solo el IVA en cada línea.
Enviar totales que no cuadran. Totales no coinciden con detalles. / total no coincide con subtotal + IVA + ICE + propina. / Pagos no coinciden con total. Recalcula con las fórmulas.
Calcular mal una línea. Subtotal del detalle no coincide con cantidad × precio − descuento. / Valor de impuesto no coincide con base y tasa. Recalcula la línea como en la factura.
Omitir unidadTiempo cuando hay plazo. Obligatoria cuando hay plazo. Agrega "unidadTiempo": "dias".

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": "03",
  "numeroDocumento": "002-001-000000001",
  "referenciaExterna": "LIQUIDACION-2026-0001",
  "claveAcceso": null,
  "fhRecibido": "2026-11-16T10:15:00-05:00",
  "fhAutorizacion": null
}
Campo Tipo Descripción
estado string recibido: el comprobante pasó nuestras validaciones y lo aceptamos. No es una autorización. 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 202 significa que la liquidación 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 y entrégalo al proveedor.

Estados de este endpoint#

Esta tabla reúne las respuestas que puedes recibir al emitir una liquidación de compra.

codEstado HTTP Cuándo ocurre Qué hacer
1001 o 1002 202 La liquidación 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. No reenvíes con otros datos.
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 liquidación no cumple una regla; el detalle viene en errores. Corrige según la tabla de errores típicos. Consume 1 documento como intento.
3004 (comprobante_duplicado) 409 Ya existe una liquidación 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 La liquidación de compra no está habilitada para tu integración, o el ruc no es el del contribuyente. Revisa tiposComprobante en 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.