API · payments

Cobros de los negocios; notificaciones autenticadas por HMAC de Mercado Pago.

GET /payments/accounts/mercadopago

Status

Lectura segura del estado, sin tokens. Scope payments:read para API keys. connection_mode es la conexión nueva que se ofrece; en países con política token es disabled mientras el interruptor de plataforma del token pegado esté apagado (F4-47). Una cuenta ya guardada se informa igual en account.

• Authentication: API key or dashboard session
• Scopes: payments:read

Responses

GET /payments/accounts/mercadopago/charges

Charges

Últimos cobros electrónicos del proyecto para Finanzas → Cobros (F4-25), el más nuevo primero. Incluye cobros de cuentas ya desconectadas. Sin datos del pagador, link de pago ni referencias del proveedor. Sesión owner/manager (payments:accounts_configure); API keys con scope payments:read.

• Authentication: API key or dashboard session
• Scopes: payments:read

Parameters

Responses

GET /payments/bookings/{booking_id}/balance

Booking Balance

Tenant desde credencial. Scope payments:read_balance; cookie + CSRF. Bearer exige Idempotency-Key en todos los POST (máximo 128 caracteres); conflicto del ledger Bearer es 422, conflicto de dominio 409. Owner/manager; staff solo tareas asignadas (no anula ni ajusta). Sin llamadas a proveedores. Montos enteros minor units, PYG exponente 0. Clave de registro permanente; misma clave con otros datos devuelve 409. Duplicados por tarea/monto/método en ventana UTC de 5 minutos se rechazan.

• Authentication: API key or dashboard session
• Scopes: None

Parameters

Responses

GET /payments/bookings/{booking_id}/charges

Booking Charges

Tenant desde credencial. Scope payments:read_balance. Historial de cobros de la tarea (recibos manuales asignados y cobros electrónicos), el más nuevo primero. applied_minor es la parte aplicada a esta tarea. La nota y el motivo de anulación son privados: owner/manager o quien registró el recibo. Staff solo tareas asignadas.

• Authentication: API key or dashboard session
• Scopes: None

Parameters

Responses

POST /payments/bookings/{booking_id}/due

Adjust Due

Tenant desde credencial. Scope payments:adjust; cookie + CSRF. Una tarea cubierta no permite ajustar el importe (409 payment_conflict, detail payment.booking_covered_by_plan); primero quitar el plan. Notas internas editables. Define (si la tarea aún no tiene valor) o ajusta el valor a cobrar, en unidad menor de la moneda del negocio (PYG y CLP enteros), con motivo obligatorio y auditoría payment.due_adjusted. Solo owner/manager. Sin valor definido, el servidor usa por defecto el total del formulario o, si no hay, el precio del catálogo del servicio al congelarlo (tareas por agendar, confirmadas, en curso y completadas). Bearer exige Idempotency-Key en todos los POST (máximo 128 caracteres). Sin llamadas a proveedores. Montos enteros minor units, PYG exponente 0. Clave de registro permanente; misma clave con otros datos devuelve 409. Duplicados por tarea/monto/método en ventana UTC de 5 minutos se rechazan.

• Authentication: API key or dashboard session
• Scopes: None

Parameters

Request body (required)

• application/json: AdjustDue

Responses

POST /payments/bookings/{booking_id}/lines/{line_id}/expense

Registrar como gasto el costo de una línea de la tarea

FIU-472: gasto de monto costo x cantidad, categoría Insumos, vinculado a la tarea (booking_id). El staff, solo en sus tareas y sus líneas: queda por aprobar. 409 expense.line_cost_required (la línea no tiene costo) o expense.line_has_expense (ya tiene otro gasto). Reintentar con la misma clave devuelve el mismo gasto.

FIU-472 (decisión 2): el costo de la línea se registra aparte, de un toque, como gasto de monto costo x cantidad, categoría «Insumos» (supplies), proveedor y comprobante opcionales (el comprobante, con POST /payments/expenses/{id}/receipt/...), vinculado a la tarea (booking_id). Con expenses:record queda aprobado; con expenses:record_own (staff: solo sus tareas y sus líneas) queda pending_approval. API key expenses:record. Reintentar con la misma clave devuelve el mismo gasto. 409 expense.line_cost_required, expense.line_has_expense.

• Authentication: API key or dashboard session
• Scopes: None

Parameters

Request body (required)

• application/json: LineExpenseIn

Responses

POST /payments/bookings/{booking_id}/payment-link

Cobrar con link de Mercado Pago el saldo de una tarea

F4-20 «Cobrar». Permiso y scope payments:link (owner/manager; staff solo en sus tareas y si el dueño no apagó «El repartidor puede cobrar»); cookie + CSRF o API key. Exige Idempotency-Key. El monto es el saldo de la tarea que calcula el core (nunca lo manda quien lo pide). Un link abierto por el mismo monto se devuelve con 200 y replay=true (nunca dos links por la misma tarea y monto); con otro monto abierto, 409 payment.link_pending. El cobro queda registrado y auditado (payment.created, payment.link_requested) antes de llamar a Mercado Pago; desde el panel el link vuelve listo (pending con checkout_url), con API key lo crea el worker enseguida (created sin URL: consultar GET /payments/bookings/{booking_id}/charges). deliver=conversation además lo manda por la conversación del cliente con una plantilla del servidor (delivery=queued; repetir la misma clave no manda dos mensajes, otra clave lo reenvía). Vence a las 48 h. 409 payment.link_unavailable (sin cuenta de producción BR/AR que coincida con el proyecto), payment.link_not_chargeable (tarea sin cliente, de prueba, en espera de seña o cerrada), payment.nothing_due, payment.parts_cover_balance (las partes abiertas ya cubren el saldo). F4-92 «Cobrar una parte»: con amount_minor el link es por esa parte (part=true), con su monto fijo. Pueden quedar varias partes abiertas a la vez; la suma de los cobros abiertos de la tarea nunca supera su saldo (422 payment_part_exceeds_balance, con remaining_minor, open_minor y currency). Las partes no se reemplazan entre sí ni las anula el link del bot o un QR/Point por el saldo; sin amount_minor, el link cobra lo que queda sin parte. Reintentar con la misma Idempotency-Key devuelve la misma parte (200, replay), aunque ya se haya pagado; otra clave es otra parte aunque el monto sea igual; la misma clave con otro monto da 409 payment.idempotency_conflict. Si baja el total, la parte que ya no entra se anula (void_reason=amount_changed).

