API reservas y contratos

1. Introducción

Bienvenido a la API de reservas y contratos de Mybooking. Este API permite extraer las reservas y contratos registradas en Mybooking para poder procesarlas y crear dashboards.

1.1 Credenciales

Consulta el funcionamiento de las credenciales con API Key y Secret Key para ver cómo funciona la autenticación en el acceso a las APIs.

1.2 URL base

Cada una de las cuentas de Mybooking son accesible a través de un subdominio único id de cliente. Si el id de cliente es rentpepe la URL base para realizar las peticiones será:

https://rentpepe.mybooking.es

2. Modelo de datos

Objecto Booking

Atributos

---

id number

Identificador de la reserva/contrato.

---

object string

Tipo de objeto, "reservation" representa una reserva/contrato

---

status string

Estado de la reserva. Los valores posibles son:

• pending_confirmation Pendiente de confirmar
• confirmed Confirmada
• in_progress En curso. Contrato abierto
• done Finalizado. Contrato cerrado.
• cancelled Cancelado.

---

date_from string

Fecha de inicio / entrega. Formato AAAA-MM-DD

---

time_from string

Hora de inicio / entrega. Formato HH:MM

---

pickup_place string

Nombre del lugar de entrega

---

pickup_place_id number

Identificador del lugar de entrega

---

date_to string

Fecha de fin / devolución. Formato AAAA-MM-DD

---

time_to string

Hora de fin / devolución. Formato HH:MM

---

return_place string

Nombre del lugar de devolución

---

return_place_id number

Identificador del lugar de devolución

---

customer_type string

Tipo de cliente. Los valores posibles son:

• individual Persona física
• legal_entity Empresa
• group_company Empresa del grupo
• internal_department Departamento interno

---

customer_id number

Identificador del cliente

---

customer_fullname string

Nombre completo del cliente

---

customer_email string

Correo electrónico del cliente

---

customer_phone string

Teléfono del cliente

---

customer_document_id string

NIF/Pasaporte del cliente

---

rental_location_code string

Código de la sucursal

---

rental_storage_id number

Identificador del grupo de sucursales (concesionarios)

---

sales_channel_code string

Código del canal de venta

---

agency_id number

Idenficicador del agencia online a través de la que cual se ha creado la reserva

---

agency_reservation_id string

Número de la reserva para la agencia online

---

agent_id number

Idenficicador del comisionista

---

agent_comission_calculation string

Cálculo de la comisión. Los valores posibles son:

• fixed_amount Importe fijo
• percentage Porcentaje

---

agent_comission_fixed_amount string

Importe fijo de la comisión. Formato NN.NN

---

agent_comission_percentage string

Porcentaje de la comisión. Formato NN.NN

---

agent_comission_base_amount string

Base para el cálculo de la comisión. Formato NN.NN

---

agent_comission_total string

Importe de la comisión. Formato NN.NN

---

agent_comission_paid boolean

Indica si la comisión se ha liquidado al comisionista o no

---

agent_comission_payment_date string

Fecha de pago de la comisión. Formato AAAA-MM-DD

---

agent_comission_prepaid_amount string

Importe prepagado al comisionista. Formato NN.NN

---

customer_language string

Idioma del cliente. Código ISO 639-1 de 2 caracteres

---

days number

Días de tarificación

---

hours number

Horas de tarificación

---

minutes number

Minutos de tarificación

---

item_cost string

Coste del recurso o vehículo. Formato NN.NN

---

extras_cost string

Coste de los extras. Formato NN.NN

---

item_cost string

Coste del recurso o vehículo. Formato NN.NN

---

time_from_cost string

Suplemento hora de entrega. Formato NN.NN

---

time_to_cost string

Suplemento hora de devolución. Formato NN.NN

---

pickup_place_cost string

Suplemento lugar de entrega. Formato NN.NN

---

return_place_cost string

