API facturación

1. Introducción

Bienvenido a la API de facturación de Mybooking. Este API permite extraer información de las facturas.

1.1 Credenciales

Consulta el funcionamiento de las credenciales con API 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 Invoice

Atributos

---

id number

Identificador de la factura

---

company_id number

Identificador de la empresa

---

object string

Tipo de objeto. En este caso "invoice" que representa una factura

---

rental_location_code string

Identificador de la sucursal. Sólo se informa cuando hay múltiples sucursales.

---

rental_storage_external_code string

Código externo del grupo de sucursales o concesionario. Sólo se informa cuando hay múltiples sucursales.

---

rental_location_external_code string

Código externo de la sucursal o instalación. Sólo se informa cuando hay múltiples sucursales.

---

sales_channel_code string

Identificador del canal de venta. Sólo se informa cuando hay múltiples canales de venta.

---

invoice_type string

Tipo de factura. Los valores posibles son:

• invoice que representa una factura y
• payment que representa un abono.

---

invoice_mode string

Modo de la factura. Los valores posibles son:

• default Factura no vinculada a un contrato
• reservation_retainer Factura de anticipo
• reservation_breakdown Conceptos desglosados
• reservation_extra Conceptos extras una vez creada la factura final

---

invoice_status string

Estado de la factura. Los valores posibles son:

• draft Borrador
• invoice Factura en firme

---

serie string

Número de serie de la factura. Cuando está emitida.

---

number string

Número de factura. Cuando está emitida.

---

date string

Fecha de emisión de la factura. Formato AAAA-MM-DD

---

concept string

Concepto de la factura

---

customer_id number

Identificador de cliente

---

customer_type string

Tipo de cliente. Los valores posibles son:

• individual Persona física
• legal_entity Persona jurídica
• internal_department Departamento interno
• legal_entity_group_company Empresa del grupo

---

customer_full_name string

Nombre completo del cliente

---

customer_document_id string

DNI/Pasaporte del cliente

---

customer_address_street string

Dirección del cliente : calle

---

customer_address_number string

Dirección del cliente : número

---

customer_address_complement string

Dirección del cliente : complemento (piso, puerta, escalera, ...)

---

customer_address_city string

Dirección del cliente : ciudad

---

customer_address_state string

Dirección del cliente : provincia

---

customer_address_country string

Dirección del cliente : país

---

customer_address_zip string

Dirección del cliente : código postal

---

payment_status string

Estado del pago. Los valores posibles son:

• pending Pendiente
• paid Pago

---

total_paid number

Estado del pago. Los valores posibles son:

• pending Pendiente
• paid Pago

---

agent_comission_prepaid_amount number

Importe del prepago de comisión al comisionista

---

total_pending number

Importe pendiente de pago

---

reference_source string

Tipo de documento facturado. Sólo está informado cuando la factura está vinculada a un contrato de alquiler o de actividades. Los valores posibles son:

• booking Contrato de alquiler
• order Contrato de actividades

---

reference string

Número del contrato de alquiler o actividades vinculado

---

reference_detail string

Número de matrícula del vehículo alquilado

---

reference_dates string

Fechas y horarios de la entrega y devolución

---

reference_subtype_id integer

Identificador del tipo de contrato

---

reference_subtype_name string

Nombre del tipo de contrato

---

reference_agency string

Nombre de la agencia online a través de la que se captó la reserva/contrato

---

currency string

Moneda de la factura. Código ISO-4271

---

total_without_taxes_1 string

Importe sin impuestos 1. Formato NN.NN

---

vat_1 string

% Tipo de impuestos 1. Formato NN.NN

---

taxes_1 string

Total impuestos del tipo de impuestos 1. Formato NN.NN

---

total_without_taxes_2 string

Importe sin impuestos 2. Formato NN.NN

---

vat_2 string

% Tipo de impuestos 2. Formato NN.NN

---

taxes_2 string

Total impuestos del tipo de impuestos 2. Formato NN.NN

---

total_without_taxes_3 string

Importe sin impuestos 3. Formato NN.NN

---

vat_3 string

% Tipo de impuestos 3. Formato NN.NN

---

taxes_3 string

Total impuestos del tipo de impuestos 3. Formato NN.NN

---

total_without_taxes_4 string

Importe sin impuestos 4. Formato NN.NN

---

vat_4 string

% Tipo de impuestos 4. Formato NN.NN

---

taxes_4 string

Total impuestos del tipo de impuestos 4. Formato NN.NN

---

total_without_taxes_5 string

Importe sin impuestos 5. Formato NN.NN

---

vat_5 string

% Tipo de impuestos 5. Formato NN.NN

---

taxes_5 string

