Autenticación y permisos
Tokens de API
Tu integración se autentica con un token de API enviado como token bearer:
Authorization: Bearer atk_live_9fK2…
- Crea tokens en el panel: Configuración → Desarrolladores para la empresa (dueños y administradores) o Portal → Desarrolladores para la cuenta de un comercio (administradores del comercio).
- El token se muestra una sola vez. Antivio solo guarda un hash; si lo pierdes, revócalo y crea otro.
- Los tokens vencen (por defecto a los 365 días, como máximo 730) y se pueden revocar en cualquier momento; un token revocado deja de funcionar en su siguiente petición.
- Envía los tokens solo desde tus servidores. Nunca en un navegador, una app móvil, una URL o un log.
- Un token se ve así:
atk_live_<43 caracteres>_<6 caracteres>. La última parte es un dígito de control: un error de tipeo se rechaza de inmediato y los escáneres de secretos reconocen un token filtrado.
Modo real y de prueba
atk_live_… | atk_test_… | |
|---|---|---|
| Envíos que ve | todos los de su cuenta | solo los de sandbox |
| Envíos que crea | reales (de sandbox mientras tu empresa está en revisión) | siempre de sandbox |
Simulador (/v1/sandbox/…) | rechazado | permitido |
| Endpoints de webhook que ve | reales y de prueba | solo de prueba |
| Peticiones por minuto | 1000 | 100 |
Los envíos de sandbox son gratis, nunca llegan a un conductor y no envían mensajes a los destinatarios. Ver Sandbox y simulador.
Permisos (scopes)
Cada token tiene los permisos que elegiste; todo lo demás se rechaza con 403 authz.forbidden.
| Permiso | Permite al token |
|---|---|
shipments:read | listar y leer envíos, su historial y etiquetas, y las ubicaciones de la cuenta |
shipments:write | además crear, cambiar, confirmar y cancelar envíos y ubicaciones, imprimir lotes de etiquetas |
rates:read | cotizar y leer los niveles de servicio |
webhooks:read | listar los endpoints de webhook y sus entregas |
webhooks:write | además crear, cambiar, probar y eliminar endpoints, rotar su secreto, reenviar entregas |
Un token nunca tiene más poder que la persona que lo creó: solo puedes dar permisos que tu rol
tiene, y en cada petición el token se limita a lo que el rol actual de esa persona permite
(403 authz.forbidden para lo demás). Si esa persona sale de la empresa o de la cuenta del
comercio, o su cuenta se desactiva, el token deja de funcionar (403 auth.token_owner_inactive).
Tokens de empresa y de comercio. El token de un comercio (creado en el portal) solo llega a
los envíos, ubicaciones y webhooks de ese comercio, sin importar qué cabeceras envíe. Un token de
la empresa llega a los de la empresa; al crear una ubicación o un envío indica de qué cliente es
con customer_account_id.
Qué puede llamar un token
Los tokens solo llegan a la API pública. Cualquier otra ruta responde
403 auth.api_token_not_allowed, tenga el token los permisos que tenga.
| Método | Ruta |
|---|---|
| GET, POST | /v1/shipments |
| GET, PATCH | /v1/shipments/{id} |
| POST | /v1/shipments/{id}/confirm, /v1/shipments/{id}/cancel |
| GET | /v1/shipments/{id}/events, /v1/shipments/{id}/label |
| POST | /v1/labels/batches |
| GET | /v1/labels/{id} |
| GET, POST | /v1/locations |
| GET, PATCH, DELETE | /v1/locations/{id} |
| GET | /v1/locations/geocode, /v1/locations/reverse-geocode |
| POST | /v1/quotes |
| GET | /v1/service-levels, /v1/service-levels/{id} |
| GET | /v1/webhook-event-types |
| GET, POST | /v1/webhook-endpoints |
| GET, PATCH, DELETE | /v1/webhook-endpoints/{id} |
| POST | /v1/webhook-endpoints/{id}/rotate-secret, /v1/webhook-endpoints/{id}/test |
| GET | /v1/webhook-endpoints/{id}/deliveries |
| POST | /v1/webhook-endpoints/{id}/deliveries/replay |
| GET | /v1/webhook-deliveries/{id} |
| POST | /v1/webhook-deliveries/{id}/replay |
| POST | /v1/sandbox/shipments/{id}/advance (tokens de prueba) |
Gestionar tokens y revelar el secreto de un endpoint se hace en el panel, por una persona, nunca con un token.
Todas las guías