API: exponer endpoint de settlements/liquidaciones a organizador (monto + comprobante PDF)

[Julianfsm10]

Contexto: Estamos integrando la API B2B de FreeTicket en un dashboard financiero interno (Finance-freeticket) para consolidar cuánto se le liquida a cada artista/organizador por evento. Revisamos el OpenAPI completo (GET /api/v1/openapi.json, CLI 0.8.0) buscando settlement/liquidat/payout/receipt/document/pdf/comprobante/disburs — ningún endpoint existe con esos conceptos.

Wish / friction: El panel de FreeTicket (tanto para el organizador como el interno) ya muestra una sección "Liquidaciones" con el monto consignado y un PDF de comprobante por evento — pero eso no está expuesto por la API B2B ni por ft admin. Hoy tenemos que recalcular el bruto/comisión/neto nosotros mismos cruzando GET /sales, GET /reports/by-event y datos de Mercado Pago, en vez de poder leer directamente el valor y el comprobante que FreeTicket ya calculó y generó internamente.

Por qué importa: Sin este endpoint, el monto que liquida FreeTicket al organizador queda como un cálculo aproximado nuestro (basado en ventas confirmadas + fee de Mercado Pago) en vez del número real/autoritativo que FreeTicket ya generó, y no hay forma de traer automáticamente el PDF de comprobante para archivarlo junto al resto de la documentación financiera.

Lo que necesitaríamos, idealmente:

• GET /events/{id}/settlement o similar: monto consignado, fecha, estado, por evento.
• Un link/descarga al PDF de comprobante asociado.

Reportado vía la skill freeticket-cli, a pedido del usuario del dashboard Finance-freeticket.

[Julianfsm10]

Nota para quien triage esto: revisé los 3 contratos OpenAPI (openapi.json B2B, admin-openapi.json, public-openapi.json) de los 4 repos públicos (freeticket-cli, freeticket-mcp, agent-skills, ai-native) y ningún settlement/liquidation/payout/receipt/document endpoint existe en ninguno.

Según ai-native/CONTRACT-GAPS.md, el proceso correcto para esto es abrir el issue en AppFreeticket/free-admin (repo privado del backend, donde vive el contrato real) y agregar la fila correspondiente al ledger — igual que se hizo con #160-#191. No tengo acceso a free-admin desde esta cuenta, así que dejo esto acá para que alguien del equipo lo traslade allá y lo sume a esa tabla si aplica.

Resumen para el traslado:

• Necesidad: endpoint de settlements/liquidaciones a organizador — monto consignado + link/descarga de comprobante PDF, por evento.
• Sugerido: GET /events/{id}/settlement o similar.
• Motivo: hoy un tercero (dashboard financiero externo consumiendo la API B2B) tiene que recalcular el bruto/comisión/neto por evento en vez de leer el valor autoritativo que FreeTicket ya calcula y muestra en su propio panel de "Liquidaciones".

[LucasLeguizamo]

Resuelto en su mayor parte: el contrato B2B 1.5.0 ya expone las liquidaciones, y el CLI las consume en #33.

ft settlements list --status PAID --json          # GET /settlements
ft reports financials --past --csv                # GET /reports/financials

• settlements list → id estándar, reference, label, estado (SENT/AWAITING_PAYMENT/PAID), monto, moneda, evento/función, hasDocument, paymentProofs[].fileName, allocations, requestedAt/paidAt.
• reports financials → una fila por función con el desglose completo: gross, platformFee, facial, paymentFee, gmf (4x1000), net, más settlementStatus/settlementId/settlementAmount. Son los mismos números de /dashboard/liquidaciones, así que ya no hace falta aproximarlos cruzando /sales con Mercado Pago.

Queda pendiente el PDF de comprobante. El contrato expone hasDocument y el fileName de cada comprobante, pero no una URL de descarga — la API lo dice explícitamente: los archivos se bajan del panel. Para archivarlo automáticamente haría falta GET /settlements/{id}/document (o una URL firmada de corta vida dentro del Settlement).

Dejo el issue abierto por esa parte; queda anotado en el ledger CONTRACT-GAPS.md.

[LucasLeguizamo]

Pedido aguas arriba: free-admin#381 — descarga del PDF de comprobante (GET /settlements/{id}/document o URL firmada) y de los paymentProofs. Cuando llegue al spec, contract-sync lo propaga a CLI y MCP y este issue se cierra.