Document payments

Record money against a reservation or a sale note. A legacy door — `POST /payments` is the newer, fuller path.

Beta

This may change at any time, with a changelog entry and a notice to recent callers — see versioning.

Download the full API pública projection: openapi.json.

Sell a unit explains this resource in prose, with runnable examples.

Method	Path	What it does
`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.

Parameter	In	Type	Required	Constraints
`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"

Example response (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
  }
}

Answers: 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.

Body

Field	Type	Required	Constraints
`reservation_id`	any	—
`sale_note_id`	any	—
`instrument`	`efectivo` \	`transferencia` \	`cheque` \
`amount_clp`	integer	yes	≥ 1, ≤ 999999999999
`paid_on`	string	yes	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"
  }'

Example response (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"
  }
}

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

Document payments

GET /document-payments

POST /document-payments

On this page

`GET /document-payments`

`POST /document-payments`