Permisos (scopes) de la API
Cada scope abre un trozo del dominio. Sin el scope, la propiedad no existe en la respuesta y el endpoint responde 403.
Los scopes se piden al crear la integración y se asignan a cada clave (nunca más de los que tiene la integración). Un endpoint puede exigir varios: hacen falta todos. El que falte va en details.required_scope del error insufficient_scope.
| Scope | Qué abre | Endpoints en v1 |
|---|---|---|
bookings:read | Leer reservas (sin datos del pasajero ni precios) | GET /bookings · GET /bookings/{id} · base de /bookings/{id}/external-id |
bookings:create | Crear reservas | Próximamente |
bookings:write | Modificar reservas | Próximamente |
bookings:cancel | Cancelar reservas | Próximamente |
customers:read | Leer clientes (hoteles, agencias, motor) | GET /customers · GET /customers/{id} |
customers:write | Modificar clientes | Próximamente |
drivers:read | Leer conductores | GET /drivers · GET /drivers/{id} |
vehicles:read | Leer vehículos | GET /vehicles · GET /vehicles/{id} |
pricing:read | Ver precios, IVA y forma de pago de las reservas | Añade `pricing` a cada reserva (API y webhooks) |
billing:read | Leer datos de facturación del cliente | Próximamente |
invoices:read | Leer facturas | Próximamente |
payments:read | Leer cobros | Próximamente |
passengers:read | Ver nombre, teléfono y correo del pasajero | Añade `passenger` a cada reserva (API y webhooks) |
tracking:read | Ver posición del vehículo en un servicio | Próximamente |
events:read | Leer el registro de eventos de la organización | GET /events |
webhooks:read | Ver los webhooks configurados | GET /webhooks · GET /webhooks/{id} · GET /webhooks/{id}/deliveries |
webhooks:write | Crear, cambiar y borrar webhooks | POST /webhooks · PATCH /webhooks/{id} · DELETE /webhooks/{id} · POST /webhooks/{id}/test |
links:read | Leer identificadores externos | GET /bookings/{id}/external-id |
links:write | Guardar identificadores externos | PUT y DELETE /bookings/{id}/external-id |
bookings:create, bookings:write, bookings:cancel, customers:write, billing:read, invoices:read, payments:read y tracking:read se aceptan al crear una integración para no tener que tocarla cuando lleguen, pero hoy no abren nada. Cuando se activen se anunciará en el changelog.
Datos sensibles: pasajero y dinero
Una reserva con bookings:read trae lo operativo: cuándo, dónde, cuántos, qué vehículo, quién la ejecuta. El pasajero y el precio van aparte, y solo aparecen si la clave tiene el scope. Lo mismo en los webhooks: el cuerpo se construye con los scopes de la integración en el momento de entregar.
Con passengers:read
{
"passenger": {
"name": "Laura Sanz",
"phone": "+34600000000",
"email": "laura@example.com"
}
}Con pricing:read
{
"pricing": {
"currency": "EUR",
"total": 48,
"vat_pct": 10,
"sale_total": null,
"extras": [
{
"name": "Silla de bebé",
"amount": 5,
"per_passenger": false
}
],
"diet": null,
"parking": null,
"night_surcharge": null,
"payment_mode": "cuenta",
"payment_status": "pendiente",
"paid_at": null
}
}Las notas internas, las observaciones, el chat, el cartel de recogida y la posición GPS no forman parte de la API en v1 con ningún scope.