• Authentication: API key or dashboard session
• Scopes: None

Parameters

Request body (required)

• application/json: PaymentLinkInput

Responses

GET /payments/bookings/balances

Booking Balances

Tenant desde credencial. Scope payments:read_balance; permiso de la matriz payments:read_balance (owner, manager, staff sobre tareas asignadas; viewer no). Saldo derivado de hasta 100 tareas en una pasada (chip de las listas). Omite las tareas que no se pueden calcular y las que el rol no ve. Sin bloqueos de filas.

• Authentication: API key or dashboard session
• Scopes: None

Parameters

Responses

GET /payments/cash

Leer caja o configuración

• Authentication: API key or dashboard session
• Scopes: cash:read

Parameters

Responses

POST /payments/cash/entries

Registrar rendición, cierre o ajuste inmutable

También exige cash:remit para rendir o cash:close para cerrar/ajustar. Staff solo lee su efectivo. No usa workspace_id externo.

• Authentication: API key or dashboard session
• Scopes: cash:read

Parameters

Request body (required)

• application/json: CashCommand

Responses

GET /payments/cash/settings

Leer caja o configuración

• Authentication: API key or dashboard session
• Scopes: cash:configure

Responses

PUT /payments/cash/settings

Configurar aviso opcional de efectivo

• Authentication: API key or dashboard session
• Scopes: cash:configure

Request body (required)

• application/json: CashAlertSettings

Responses

POST /payments/charges/{charge_id}/apply-to-account

Usar un pago «a devolver» para otra deuda

Tenant desde credencial. Scope payments:adjust; cookie + CSRF; solo owner/manager. Un pago tardío electrónico separado «a devolver» (refund_due) no compensa deudas del cliente; con confirm=true pasa al saldo del cliente y desde ahí cubre sus deudas más antiguas (FIFO). Auditoría payment.applied_to_account; idempotente (repetirlo devuelve el mismo resultado). No llama a Mercado Pago ni devuelve dinero. 409 payment.not_refund_due si el cobro no está «a devolver»; 409 payment.in_mediation con un reclamo abierto en MP.

• Authentication: API key or dashboard session
• Scopes: None

Parameters

Request body (required)

• application/json: ApplyToAccount

Responses

POST /payments/charges/{charge_id}/cancel

Anular un cobro abierto de una tarea (link, QR o Point)

F4-92. Permiso y scope payments:link (owner/manager; staff solo en sus tareas y si el dueño no apagó «El repartidor puede cobrar», si no 403); cookie + CSRF o API key (un QR o Point, solo sesión del panel). Anula un cobro abierto de la tarea, sea una parte o el cobro por el saldo (link, QR o Point; la tarjeta no), con void_reason=charge_cancelled; en Mercado Pago se cancela en el momento y, si falla, con reintentos. Un pago verificado que llegue igual queda en revisión. Los demás cobros no cambian. Repetir sobre un cobro anulado o vencido es un no-op. 409 payment.charge_not_found (no existe, es de otro proyecto o no es visible para quien pide), payment.charge_not_open (ya pagado u otro estado final).

• Authentication: API key or dashboard session
• Scopes: None

Parameters

Responses

GET /payments/charges/{charge_id}/fiscal

Marcador fiscal y comprobantes de un cobro

F4-85. Tenant desde credencial. Scope/permiso payments:fiscal (owner/manager). Fiuit nunca emite comprobantes; devuelve el marcador manual (not_required, pending o issued_external con número y fecha) y los comprobantes del emisor externo del negocio, si hay. Otro proyecto o un id inexistente dan 404 payment.not_found.

• Authentication: API key or dashboard session
• Scopes: None

Parameters

Responses

PUT /payments/charges/{charge_id}/fiscal

Marcar si un cobro lleva comprobante fiscal

F4-85. Tenant desde credencial. Scope/permiso payments:fiscal (owner/manager); cookie + CSRF. Idempotente (repetir lo mismo no cambia nada). Solo cobros que recibieron dinero (409 fiscal.charge_not_paid; uno anulado, 409 payment.voided); si el emisor conectado ya emitió la factura, 409 fiscal.document_issued. Fecha futura, 409 fiscal.future_date. Auditado (payment.fiscal_marked); el monto del cobro no cambia.

• Authentication: API key or dashboard session
• Scopes: None

Parameters

Request body (required)

• application/json: ChargeFiscalMark

Responses

GET /payments/charges/{charge_id}/refunds

Devoluciones de un cobro electrónico

Tenant desde credencial. Scope/permiso payments:refund (solo owner/manager). Lo devuelto (acreditado), lo pedido en curso (pending) y lo que todavía se puede devolver (refundable_minor). Si el cobro no admite devolución desde Fiuit, refundable_minor es 0 y refund_blocked trae el motivo (cobro manual, no pagado, contracargo, reclamo abierto, devolución parcial sin monto conocido, orden QR/Point, pago sin id de Mercado Pago o cobro pasado al saldo del cliente). Otro proyecto o un id inexistente dan el mismo 409 payment.charge_not_found.

• Authentication: API key or dashboard session
• Scopes: None

Parameters

Responses

POST /payments/charges/{charge_id}/refunds

Devolver (total o parcial) un cobro de Mercado Pago

