# 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

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

# 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

# 3.3 Resumen de reservas (versión extendida)

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

# 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

    {
      "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
      }
    }