Saltar al contenido
EntrarEmpieza ahoraEmpieza
Primeros pasos
Contrato OpenAPI 3.1: openapi.yaml
Empezar

Primeros pasos con la API

De la clave al primer webhook en cinco llamadas. Todo son peticiones reales: cópialas, cambia la clave y ejecuta.

1 · Consigue una clave

Las claves las emite We Are Transfers para una integración de tu organización (tu ERP, tu PMS, tu CRM…), con los scopes que esa integración necesita y en un entorno (live o test). El secreto completo se enseña una sola vez al crearla: guárdalo en tu gestor de secretos. Después solo se ve el prefijo (wat_live_Ab3dEf7h).

Formato

wat_live_ o wat_test_ seguido de 40 caracteres alfanuméricos. Va en Authorization: Bearer. Nunca en la URL.

2 · Comprueba quién eres

curl
curl https://wearetransfers.com/api/v1/integrations/me \
  -H "Authorization: Bearer $WAT_API_KEY"
json
{
  "integration": {
    "id": "3f1c2a9e-8d6b-4a1f-9c2e-5b7d8e9f0a11",
    "name": "ERP Volcano",
    "kind": "erp"
  },
  "organization": {
    "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "code": "1003",
    "name": "Transfers Levante SL"
  },
  "key": {
    "prefix": "wat_live_Ab3dEf7h",
    "name": "Producción ERP"
  },
  "environment": "live",
  "scopes": [
    "bookings:read",
    "customers:read",
    "events:read",
    "webhooks:read",
    "webhooks:write",
    "links:read",
    "links:write"
  ],
  "rate_limits": {
    "per_minute": {
      "key": 600,
      "organization": 1200,
      "endpoint": 300
    }
  },
  "api_version": "v1"
}

scopes son los scopes efectivos: los de la clave que también tiene la integración. Si falta uno que esperabas, no llames a nada más: pídelo.

3 · Lee las reservas

curl
curl "https://wearetransfers.com/api/v1/bookings?status=confirmed&pickup_from=2026-09-18T00:00:00Z&limit=2" \
  -H "Authorization: Bearer $WAT_API_KEY"
