API Reference

Liquidaciones de compra

codDoc 03 — la emite el COMPRADOR (tu empresa) cuando el proveedor no puede facturar (servicios personales, extranjeros no residentes, etc.). Estructura casi idéntica a la factura pero el sujeto del comprobante es el PROVEEDOR, no el comprador. El proveedor se selecciona/crea como PersonaEmpresa con es_proveedor=True (el flag ya existe, no se crea entidad nueva).

Eventos

Cada liquidación emite liquidacion.creada al encolarse y liquidacion.autorizada / liquidacion.rechazada / liquidacion.devuelta al resolverse el SRI.

Emitir una liquidación

POST /api/v1/liquidaciones-compra — Crea y encola una liquidación (async)

Body

Parámetro	Tipo	Descripción
`proveedor_id` optional	integer	ID del proveedor en tu catálogo (PersonaEmpresa). Si lo envías, los datos del proveedor se pueden omitir y la flag es_proveedor se asegura.
`proveedor_tipo_id` required	string	Tipo de identificación del proveedor (tabla SRI).
`proveedor_identificacion` required	string	RUC/cédula/doc. del proveedor.
`proveedor_razon_social` required	string	Razón social del proveedor.
`proveedor_direccion` optional	string	Dirección del proveedor.
`email` optional	string	Email para enviar el RIDE.
`cod_doc_sustento` optional	string	Código del doc. sustento (opcional). Las LC suelen NO traerlo.
`doc_sustento_numero` optional	string	Número del doc. sustento (15 dígitos, acepta con o sin guiones).
`doc_sustento_fecha` optional	date	Fecha del doc. sustento (ISO 8601).
`detalles` required	array	Líneas. Mínimo 1. Misma forma que en factura.
`pagos` optional	array	Formas de pago (mismo shape que en la factura). Si se omite, se persiste un único pago '01' (efectivo) por el total.
`condicion_pago` optional	string	'contado' (default) o 'credito'.
`fecha_vencimiento` optional	date	Solo si 'condicion_pago'='credito' (YYYY-MM-DD).
`sucursal_id` optional	integer	Sucursal emisora. Se infiere del usuario si se omite.
`es_borrador` optional	boolean	Si true, guarda como BORRADOR sin encolar al SRI.
`idempotency_key` optional	string	Idempotencia (también header Idempotency-Key).

Respuesta (201 Created)

{
  "id": 5,
  "numero_comprobante": "001-001-000000001",
  "fecha_emision": "2026-07-05T12:00:00",
  "proveedor_tipo_id": "04",
  "proveedor_identificacion": "1798888888001",
  "proveedor_razon_social": "PROVEEDOR S.A.",
  "proveedor_direccion": "Av. Proveedor 1",
  "subtotal_0": 0.0,
  "subtotal_15": 100.0,
  "iva": 15.0,
  "total": 115.0,
  "estado": "PENDIENTE",
  "clave_acceso": null,
  "numero_autorizacion": null,
  "proveedor_id": 10,
  "detalles": [ { "...": "..." } ],
  "pagos": [ { "forma_pago": "01", "total": 115.0 } ]
}

import { Emitoo } from "emitoo";

const client = new Emitoo(); // lee la API key de EMITOO_API_KEY

const lc = await client.liquidaciones.crear(
  {
    proveedor_tipo_id: "04",
    proveedor_identificacion: "1798888888001",
    proveedor_razon_social: "PROVEEDOR S.A.",
    proveedor_direccion: "Av. Proveedor 1",
    detalles: [
      { codigo_principal: "SRV-1", descripcion: "Servicio de consultoría",
        cantidad: 1, precio_unitario: 100.0, tarifa_iva: 15 },
    ],
  },
  { idempotencyKey: "lc-90210" },
);

from emitoo import EmitooClient

client = EmitooClient()  # lee la API key de EMITOO_API_KEY

lc = client.liquidaciones.crear(
    {
        "proveedor_tipo_id": "04",
        "proveedor_identificacion": "1798888888001",
        "proveedor_razon_social": "PROVEEDOR S.A.",
        "detalles": [
            {"codigo_principal": "SRV-1", "descripcion": "Servicio de consultoría",
             "cantidad": 1, "precio_unitario": 100.0, "tarifa_iva": 15},
        ],
    },
    idempotency_key="lc-90210",
)

client, err := emitoo.New("") // lee la API key de EMITOO_API_KEY
if err != nil {
	log.Fatal(err)
}
ctx := context.Background()

lc, err := client.Liquidaciones.Crear(ctx, emitoo.M{
	"proveedor_tipo_id":        "04",
	"proveedor_identificacion": "1798888888001",
	"proveedor_razon_social":   "PROVEEDOR S.A.",
	"proveedor_direccion":      "Av. Proveedor 1",
	"detalles": []emitoo.M{
		{"codigo_principal": "SRV-1", "descripcion": "Servicio de consultoría",
			"cantidad": 1, "precio_unitario": 100.0, "tarifa_iva": 15},
	},
}, emitoo.WithIdempotencyKey("lc-90210"))
if err != nil {
	log.Fatal(err)
}

curl -X POST https://api.emitoo.io/api/v1/liquidaciones-compra \
  -H "X-API-Key: $EMITOO_API_KEY" \
  -H "Idempotency-Key: lc-90210" \
  -H "Content-Type: application/json" \
  -d '{
    "proveedor_tipo_id": "04",
    "proveedor_identificacion": "1798888888001",
    "proveedor_razon_social": "PROVEEDOR S.A.",
    "detalles": [
      { "codigo_principal": "SRV-1", "descripcion": "Servicio de consultoría",
        "cantidad": 1, "precio_unitario": 100.00, "tarifa_iva": 15 }
    ]
  }'

¿Cuándo se considera autorizada?

La liquidación responde al instante en PENDIENTE. Te avisamos por webhook con liquidacion.autorizada, o puedes hacer polling al endpoint de estado de más abajo.

Atajo: retención automática

Las liquidaciones suelen ir acompañadas de su retención (codSustento '03'). Tras autorizar una liquidación, la UI ofrece crear la retención prellenando el doc sustento.

Obtener una liquidación

GET /api/v1/liquidaciones-compra/{id} — Detalle completo, con líneas y pagos

Consultar el estado

GET /api/v1/liquidaciones-compra/{id}/status — Solo el estado actual (más liviano, ideal para polling)

Reenviar al SRI

POST /api/v1/liquidaciones-compra/{id}/reenviar — Re-encola la liquidación al worker (sin body)

RIDE (PDF)

GET /api/v1/liquidaciones-compra/{id}/ride — Devuelve el PDF binario

Reenviar por email

POST /api/v1/liquidaciones-compra/{id}/email?to=opcional — Envía el RIDE (y el XML firmado) por email

Listado

GET /api/v1/liquidaciones-compra — Listado compacto (id, número, fecha, proveedor, total, estado, ambiente)