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). Lo que no se aplica queda como anticipo (saldo a favor del cliente) para aplicarlo después, y un cobro también puede cancelarse con cruce contra cuentas contables. Incluye reportes de cartera por antigüedad y estado de cuenta por cliente.

Registrar un cobro

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

Body

Forma de aplicaciones[]

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,
  "monto_anticipo": 0,
  "saldo_anticipo": 0,
  "cruce_lineas": [],
  "creado_en": "2026-07-06T15:00:03",
  "aplicaciones": [
    { "id": 101, "factura_id": 177, "monto_aplicado": 100.0, "desde_anticipo": false, "fecha_aplicacion": null },
    { "id": 102, "factura_id": 181, "monto_aplicado": 50.0, "desde_anticipo": false, "fecha_aplicacion": null }
  ]
}

Errores

Listar cobros

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

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

Cambiar la fecha de un cobro

PATCH /api/v1/cobros/{id}/fecha — Corrige la fecha del cobro, de su ingreso en el banco y de su asiento (sin rehacerlo)

{
  "fecha": "2026-09-28T15:00:00",
  "asiento_movido": true,
  "avisos": []
}

asiento_movido indica si el cobro tenía asiento y se movió con él (mismo número); avisos lista efectos colaterales (por ejemplo, el ingreso se desmarcó de una conciliación en curso). Si parte del anticipo ya se aplicó, el cobro no puede quedar después de esa aplicación. Reglas comunes en fechas contables: 400 por fecha inválida, 409 si el cobro está anulado o el cambio toca una conciliación bancaria cerrada.

Cobros con cruce

Un cobro con cruce cancela facturas o notas de débito contra una o varias cuentas contables en vez de caja o bancos (por ejemplo, compensar con lo que le debes a ese cliente). No mueve dinero y genera el asiento Debe las cuentas del cruce / Haber cuentas por cobrar. Las líneas tienen la misma forma y reglas que en pagos con cruce: medio "15", sin cuenta_dinero_id, Σ cruce[].monto igual a monto al centavo y aplicado completo a documentos (no deja anticipo); si no, 422. La cuenta no puede ser de caja/bancos ni la propia cuenta por cobrar a clientes (400). El cobro trae las líneas en cruce_lineas.

{
  "cliente_id": 12,
  "fecha": "2026-10-06T10:00:00",
  "medio": "15",
  "monto": 300.00,
  "aplicaciones": [
    { "factura_id": 205, "monto_aplicado": 300.00 }
  ],
  "cruce": [
    { "cuenta_id": 2210, "monto": 300.00, "tercero_id": 12, "descripcion": "Compensación con CxP al cliente" }
  ]
}

Anticipos (saldo a favor)

Un cobro que recibe más de lo que aplica deja la diferencia como anticipo: monto_anticipo es lo que quedó sin aplicar al crearlo y saldo_anticipo lo que falta aplicar. Contablemente es un pasivo (201.10 Anticipos de clientes) hasta que se aplica a una factura o nota de débito del mismo cliente. Aplicarlo baja el saldo del documento sin mover dinero y genera su propio asiento con la fecha de aplicación.

Registrar un anticipo y aplicarlo después

Registrar un anticipo emite el evento cobro.registrado de siempre; aplicarlo emite factura.pagada (o nota_debito.pagada) si el documento queda en cero. No hay eventos propios de anticipos.

const cobro = await client.cobros.crear({
  cliente_id: 12,
  fecha: new Date().toISOString(),
  medio: "20",
  monto: 1000.0,
  cuenta_dinero_id: 3,
  aplicaciones: [], // todo queda como anticipo
});

// Cuando emites la factura:
await client.cobros.aplicarAnticipo(cobro.id, {
  fecha: "2026-09-15",
  aplicaciones: [{ factura_id: 190, monto_aplicado: 400.0 }],
});

cobro = client.cobros.crear({
    "cliente_id": 12,
    "fecha": "2026-09-01T10:00:00",
    "medio": "20",
    "monto": 1000.00,
    "cuenta_dinero_id": 3,
    "aplicaciones": [],  # todo queda como anticipo
})

# Cuando emites la factura:
client.cobros.aplicar_anticipo(cobro["id"], {
    "fecha": "2026-09-15",
    "aplicaciones": [{"factura_id": 190, "monto_aplicado": 400.00}],
})

cobro, err := client.Cobros.Crear(ctx, emitoo.M{
	"cliente_id":       12,
	"fecha":            time.Now().Format(time.RFC3339),
	"medio":            "20",
	"monto":            1000.0,
	"cuenta_dinero_id": 3,
	"aplicaciones":     []emitoo.M{}, // todo queda como anticipo
})
if err != nil {
	log.Fatal(err)
}

// Cuando emites la factura:
_, err = client.Cobros.AplicarAnticipo(ctx, int(cobro["id"].(float64)), emitoo.M{
	"fecha":        "2026-09-15",
	"aplicaciones": []emitoo.M{{"factura_id": 190, "monto_aplicado": 400.0}},
})

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-09-01T10:00:00",
    "medio": "20",
    "monto": 1000.00,
    "referencia": "TRF-1",
    "cuenta_dinero_id": 3,
    "aplicaciones": []
  }'

Anticipos por aplicar

GET /api/v1/cobros/anticipos?cliente_id= — Cobros no anulados con saldo_anticipo > 0, del más antiguo al más reciente

[
  {
    "cobro_id": 95,
    "fecha": "2026-09-01T10:00:00",
    "cliente_id": 12,
    "cliente_nombre": "ACME S.A.",
    "referencia": "TRF-1",
    "monto_anticipo": 1000.0,
    "saldo_anticipo": 600.0
  }
]

Aplicar un anticipo

POST /api/v1/cobros/{id}/aplicar-anticipo — Aplica el anticipo del cobro a facturas o notas de débito del mismo cliente

{
  "fecha": "2026-09-15",
  "aplicaciones": [
    { "factura_id": 190, "monto_aplicado": 400.00 }
  ]
}

Devuelve el cobro con la nueva aplicación (desde_anticipo: true y su fecha_aplicacion).

Deshacer una aplicación del anticipo

DELETE /api/v1/cobros/{id}/aplicaciones/{aplicacion_id}?fecha= — Devuelve el saldo al documento y al anticipo, y revierte su asiento

Solo para aplicaciones hechas desde el anticipo (409 si la aplicación se hizo con el cobro). fecha (query, opcional) es la del reverso del asiento; sin ella, la de la aplicación si su período sigue abierto (400 si no es válida). Devuelve el cobro actualizado.

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

saldo_a_favor es la suma de los anticipos del cliente aún sin aplicar; se informa aparte y no se resta de saldo_pendiente.

{
  "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,
  "total_retenido": 0,
  "saldo_pendiente": 50.0,
  "saldo_a_favor": 600.0
}

Exportar a CSV

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

Como todas las descargas CSV de la API, el archivo empieza con el BOM UTF-8 para que Excel muestre bien las tildes y la ñ. Si lo lees por código, usa utf-8-sig (Python) o descarta el primer carácter \uFEFF.

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:

// 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 }
    ]
  }
}