Total impuestos del tipo de impuestos 5. Formato NN.NN

---

total_without_taxes string

Importe total antes de impuestos. Formato NN.NN

---

total_taxes string

Total de impuestos. Formato NN.NN

---

total string

Total. Formato NN.NN

---

items Array

Líneas de la factura

---

charges Array

Cobros

---

Objecto InvoiceItem

Atributos

---

id number

Identificador de la línea de la factura

---

object string

Tipo de objeto, "invoice_item" representa una línea de factura

---

concepto string

Concepto facturado

---

quantity number

Cantidad

---

vat_percentage string

Tipo de impuestos. Formato NN.NN

---

taxes_included boolean

Indica si el precio incluye impuestos

---

price_without_taxes string

Importe unitario sin impuestos

---

unit_taxes string

Importe impuestos unitario. Formato NN.NN

---

price string

Precio de una unidad con impuestos. Formato NN.NN

---

total_without_taxes string

Importe total sin impuestos. Formato NN.NN

---

subtotal string

Subtotal de la línea de factura. Formato NN.NN

---

taxes string

Importe de los impuetos de la línea de factura. Formato NN.NN

---

total string

Importe total, incluyendo impuestos, de la línea de factura. Formato NN.NN

---

external_code string

Código externo vinculado con el ERP

---

Objecto Charge

Atributos

---

id number

Identificador de la línea de la factura

---

object string

Tipo de objeto, "charge" representa un cobro

---

payment_type string

Tipo de pago. Los valores posibles son:

• charge Cobro
• payment Devolución

---

rental_location_code string

Identificador de la sucursal. Sólo se informa cuando hay múltiples sucursales.

---

sales_channel_code string

Identificador del canal de venta. Sólo se informa cuando hay múltiples canales de venta.

---

date string

Fecha del cobro en formato YYYY-MM-DDTHH:mm:SS.MSN.+NN:NN

---

amount string

Importe cobrado. Formato NN.NN

---

currency string

Moneda del cobro. Código ISO-4271

---

status string

Estado de pago. Los valores posibles son:

• done Cobrado

payment_method_id string

Forma de pago. Los valores posibles son:

• credit_card Tarjeta de crédito
• cash Efectivo
• bank_transfer Transferencia bancaria
• paypal_standard Paypal
• redsys_256 TPV Virtual - Redsys
• addon_payments TPV Virtual - Addon Payments
• cecabank TPV Virtual - Cecabank
• webpay TPV Virtual - Webpay transbank
• tpv_online TPV Online
• check Cheque
• promissory_note Pagaré
• booking_portal Portal / Agencia online

---

external_operation_number string

Código externo de la operación. En el caso de tarjeta de crédito

---

origin string

Origen del cobro

---

deposit_kept boolean

Indica si el cobro corresponde a la retención del importe de la fianza/franquicia

---

offline_physical_device_id string

Indica el código del dispositivo físico, datáfono, con el que se ha realizado el cobro.

---