Tenant desde credencial. Scope/permiso payments:refund (solo owner/manager); cookie + CSRF. Exige confirm=true e Idempotency-Key. Sin amount_minor devuelve todo lo que queda. El pedido queda registrado y auditado (payment.refund_requested) antes de llamar a Mercado Pago, con la misma clave de idempotencia en cada reintento; la respuesta trae status succeeded, failed (rechazo definitivo, con aviso a owner/manager) o pending (respuesta ambigua o en proceso; el worker reintenta). Repetir la misma clave devuelve la misma devolución; con otro monto o motivo, 409 payment.idempotency_conflict. Nunca más de lo cobrado (servicio y base de datos) → 409 payment.refund_exceeds_remaining o payment.already_refunded. 409 payment.not_refundable, payment.in_mediation, payment.refund_manual_unsupported (un cobro manual se anula), payment.refund_unsupported_method (orden QR/Point, se devuelve en Mercado Pago), payment.refund_unavailable (sin id del pago en MP), payment.refund_amount_unavailable, payment.refund_plan_unsupported (paquete o club), payment.refund_applied_to_account (pasado al saldo del cliente con «Usar para otra deuda»; limitación hasta F4-56). El cobro pasa a partially_refunded o refunded; lo devuelto se descuenta del saldo de la tarea, de Financiero, de las comisiones y de la seña en estadísticas.

• Authentication: API key or dashboard session
• Scopes: None

Parameters

Request body (required)

• application/json: RefundInput

Responses

POST /payments/commissions/adjustments

Ajustar la comisión de un día

Ajuste manual con signo y motivo, inmutable y auditado, sobre un día abierto. Un día de un período liquidado da 409 commission.period_settled (F4-77); el ajuste va en un día abierto. Owner/manager. No usa workspace_id externo.

• Authentication: API key or dashboard session
• Scopes: commissions:adjust

Parameters

Request body (required)

• application/json: CommissionAdjustmentInput

Responses

GET /payments/commissions/day

Día de comisiones por profesional

Cobrado por método, propinas, comisión, ajustes y diferencias de caja de cada profesional en un día local, calculado al vuelo (sin cierre diario). Staff ve solo lo suyo; owner/manager ven a todos y lo cobrado sin profesional. Los cobros de tareas completadas se atribuyen a quien tenía sus recursos al completar; mientras siga abierta, a quien los tiene hoy. Tareas no_show/cancelled/failed no generan comisión ni unattributed_minor; sus cobros permanecen como ingreso del negocio en Financiero/Caja. No usa workspace_id externo.

• Authentication: API key or dashboard session
• Scopes: commissions:read

Parameters

Responses

GET /payments/commissions/export

Exportar comisiones (CSV)

Una fila por profesional y día, importes en unidad menor y moneda. Auditado (commission.exported). Staff solo lo propio. No usa workspace_id externo.

• Authentication: API key or dashboard session
• Scopes: commissions:export

Parameters

Responses

GET /payments/commissions/report

Reporte de comisiones por período y profesional

Totales por profesional entre start y end (días locales, inclusive, hasta 366), calculados al vuelo; cada tarea cuenta una vez. Staff solo lo propio (member_id de otra persona da 403). En F4-77 los días de un período liquidado salen del asiento congelado (settlements); la comisión de una anulación o devolución se revierte en el día del cobro original y el período de la devolución lo avisa en reversals; carried_minor (dentro de adjustments_minor) corrige un período ya liquidado. No usa workspace_id externo.

• Authentication: API key or dashboard session
• Scopes: commissions:read

Parameters

Responses

GET /payments/commissions/rules

Listar reglas de comisión

Staff ve las reglas generales y las suyas. No usa workspace_id externo.

• Authentication: API key or dashboard session
• Scopes: commissions:read

Responses

POST /payments/commissions/rules

Crear regla de comisión

Porcentaje (rate_bp, 4000 = 40 %) o monto fijo (amount_minor, por tarea o por unidad de producto), por profesional y por servicio o producto, con o sin descontar la comisión del medio de pago, vigente desde valid_from. Dos reglas del mismo alcance que se superponen dan 409 commission.rule_overlap. Owner/manager. No usa workspace_id externo.

• Authentication: API key or dashboard session
• Scopes: commissions:configure

Request body (required)

• application/json: CommissionRuleInput

Responses

POST /payments/commissions/rules/{rule_id}/end

Terminar una regla de comisión

Fija el último día de vigencia (inclusive). Una regla no se edita: se termina y se crea otra. Owner/manager. No usa workspace_id externo.

• Authentication: API key or dashboard session
• Scopes: commissions:configure

Parameters

Request body (required)

• application/json: CommissionRuleEnd

Responses

GET /payments/commissions/settlements

Liquidaciones de comisiones de un período

F4-77. Liquidaciones que tocan start..end (días locales, inclusive, hasta 366), con los montos congelados, los ajustes automáticos que ya congelaron de otros períodos (carried_from) y lo que cada una tiene pendiente de pasar como ajuste automático al período abierto siguiente (pending_carry_minor, carry_day). Staff solo lo propio (member_id de otra persona da 403). No usa workspace_id externo.

• Authentication: API key or dashboard session
• Scopes: commissions:read

Parameters

Responses

POST /payments/commissions/settlements

Liquidar comisiones de una persona y un período

F4-77. Congela la comisión y los ajustes de start..end (días locales, hasta hoy) de una persona en un asiento inmutable, con motivo, autor y fecha; auditoría commission.settled y evento interno commission.settled. Idempotente por Idempotency-Key y por período; liquidar otra vez el mismo período (otra clave, otro worker) devuelve el mismo asiento; otro período que se superpone da 409 commission.period_settled; un día futuro da 409 commission.future_day. Desde entonces esos días leen el asiento. Un cambio posterior (anulación, devolución o regla retroactiva) no lo reescribe; queda como ajuste automático (carried_minor) en el primer día abierto después del período, con referencia a esta liquidación. expected es opcional y lleva moneda y componentes mostrados al confirmar; si difieren del asiento que se congelaría, responde 409 commission.amounts_changed sin escribir. Un reintento de la misma clave devuelve su asiento original. Owner/manager. No usa workspace_id externo.

• Authentication: API key or dashboard session
• Scopes: commissions:settle

Parameters

Request body (required)

• application/json: CommissionSettlementInput

Responses

GET /payments/customers/{customer_id}/account/receipts

Customer Account Receipts

Tenant desde credencial. Permiso/scope customer_account:read (owner/manager; F4-35). Historial de cobros del cliente, también los pagos a cuenta y los anulados, el más nuevo primero y paginado. unapplied_minor es lo que no está asignado a una tarea. La nota y el motivo de anulación son privados.

