Partner API v1

Integra CUBIO en tu sistema

Partner API para crear, gestionar y hacer seguimiento de reservas de transporte. Perfecta para agencias, sistemas corporativos y desarrolladores.

EmpezarSwagger UI

RESTful & JSON

API moderna con respuestas JSON. Fácil de integrar con cualquier lenguaje.

OAuth 2.0

Client Credentials flow con scopes granulares para control de permisos.

Rate Limiting

1000 requests/min en producción. Suficiente para cualquier integración.

Webhooks

Notificaciones en tiempo real con firma HMAC y reintentos automáticos.

¿Para quién es esta API?

Diseñada para partners que quieren ofrecer servicios de transporte a sus clientes.

Agencias de viajes

Integra reservas de transfer en tu plataforma de viajes.

Sistemas de gestión hotelera

Ofrece transfers desde tu PMS o channel manager.

Apps de turismo

Añade transporte VIP a tu app de experiencias.

Portales corporativos

Automatiza reservas desde tu intranet o ERP.

Quick Start

Empieza a hacer llamadas a la API en minutos.

1

Obtén tus credenciales

Contacta con CUBIO para obtener tu cuenta de partner. Recibirás un client_id y client_secret para OAuth 2.0.

Variables de entorno
CUBIO_CLIENT_ID=your_partner_client_id
CUBIO_CLIENT_SECRET=your_partner_client_secret
CUBIO_API_URL=https://api.cubio.io/api/v1
2

Autentícate con OAuth 2.0

Usa el flujo Client Credentials para obtener un access token. Especifica los scopes que necesitas.

POST/api/v1/oauth/token
curl -X POST https://api.cubio.io/api/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=quotes:read bookings:create bookings:read bookings:cancel"
Response 200
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "quotes:read bookings:create bookings:read bookings:cancel"
}
3

Obtén una cotización

Antes de crear una reserva, obtén los precios y vehículos disponibles.

POST/api/v1/partners/quotes
curl -X POST https://api.cubio.io/api/v1/partners/quotes \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": {
      "name": "Aeropuerto de Valencia",
      "latitude": 39.4893,
      "longitude": -0.4785
    },
    "destination": {
      "name": "Hotel Las Arenas, Valencia",
      "latitude": 39.4533,
      "longitude": -0.3242
    },
    "scheduledDateTime": "2026-02-10T14:30:00",
    "pickupTimezone": "Europe/Madrid",
    "passengerCount": 2,
    "extras": [],
    "locale": "es"
  }'
Response 200
{
  "hasCoverage": true,
  "routeInfo": {
    "distanceKm": 12.5,
    "durationMinutes": 20,
    "polyline": "...",
    "routeSource": "google"
  },
  "vehicleOptions": [
    {
      "vehicleTypeId": 1,
      "vehicleTypeName": "Berlina",
      "maxPassengers": 4,
      "maxLuggage": 2,
      "available": true,
      "basePrice": 45.00,
      "markupAmount": 5.00,
      "subtotal": 50.00,
      "taxAmount": 5.00,
      "totalPrice": 55.00,
      "currency": "EUR"
    },
    {
      "vehicleTypeId": 2,
      "vehicleTypeName": "Van",
      "maxPassengers": 7,
      "maxLuggage": 6,
      "available": true,
      "totalPrice": 75.00,
      "currency": "EUR"
    }
  ],
  "availableExtras": [...],
  "pricesIncludeTax": true,
  "taxRate": 10,
  "currency": "EUR"
}
4

Crea la reserva

Usa el vehicleTypeId de la cotización para crear la reserva.

POST/api/v1/partners/bookings
curl -X POST https://api.cubio.io/api/v1/partners/bookings \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": {
      "name": "Aeropuerto de Valencia",
      "latitude": 39.4893,
      "longitude": -0.4785
    },
    "destination": {
      "name": "Hotel Las Arenas, Valencia",
      "latitude": 39.4533,
      "longitude": -0.3242
    },
    "scheduledDateTime": "2026-02-10T14:30:00",
    "pickupTimezone": "Europe/Madrid",
    "vehicleTypeId": 1,
    "passengerCount": 2,
    "guestName": "Juan Pérez",
    "guestEmail": "juan@example.com",
    "guestPhone": "+34600123456",
    "guestLocale": "es",
    "partnerReference": "RES-2026-001",
    "flightInfo": {
      "flightNumber": "VY1234",
      "airline": "Vueling",
      "arrivalTime": "2026-02-10T14:00:00",
      "terminal": "T1"
    },
    "notes": "Pasajero con equipaje extra"
  }'
