API Reference

Cobros

Cuentas por cobrar (CxC): registra el dinero que recibes de un cliente y aplícalo contra una o varias facturas a crédito (abono parcial o pago consolidado). Incluye reportes de cartera por antigüedad y estado de cuenta por cliente.

Autenticación

Todos los endpoints de este recurso requieren el header X-API-Key con una API key que tenga permisos sobre el recurso cobros. 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 cobro

POST /api/v1/cobros — Crea un cobro y sus aplicaciones a factura(s)

Body

Parámetro	Tipo	Descripción
`cliente_id` required	integer	Id del cliente (PersonaEmpresa con es_cliente=true).
`fecha` required	datetime	Fecha en que se recibió 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 cobro. Debe cuadrar (±0.01) con la Σ de aplicaciones.monto_aplicado.
`referencia` optional	string	Referencia libre (n° de depósito, transferencia, etc). Máx 120 caracteres.
`notas` optional	string	Notas internas.
`cuenta_dinero_id` optional	integer	Cuenta de caja/banco donde ingresó 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: { factura_id, monto_aplicado }.

Forma de `aplicaciones[]`

Parámetro	Tipo	Descripción
`factura_id` required	integer	Factura a la que se aplica el pago. Debe estar AUTORIZADA.
`monto_aplicado` required	number	Monto aplicado a esa factura. No puede superar el saldo pendiente de la factura.

import { Emitoo } from "emitoo";

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

const cobro = await client.cobros.crear({
  cliente_id: 12,
  fecha: new Date().toISOString(),
  medio: "01",
  monto: 150.0,
  referencia: "DEP-88213",
  aplicaciones: [
    { factura_id: 177, monto_aplicado: 100.0 },
    { factura_id: 181, monto_aplicado: 50.0 },
  ],
});

from emitoo import EmitooClient

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

cobro = client.cobros.crear({
    "cliente_id": 12,
    "fecha": "2026-07-06T15:00:00",
    "medio": "01",
    "monto": 150.00,
    "referencia": "DEP-88213",
    "aplicaciones": [
        {"factura_id": 177, "monto_aplicado": 100.00},
        {"factura_id": 181, "monto_aplicado": 50.00},
    ],
})

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

cobro, err := client.Cobros.Crear(ctx, emitoo.M{
	"cliente_id": 12,
	"fecha":      time.Now().Format(time.RFC3339),
	"medio":      "01",
	"monto":      150.0,
	"referencia": "DEP-88213",
	"aplicaciones": []emitoo.M{
		{"factura_id": 177, "monto_aplicado": 100.0},
		{"factura_id": 181, "monto_aplicado": 50.0},
	},
})
if err != nil {
	log.Fatal(err)
}

curl -X POST https://api.emitoo.io/api/v1/cobros \
  -H "X-API-Key: $EMITOO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cliente_id": 12,
    "fecha": "2026-07-06T15:00:00",
    "medio": "01",
    "monto": 150.00,
    "referencia": "DEP-88213",
    "aplicaciones": [
      { "factura_id": 177, "monto_aplicado": 100.00 },
      { "factura_id": 181, "monto_aplicado": 50.00 }
    ]
  }'

Respuesta (201 Created)

{
  "id": 88,
  "fecha": "2026-07-06T15:00:00",
  "cliente_id": 12,
  "medio": "01",
  "monto": 150.0,
  "referencia": "DEP-88213",
  "notas": null,
  "cuenta_dinero_id": null,
  "anulado": false,
  "anulado_motivo": null,
  "anulado_en": null,
  "creado_en": "2026-07-06T15:00:03",
  "aplicaciones": [
    { "id": 101, "factura_id": 177, "monto_aplicado": 100.0 },
    { "id": 102, "factura_id": 181, "monto_aplicado": 50.0 }
  ]
}

Errores

Código	Cuándo ocurre
`404`	El cliente no existe, o alguna de las facturas referenciadas en `aplicaciones` no existe.
`409`	Una factura no está AUTORIZADA, o el `monto_aplicado` de una línea supera su saldo pendiente.
`422`	El `medio` no es un código válido de la Tabla 24 SRI, o Σ(aplicaciones) no cuadra con `monto`.