• Authentication: API key or dashboard session
• Scopes: None

Parameters

Responses

GET /payments/customers/{customer_id}/account/tasks

Customer Account Tasks

Tenant desde credencial. Permiso/scope customer_account:read (owner/manager; F4-35). Desglose por tarea vigente de la cuenta del cliente: a cobrar, cobrado y saldo de cada una, las más recientes primero. Paginado (limit hasta 100, offset); open_only deja solo las tareas con saldo. Staff no accede.

• Authentication: API key or dashboard session
• Scopes: None

Parameters

Responses

GET /payments/customers/{customer_id}/balance

Customer Balance

• Authentication: API key or dashboard session
• Scopes: None

Parameters

Responses

GET /payments/expense-categories

Listar categorías de gasto

F4-73. Las 11 categorías fijas del proyecto (se crean en el primer uso) con key estable, kind (variable, fixed, staff, tax, fee, other), su nombre fijo en el idioma del proyecto (FIU-324: no se renombran) y si están ocultas. Owner/manager o scope expenses:read.

• Authentication: API key or dashboard session
• Scopes: expenses:read

Responses

PATCH /payments/expense-categories/{category_id}

Ocultar o mostrar una categoría de gasto

F4-73. hidden la oculta de la carga del panel (o la vuelve a mostrar); los gastos ya cargados no cambian. FIU-324 (decisión del dueño, 2026-10-22): las categorías son fijas, no se renombran (un name en el cuerpo da 422); de ellas salen el DRE, el flujo y el informe MEI y para organizarse están las etiquetas (/payments/expense-tags). No se crean ni se borran categorías. Auditado. Owner/manager o scope expenses:record.

• Authentication: API key or dashboard session
• Scopes: expenses:record

Parameters

Request body (required)

• application/json: ExpenseCategoryPatch

Responses

GET /payments/expense-tags

Listar etiquetas de gastos

FIU-324. Las etiquetas libres del proyecto, las más usadas primero (después por nombre), con la categoría que recuerda cada una (la última con la que se usó: al cargar un gasto con esa etiqueta y sin category_id, se usa esa) y cuántos gastos vigentes la tienen (el staff cuenta solo los suyos). Las etiquetas se crean al usarlas en un gasto (tags). Owner/manager, staff (expenses:record_own) o scope expenses:read.

• Authentication: API key or dashboard session
• Scopes: expenses:read

Responses

PATCH /payments/expense-tags/{tag_id}

Renombrar una etiqueta de gastos

FIU-324. Nuevo nombre (1 a 40 caracteres, espacios de más se recortan). Si otra etiqueta ya tiene ese nombre sin distinguir mayúsculas, 409 expense_tag.name_taken (se unen con merge). Auditado (expense_tag.renamed). Owner/manager o scope expenses:record.

• Authentication: API key or dashboard session
• Scopes: expenses:record

Parameters

Request body (required)

• application/json: ExpenseTagPatch

Responses

DELETE /payments/expense-tags/{tag_id}

Borrar una etiqueta de gastos

FIU-324. La etiqueta sale de todos sus gastos y se borra; los gastos no se tocan. Auditado (expense_tag.deleted). Owner/manager o scope expenses:record.

• Authentication: API key or dashboard session
• Scopes: expenses:record

Parameters

Responses

POST /payments/expense-tags/{tag_id}/merge

Unir una etiqueta en otra

FIU-324. «Uní moto con motos»: los gastos de tag_id pasan a into_id (un gasto que ya tenía las dos queda con una) y tag_id se borra. La que queda conserva su categoría recordada (si no tenía, toma la de la otra). La misma etiqueta, 409 expense_tag.merge_same; una que no existe, 404. Auditado (expense_tag.merged). Owner/manager o scope expenses:record.

• Authentication: API key or dashboard session
• Scopes: expenses:record

Parameters

Request body (required)

• application/json: ExpenseTagMerge

Responses

GET /payments/expenses

Listar gastos

F4-73. Gastos del proyecto, del más reciente al más viejo (occurred_on = día local del proyecto). total_minor suma solo los aprobados del filtro, sin anulados, pendientes, rechazados ni de prueba (independiente de la página); include_voided e include_test solo los muestran y status (F4-74) deja solo ese estado. Staff (expenses:record_own, F4-74) ve solo los gastos que cargó. Un gasto sin resource_id es «General» (sin prorrateo). Importes en unidad menor de la moneda del proyecto (PYG y CLP sin decimales). Owner/manager o scope expenses:read. No usa workspace_id externo.

• Authentication: API key or dashboard session
• Scopes: expenses:read

Parameters

Responses

POST /payments/expenses

Cargar un gasto

F4-73. Gasto en unidad menor de la moneda del proyecto (currency obligatoria e igual a la del proyecto; PYG y CLP sin decimales; mismo tope por moneda que los cobros manuales). occurred_on por defecto es hoy en la zona del proyecto; no acepta fechas futuras. La categoría «Comisiones del equipo» es una línea calculada y no se carga a mano (409 expense.computed_category). Idempotency-Key obligatoria: la misma clave con el mismo cuerpo devuelve el mismo gasto; con otro cuerpo, 409 payment.idempotency_conflict. is_test se guarda pero no suma. Queda en la auditoría y emite expense.recorded. Owner/manager o scope expenses:record: queda approved. Staff (expenses:record_own, F4-74): queda pending_approval y no suma hasta que owner/manager lo aprueben. No usa workspace_id externo.

• Authentication: API key or dashboard session
• Scopes: expenses:record

Parameters

Request body (required)

• application/json: ExpenseInput

Responses

GET /payments/expenses/{expense_id}

Ver un gasto

F4-79. Un gasto con su estado, comprobante (si tiene), revisión y anulación; es el detalle de un movimiento expense de Movimientos. Owner/manager o scope expenses:read; staff (expenses:record_own) solo los que cargó (uno ajeno da 404, igual que uno inexistente).

• Authentication: API key or dashboard session
• Scopes: expenses:read

Parameters

Responses

PATCH /payments/expenses/{expense_id}

Corregir un gasto

