Docs / API Reference / Pagos a proveedores
API Reference

Pagos a proveedores

Cuentas por pagar (CxP): registra el dinero que le pagas a un proveedor y aplícalo contra una o varias compras (abono parcial o pago consolidado). Espejo exacto de Cobros sobre Compra en vez de Factura. Incluye la agenda de pagos semanal.

Autenticación

Todos los endpoints de este recurso requieren el header X-API-Key con una API key que tenga permisos sobre el recurso pagos_proveedor. Igual que el resto de la API, el tenant se resuelve por la propia key (no hace falta X-Tenant-Id en integraciones vía API pública).

Registrar un pago

POST /api/v1/pagos-proveedor — Crea un pago y sus aplicaciones a compra(s)

Body

Parámetro Tipo Descripción
proveedor_id required integer Id del proveedor (PersonaEmpresa con es_proveedor=true).
fecha required datetime Fecha en que se entregó el dinero (ISO 8601).
medio required string Medio de pago — código de la Tabla 24 SRI (ej. '01' efectivo, '16' t. débito, '19' t. crédito).
monto required number Monto total del pago. Debe cuadrar (±0.01) con la Σ de aplicaciones.monto_aplicado.
referencia optional string Referencia libre (n° de transferencia, cheque, etc). Máx 120 caracteres.
notas optional string Notas internas.
cuenta_dinero_id optional integer Cuenta de caja/banco desde la que salió el dinero (módulo de cajas y bancos, fase posterior).
sucursal_id optional integer Sucursal de trazabilidad. Si se omite, se infiere del usuario.
aplicaciones required array Mínimo 1 elemento. Cada uno: { compra_id, monto_aplicado }.

Forma de aplicaciones[]

Parámetro Tipo Descripción
compra_id required integer Compra (documento recibido) a la que se aplica el pago.
monto_aplicado required number Monto aplicado a esa compra. No puede superar su saldo pendiente (total − total_pagado). 
import { Emitoo } from "emitoo";

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

const pago = await client.pagosProveedor.crear({
  proveedor_id: 7,
  fecha: new Date().toISOString(),
  medio: "01",
  monto: 320.0,
  referencia: "TRF-55021",
  aplicaciones: [
    { compra_id: 214, monto_aplicado: 200.0 },
    { compra_id: 219, monto_aplicado: 120.0 },
  ],
});

Respuesta (201 Created)

{
  "id": 41,
  "fecha": "2026-07-06T09:30:00",
  "proveedor_id": 7,
  "medio": "01",
  "monto": 320.0,
  "referencia": "TRF-55021",
  "notas": null,
  "cuenta_dinero_id": null,
  "anulado": false,
  "anulado_motivo": null,
  "anulado_en": null,
  "creado_en": "2026-07-06T09:30:04",
  "aplicaciones": [
    { "id": 61, "compra_id": 214, "monto_aplicado": 200.0 },
    { "id": 62, "compra_id": 219, "monto_aplicado": 120.0 }
  ]
}

Errores

Código Cuándo ocurre
404El proveedor no existe, o alguna de las compras referenciadas en aplicaciones no existe.
409El monto_aplicado de una línea supera el saldo pendiente de esa compra.
422El medio no es un código válido de la Tabla 24 SRI, o Σ(aplicaciones) no cuadra con monto.

Listar pagos

GET /api/v1/pagos-proveedor?proveedor_id=&desde=&hasta=&limit=&offset= — Listado con filtros opcionales

Parámetro Tipo Descripción
proveedor_id optional integer Filtra por proveedor.
desde optional date Fecha inicial (inclusive).
hasta optional date Fecha final (inclusive).
limit optional integer Default 50.
offset optional integer Default 0.

Obtener un pago

GET /api/v1/pagos-proveedor/{id} — Detalle completo, con sus aplicaciones a compra

Anular un pago

POST /api/v1/pagos-proveedor/{id}/anular — Anula el pago y revierte sus aplicaciones (el saldo de las compras vuelve a subir)

Body

Parámetro Tipo Descripción
motivo required string Motivo de la anulación. Máx 300 caracteres.

Un pago anulado no se puede volver a anular

Un segundo intento de anular el mismo pago responde 409. Si necesitas corregir el monto o las compras aplicadas, anula y crea un pago nuevo.

Agenda de pagos

GET /api/v1/pagos-proveedor/agenda — Compras con saldo pendiente, agrupadas por semana ISO (lunes) de fecha_vencimiento

Cada compra con saldo > 0 se agrupa en la semana (lunes ISO) de su fecha_vencimiento (o de fecha_emision si no tiene vencimiento). Útil para planificar los pagos de la semana. 

{
  "semanas": [
    {
      "semana": "2026-07-06",
      "total": 320.0,
      "cantidad": 2,
      "compras": [
        {
          "id": 214,
          "numero_doc": "001-001-000000214",
          "proveedor_razon_social": "Distribuidora Andina S.A.",
          "fecha_vencimiento": "2026-07-08",
          "total": 200.0,
          "total_pagado": 0,
          "saldo": 200.0
        },
        {
          "id": 219,
          "numero_doc": "001-002-000000019",
          "proveedor_razon_social": "Suministros del Pacífico",
          "fecha_vencimiento": "2026-07-10",
          "total": 120.0,
          "total_pagado": 0,
          "saldo": 120.0
        }
      ]
    }
  ],
  "total_general": 320.0
}

Eventos

Este módulo emite los siguientes eventos:

Evento Cuándo se dispara
pago_proveedor.registradoSe creó un pago (POST /pagos-proveedor).
pago_proveedor.anuladoSe anuló un pago (POST /pagos-proveedor/{id}/anular).
compra.pagadaEl saldo de una compra llegó a 0 tras aplicar un pago.
 
// POST https://tu-app.com/webhooks/emitoo
// X-Emitoo-Event: pago_proveedor.registrado

{
  "evento": "pago_proveedor.registrado",
  "data": {
    "id": 41,
    "proveedor_id": 7,
    "medio": "01",
    "monto": 320.0,
    "referencia": "TRF-55021",
    "compras": [214, 219]
  }
}

Automatiza el pago a proveedores

Combina compra.creada con un workflow para avisar por email o WhatsApp cuando llega una compra con vencimiento próximo, usando la misma agenda que ves en GET /pagos-proveedor/agenda.
Anterior ← Cobros