Integración y migración

Ejemplos iniciales ejecutables

Node.js 24 y biblioteca estándar de Python 3. Configure OSRM_API_KEY en el entorno del servidor; nunca incluya secretos en el código del navegador. Los ejemplos realizan llamadas reales y consumen créditos normales.

SDK · API v1.1

Versión del SDK JavaScript en el repositorio: 1.1.0. Los SDK de JavaScript y Python admiten tareas asíncronas y endpoints de sandbox y metadatos. Instale JavaScript desde npm y Python desde PyPI.

Lista de verificación de migración

1. Valide el análisis de respuestas en el sandbox con datos de prueba antes de una llamada real de pago.
2. OSRM usa longitude,latitude. Los arrays point y matrix de /api/1 usan latitude,longitude. El adaptador de ejemplo muestra esta conversión.
3. Compare endpoint, perfil, campos de respuesta y límites del plan. La compatibilidad no garantiza un reemplazo directo completo de todos los proveedores.
4. Restrinja la clave real por servicio, origin/IP, caducidad y presupuesto del proyecto; después haga una prueba real de bajo volumen.
5. Use un período de transición de 1 o 24 horas, verifique la nueva clave y revoque los alias antiguos.

Tareas asíncronas

Operaciones: geocode_batch, matrix, optimize. POST /api/jobs devuelve 202 y un ID de tarea. El mismo Idempotency-Key y contenido devuelven la tarea existente; otro contenido devuelve 409.

curl -X POST https://osrmroute.com/api/jobs \
  -H "Authorization: Bearer $OSRM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: your-durable-operation-id-001" \
  -d '{"operation":"geocode_batch","input":{"queries":["Baku, Azerbaijan"]}}'

GET    /api/jobs/{id}
GET    /api/jobs/{id}?result=1
DELETE /api/jobs/{id}     # queued jobs only
States: queued → running → completed | failed | unknown
queued → cancelled | expired
Inputs/results: encrypted, 24-hour expiry
Unknown outcomes: investigate X-Request-Id; never auto-retry
Normal API entitlement, origin/IP policy and credits apply at dispatch.

Notificaciones firmadas

Cree un webhook HTTPS público, guarde el secreto de un solo uso y envíe webhook_id al crear una tarea. Verifique X-OSRM-Timestamp y X-OSRM-Signature con el cuerpo sin modificar.

signature = "sha256=" + HMAC_SHA256(secret, timestamp + "." + rawBody)
Reject timestamps outside ±300 seconds.
Compare signatures in constant time. Persist event IDs to deduplicate.
Callbacks contain event ID, job ID and state; fetch results with the API key.
Timeout: 10s. At most 5 attempts with backoff. No redirects.
Treat repeated delivery as normal; do not repeat a charge or job.

Errores, trazabilidad y metadatos de origen

Los errores mantienen error y añaden type, title, status, detail, code, request_id y retryable. Use X-Request-Id para soporte y seguimiento de solicitudes.

GET /api/source-metadata   # live key, info scope
Coverage/freshness/source evidence only; no inferred legal speed limit.
Trace retention: 7 days; service names, durations and status only.
No request coordinates, payload, raw keys or SQL text in traces.