F4-73. Solo cambian los campos presentes (null borra nota, método, beneficiario, recurso, servicio o persona). Cada cambio queda en la auditoría con el valor anterior y el nuevo (expense.updated). Un gasto anulado no se edita (409 expense.voided) ni uno rechazado (409 expense.rejected); sin cierre de período. Cada cambio queda también en el historial (GET .../edits, F4-74). Moneda, origen y is_test no cambian. Owner/manager o scope expenses:record; staff (expenses:record_own) solo los suyos mientras siguen pendientes (409 expense.not_pending; uno ajeno da 404).

• Authentication: API key or dashboard session
• Scopes: expenses:record

Parameters

Request body (required)

• application/json: ExpensePatch

Responses

POST /payments/expenses/{expense_id}/approve

Aprobar un gasto pendiente

F4-74. Un gasto del staff en pending_approval pasa a approved (desde ahora suma) con revisor y fecha; emite expense.approved y queda en el historial y la auditoría. Repetir devuelve el mismo resultado. Un gasto que no está pendiente da 409 expense.not_pending; nadie aprueba lo que cargó (409 expense.self_review, también lo exige la base). Owner/manager o scope expenses:approve.

• Authentication: API key or dashboard session
• Scopes: expenses:approve

Parameters

Responses

GET /payments/expenses/{expense_id}/edits

Historial de un gasto

F4-74. Cada corrección, aprobación, rechazo o anulación del gasto, de la más vieja a la más nueva: quién (actor_type user o api_key, actor_id), cuándo y los campos que cambiaron con su valor anterior y el nuevo (ids y fechas como texto). Solo se agrega: no se edita ni se borra. Sin cierre de período. Owner/manager o scope expenses:read; staff (expenses:record_own) solo el de los gastos que cargó (uno ajeno da 404).

• Authentication: API key or dashboard session
• Scopes: expenses:read

Parameters

Responses

POST /payments/expenses/{expense_id}/reject

Rechazar un gasto pendiente

F4-74. Un gasto del staff en pending_approval pasa a rejected con motivo obligatorio (review_reason), revisor y fecha; emite expense.rejected y queda en el historial y la auditoría. Rechazado es final: no suma, no se corrige ni se anula (409 expense.rejected); se carga uno nuevo. Repetir con el mismo motivo devuelve el mismo resultado; con otro, 409 expense.review_conflict. Nadie rechaza lo que cargó (409 expense.self_review). Owner/manager o scope expenses:approve.

• Authentication: API key or dashboard session
• Scopes: expenses:approve

Parameters

Request body (required)

• application/json: ExpenseReject

Responses

POST /payments/expenses/{expense_id}/void

Anular un gasto

F4-73. Un gasto nunca se borra: anular deja motivo, autor y fecha y emite expense.voided. Repetir con el mismo motivo devuelve el mismo resultado; con otro motivo, 409 payment.void_conflict. Un gasto rechazado no se anula (409 expense.rejected). Owner/manager o scope expenses:void.

• Authentication: API key or dashboard session
• Scopes: expenses:void

Parameters

Request body (required)

• application/json: ExpenseVoid

Responses

GET /payments/expenses/high-amount

Umbral de monto alto de la carga conversada (segunda confirmación)

F4-83. Desde cuánto un gasto cargado conversando (Wagy, MCP, bot de equipo) pide una segunda confirmación: el doble del precio mensual del plan del proyecto en su moneda (decisión del dueño, no un número fijo). Sin precio publicado para la moneda, threshold_minor es nulo y todo monto cuenta como alto. Con amount_minor responde además si ese monto alcanza el umbral (inclusive). No escribe nada. Owner/manager, staff (que carga los suyos) o scope expenses:record. El número (threshold_minor) solo lo recibe el owner o una API key que emitió el owner (rol vigente): ver el plan es solo suyo. Manager, staff y las demás keys reciben threshold_minor: null y usan high. No usa workspace_id externo.

• Authentication: API key or dashboard session
• Scopes: expenses:record

Parameters

Responses

GET /payments/expenses/pending

Contar los gastos por aprobar

F4-74. Contador de quien aprueba: cantidad y suma de los gastos del staff en pending_approval, sin los de prueba, en unidad menor de la moneda del proyecto. Owner/manager o scope expenses:approve. No usa workspace_id externo.

• Authentication: API key or dashboard session
• Scopes: expenses:approve

Responses

GET /payments/finance/accounts

Cuentas que componen el saldo actual o el crédito del Resumen

Proyección canónica F4-35, sin filtro de período. Owner/manager o scope finance:analyze; nunca staff.

• Authentication: API key or dashboard session
• Scopes: finance:analyze

Parameters

Responses

GET /payments/finance/availability

Finance Availability

Tenant desde credencial; unidades menores de la moneda del negocio. Staff solo recibos y caja propios. Ver docs/api/financiero.md.

• Authentication: API key or dashboard session
• Scopes: payments:read

Responses

GET /payments/finance/collections

Finance Collections

F4-26. Números de cobros del período por fecha local de cobro, en la moneda y zona del proyecto: bruto, devuelto, comisión del proveedor (Mercado Pago, fee_details), comisión de Fiuit y neto; por método, servicio y día/semana; y lo estimado (completado sin ningún cobro). Solo lectura. Owner/manager o scope finance:analyze; staff/viewer cerrados. Sin anulados ni de prueba.

• Authentication: API key or dashboard session
• Scopes: finance:analyze

Parameters

Responses

GET /payments/finance/collections/export

Finance Collections Export

F4-26. CSV de conciliación de cobros por fecha local de cobro: bruto, devuelto, comisión del proveedor (y si fue informada), comisión de Fiuit, neto e id del pago en el proveedor. Owner/manager o API key con finance:analyze y finance:export; staff/viewer cerrados. Sin anulados ni de prueba.

• Authentication: API key or dashboard session
• Scopes: finance:analyze, finance:export

Parameters

Responses

GET /payments/finance/customers

Finance Customers

Lectura de valores congelados y cuenta F4-35. Owner/manager o scope finance:analyze; staff/viewer cerrados. Importes en unidad menor, sin PII adicional. Datos actuales, estimaciones rotuladas.