Suplemento lugar de devolución. Formato NN.NN

---

driver_age_cost string

Suplemento edad del conductor. Formato NN.NN

---

category_supplement_1_cost string

Suplemento extra vinculado al vehículo o servicio. Formato NN.NN

---

category_supplement_2_cost string

Suplemento extra vinculado al vehículo o servicio. Formato NN.NN

---

category_supplement_3_cost string

Suplemento extra vinculado al vehículo o servicio. Formato NN.NN

---

supplement_1_cost string

Suplemento extra. Formato NN.NN

---

supplement_2_cost string

Suplemento extra. Formato NN.NN

---

supplement_3_cost string

Suplemento extra. Formato NN.NN

---

total_cost string

Coste total. Formato NN.NN

---

product_deposit_cost string

Importe de la fianza/franquicia del vehículo. Formato NN.NN

---

product_guarantee_cost string

Importe de la garantía del vehículo. Formato NN.NN

---

driver_age_deposit string

Fianza o depósito por la edad del conductor. Formato NN.NN

---

product_deposit_reduction_amount string

Reducción del importe de la fianza/franquicia del vehículo. Formato NN.NN

---

product_guarantee_reduction_amount string

Reducción del importe de la garantía del vehículo. Formato NN.NN

---

total_deposit string

Total de la fianza + garantía. Formato NN.NN

---

total_paid string

Total pagado. Formato NN.NN

---

total_pending string

Importe pendiente de pago. Formato NN.NN

---

reservation_lines array

Array de objetos BookingLine que representan los servicios contratados

Objecto BookingLine

Atributos

---

id number

Identificador de la línea reserva/contrato.

---

object string

Tipo de objeto, "reservation_line" representa una reserva/contrato

---

item_id string

Código de la categoría (BookingCategory) contratada

---

item_description string

Nombre o descripción de la categoría (BookingCategory) contratada

---

item_unit_cost_base string

Coste inicial de 1 unidad contratada (BookingCategory). Es el coste en el momento de la creación del contrato para las fechas seleccionadas de inicio. Formato NN.NN

---

item_unit_cost string

Coste de 1 unidad contratada (para todos los días). Formato NN.NN

---

item_cost string

Coste de todas las unidades contratadas (para todos los días). Formato NN.NN

---

quantity number

Número de unidades contratadas

---

product_deposit_unit_cost string

Importe de la fianza / franquicia de 1 unidad contratada (para todos los días). Formato NN.NN

---

product_deposit_cost string

Importe de la fianza / franquicia de todas las unidades contratadas (para todos los días). Formato NN.NN

---

category_supplement_1_unit_cost string

Importe suplemento 1 para 1 unidad contratada (para todos los días). Formato NN.NN

---

category_supplement_1_cost string

Importe suplemento 1 para todas las unidades contratada (para todos los días). Formato NN.NN

---

category_supplement_2_unit_cost string

Importe suplemento 2 para 1 unidad contratada (para todos los días). Formato NN.NN

---

category_supplement_2_cost string

Importe suplemento 2 para todas las unidades contratada (para todos los días). Formato NN.NN

---

category_supplement_3_unit_cost string

Importe suplemento 3 para 1 unidad contratada (para todos los días). Formato NN.NN

---

category_supplement_3_cost string

Importe suplemento 3 para todas las unidades contratada (para todos los días). Formato NN.NN

---

reservation_lines array

Array de objetos BookingLineResource que representan los recursos o vehículos

Objecto BookingLineResource

Atributos

---

id number

Identificador del recurso de la reserva/contrato.

---

object string

Tipo de objeto, "reservation_line_resource" representa el recurso de la reserva/contrato

---

reference string

Identificador del recurso o vehículo (BookingItem)

---

stock_plate string

Número de matrícula del recurso o vehículo (BookingItem)

Objecto BookingExtra

Atributos

id number

Identificador del extra de la reserva/contrato.

---

