La API pública ahora cuenta la reserva junto con su cadena de proveedores

El sobre se mantiene: status, errors y data. La autenticación sigue siendo el Bearer de la clave pública. Hay que revisar el alcance de la clave, los campos nuevos en reservas y los endpoints nuevos.

Qué no tiene que rehacerse

Siguen igual el listado y el detalle de clientes, cotizaciones, pagos de clientes, reembolsos, viajes, planes, proveedores, usuarios, sedes, monedas y métodos de pago. También siguen igual las notas de seguimiento de una reserva.

GET /api/public/v1/reservations/{id}/followup_notes

Los filtros que ya usaba el listado de reservas no cambiaron: fechas de viaje, fechas de asignación, plan_id, trip_id, reservation_status y payment_status. La paginación sigue siendo skip y take. take es opcional, vale 100 si no se envía y no pasa de 1000.

Las reservas de un cliente siguen siendo solo aquellas en las que ese cliente es el titular. Estas dos rutas siguen devolviendo un arreglo plano dentro de data. No pasaron al formato { items, total } del listado general.

GET /api/public/v1/clients/{id}/reservations

GET /api/public/v1/clients/by_identification/{identification}/reservations

Alcances nuevos

Una clave con reservations puede leer las facturas de proveedores de una reserva. Para pagos a proveedores y cuentas bancarias hacen falta estos alcances. Sin el alcance, la respuesta es 403. La clave debe emitirse con los alcances que el agente vaya a usar.

Alcance	Endpoint que lo exige
`provider_invoices`	`GET /api/public/v1/provider_invoices/{id}/payments`
`provider_invoice_payments`	`GET /api/public/v1/provider_invoice_payments`
`bank_accounts`	`GET /api/public/v1/bank_accounts`

Campos nuevos en los listados de reservas

Estos cuatro GET siguen con el alcance reservations y agregan campos. Todos pueden llegar nulos. El resto de los campos anteriores se conserva.

GET /api/public/v1/reservations

GET /api/public/v1/reservations/{id}

GET /api/public/v1/clients/{id}/reservations

GET /api/public/v1/clients/by_identification/{identification}/reservations

Campos	Qué representan
`agent_id`, `agent_name`	Agente de la reserva.
`intermediary_id`, `intermediary_name`	Intermediario de la reserva.
`marketing_source_id`, `marketing_source_name`	Origen comercial.
`private_notes`	Notas privadas de la reserva.
`operator_id`, `operator_name`	Operador del viaje.
`invoice_number`, `invoice_notes`	Número y notas de la factura de venta.

Un parser que ignore claves desconocidas sigue funcionando. Un parser que rechace claves de más hay que ampliarlo.

Utilidad y comisiones, solo en el detalle

GET /api/public/v1/reservations/{id}

El detalle agrega cinco valores numéricos. No vienen en los listados.

Campo	Significado
`own_income`	Ingreso propio.
`agent_commission_value`	Comisión del agente.
`agency_commission_value`	Comisión de la agencia.
`intermediary_commission_value`	Comisión del intermediario.
`profit`	Utilidad de la reserva.

Facturas de proveedores de una reserva

GET /api/public/v1/reservations/{id}/provider_invoices

Alcance: reservations 404 si la reserva no existe

data trae tres bloques:

Bloque	Contenido
`items`	Facturas de esa reserva, ordenadas por id.
`extra.trip_shared_provider_invoices`	Facturas del mismo viaje sin reserva asignada. Si la reserva no tiene viaje, este arreglo va vacío.
`summary`	Totales estimados en moneda local.

Cada factura

Tanto en items como en extra.trip_shared_provider_invoices:

Campo	Nota
`id`
`reference`
`currency_code`	Moneda de la factura.
`provider_id`
`provider_name`
`status`
`total_value`	En la moneda de la factura.
`paid_value`	En la moneda de la factura.
`unpaid_value`	Valor pendiente, en la moneda de la factura.

summary

Va en moneda local. Estos tres corresponden a las facturas de la reserva:

estimated_lc_total_provider_charge_value
estimated_lc_provider_paid_value
estimated_lc_provider_unpaid_value

Estos tres incluyen además las facturas del viaje que no tienen reserva asignada:

estimated_lc_total_global_provider_charge_value
estimated_lc_total_global_provider_paid_value
estimated_lc_total_global_provider_unpaid_value

Pagos de una factura de proveedor

GET /api/public/v1/provider_invoices/{id}/payments

Alcance: provider_invoices 404 si la factura no existe data.items y data.total

Paginación con skip y take. Orden: id del pago, ascendente.

Campo	Nota
`id`
`date`	Puede llegar nulo.
`value`	Valor del pago en `currency_code`.
`currency_code`	Moneda del pago.
`bank_account_id`	Puede llegar nulo. Corresponde al `id` de `GET /api/public/v1/bank_accounts`.
`bank_account_name`	Puede llegar nulo.
`bank_account_number`	Puede llegar nulo.

Listado de pagos a proveedores

GET /api/public/v1/provider_invoice_payments

Alcance: provider_invoice_payments data.items y data.total

Paginación con skip y take. Orden: id del pago, ascendente. Cada ítem repite los campos del pago de una factura y agrega:

Campo	Nota
`provider_invoice_id`
`reservation_id`	Nulo cuando la factura no tiene reserva.
`trip_id`	Puede ser nulo.

Filtros

Opcionales, dentro de filters. Si filters no es un objeto, o trae una clave que no está en esta lista, la respuesta es 422.

Filtro	Uso
`date_from`, `date_to`	Formato `Y-m-d`. Filtran el campo `date` e incluyen el día completo.
`trip_id`	Pagos de ese viaje.
`reservation_id`	Pagos cuya factura tiene esa reserva. Una factura con `reservation_id` nulo no entra en este filtro.
`provider_invoice_id`	Pagos de esa factura.
`bank_account_id`	Pagos de esa cuenta.

Cuentas bancarias

GET /api/public/v1/bank_accounts

Alcance: bank_accounts data.items y data.total Sin filtros

Paginación con skip y take. Orden: id, ascendente. bank_account_id de un pago corresponde al id de esta lista.

Campo
`id`
`name`
`number`
`account_type`
`currency_code`
`bank_name`
`status`

Cómo conviene que un agente actualice su cliente

Amplíe el esquema de reserva con los campos nuevos y acepte nulos.
Lea la utilidad del detalle en profit.
Deje own_income, las comisiones y profit fuera de los listados. Si los necesita, pida el detalle.
En las facturas de una reserva, lea los montos de cada factura en su currency_code y el summary como moneda local.
Pida el alcance provider_invoices para los pagos de una factura y provider_invoice_payments para el listado con filtros.
Acepte date, bank_account_id, bank_account_name y bank_account_number nulos en un pago.
Pida el alcance bank_accounts para consultar las cuentas. Sin ese alcance la respuesta es 403.