Esta guía explica paso a paso cómo solicitar credenciales de acceso API a navieras (Maersk, CMA CGM, COSCO, Hapag-Lloyd, etc.) y sistemas externos similares, y cómo registrarlas en heyAtlas.
1. ¿Cuándo las necesitas?
Las herramientas de heyAtlas, como consulta de tarifas, seguimiento de contenedor/buque, obtención de tarifas y booking, se conectan a la API de la naviera en nombre de tu empresa. Esta conexión requiere las credenciales API que la naviera emite específicamente para ti. Sin credenciales, las herramientas relacionadas no pueden funcionar, y el asistente te pedirá los datos de conexión.
2. A quién pedir y cómo
- Tu primer contacto es el representante de cuenta o representante de ventas de tu empresa en la naviera.
- En la mayoría de las navieras grandes, la solicitud se deriva al equipo de integración/IT a través de tu representante.
- Indica en tu solicitud: el caso de uso (p. ej., consulta de tarifas, seguimiento de contenedores), el entorno que necesitas (prueba/producción) y tu código de cliente.
Plantilla de correo de solicitud para copiar y pegar
Asunto: Solicitud de acceso API / integración — [Nombre de la empresa], cliente n.º: [XXXX]
Hola,
En [Nombre de la empresa] gestionamos nuestras operaciones a través de nuestro asistente digital. ¿Podrían compartir las credenciales de acceso API asignadas a nosotros (nombre de usuario / clave API, URL de endpoint y código de cliente si aplica)? Nuestro caso de uso: [consulta de tarifas / seguimiento de contenedores / booking]. Nos gustaría recibir primero los datos del entorno de prueba y, tras la validación, las credenciales de producción.
Por favor, compartan contraseñas y claves por un canal seguro en lugar del cuerpo del correo.
Gracias.
3. Qué debes solicitar
| Ítem | Notas |
|---|
| Nombre de usuario API / Client ID | Identidad de inicio de sesión |
| Contraseña API / clave / Client Secret | Valor secreto — debe compartirse por un canal seguro |
| URL de endpoint | Las direcciones de prueba y producción pueden ser diferentes |
| Código de cliente | Obligatorio en algunas navieras |
| Entorno | Prueba (sandbox) o producción |
| Restricción de IP | Si la naviera aplica una allowlist de IP, deben añadirse las IP de heyAtlas |
4. Consejos específicos por naviera
- Navieras con portal de desarrolladores de autoservicio (p. ej., Maersk, CMA CGM, Hapag-Lloyd): puedes registrarte en el portal de desarrolladores de la naviera en nombre de tu empresa, crear una aplicación y generar tu propia clave. La aprobación puede tardar algunos días hábiles.
- Navieras con proceso manual: se completa un formulario a través de tu representante; el equipo de integración entrega las claves.
- No necesitas saber qué tipo de autenticación (API Key, OAuth2, etc.) usa cada naviera; la definición del sistema de heyAtlas aplica automáticamente el método correcto. Tu tarea es simplemente introducir de forma completa los datos que proporciona la naviera.
5. Introducir los datos en heyAtlas
- Abre Configuración → Credenciales en el portal (se requiere permiso de administrador de empresa).
- Selecciona el sistema correspondiente (naviera) y completa los campos proporcionados por la naviera.
- Puedes definir múltiples credenciales para el mismo sistema y marcar una como predeterminada (p. ej., distintos códigos de cliente).
- Después de guardar, verifica la conexión probando la herramienta relacionada a través del asistente.
Consulta también: Gestión de credenciales y Conexiones del sistema.
6. Seguridad
- Evita recibir contraseñas y claves como texto plano en el cuerpo del correo; prefiere un enlace de intercambio seguro.
- heyAtlas almacena las credenciales cifradas y nunca las muestra como texto plano en pantalla.
- Si sospechas una filtración, pide a la naviera que rote la clave y actualiza el nuevo valor en heyAtlas.
- Consulta también: Seguridad de credenciales.
7. Problemas comunes
- Errores 401 / 403: la contraseña puede estar mal escrita, vencida o la cuenta aún no activada. Vuelve a introducir los datos; si persiste, pide a tu representante que los verifique.
- Confusión entre prueba / producción: una clave de prueba no funcionará contra el endpoint de producción (o viceversa). Revisa qué datos de entorno se introdujeron.
- "Acceso concedido" pero nada funciona: algunas navieras activan suscripciones API por producto (p. ej., solo tracking); pregunta qué productos cubre tu suscripción.
- Bloqueo de IP: si la naviera aplica restricciones de IP, la IP desde la que llama heyAtlas debe incluirse en la allowlist; puedes solicitar los detalles de IP a nuestro equipo de soporte.
8. Obtener ayuda
Si el proceso se estanca, abre un ticket de soporte en Soporte → Mis Tickets; solo indica de qué naviera se trata y en qué paso estás bloqueado.