object string

Tipo de objeto, "reservation_extra" representa un extra de la reserva/contrato

---

extra_id string

Código del extra (BookingExtra)

---

extra_description string

Nombre o descripción del extra (BookingCategory)

---

extra_unit_cost string

Coste de 1 unidad (para todos los días). Formato NN.NN

---

extra_cost string

Coste de todas las unidades contratadas (para todos los días). Formato NN.NN

---

quantity number

Número de unidades

Objecto BookingCharge

Atributos

---

id number

Identificador del cobro de la reserva/contrato.

---

object string

Tipo de objeto, "charge" representa un cobro de la reserva/contrato

    {
      "id": 2275,
      "object": "reservation",
      "status": "confirmed",
      "date_from": "2023-06-20",
      "time_from": "09:00",
      "pickup_place": "Aeropuerto de Mahón",
      "pickup_place_id": 2,
      "date_to": "2023-06-22",
      "time_to": "09:00",
      "return_place": "Aeropuerto de Mahón",
      "return_place_id": 2,
      "customer_type": "individual",
      "customer_id": 202,
      "customer_fullname": "Brad Stark",
      "customer_email": "info@mybooking.es",
      "customer_phone": "666101010",
      "customer_document_id": "55555555R",
      "rental_location_code": "MAHON",
      "rental_storage_id": 3,
      "sales_channel_code": null,
      "agency_id": null,
      "agency_reservation_id": null,
      "agent_id": null,
      "agent_comission_calculation": null,
      "agent_comission_fixed_amount": "0.0",
      "agent_comission_percentage": "0.0",
      "agent_comission_base_amount": "0.0",
      "agent_comission_total": "0.0",
      "agent_comission_paid": false,
      "agent_comission_payment_date": null,
      "agent_comission_prepaid_amount": "0.0",
      "customer_language": "es",
      "days": 2,
      "hours": 0,
      "minutes": 0,
      "item_cost": "90.0",
      "extras_cost": "10.0",
      "time_from_cost": "0.0",
      "time_to_cost": "0.0",
      "pickup_place_cost": "10.0",
      "return_place_cost": "10.0",
      "driver_age_cost": "0.0",
      "category_supplement_1_cost": "0.0",
      "category_supplement_2_cost": "0.0",
      "category_supplement_3_cost": "0.0",
      "supplement_1_cost": "0.0",
      "supplement_2_cost": "0.0",
      "supplement_3_cost": "0.0",
      "total_cost": "120.0",
      "product_deposit_cost": "0.0",
      "product_guarantee_cost": "0.0",
      "driver_age_deposit": "0.0",
      "product_deposit_reduction_amount": "0.0",
      "product_guarantee_reduction_amount": "0.0",
      "total_deposit": "0.0",
      "total_paid": "120.0",
      "total_pending": "0.0",
      "reservation_lines": [
        {
          "id": 3197,
          "object": "reservation_line",
          "item_id": "B",
          "item_description": "Grupo B",
          "item_unit_cost_base": "60.0",
          "item_unit_cost": "90.0",
          "item_cost": "90.0",
          "quantity": 1,
          "product_deposit_unit_cost": "0.0",
          "product_deposit_cost": "0.0",
          "category_supplement_1_unit_cost": "0.0",
          "category_supplement_1_cost": "0.0",
          "category_supplement_2_unit_cost": "0.0",
          "category_supplement_2_cost": "0.0",
          "category_supplement_3_unit_cost": "0.0",
          "category_supplement_3_cost": "0.0",
          "reservation_line_resources": [
            {
              "id": 3203,
              "object": "reservation_line_resource",
              "reference": "5510KNG",
              "stock_plate": "5510KNG"
            }
          ]
        }
      ],
      "reservation_extras": [
        {
          "id": 703,
          "object": "reservation_extra",
          "extra_id": "SEGURO-EXTRA",
          "extra_description": "Seguro Extra",
          "extra_unit_cost": "10.0",
          "quantity": 1,
          "extra_cost": "10.0"
        }
      ],
      "charges": [
        {
          "id": 2638,
          "object": "charge",
          "date": "2023-06-16T04:37:27.000+00:00",
          "amount": "45.0",
          "currency": "EUR",
          "payment_method_id": "redsys256"
        },
        {
          "id": 2639,
          "object": "charge",
          "date": "2023-06-16T04:40:12.000+00:00",
          "amount": "45.0",
          "currency": "EUR",
          "payment_method_id": "redsys256"
        },
        {
          "id": 2644,
          "object": "charge",
          "date": "2023-06-16T11:45:17.000+00:00",
          "amount": "30.0",
          "currency": "EUR",
          "payment_method_id": "redsys256"
        }
      ]
    }