{
  "data": [
    {
      "id": 115,
      "object": "invoice",
      "company_id": 1,
      "rental_location_code": "MAHON",
      "rental_location_external_code": "1234",
      "rental_storage_external_code": "4441",
      "sales_channel_code": null,
      "invoice_type": "invoice",
      "invoice_mode": "default",
      "invoice_status": "draft",
      "serie": "A",
      "number": null,
      "date": "2022-07-26",
      "concept": "Factura Reserva 2223 - 26/07/2022 13:15 - 30/07/2022 10:00 - 8493JXR",
      "customer_id": 440,
      "customer_type": "individual",
      "customer_full_name": "Brad Stark",
      "customer_document_id": "55555555R",
      "customer_address_street": "",
      "customer_address_number": "",
      "customer_address_complement": "",
      "customer_address_city": "",
      "customer_address_state": "",
      "customer_address_country": "",
      "customer_address_zip": "",
      "payment_status": "paid",
      "total_paid": "227.0",
      "agent_comission_prepaid_amount": "0.0",
      "total_pending": "0.0",
      "reference_source": "booking",
      "reference": "2223",
      "reference_detail": "8493JXR",
      "reference_dates": "26/07/2022 13:15 - 30/07/2022 10:00",
      "reference_subtype_id": 1,
      "reference_subtype_name": "Alquiler",
      "reference_agency": null,
      "currency": "EUR",
      "total_without_taxes_1": "187.61",
      "total_without_taxes_2": "0.0",
      "total_without_taxes_3": "0.0",
      "total_without_taxes_4": "0.0",
      "total_without_taxes_5": "0.0",
      "discount_type": "percent",
      "discount_tp": "0.0",
      "discount_1": "0.0",
      "discount_2": "0.0",
      "discount_3": "0.0",
      "discount_4": "0.0",
      "discount_5": "0.0",
      "subtotal_1": "0.0",
      "subtotal_2": "0.0",
      "subtotal_3": "0.0",
      "subtotal_4": "0.0",
      "subtotal_5": "0.0",
      "vat_1": "21.0",
      "vat_2": "0.0",
      "vat_3": "0.0",
      "vat_4": "0.0",
      "vat_5": "0.0",
      "taxes_1": "39.39",
      "taxes_2": "0.0",
      "taxes_3": "0.0",
      "taxes_4": "0.0",
      "taxes_5": "0.0",
      "total_without_taxes": "187.61",
      "discount": "0.0",
      "subtotal": "187.61",
      "total_taxes": "39.39",
      "total": "227.0",
      "items": [
        {
          "id": 115,
          "object": "invoice_item",
          "concept": "Alquiler Grupo C",
          "quantity": 1,
          "vat_percentage": "21.0",
          "taxes_included": true,
          "price_without_taxes": "177.69",
          "unit_taxes": "37.31",
          "price": "215.0",
          "total_without_taxes": "177.69",
          "subtotal": "177.69",
          "taxes": "37.31",
          "total": "215.0",
          "external_code": ""
        },
        {
          "id": 115,
          "object": "invoice_item",
          "concept": "Seguro Extra",
          "quantity": 1,
          "vat_percentage": "21.0",
          "taxes_included": true,
          "price_without_taxes": "9.92",
          "unit_taxes": "2.08",
          "price": "12.0",
          "total_without_taxes": "9.92",
          "subtotal": "9.92",
          "taxes": "2.08",
          "total": "12.0",
          "external_code": null
        }
      ],
      "charges": [
        {
          "id": 2638,
          "object": "charge",
          "payment_type": "charge",
          "rental_location_code": "MAHON",
          "sales_channel_code": null,
          "date": "2022-07-26T11:14:00.000+00:00",
          "amount": "227.0",
          "currency": "EUR",
          "status": "done",
          "payment_method_id": "credit_card",
          "external_operation_number": "",
          "origin": null,
          "deposit_kept": false,
          "offline_physical_device_id": null
        }
      ],
      "accounting_processed": false
    }
  ],
  "total": 29
}

3. API

3.1 Obtener facturas

GET /api/v1/integration/invoices

Obtiene facturas.

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 20 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 10 x defecto	Opcional
rental_storage_external_code	Código externo grupo sucursales o concesionario	Filtra por grupos o concesionarios	Opcional
rental_location_code	Identificador de la sucursal	Filtra por sucursales	Opcional
rental_location_external_code	Código externo sucursal o instalación	Filtra por sucursales o instalaciones	Opcional
accounting_processed	Facturas procesadas	Filtra sólo las procesadas o no procesadas	Opcional
from	Fecha factura desde	Filtra sólo las emitidas a partir de una fecha	Opcional
to	Fecha factura hasta	Filtra sólo las emitidas hasta una fecha	Opcional

# Script para obtener la firma en Ruby
require 'openssl'
SECRET_KEY='MI-SECRET-KEY'
url='/api/v1/integration/invoices?page=0&page_size=20&accounting_processed=false&from=2023-03-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/invoices?page=0&page_size=20&accounting_processed=false&from=2023-03-01'

Respuesta de la petición

Obtiene un Array de objetos tipo Invoice

3.2 Registra que una factura ha sido procesada

POST /api/v1/integration/invoice/:id/processed

Registra que una factura ha sido integrada. Permite indicar también si se ha producido un error en la integración para poderlo analizar

Se indicará el id de la factura en el path en lugar de :id

Se enviará un objeto JSON con los siguientes atributos

Parámetro	Descripción	Detalle
destination_system	Sistema destino	Nombre de la plataforma en la que se ha integrado	Obligatorio
destination_entity	Entidad destino	Nombre de la entidad en el sistema destino	Obligatorio
processed	Procesado con éxito	"true" si se ha procesado y "false" si no	Obligatorio
destination_id	Identif. en destino	Id de la entidad en el sist. destino (si procesado)	Obligatorio*
error_message	Mensaje de error	Detalle del error en la integración (si no procesado)	Obligatorio*

Si la factura se ha procesado y se ha integrado en el sistema destino, se indicará el parámetro destination_id con el identificador en el sistema destino. Si se ha producido un errror se indicará el error en el parámetros error_message para que puedan analizarse y reintentarse de nuevo.

{
    "destination_system": "ERP Contabilidad",
    "destination_entity": "Factura",
    "processed": "true",
    "destination_id": "1209209"
}