Desarrolladores

API de red

Vende traslados en toda la red sin contratar operador por operador. Regístrate, prueba con tu clave esta misma tarde y pasa a producción tras una revisión.

Intégrate en un día

Todo lo necesario para probar está en el alta. Nadie tiene que darte acceso a la clave de prueba.

Regístrate en el portal. Recibes una clave de prueba tmc_test_ en ese momento: guárdala, solo se muestra una vez.
Cotiza y reserva con ella. No interviene ninguna flota real, no se cobra nada y no se avisa a nadie.
Añade en el portal la URL de tu webhook y guarda el secreto que aparece una sola vez.
Reproduce los escenarios y comprueba que tu sistema recibe cada evento.
Tu cuenta queda en revisión. Una persona la aprueba y emite tu clave de producción.

Crear cuenta de socio

curl https://api.transfersmanager.ai/api/v1/channel-api/me \
  -H "X-API-Key: tmc_test_..."

curl -X POST https://api.transfersmanager.ai/api/v1/channel-api/quotes \
  -H "X-API-Key: tmc_test_..." -H "Content-Type: application/json" \
  -d '{"origin_lat":36.68,"origin_lng":-4.49,"destination_lat":36.51,"destination_lng":-4.88,
       "pickup_datetime":"2027-03-14T10:30:00+01:00","passengers":2}'

Con una clave de producción, una reserva devuelve un enlace de pago y entra en la red cuando se paga. Solo se cotiza donde hay oferta real de flotas verificadas: consulta /coverage antes de cotizar. Si no la hay, /quotes responde 503 no_operators.

Endpoints

Base: /api/v1/channel-api. Autenticación con la cabecera X-API-Key o Authorization: Bearer. Una referencia ajena responde 404, igual que una inexistente.

GET /me: Quién es esta clave y si es de prueba.
GET /coverage: Dónde hay oferta real: zonas aproximadas, o la respuesta exacta para un punto con lat y lng. No nombra flotas.
POST /quotes: Precio con neto, comisión y total. La cotización vive cinco minutos y se reserva una vez.
POST /bookings: Reserva idempotente por external_ref. Repetirla devuelve la misma reserva.
GET /bookings/{ref}: Una reserva por external_ref o booking_id.
POST /bookings/{ref}/cancel: Cancela. Sin pagar, cierra el enlace. Pagada, devuelve según la escala de cancelación del operador.
GET /bookings/{ref}/voucher: Datos de la reserva para tu propio bono. No hay pase ni PDF: esos documentos nombran al operador.
GET /flights/{number}?date=YYYY-MM-DD: Un vuelo por número y fecha. 404 flight_not_found si no existe y 503 flight_status_unavailable con Retry-After si no se sabe.
POST /pickup-suggestion: Cuándo reservar la recogida para un vuelo. No reserva nada ni fija precio.
POST /test/bookings/{ref}/scenario: Solo claves de prueba: reproduce un escenario.
GET /test/bookings/{ref}/events: Solo claves de prueba: lo que ha pasado en una reserva de prueba.

Claves de prueba

Una clave tmc_test_ responde con el mismo contrato desde un mundo aislado: la reserva no es un servicio real y ninguna flota la ve. El precio es una estimación por distancia en línea recta, marcada con is_approximate. La reserva queda confirmada al momento y no lleva enlace de pago. Los vuelos y recogidas son inventados. Primero driver_assigned; después el resto.

driver_assigned: Se asigna conductor.
driver_delayed: Aviso de retraso, con delay_minutes. Solo existe en el mundo de prueba: hoy producción no emite este evento.
driver_position: Una posición del coche inventada.
no_show: El conductor llega y el pasajero no se presenta.
completed: El servicio se hace completo.

curl -X POST https://api.transfersmanager.ai/api/v1/channel-api/test/bookings/my-ref-1/scenario \
  -H "X-API-Key: tmc_test_..." -H "Content-Type: application/json" \
  -d '{"scenario":"driver_assigned"}'

Webhooks

Una URL por cuenta, configurada en el portal. Cada entrega va firmada con tu secreto, igual que en la API para socios, y las claves de prueba también los reciben.

Verifica la firma sobre el cuerpo original, antes de interpretar el JSON.
Reintentos con espera creciente desde 30 segundos y hasta una hora, 12 intentos en total. Mientras un intento falla, no se envían los siguientes eventos de tu cuenta en esa pasada.
Desde el portal ves los últimos 50 eventos y puedes reenviar cualquiera. Se conserva el mismo identificador de entrega para que detectes duplicados. Se guardan 30 días.
Posición en vivo: booking.driver_position es opcional y está apagado por defecto. Se activa en el portal. Solo se envía con el coche de camino, en la recogida o con el pasajero a bordo, como mucho cada 30 segundos, y solo lleva identificadores de la reserva y coordenadas. Una posición no se reintenta ni se reenvía. Un receptor que falla o tarda 1,5 segundos o más se pausa 5 minutos.

import crypto from 'node:crypto';

// rawBody: the request body as a string or Buffer, BEFORE JSON.parse.
export function verifyTmSignature(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false; // older than 5 minutes

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${t}.${rawBody}`)
    .digest('hex');

  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1 ?? '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Reglas

Antelación mínima: se comprueba al cotizar y al reservar, con la comunidad autónoma de las coordenadas de recogida. Si no se puede saber o la dirección las contradice, se aplica el mínimo más estricto. Responde 422 lead_time_too_short con la cifra y su base legal. Las claves de prueba aplican siempre el más estricto.
Una reserva inmediata (immediate: true) requiere una recogida a menos de 24 horas y, sin flota pactada, al menos 60 minutos por delante.
El contrato no revela la flota: ni en cotizaciones, ni en cobertura, ni en el bono.

{
  "detail": {
    "error": "lead_time_too_short",
    "message": "Pickups in Cataluña must be booked at least 15 minutes ahead.",
    "minimum_minutes": 15,
    "community": "ES-CT",
    "community_name": "Cataluña",
    "legal_basis": "Decreto-ley 9/2022, ..."
  }
}

Límites

Peticiones: 120 por minuto y clave por defecto; 429 si se supera. Las claves de prueba comparten un único límite por cuenta.
Claves de prueba: 3 activas por cuenta.
Reservas de prueba: 1.000 por cuenta y 50 eventos por reserva.
Altas: 5 al día por IP.
Cotización: 5 minutos de vida.
/coverage: Hasta 1.500 zonas de 0,5 grados; se puede guardar en caché 5 minutos.
Webhook: 5 segundos por entrega; 3 para una posición.

Recursos

Colección Postman
Registro de cambios
Estado del servicio: responde 200 cuando la API y su base de datos funcionan.

¿Trabajas con un solo operador?

Ver la API para socios