Autenticación
Cada llamada a /api/v1 lleva una clave de API en el encabezado Authorization. Es el único esquema: igual en esta guía, en la referencia y en los ejemplos.
HTTP
Authorization: Bearer ruta_ab12cd34ef56_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxUsala siempre desde tu servidor, nunca en una página web o una app pública: quien tenga la clave puede crear entregas a tu nombre.
Formato
| Clave | Entorno |
|---|---|
ruta_<prefijo>_<secreto> |
Real (producción): entregas reales del courier. |
ruta_test_<prefijo>_<secreto> |
De prueba: espacio aislado. |
El prefijo (12 caracteres) identifica la clave en el panel. Ruta guarda sólo una huella SHA-256 de la clave completa y la compara en tiempo constante: si la perdés, no se puede recuperar; rotala o creá otra.
Permisos (scopes)
| Permiso | Habilita |
|---|---|
deliveries:write |
Crear (una o en lote), corregir, cancelar y, con una clave de prueba, simular entregas. |
deliveries:read |
Consultar y listar entregas, la etiqueta PDF y las zonas. |
proof:read |
El comprobante de entrega con enlaces firmados de 5 minutos. |
Una llamada sin el permiso que necesita recibe 403 API_KEY_SCOPE_MISSING.
Claves de toda la empresa y claves de un comercio
- Una clave de la empresa ve todas sus entregas, cualquiera sea su origen (panel, app, CSV, formulario de comercio, integración u otra clave), y puede crear entregas para cualquier comercio de la empresa.
- Una clave de un comercio sirve para que cada tienda se integre sola: sólo crea entregas de ese comercio (si omitís
shipperIdse usa el suyo; otroshipperIdresponde404) y sólo ve las suyas. Cualquier otra entrega responde404, igual que una inexistente.
Ninguna clave ve entregas de otra empresa.
Rotar y revocar
- Rotar genera un secreto nuevo para la misma clave: el anterior deja de funcionar en ese instante. Para cambiar sin cortes, creá una segunda clave, actualizá tu sistema y revocá la primera.
- Revocar es definitivo: toda llamada con esa clave recibe
401 API_KEY_REVOKED.
Respuestas de autenticación
| Situación | Respuesta |
|---|---|
Falta Authorization: Bearer … (o está repetido) |
401 AUTHENTICATION_REQUIRED |
| Clave mal copiada, inexistente o reemplazada por una rotación | 401 API_KEY_INVALID |
| Clave revocada | 401 API_KEY_REVOKED |
| El plan de la empresa no incluye la API | 403 PLAN_FEATURE_UNAVAILABLE |
| La clave no tiene el permiso de la llamada | 403 API_KEY_SCOPE_MISSING |