3. API

3.1 Obtener reservas

GET /api/v1/integration/reservations

Obtiene los contratos de alquiler.

El volumen de datos que puede llegar a devolver este end-point puede ser demasiado grande para obtenerlos en una única petición. Por esto, se ha implementado con un sistema de paginación que permite ir obtiendo los datos en grupos más reducidos. De forma predeterminada obtiene 100 elementos y retorna el número total de forma que permite implementar un sistema de navegación.

Petición

Parámetro	Descripción	Detalle
page	Núm. de página	Número de la página solicitada. Valor 0 x defecto	Opcional
page_size	Núm. de registros por página	Permite paginar. Valor 100 x defecto	Opcional
sales_channel_id	Identificador canal de venta	Filtra por canal de venta	Opcional
rental_location_code	Identificador de la sucursal	Filtra por sucursales	Opcional
last_update	Última actualización	Filtra los creados/actualizados a partir de fecha	Opcional

# Script para obtener la firma en Ruby
require 'openssl'
SECRET_KEY='MI-SECRET-KEY'
url='/api/v1/integration/customers?page=0&page_size=20&last_update=2023-05-01'
signature = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha1'), SECRET_KEY, url)

# Comando CURL usando el API y la firma para realizar la petición
curl -H "Authorization: {API-KEY}:{signature}" -H "Content-Type: application/json" -X GET 'https://micuenta.mybooking.es/api/v1/integration/reservations?page=0&page_size=20&last_update=2023-05-01'

3.2 Obtener una reserva

GET /api/v1/integration/reservation/:id

Obtiene un contrato de alquiler.

3.3 Resumen de reservas (versión extendida)

GET /api/booking/reservation-report

Obtiene los contratos de alquiler.

El volumen de datos que puede llegar a devolver este end-point puede ser demasiado grande para obtenerlos en una única petición. Por esto, se ha implementado con un sistema de paginación que permite ir obtiendo los datos en grupos más reducidos. De forma predeterminada obtiene los 10 últimos contratos y retorna el número total de contratos de forma que permite implementar un sistema de navegación.

Petición

Parámetro	Descripción	Detalle
page	Núm. de página	Número de la página solicitada. Valor 0 x defecto	Opcional
page_size	Núm. de registros por página	Permite paginar para obtener todos los contratos. Valor 10 x defecto	Opcional
search_type	Tipo de búsqueda	Básica/Textual (basic_search) - Avanzada/Filtro (advanced_search)	Opcional
date_filter	Filtro de fechas	Creación (creation_date) Entrega (pickup_date) Dev. (return_date)	Opcional
from	Filtro fechas (desde)	Fecha inicio para el filtro de fechas. Formato AAAA-MM-DD	Opcional
to	Filtro fechas (hasta)	Fecha final para el filtro de fechas. Formato AAAA-MM-DD	Opcional

# Script para obtener la firma en Ruby
require 'openssl'
SECRET_KEY='MI-SECRET-KEY'
url='/api/booking/reservation-report?page=0&page_size=10&search_type=advanced_search&date_filter=creation_date&from=2022-10-01&to=2022-10-05'
signature = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha1'), SECRET_KEY, url)