Listar cobros

GET /api/v1/cobros?cliente_id=&desde=&hasta=&limit=&offset= — Listado con filtros opcionales

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

Obtener un cobro

GET /api/v1/cobros/{id} — Detalle completo, con sus aplicaciones a factura

Anular un cobro

POST /api/v1/cobros/{id}/anular — Anula el cobro y revierte sus aplicaciones (el saldo de las facturas vuelve a subir)

Body

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

Un cobro anulado no se puede volver a anular

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

Cartera por antigüedad

GET /api/v1/cobros/cartera — Saldo pendiente agrupado en buckets 0-30 / 31-60 / 61-90 / 90+ días

Los días se cuentan desde fecha_vencimiento de cada factura a crédito con saldo pendiente.

{
  "buckets": [
    { "dias": "0-30",  "total": 1240.50, "cantidad": 8 },
    { "dias": "31-60", "total": 430.00,  "cantidad": 3 },
    { "dias": "61-90", "total": 0,       "cantidad": 0 },
    { "dias": "90+",   "total": 210.00,  "cantidad": 1 }
  ],
  "total_general": 1880.50
}

Estado de cuenta de un cliente

GET /api/v1/cobros/estado-cuenta/{cliente_id} — Facturas, cobros y notas de crédito aplicadas, con saldo corrido

{
  "cliente_id": 12,
  "cliente_razon_social": "ACME S.A.",
  "cliente_identificacion": "0991234567001",
  "lineas": [
    {
      "factura_id": 177,
      "numero_comprobante": "001-001-000000177",
      "fecha_emision": "2026-07-03T10:12:34",
      "fecha_vencimiento": "2026-08-02",
      "total": 150.0,
      "total_cobrado": 100.0,
      "total_nc_aplicadas": 0,
      "saldo": 50.0
    }
  ],
  "total_facturado": 150.0,
  "total_cobrado": 100.0,
  "total_nc": 0,
  "saldo_pendiente": 50.0
}

Exportar a CSV

GET /api/v1/cobros/estado-cuenta/{cliente_id}?format=csv — Mismo reporte, como archivo CSV descargable

Exportar a PDF

GET /api/v1/cobros/estado-cuenta/{cliente_id}/pdf — El mismo reporte, como PDF (Content-Type: application/pdf)

Eventos

Este módulo emite los siguientes eventos:

Evento	Cuándo se dispara
`cobro.registrado`	Se creó un cobro (POST /cobros).
`cobro.anulado`	Se anuló un cobro (POST /cobros/{id}/anular).
`factura.pagada`	El saldo de una factura llegó a 0 tras aplicar un cobro (o una nota de crédito).
`factura.por_vencer`	Una factura a crédito con saldo vence en 3 días. Lo emite un job diario a las 07:00 (America/Guayaquil).
`factura.vencida`	Una factura a crédito con saldo venció ayer. Mismo job diario a las 07:00 (America/Guayaquil).

// POST https://tu-app.com/webhooks/emitoo
// X-Emitoo-Event: cobro.registrado

{
  "evento": "cobro.registrado",
  "data": {
    "id": 88,
    "cliente_id": 12,
    "medio": "01",
    "monto": 150.0,
    "referencia": "DEP-88213",
    "aplicaciones": [
      { "factura_id": 177, "monto_aplicado": 100.0 },
      { "factura_id": 181, "monto_aplicado": 50.0 }
    ]
  }
}

Recordatorios automáticos de cobro

Combina factura.por_vencer con un workflow y el nodo de acción de email para enviar recordatorios de pago automáticos a tus clientes 3 días antes del vencimiento, sin escribir código.

Cobros

Registrar un cobro

Body

Forma de aplicaciones[]

Respuesta (201 Created)

Errores

Listar cobros

Obtener un cobro

Anular un cobro

Body

Cartera por antigüedad

Estado de cuenta de un cliente

Exportar a CSV

Exportar a PDF

Eventos

Forma de `aplicaciones[]`