• Authentication: API key or dashboard session
• Scopes: finance:analyze

Parameters

Responses

GET /payments/finance/customers/{customer_id}

Finance Customer

Lectura de valores congelados y cuenta F4-35. Owner/manager o scope finance:analyze; staff/viewer cerrados. Importes en unidad menor, sin PII adicional. Datos actuales, estimaciones rotuladas.

• Authentication: API key or dashboard session
• Scopes: finance:analyze

Parameters

Responses

GET /payments/finance/debt

Finance Debt

Lectura de valores congelados y cuenta F4-35. Owner/manager o scope finance:analyze; staff/viewer cerrados. Importes en unidad menor, sin PII adicional. Datos actuales, estimaciones rotuladas.

• Authentication: API key or dashboard session
• Scopes: finance:analyze

Parameters

Responses

GET /payments/finance/export

Finance Export

Tenant desde credencial; unidades menores de la moneda del negocio. Staff solo recibos y caja propios. Ver docs/api/financiero.md.

• Authentication: API key or dashboard session
• Scopes: finance:export, payments:read

Parameters

Responses

GET /payments/finance/forecast

Finance Forecast

Lectura de valores congelados y cuenta F4-35. Owner/manager o scope finance:analyze; staff/viewer cerrados. Importes en unidad menor, sin PII adicional. Datos actuales, estimaciones rotuladas.

• Authentication: API key or dashboard session
• Scopes: finance:analyze

Responses

GET /payments/finance/movements

Finance Movements

Tenant desde credencial; unidades menores de la moneda del negocio. Staff solo recibos y caja propios. Ver docs/api/financiero.md.

• Authentication: API key or dashboard session
• Scopes: payments:read

Parameters

Responses

GET /payments/finance/overview

Resumen mensual de Dinero

F4-80. Para el gráfico del Inicio: Entró / Salió / Quedó realizados de los 2 períodos anteriores y del actual (hasta hoy) y, en el actual y el siguiente, lo que falta, siempre una suma de cosas con fecha: tareas agendadas (lo ya recibido de pago o seña antes del período es «seguro»; el saldo, «previsto»), gastos recurrentes que vencen («seguros»), comisión del equipo estimada sobre esas tareas y gastos por aprobar («previstos»). period: month, week (lunes a domingo) o day (solo hoy). La comisión de cobro no se estima y los saldos por cobrar no tienen vencimiento: ambos se avisan en notes. Solo lectura. Owner/manager o scope finance:analyze; staff/viewer cerrados.

• Authentication: API key or dashboard session
• Scopes: finance:analyze

Parameters

Responses

GET /payments/finance/report-evidence

Finance Report Evidence

Lectura de valores congelados y cuenta F4-35. Owner/manager o scope finance:analyze; staff/viewer cerrados. Importes en unidad menor, sin PII adicional. Datos actuales, estimaciones rotuladas.

• Authentication: API key or dashboard session
• Scopes: finance:analyze

Parameters

Responses

GET /payments/finance/reports

Finance Reports

Lectura de valores congelados y cuenta F4-35. Owner/manager o scope finance:analyze; staff/viewer cerrados. Importes en unidad menor, sin PII adicional. Datos actuales, estimaciones rotuladas.

• Authentication: API key or dashboard session
• Scopes: finance:analyze

Parameters

Responses

GET /payments/finance/result

Resultado del período

F4-76. Resultado con base caja en la moneda y zona del proyecto: Entró (cobrado menos devuelto, misma población que finance/collections: sin anulados, de prueba, en revisión ni cobros con devolución parcial de monto desconocido), Salió (gastos aprobados + línea calculada de comisiones del equipo + línea calculada de comisiones de cobro informadas) y Quedó, con margen, vendido como dato secundario y comparación contra el período anterior. group_by period (día o semana), resource, service o category; filtros service_id y resource_id. Gastos sin recurso o servicio = «General» (key null), sin prorrateo; los ajustes manuales de comisión van al recurso de la persona ese día (por servicio, a «General»). Advertencias: missing_expenses, refund_amount_unavailable, provider_fee_unknown, resource_overlap. Solo lectura. Owner/manager o scope finance:analyze; staff/viewer cerrados. 409 finance.invalid_period.

• Authentication: API key or dashboard session
• Scopes: finance:analyze

Parameters

Responses

GET /payments/finance/result/export

Exportar el Resultado (XLSX para el contador o CSV)

F4-81. Los números del Resultado (GET /payments/finance/result) como archivo, sin recalcular. CSV: un movimiento por renglón (cobro, devolución, comisión de cobro, comisión del equipo, gasto) con kind, category, resource, service, member, customer, amount en decimales legibles y amount_minor; la suma de amount_minor es el result_minor del período. UTF-8 con BOM; separador ; y coma decimal si la moneda usa coma (BRL, ARS, CLP, COP, PYG, UYU, EUR), , y punto si no (MXN, PEN, USD). PYG y CLP sin decimales. Fechas: día local del proyecto. XLSX: hojas Resumen, Movimientos, Por categoría, Por recurso, Por servicio, Comisiones y Cobros electrónicos (bruto, comisión, neto e id del pago en Mercado Pago). Textos con = + - @ al inicio llevan apóstrofo. Owner/manager o API key con finance:analyze y finance:export; staff/viewer cerrados. receipt_url va vacío: el comprobante de cada gasto viaja en el paquete ZIP (POST /payments/finance/result/packages), donde la columna dice su archivo. PDF (F4-82): una hoja A4 con Entró, Salió y Quedó, el detalle, las 5 categorías que más salieron, los avisos y un espacio para firma; importes con el formato de la moneda (PYG con su código).

• Authentication: API key or dashboard session
• Scopes: finance:analyze, finance:export

Parameters

Responses

GET /payments/finance/result/lines

Composición de un número del Resultado