# Comando CURL usando el API y la firma para realizar la petición
curl -H "Authorization: {API-KEY}:{signature}" -H "Content-Type: application/json"  -X GET '/api/booking/reservation-report?page=0&page_size=10&search_type=advanced_search&date_filter=creation_date&from=2022-10-01&to=2022-10-05'

Respuesta de la petición

Devuelve un JSON con los siguientes atributos

Atributo	Descripción	Detalle
data	Contratos	array[Object]
	id	Número del contrato
	date_from	Fecha inicio
	time_from	Hora de inicio
	date_to	Fecha fin
	time_to	Hora de fin
	pickup_place	Punto de entrega
	return_place	Punto de devolución
	days	Duración en días facturados
	hours	Duración en horas facturados
	minutes	Duración en minutos facturados
	contract_type_id	Código del tipo de contrato
	contract_type_name	Nombre del tipo de contrato
	rate_type_id	Código del tipo de tarifa
	rate_type_name	Nombre del tipo de tarifa
	status	Estado (pending_confirmation, confirmed, in_progress, done, cancelled)
	total_cost	Importe total
	total_paid	Importe pagado
	total_pending	Importe pendiente de pago
	creation_date	Fecha y hora de creación
	created_by_manager	true => back-office, false => reserva recibida por la web
	customer_type	Tipo de cliente (individual, legal_entity, internal_department, legal_entity_group_company)
	customer_id	Identificador del cliente
	customer_fullname	Nombre completo del cliente
	customer_name	Nombre del cliente (persona física)
	customer_surname	Apellidos del cliente (persona física)
	customer_document_id	Nif/Pasaporte del cliente (persona física)
	customer_company_name	Nombre empresa (persona jurídica)
	customer_company_document_id	NIF empresa (persona jurídica)
	customer_phone_prefix	Prefijo teléfono
	customer_phone	Teléfono
	customer_email	Correo electrónico
	customer_name	Nombre del cliente (persona física)
	customer_surname	Apellidos del cliente (persona física)
	customer_document_id	Nif/Pasaporte del cliente (persona física)
	driver_name	Nombre del conductor
	driver_surname	Apellidos del conductor
	driver_name	Nombre del conductor
	driver_age	Edad del conductor
	driver_date_of_birth	Fecha de nacimiento del conductor
	rental_location_code	Código de la sucursal que gestiona el contrato
	rental_location_name	Nombre de la sucursal que gestiona el contrato
	return_rental_location_code	Código de la sucursal donde se realiza la devolución
	rental_storage_id	Código del grupo de sucursales que gestiona el contrato
	rental_storage_name	Nombre del grupo de sucursales que gestiona el contrato
	sales_channel_code	Código del canal de venta de adquisición de la reserva
	family_name	Nombre de la familia del tipo de categoría contratada
	item_id	Código del tipo de categoría contratada
	item_description	Nombre del tipo de categoría contratada
	item_id	Código del tipo de categoría contratada
	booking_item_reference	Código del vehículo
	booking_item_stock_plate	Matrícula del vehículo
	booking_item_km_miles_on_pickup	Km en la entrega
	booking_item_km_miles_on_return	Km en la devolución
	booking_item_km_miles_total	Km realizados
	agency_id	Código de la OTA de adquisición
	agency_name	Nombre de la OTA de adquisición
	agent_id	Código del comisionista
	agent_name	Nombre del comisionista
	agent_comission_calculation	Tipo de comisión (percentage -porcentaje- o fixed_amount - importe fijo-)
	agent_comission_fixed_amount	Importe fijo comisión
	agent_comission_percentage	Porcentaje de comisión
	agent_comission_base_amount	Importe base para el cálculo de la comisión
	agent_comission_total	Importe total comisión
	agent_comission_paid	Indica si se ha pagado o no la comisión
	agent_comission_payment_date	Fecha de pago de la comisión