json
{
  "data": [
    {
      "id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "reference": "10031234",
      "external_id": "VLC-2026-000123",
      "status": "confirmed",
      "service_type": "transfer",
      "hours": null,
      "pickup_at": "2026-09-18T08:30:00+00:00",
      "end_at": null,
      "pickup": {
        "address": "Aeropuerto de Valencia (VLC)",
        "lat": 39.4893,
        "lng": -0.4816
      },
      "destination": {
        "address": "Hotel Las Arenas, Valencia",
        "lat": 39.4735,
        "lng": -0.3245
      },
      "distance_km": 12.4,
      "flight": {
        "number": "VY1234",
        "pending": false
      },
      "passengers": {
        "count": 2,
        "luggage": 2,
        "luggage_big": 2,
        "luggage_small": 0,
        "baby_seats": 0,
        "child_seats": 0,
        "booster_seats": 0,
        "wheelchair": false
      },
      "vehicle_category": "sedan",
      "customer": {
        "id": "7e6d5c4b-3a2b-4c1d-9e8f-7a6b5c4d3e2f",
        "name": "Hotel Las Arenas"
      },
      "assignment": {
        "external": false,
        "driver": {
          "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
          "name": "Marta Gil",
          "nickname": "Marta"
        },
        "vehicle": {
          "id": "5f4e3d2c-1b0a-4f9e-8d7c-6b5a4f3e2d1c",
          "plate": "1234 KLM",
          "model": "Mercedes Clase E"
        }
      },
      "role": "originator_and_executor",
      "channel": "customer_engine",
      "confirmation": {
        "mode": "auto",
        "confirmed_at": "2026-09-17T18:02:11+00:00"
      },
      "event_reference": null,
      "created_at": "2026-09-17T18:02:11.204Z"
    },
    {
      "id": "4d5e6f70-8a9b-4c0d-9e1f-2a3b4c5d6e7f",
      "reference": "10031235",
      "external_id": null,
      "status": "confirmed",
      "service_type": "transfer",
      "hours": null,
      "pickup_at": "2026-09-18T08:30:00+00:00",
      "end_at": null,
      "pickup": {
        "address": "Aeropuerto de Valencia (VLC)",
        "lat": 39.4893,
        "lng": -0.4816
      },
      "destination": {
        "address": "Hotel Las Arenas, Valencia",
        "lat": 39.4735,
        "lng": -0.3245
      },
      "distance_km": 12.4,
      "flight": {
        "number": "VY1234",
        "pending": false
      },
      "passengers": {
        "count": 2,
        "luggage": 2,
        "luggage_big": 2,
        "luggage_small": 0,
        "baby_seats": 0,
        "child_seats": 0,
        "booster_seats": 0,
        "wheelchair": false
      },
      "vehicle_category": "sedan",
      "customer": {
        "id": "7e6d5c4b-3a2b-4c1d-9e8f-7a6b5c4d3e2f",
        "name": "Hotel Las Arenas"
      },
      "assignment": {
        "external": true,
        "driver": null,
        "vehicle": null
      },
      "role": "originator",
      "channel": "customer_engine",
      "confirmation": {
        "mode": "auto",
        "confirmed_at": "2026-09-17T18:02:11+00:00"
      },
      "event_reference": null,
      "created_at": "2026-09-17T18:02:11.204Z"
    }
  ],
  "next_cursor": "WyJib29raW5ncyIsIjIwMjYtMDktMTdUMTg6MDI6MTEuMjA0WiIsIjBjMWQyZTNmLTRhNWItNGM2ZC04ZTdmLTlhMGIxYzJkM2U0ZiJd.q1Zw8N3kPf2LgT7c",
  "has_more": true
}

La segunda reserva la ejecuta otra empresa (ha salido a la bolsa): assignment.external es true y su conductor y su vehículo no se exponen. Fíjate también en que no hay passenger ni pricing: esta clave no tienepassengers:read ni pricing:read.

4 · Página siguiente

curl
curl "https://wearetransfers.com/api/v1/bookings?status=confirmed&pickup_from=2026-09-18T00:00:00Z&limit=2&cursor=WyJib29raW5ncyIsIjIwMjYtMDktMTdUMTg6MDI6MTEuMjA0WiIsIjBjMWQyZTNmLTRhNWItNGM2ZC04ZTdmLTlhMGIxYzJkM2U0ZiJd.q1Zw8N3kPf2LgT7c" \
  -H "Authorization: Bearer $WAT_API_KEY"

Repite los mismos filtros y añade cursor con el next_cursor anterior, hasta que has_more sea false. Detalle en Paginación.

5 · Deja de sondear: un webhook

Con webhooks:write, dos llamadas y ya recibes cada cambio. El secret vuelve una sola vez: es con lo que verificarás la firma de cada entrega.

curl
curl -X POST https://wearetransfers.com/api/v1/webhooks \
  -H "Authorization: Bearer $WAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://tu-servidor.com/wat","events":["booking.created","booking.updated","booking.cancelled"]}'
json
{
  "id": "9f1c2d3e-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
  "url": "https://tu-servidor.com/wat",
  "events": [
    "booking.created",
    "booking.updated",
    "booking.cancelled"
  ],
  "active": true,
  "secret": "whsec_…"
}
curl
curl -X POST https://wearetransfers.com/api/v1/webhooks/9f1c2d3e-4a5b-4c6d-8e9f-0a1b2c3d4e5f/test \
  -H "Authorization: Bearer $WAT_API_KEY"

Responde 202 y en unos segundos llega un webhook.test a tu servidor. Comprueba siempre la cabecera X-WAT-Signature antes de leer el cuerpo: Firmas.

6 · Lo que viene después

Primeros pasos · API de WAT