F4-80. Los renglones que suman un número del Resultado (los mismos que exporta finance/result/export): cobros (income), devoluciones (refund), comisiones de cobro (payment_fee), comisiones del equipo calculadas (staff_commission) y gastos aprobados (expense), con signo y por día local. Mismos filtros que finance/result; row abre una fila de group_by (general = «General»), side el lado Entró (in) o Salió (out) y kind un renglón del DRE. total_minor suma todos los que cumplen el filtro (data trae hasta limit, más reciente primero): Entró, -Salió, Quedó o el resultado de la fila. Solo lectura. Owner/manager o scope finance:analyze; customer_name con API key solo con customer_account:read. 409 finance.invalid_period.

• Authentication: API key or dashboard session
• Scopes: finance:analyze

Parameters

Responses

GET /payments/finance/result/packages

Mis paquetes para el contador

F4-82. Cada persona (o key) ve solo sus paquetes. Owner/manager o API key con finance:analyze y finance:export.

• Authentication: API key or dashboard session
• Scopes: finance:analyze, finance:export

Responses

POST /payments/finance/result/packages

Pedir el paquete ZIP para el contador del período

F4-82. Un ZIP con el XLSX de GET /payments/finance/result/export (las 7 hojas, con la columna «Comprobante» apuntando al archivo dentro del ZIP), el PDF de resumen de una hoja (format=pdf) y los comprobantes de los gastos aprobados del período, con nombre AAAA-MM-DD_<monto>_<categoria>.<ext> en la carpeta comprovantes/, comprobantes/ o receipts/ según lang. Mismos números que el Resultado, sin recalcular. Los comprobantes solo van si lo pide una sesión (owner/manager): con API key el paquete lleva XLSX y PDF (receipts_included: false). Si es chico (hasta 2000 renglones y 20 comprobantes que suman 5 MB) responde 201 listo; si no, 202 pending y lo arma el worker. Topes: 50000 renglones (409 finance.export_too_large), 1000 comprobantes y 100 MB de comprobantes (409 finance.package_too_large); un paquete abierto por persona (409 finance.package_in_progress). El archivo vence a las 48 h. Auditado (finance.exported con report: package).

• Authentication: API key or dashboard session
• Scopes: finance:analyze, finance:export

Request body (required)

• application/json: FinancePackageInput

Responses

GET /payments/finance/result/packages/{package_id}

Estado de un paquete

F4-82. El paquete de otra persona o de otro proyecto responde 404 finance.package_not_found.

• Authentication: API key or dashboard session
• Scopes: finance:analyze, finance:export

Parameters

Responses

GET /payments/finance/result/packages/{package_id}/download

Bajar el ZIP con el link firmado

F4-82. Usá el download_url de GET /payments/finance/result/packages/{package_id} tal cual, con la misma sesión o API key que lo pidió. Link vencido o adulterado → 403 finance.package_link_invalid; paquete vencido → 404 finance.package_expired; todavía armándose → 404 finance.package_not_ready.

• Authentication: API key or dashboard session
• Scopes: finance:analyze, finance:export

Parameters

Responses

GET /payments/finance/summary

Finance Summary

Tenant desde credencial; unidades menores de la moneda del negocio. Staff solo recibos y caja propios. Ver docs/api/financiero.md.

• Authentication: API key or dashboard session
• Scopes: finance:analyze

Parameters

Responses

GET /payments/finance/tasks

Finance Tasks

Tenant desde credencial; unidades menores de la moneda del negocio. Staff solo recibos y caja propios. Ver docs/api/financiero.md.

• Authentication: API key or dashboard session
• Scopes: finance:analyze

Parameters

Responses

POST /payments/manual

Record Manual