Response 201
{
  "bookingId": 12345,
  "serviceNumber": "SRV-2026-001",
  "partnerReference": "RES-2026-001",
  "status": "SIN_ASIGNAR",
  "paymentStatus": "PENDING",
  "origin": {
    "name": "Aeropuerto de Valencia",
    "latitude": 39.4893,
    "longitude": -0.4785
  },
  "destination": {
    "name": "Hotel Las Arenas, Valencia",
    "latitude": 39.4533,
    "longitude": -0.3242
  },
  "scheduledDateTime": "2026-02-10T14:30:00",
  "vehicleTypeName": "Berlina",
  "passengerCount": 2,
  "basePrice": 45.00,
  "markupAmount": 5.00,
  "totalPrice": 55.00,
  "currency": "EUR",
  "guestName": "Juan Pérez",
  "guestEmail": "juan@example.com",
  "guestAccessUrl": "https://passenger.cubio.io/onboarding?token=xxx",
  "createdAt": "2026-02-05T10:00:00Z"
}

OAuth Scopes

Solicita solo los permisos que necesitas para tu integración.

quotes:readObtener cotizaciones de viajes
bookings:createCrear reservas y payment intents
bookings:readLeer reservas y tracking
bookings:cancelCancelar reservas
profile:readLeer perfil del partner
profile:writeActualizar perfil del partner

Endpoints

Base URL: https://api.cubio.io/api/v1

Cotizaciones

Obtener precios y disponibilidad antes de reservar

POST/partners/quotes

Reservas

Crear, consultar y cancelar reservas

POST/partners/bookings
GET/partners/bookings
GET/partners/bookings/{bookingId}
DELETE/partners/bookings/{bookingId}

Tracking

Seguimiento en tiempo real del servicio

GET/partners/tracking/active

Pagos

Integración con Stripe para pagos

POST/partners/payments/intent

Ubicaciones

Gestiona ubicaciones predefinidas

GET/partners/locations
POST/partners/locations
PUT/partners/locations/{locationId}
DELETE/partners/locations/{locationId}

Perfil & Stats

Información del partner y estadísticas

GET/partners/me
PUT/partners/me
GET/partners/stats
GET/partners/stats/chart

Estados del servicio

Ciclo de vida de una reserva en CUBIO.

SIN_ASIGNAR

Sin asignar

C_ASIGNADO

Conductor asignado

V_ASIGNADO

Vehículo asignado

EN_CAMINO

Conductor en camino

EN_ORIGEN

Conductor en origen

INICIADO

Servicio iniciado

FINALIZADO

Servicio finalizado

NO_SHOW_CLIENTE

Cliente no se presentó

Webhooks

Recibe notificaciones instantáneas cuando cambie el estado de una reserva. Configura tu endpoint en el perfil del partner.

Firma HMAC-SHA256

Header X-Cubio-Signature

Reintentos automáticos

Backoff exponencial en caso de fallo

Headers informativos

X-Cubio-Event y X-Cubio-Event-Id

Payload de ejemplo
{
  "event": "booking.driver_assigned",
  "event_id": "evt_abc123xyz",
  "partner_code": "AGENCY_001",
  "timestamp": "2026-02-10T13:00:00Z",
  "data": {
    "booking_id": 12345,
    "service_number": "SRV-2026-001",
    "partner_reference": "RES-2026-001",
    "status": "C_ASIGNADO",
    "driver": {
      "name": "Carlos García",
      "phone": "+34600123456"
    },
    "vehicle": {
      "plate": "1234 ABC",
      "model": "Mercedes E-Class"
    }
  }
}

Eventos disponibles

booking.createdReserva creada
booking.confirmedReserva confirmada (pago procesado)
booking.cancelledReserva cancelada
booking.driver_assignedConductor asignado al servicio
booking.driver_en_routeConductor en camino (EN_CAMINO)
booking.completedServicio finalizado (FINALIZADO)
payment.receivedPago recibido
payment.refundedReembolso procesado

Códigos de respuesta

La API utiliza códigos HTTP estándar.

200OK - Solicitud exitosa
201Created - Recurso creado correctamente
400Bad Request - Parámetros inválidos
401Unauthorized - Token inválido o expirado
403Forbidden - Scope insuficiente
404Not Found - Recurso no encontrado
422Unprocessable - Error de validación
429Too Many Requests - Rate limit excedido
500Server Error - Error interno

Recursos

Swagger UI

Documentación interactiva

OAuth Metadata

Configuración OAuth

Sandbox

Entorno de pruebas

¿Quieres integrar CUBIO?

Contacta con nosotros para obtener tus credenciales de partner y acceso al sandbox de pruebas.

Solicitar accesoVer Swagger