Pagos de documentos

Registrar dinero contra una reserva o una nota de venta. Puerta heredada — `POST /payments` es la vía nueva y más completa.

Beta

Puede cambiar en cualquier momento, con una entrada en el changelog y aviso a quienes la llamaron recientemente — ver versionado.

Descarga la proyección completa de la API pública: openapi.json.

Vender una unidad explica este recurso en prosa, con ejemplos ejecutables.

Método	Ruta	Qué hace
`GET`	`/document-payments`	DEPRECATED — the payments and running totals for one document
`POST`	`/document-payments`	DEPRECATED — record a payment against a reservation or a sale note

`GET /document-payments`

DEPRECATED — the payments and running totals for one document

The query must name exactly one of reservation_id / sale_note_id. Deliberately no fetch-by-id route — a payment is only ever read in the context of the document it belongs to.

DEPRECATED (payments ledger T11). The rows served here are now the ALLOCATIONS against the document’s obligation, projected into this endpoint’s existing shape; id is the payment’s id and amount_clp is what that payment settles ON THIS DOCUMENT. The totals are unchanged and still come from the one roll-up (BR-249). GET /obligations/\{id\} and GET /contacts/\{id\}/ledger are the replacements.

Parámetro	En	Tipo	Obligatorio	Restricciones
`reservation_id`	query	any	no
`sale_note_id`	query	any	no

curl https://api.vitrinadev.com/api/v1/document-payments \
  -H "Authorization: Bearer $VITRINA_KEY"

Ejemplo de respuesta (200)

{
  "data": {
    "payments": [
      {
        "id": "d6d6d6d6-0000-4000-8000-000000000002",
        "tenant_id": "a1a1a1a1-0000-4000-8000-000000000001",
        "reservation_id": null,
        "sale_note_id": "d4d4d4d4-0000-4000-8000-000000000001",
        "carried_from_reservation_id": "d3d3d3d3-0000-4000-8000-000000000001",
        "instrument": "tarjeta_credito",
        "amount_clp": 8900000,
        "paid_on": "2026-09-24",
        "bank": null,
        "account_number": null,
        "document_number": "482910",
        "note": null,
        "card_fee_bps": 250,
        "card_surcharge_clp": 222500,
        "card_surcharge_source": "calculado",
        "created_at": "2026-09-24T12:05:00.000Z"
      }
    ],
    "totals": {
      "total_a_pagar_clp": 8900000,
      "total_pagos_clp": 8900000,
      "saldo_clp": 0,
      "recargo_tarjeta_clp": 222500,
      "total_a_cobrar_clp": 9122500,
      "payment_count": 1,
      "complete": true,
      "gaps": []
    }
  },
  "meta": {
    "total": 1
  }
}

Responde: 200 · 400 · 401 · 403 · 404 · 409 · 429

`POST /document-payments`

DEPRECATED — record a payment against a reservation or a sale note

The body must name exactly one of reservation_id / sale_note_id (UUID or folio).

DEPRECATED (payments ledger T11). This endpoint no longer writes document_payment: it records a customer_payment and allocates it to the document's customer_obligation, so there is exactly one answer to "how much has this customer paid us". It is kept because the ERP screens call it daily, and its request and response shapes are unchanged. Use POST /payments for anything new — it can split one payment across several obligations, leave a surplus as the contact’s credit, accept an Idempotency-Key, and be reversed, none of which this door can express. Idempotency-Key IS honoured here too.

⚠ amount_clp in the response is WHAT LANDED ON THE DOCUMENT (the allocation), which equals the amount recorded on every path that had an obligation to settle, and is 0 when the document had none (no holder contact, or nothing owed) — the payment itself is still the full amount and is readable on the contact’s ficha through GET /payments.

Cuerpo

Campo	Tipo	Obligatorio	Restricciones
`reservation_id`	any	—
`sale_note_id`	any	—
`instrument`	`efectivo` \	`transferencia` \	`cheque` \
`amount_clp`	integer	sí	≥ 1, ≤ 999999999999
`paid_on`	string	sí	patrón `^\d{4}-\d{2}-\d{2}$`
`card_surcharge_clp`	integer \| null	—	≥ 0, ≤ 999999999999
`bank`	string \| null	—	máx. 120
`account_number`	string \| null	—	máx. 120
`document_number`	string \| null	—	máx. 120
`note`	string \| null	—	máx. 2000

curl -X POST https://api.vitrinadev.com/api/v1/document-payments \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reservation_id": "d3d3d3d3-0000-4000-8000-000000000001",
    "instrument": "transferencia",
    "amount_clp": 300000,
    "paid_on": "2026-09-18",
    "bank": "Banco Estado",
    "note": "abono al tomar la reserva"
  }'

Ejemplo de respuesta (201)

{
  "data": {
    "id": "d6d6d6d6-0000-4000-8000-000000000001",
    "tenant_id": "a1a1a1a1-0000-4000-8000-000000000001",
    "reservation_id": "d3d3d3d3-0000-4000-8000-000000000001",
    "sale_note_id": null,
    "carried_from_reservation_id": null,
    "instrument": "transferencia",
    "amount_clp": 300000,
    "paid_on": "2026-09-18",
    "bank": "Banco Estado",
    "account_number": null,
    "document_number": null,
    "note": "abono al tomar la reserva",
    "card_fee_bps": null,
    "card_surcharge_clp": null,
    "card_surcharge_source": null,
    "created_at": "2026-09-18T16:41:02.000Z"
  }
}

Responde: 201 · 400 · 401 · 403 · 404 · 409 · 429

Pagos de documentos

GET /document-payments

POST /document-payments

En esta página

`GET /document-payments`

`POST /document-payments`