API de TaxiCFG

El mapa y el despacho de TaxiCFG como servicio para otras aplicaciones: rutas por carretera en toda Cuba, matriz de distancias, lugares, zona, direcciones cubanas («37 e/ 46 y 48») y cotizaciones. Pensada para Cuba: respuestas pequeñas, sin dependencias externas y sin que la aplicación tenga que saber nada del mapa.

La API es para las aplicaciones de TaxiCFG y los socios que el dueño aprueba. Una clave la crea el dueño desde el panel. TaxiCFG registra cifras y nunca cobra ni paga dinero por nadie.

La clave

Cada aplicación tiene una clave tcfg_<id>_<secreto>, con permisos (leer, pedir, avisos) y un límite por minuto. Va en cada petición:

Authorization: Bearer tcfg_k7m2x9p4q1z8_…

El secreto se enseña una sola vez al crear o rotar la clave; TaxiCFG guarda solo su huella. Úsala desde tu servidor, nunca desde un navegador o una app instalada. Si se filtra, rótala desde el panel: la anterior deja de valer en el acto.

Las rutas

Ruta	Qué hace
`GET /api/v1/yo`	Qué aplicación eres, tus permisos y tu límite.
`GET /api/v1/ruta?olat&olng&dlat&dlng`	La ruta por carretera entre dos puntos: km, minutos y la línea. El mismo km que cotiza TaxiCFG. Sin carretera, `404 sin_carretera`: nunca se estima en línea recta.
`POST /api/v1/matriz`	Hasta 15 puntos, todos contra todos, por carretera. Para ordenar paradas.
`GET /api/v1/lugares?q&lat&lng`	Busca un lugar en todo el país desde un solo campo. No hay que elegir provincia: lo cercano a `lat,lng` sale primero y cada resultado trae la suya.
`GET /api/v1/zona?lat&lng`	Municipio y provincia de un punto, y si hoy se llega.
`GET /api/v1/direccion?q&lat&lng`	Una dirección cubana resuelta a su esquina o su cuadra, con confianza. La ciudad se elige sola por `lat,lng`.
`POST /api/v1/cotizar`	Los mismos precios que ve el pasajero en la app.
`POST /api/v1/viajes`	Pide un viaje a nombre de tu cliente (firmado). Un viaje normal de TaxiCFG, con guía `TC-12345678-9` y enlace de seguimiento. Tu `ref` lo hace idempotente: repetirla devuelve el mismo viaje, aunque cambie el resto. Donde no hay tarifa (subasta), `409 subasta_no_disponible`.
`GET /api/v1/viajes/{id}`	El estado de un viaje tuyo, por id o por guía: lo que ve el pasajero, nunca el teléfono del chofer.
`POST /api/v1/viajes/{id}/cancelar`	Cancela mientras se pueda (firmado).
`PUT / GET / DELETE /api/v1/webhook`	Tu webhook: cada cambio del viaje te llega firmado (Standard Webhooks), al menos una vez, con reintentos.
`POST /api/v1/firma/prueba`	Comprueba tu firma antes de integrar lo que escribe.
`GET /api/v1/openapi.json`	El contrato completo (OpenAPI 3.1), sin clave.

Un ejemplo

curl "https://taxicfg.com/api/v1/ruta?olat=22.146&olng=-80.436&dlat=22.129&dlng=-80.456" \
  -H "Authorization: Bearer tcfg_…"

{ "km": 3.9, "min": 11, "puntos": [[22.146, -80.436], …], "motor": 5 }

Errores y límites

Siempre JSON: { "error": "sin_carretera" } con el código HTTP que toca. Sin clave o con una mala, 401; sin el permiso, 403; por encima del límite por minuto, 429 con Retry-After en segundos (también tras veinte claves malas en un minuto desde una misma dirección: demasiados_intentos); un cuerpo de más de 16 KB, 413 cuerpo_grande.

La firma de lo que escribe

Lo que crea o cambia algo (en la fase 2: pedir y cancelar viajes) va firmado con el secreto de tu clave. Tres cabeceras:

X-TaxiCFG-Timestamp: 1761782400          # epoch en segundos, ±5 minutos
X-TaxiCFG-Nonce: 9f3c…                   # 16 a 64 caracteres, de un solo uso
X-TaxiCFG-Signature: <hex>              # HMAC-SHA256 con el secreto sobre:
                                         # MÉTODO\nRUTA\nTIMESTAMP\nNONCE\nSHA256HEX(CUERPO)

Pruébala contra POST /api/v1/firma/prueba: responde { "ok": true } o te dice qué falla (firma_caducada, firma_invalida, firma_repetida).

Los avisos (webhooks)

Con el permiso avisos, pon tu URL con PUT /api/v1/webhook y guarda el secreto whsec_… que se enseña una sola vez. Cada cambio de un viaje tuyo llega como POST con un JSON { type, timestamp, data } y tres cabeceras al estilo Standard Webhooks:

webhook-id: msg_…                 # único por aviso: desduplica con él
webhook-timestamp: 1761782400      # epoch en segundos
webhook-signature: v1,<base64>     # HMAC-SHA256 con el secreto sobre "id.timestamp.cuerpo"

Eventos: viaje.creado, viaje.reservado (un chofer reservó tu programado), viaje.aceptado, viaje.llegando, viaje.recogido, viaje.completado, viaje.cancelado, viaje.sin_chofer, viaje.buscando, viaje.subasta, viaje.programado. Son al menos una vez: si tu servidor no responde 2xx en 10 s, se reintenta a 1 min, 5 min, 30 min, 2 h y 12 h, y a los cinco fallos se rinde (lo ves en GET /api/v1/webhook). Un aviso que no llega no toca el viaje: siempre puedes preguntar por su estado.

Versiones

La versión va en la URL (/api/v1/). Un cambio que rompa algo sale como /api/v2/ y se anuncia aquí con fecha; la v1 sigue viva mientras se anuncie lo contrario.