total	Número total contratos	Permite paginar para obtenerlos todos
summary	Resumen contratos	[Object]
	total_cost	Importe total
	total_paid	Importe pagado
	total_pending	Importe pendiente de pago

    {
      "data": 
      [        
        {
          "id": 2234,
          "customer_id": 440,
          "customer_name": "Brad",
          "customer_surname": "Stark",
          "customer_phone_prefix": "34",
          "customer_phone": "666101010",
          "customer_email": "info@mybooking.es",
          "customer_document_id": "55555555R",
          "customer_company_name": "",
          "customer_company_document_id": "",
          "customer_type": "individual",
          "customer_fullname": "Brad Stark",
          "customer_stock_plate": null,
          "customer_work_order": null,
          "driver_name": "Brad",
          "driver_surname": "Stark",
          "driver_document_id": "55555555R",
          "driver_age": 41,
          "driver_date_of_birth": "1980-12-10",
          "date_from": "2022-10-04",
          "time_from": "07:00",
          "date_to": "2022-10-07",
          "time_to": "23:00",
          "pickup_place": "Aeropuerto de Mahón",
          "return_place": "Aeropuerto de Mahón",
          "days": 4,
          "hours": 0,
          "minutes": 0,
          "number_of_adults": 0,
          "number_of_children": 0,
          "number_of_adults_out": 0,
          "number_of_children_out": 0,
          "renewal_on_finish": false,
          "with_optional_external_driver": false,
          "status": "confirmed",
          "total_cost": "107.0",
          "total_paid": "0.0",
          "total_pending": "107.0",
          "payment_status": "none",
          "creation_date": "2022-10-03T12:23:30.000+00:00",
          "created_by_manager": true,
          "pay_now": false,
          "rental_location_code": "MAHON",
          "rental_location_name": "OFICINA MAHÓN",
          "return_rental_location_code": "MAHON",
          "rental_storage_id": 3,
          "rental_storage_name": "MAHON",
          "sales_channel_code": null,
          "agency_id": null,
          "agency_reservation_id": null,
          "agency_name": null,
          "item_id": "B",
          "item_description": "Grupo B",
          "family_name": null,
          "booking_item_reference": "7",
          "booking_item_stock_plate_name": "6213GGG",
          "booking_item_stock_plate": "6213GGG",
          "booking_item_stock_reference": null,
          "booking_item_km_miles_on_pickup": 0,
          "booking_item_km_miles_on_return": 0,
          "booking_item_km_miles_total": 0,
          "billing_monthly_amount": "0.0",
          "deposit_status": "",
          "deposit_received": false,
          "total_deposit_received_amount": "0.0",
          "deposit_received_from_reservation": false,
          "total_deposit_received_from_reservation_amount": "0.0",
          "deposit_returned": false,
          "total_deposit_returned_amount": "0.0",
          "deposit_returned_to_reservation": false,
          "total_deposit_returned_to_reservation_amount": "0.0",
          "deposit_kept": false,
          "total_deposit_kept_amount": "0.0",
          "agent_id": null,
          "agent_name": null,
          "agent_comission_calculation": null,
          "agent_comission_fixed_amount": "0.0",
          "agent_comission_percentage": "0.0",
          "agent_comission_base_amount": "0.0",
          "agent_comission_total": "0.0",
          "agent_comission_paid": false,
          "agent_comission_payment_date": null,
          "agent_comission_prepaid_amount": "0.0",
          "rate_type_id": 1,
          "rate_type_name": "Estándar",
          "comments": null,
          "notes": null,
          "contract_type_id": 2,
          "contract_type_name": "Alquiler"
        }
      ],
      "total": 8,
      "summary": {
         "total_cost": 698.4,
         "total_paid": 490.4,
         "total_pending": 208
      }
    }