Cobro unificado (F3-492), el único comando para registrar un pago recibido fuera de la pasarela, de una tarea o seña (allocations) o a cuenta del cliente (sin allocations); la venta y renovación de un plan lo usan por dentro. method es obligatorio (cash, card, transfer, pix, mercadopago = recibido por Mercado Pago fuera de Fiuit, other). audit_log payment.recorded guarda quién, monto, forma de pago, propósito y origen (task, account o plan). Tenant desde credencial. Scope payments:record; cookie + CSRF. Bearer exige Idempotency-Key en todos los POST (máximo 128 caracteres); conflicto del ledger Bearer es 422, conflicto de dominio 409. Owner/manager; staff solo tareas asignadas (no anula ni ajusta) y solo si el dueño no apagó «El repartidor puede cobrar» (staff_can_collect, encendido por defecto; apagado por el dueño, 403). Sin llamadas a proveedores. Montos enteros minor units, PYG exponente 0. Clave de registro permanente; misma clave con otros datos devuelve 409. Duplicados por tarea/monto/método en ventana UTC de 5 minutos se rechazan. Los cobros paid aplicados a una tarea se suman con los de pasarela; al cubrir la seña requerida, pending_payment pasa a confirmed de forma auditada e idempotente. El crédito a cuenta sin asignar no confirma. Una tarea cubierta rechaza ajustes de cobro y asignaciones manuales (409 payment_conflict, detail payment.booking_covered_by_plan); primero quitar el plan. Una tarea que queda pagada por completo con este cobro (efectivo o transferencia) también hace avanzar la etapa con la salida «Avanza sola al recibir el pago» (#1064), igual que un cobro de Mercado Pago; un pago parcial no la mueve. FIU-473 impide imputar un adicional de presupuesto sin aprobar (409 payment_conflict, detail payment.quote_pending), incluso con allow_overpayment. Se puede registrar dinero recibido sin imputarlo a esa diferencia; lo ya imputado se conserva.

• Authentication: API key or dashboard session
• Scopes: None

Parameters

Request body (required)

• application/json: RecordManual

Responses

POST /payments/manual/{charge_id}/allocations

Allocate Manual

Tenant desde credencial. Scope payments:record; cookie + CSRF. Bearer exige Idempotency-Key en todos los POST (máximo 128 caracteres); conflicto del ledger Bearer es 422, conflicto de dominio 409. Owner/manager; staff solo tareas asignadas (no anula ni ajusta) y solo si el dueño no apagó «El repartidor puede cobrar» (staff_can_collect, encendido por defecto; apagado por el dueño, 403). Sin llamadas a proveedores. Montos enteros minor units, PYG exponente 0. Clave de registro permanente; misma clave con otros datos devuelve 409. Duplicados por tarea/monto/método en ventana UTC de 5 minutos se rechazan. Asignar un recibo paid concilia la seña; el total manual aplicado más pasarela debe alcanzar la seña para confirmar; replay no duplica confirmación ni avisos. Una tarea cubierta rechaza ajustes de cobro y asignaciones manuales (409 payment_conflict, detail payment.booking_covered_by_plan); primero quitar el plan. En FIU-473, la imputación respeta el último presupuesto aceptado; un adicional pendiente o rechazado devuelve 409 payment_conflict con detail payment.quote_pending, incluso con allow_overpayment.

• Authentication: API key or dashboard session
• Scopes: None

Parameters

Request body (required)

• application/json: AllocationInput

Responses

POST /payments/manual/{charge_id}/void

Void Manual

Tenant desde credencial. Scope payments:void; cookie + CSRF. Bearer exige Idempotency-Key en todos los POST (máximo 128 caracteres); conflicto del ledger Bearer es 422, conflicto de dominio 409. Owner/manager; staff solo tareas asignadas (no anula ni ajusta). Sin llamadas a proveedores. Montos enteros minor units, PYG exponente 0. Clave de registro permanente; misma clave con otros datos devuelve 409. Duplicados por tarea/monto/método en ventana UTC de 5 minutos se rechazan. Si el total válido queda debajo de la seña, una tarea confirmed con payment_status paid vuelve a pending_payment únicamente antes de iniciar y antes de start_at (si existe). Conserva horario y capacidad, sin nuevo vencimiento; no reabre estados iniciados o terminales. Reembolso parcial sin monto conciliado impide deducir el faltante.

• Authentication: API key or dashboard session
• Scopes: None

Parameters

Request body (required)

• application/json: ReasonInput

Responses

GET /payments/payment-links/availability

¿Se puede cobrar con link?

F4-20. Permiso y scope payments:link. Solo available y el motivo (reason, los de MercadoPagoMethodView); sin datos de la cuenta. El panel muestra «Cobrar» solo si está disponible.

• Authentication: API key or dashboard session
• Scopes: None

Responses

GET /payments/recurring-expenses

Gastos que se repiten

F4-75. Los gastos recurrentes del proyecto (alquiler, sueldos fijos, servicios) con su próxima fecha (next_on, día local) y status (active, paused, ended). Owner/manager o scope expenses:read.

• Authentication: API key or dashboard session
• Scopes: expenses:read

Responses

POST /payments/recurring-expenses

Crear un gasto que se repite cada semana o cada mes

F4-75. cadence weekly (day 1 lunes … 7 domingo) o monthly (day 1-31; en meses más cortos, el último día). Importe en unidad menor de la moneda del proyecto (currency obligatoria e igual; mismo tope que los gastos). starts_on por defecto hoy, como mucho un año para atrás (409 expense_recurring.starts_too_early); ends_on opcional. Cada fecha que toca carga un gasto aprobado con source: recurring y recurring_id, el mismo día (lo que ya tocaba desde starts_on se carga al crear); nunca dos veces la misma fecha, aunque haya reintentos o dos procesos a la vez. Sin nómina: un sueldo fijo es un recurrente de «Sueldos». «Comisiones del equipo» no se carga (409 expense.computed_category). Idempotency-Key obligatoria: misma clave y cuerpo devuelve el mismo recurrente; otro cuerpo, 409 payment.idempotency_conflict. Auditado. Owner/manager o scope expenses:record.

• Authentication: API key or dashboard session
• Scopes: expenses:record

Parameters

Request body (required)

• application/json: RecurringInput

Responses

PATCH /payments/recurring-expenses/{recurring_id}

Cambiar, pausar, reanudar o terminar un gasto que se repite

F4-75. Cambia lo que viene de acá en adelante: los gastos ya cargados no se tocan (se corrigen o anulan como cualquier gasto). paused: true no genera; al reanudar sigue desde hoy (lo pausado no se recupera). Cambiar cadence o day recalcula desde hoy; ends_on termina (status: ended) y quitarlo lo retoma. Auditado con antes y después. Owner/manager o scope expenses:record.

• Authentication: API key or dashboard session
• Scopes: expenses:record

Parameters

Request body (required)

• application/json: RecurringPatch

Responses

POST /payments/recurring-expenses/{recurring_id}/skip

Saltear la próxima fecha de un gasto que se repite

F4-75. on tiene que ser la próxima fecha (next_on): pasa a la siguiente sin cargar el gasto. Repetirlo no saltea otra; una fecha posterior da 409 expense_recurring.not_next, una ya cargada 409 expense_recurring.already_recorded (se anula el gasto) y un recurrente terminado 409 expense_recurring.ended. Auditado. Owner/manager o scope expenses:record.

• Authentication: API key or dashboard session
• Scopes: expenses:record

Parameters

Request body (required)

• application/json: RecurringSkip

Responses

GET /payments/task-margins

Margen por tarea (líneas con costo)

FIU-472: finance:analyze y, desde FIU-597, tasks:costs (por defecto solo el dueño; una API key, con payments:read_balance). Precio - costo de las líneas con costo cargado, por tarea; una tarea sin ningún costo no aparece (no se muestra 100 % de margen).

FIU-472: margen por tarea en Dinero, finance:analyze y tasks:costs (FIU-597: por defecto solo el dueño; el resto, 403). Precio menos costo de las líneas con costo cargado; una tarea sin ningún costo no aparece (nunca un 100 %). margin_bp: puntos básicos (2500 = 25,00 %).

• Authentication: API key or dashboard session
• Scopes: None

Responses

POST /payments/tips

Registrar una propina

Propina para un profesional: no es venta del negocio ni base de comisión. Staff solo para sí (si el negocio permite que cobre); una API key debe indicar member_id. No usa workspace_id externo.

• Authentication: API key or dashboard session
• Scopes: payments:record

Parameters

Request body (required)

• application/json: TipInput

Responses

POST /payments/tips/{tip_id}/void

Anular una propina

Con motivo; resta el día en que se anula. Owner/manager. No usa workspace_id externo.

• Authentication: API key or dashboard session
• Scopes: payments:void

Parameters

Request body (required)

• application/json: ReasonInput

Responses