Conectar Vizion: rastrear contenedores con hitos desde una API key emitida por ventas
La API Key de Vizion la emite el equipo de ventas de Vizion al abrir su cuenta: no hay registro autoservicio. Pegue la clave como único campo api_key en Integration, pruebe, mapee y active.
El conector de Vizion hace un solo trabajo: tracking de contenedores para drayage. Usted inicia un seguimiento (una referencia) con un número de contenedor, de conocimiento de embarque o de reserva, y el conector devuelve las actualizaciones de hitos de ese envío: cada hito lleva una hora planificada (una estimación, ETA) o una hora real (ATA), para que vea tanto lo esperado como lo que realmente ocurrió. Ese es todo el alcance: no trae pedidos, no crea envíos ni despachos, no reserva citas en terminal y no escribe nada de vuelta en Vizion. Una conexión trabaja con una API Key de Vizion.
Requisitos previos#
- Una cuenta de Vizion abierta con el equipo de ventas de Vizion, con acceso a la API incluido. La API Key la emite ventas de Vizion al abrir la cuenta: no hay página de registro autoservicio, así que si aún no tiene una clave, obtenerla de ventas de Vizion es el paso cero, antes de cualquier cosa en este sistema.
- La API Key en sí, tal como ventas de Vizion se la emitió. Conserve el mensaje o documento original en el que llegó: si la clave se pierde o es rechazada, solo ventas de Vizion puede reemitirla; no se puede consultar ni regenerar desde una página de ajustes.
- Al menos un número de contenedor, de conocimiento de embarque o de reserva que de verdad quiera rastrear, para contrastar los primeros hitos con un envío que conoce. Cuando tenga el código del transportista (SCAC) de ese envío, téngalo también listo: Vizion puede identificar al transportista automáticamente, pero su propia guía recomienda facilitar el código del transportista siempre que pueda.
Obtener credenciales#
- Contacte con ventas de Vizion y abra su cuenta de Vizion con acceso a la API, si aún no lo ha hecho. La API Key la emite ventas de Vizion como parte de la apertura de la cuenta.
- Reciba la API Key de ventas de Vizion. No hay registro autoservicio ni página de desarrolladores donde pueda crear una usted mismo: si una página o una persona le ofrece "registrar" una clave de Vizion fuera del proceso de apertura de la cuenta, esa no es la forma en que se emite esta clave.
- Copie la clave completa de una vez, exactamente como fue emitida (las claves de esta conexión empiezan con vizion_), y téngala lista para pegar. No la acorte y no le añada ningún prefijo.
- Solo hay esta credencial, y solo una dirección de Vizion que conocer: https://prod.vizionapi.com. No hay una dirección de sandbox separada que configurar: la clave que le emitieron se prueba y se ejecuta contra esa misma dirección.
Completar en Integration#
- Abra Integration → Marketplace → Vizion → Nueva conexión.
- api_key, obligatorio, Vizion API Key: pegue la clave completa que ventas de Vizion le emitió, que empieza con vizion_. Es el único campo de esta conexión. Es un campo de tipo contraseña y se guarda como secreto. Pegue solo la clave, exactamente como fue emitida: el sistema la envía por sí mismo como encabezado X-API-Key.
- Guarde la conexión y ejecute la prueba antes de cambiar cualquier otra cosa: con un solo campo, una prueba fallida trata de esa clave o de si la cuenta detrás de ella está activa, no de averiguar cuál de muchos campos está mal.
Probar la conexión#
Haga clic en Probar la conexión. Con su clave completada, la prueba envía una solicitud real de solo lectura: GET https://prod.vizionapi.com/references?limit=1, con su clave enviada como encabezado X-API-Key, con un tiempo límite de 12 segundos. Solo lista sus referencias activas, limitadas a una, así que no cambia nada en Vizion. Una respuesta aprobada vuelve como "Vizion authentication passed". Si la clave es rechazada, la prueba reporta HTTP_401. Si api_key está vacío, se detiene con MISSING_CREDENTIALS. Una solicitud que no puede completarse reporta CONNECTION_FAILED. Corrija la causa que indica el resultado y pruebe de nuevo.
Mapping / elegir plantilla#
Elija el mapping estándar de Vizion. Toma cada actualización de hitos que Vizion devuelve para una referencia y la alinea con el registro del contenedor que sigue aquí en el tracking de drayage, conservando la distinción que el propio Vizion hace: un hito marcado como planificado lleva una hora estimada (ETA), y uno que no lo está lleva la hora real (ATA). Tras aprobar la prueba, inicie el seguimiento de un contenedor, conocimiento de embarque o reserva que conozca y compare los primeros hitos (evento, lugar, y si cada hora es planificada o real) con lo que Vizion muestra para el mismo envío. Si coinciden, el mapping es correcto y puede activar.
Activar#
Tras activar, puede iniciar el seguimiento desde un número de contenedor, de conocimiento de embarque o de reserva, y la conexión mantiene las actualizaciones de hitos de esas referencias llegando aquí al tracking de drayage. Al iniciar una referencia se aplican dos reglas de Vizion: dé el conocimiento de embarque o el número de reserva, nunca ambos a la vez (una solicitud con los dos es rechazada), y añada el código del transportista (SCAC) siempre que lo tenga, porque la identificación automática del transportista es el recurso de reserva, no la vía preferida. Las actualizaciones de una referencia también pueden llegar como notificaciones enviadas, con la misma forma que las actualizaciones obtenidas, así que lo que ve aquí se mantiene coherente en ambos casos. Vigile las primeras referencias en Runs / Logs y compare algunos envíos con Vizion antes de dejar la conexión sin supervisión.
Lo que esta conexión no hace: no trae pedidos ni envíos de ningún otro sistema, no crea despachos ni cargas, no reserva ni cambia citas en terminal y no envía datos de seguimiento de vuelta a Vizion. Además, solo rastrea las referencias que usted inicia: no importa un historial de envíos creado en otro lugar.
Preguntas frecuentes#
La prueba falla con HTTP_401
Vizion rechazó la clave enviada. Las causas habituales son una clave recortada al copiarla, un carácter distinto del original emitido, o una clave que Vizion ya reemplazó o que aún no activó en su cuenta. Esta conexión envía la clave como encabezado X-API-Key, exactamente como especifica la documentación oficial, así que la forma de envío no es la variable: lo es el valor de la clave.
Compare la clave pegada carácter por carácter con el original que ventas de Vizion le emitió, corrija cualquier diferencia, guarde y pruebe de nuevo. Si la clave pegada coincide exactamente con el original y la prueba sigue reportando HTTP_401, contacte con ventas de Vizion y pida que confirmen que la clave está activa en su cuenta o que la reemitan: solo ventas de Vizion puede hacerlo, no hay ninguna página donde pueda restablecerla usted mismo.
La prueba se detiene con MISSING_CREDENTIALS
El campo api_key está vacío, así que no hay clave que enviar y la prueba no puede comprobar nada. Esta conexión tiene exactamente un campo, así que la credencial no puede estar escondida en otra parte.
Pegue la clave completa que ventas de Vizion le emitió en api_key, guarde la conexión y pruebe de nuevo. Si aún no tiene una clave, obténgala primero de ventas de Vizion: no hay página de registro para crear una.
No hay página de registro: ¿de dónde sale una API Key de Vizion?
Es así por diseño del lado de Vizion: la API Key no es autoservicio. Las claves las emite ventas de Vizion cuando se abre una cuenta de Vizion, así que deliberadamente no hay ninguna página pública que cree una, y este sistema tampoco puede generar una para usted.
Contacte con ventas de Vizion, abra la cuenta con acceso a la API y reciba la clave de ellos. Después vuelva a esta conexión, pegue la clave en api_key, guarde y pruebe. Si su empresa ya tiene una cuenta de Vizion, pregunte al colega que la abrió dónde quedó registrada la clave emitida, antes de abrir una segunda cuenta.
Iniciar el seguimiento falla con INVALID_REQUEST: conocimiento de embarque y reserva a la vez
Vizion valida los dos números como alternativas: una solicitud de seguimiento puede llevar un conocimiento de embarque o un número de reserva, pero una solicitud con ambos a la vez es rechazada por esa validación. Es una regla del lado de Vizion, no un fallo de ninguno de los números: cada uno por su lado es aceptable.
Inicie el seguimiento de nuevo con uno solo de los dos números: conserve el conocimiento de embarque o el número de reserva y quite el otro. Como alternativa, puede dar un número de contenedor como identificador. Añada también el código del transportista (SCAC) cuando lo tenga.
Iniciar el seguimiento falla con INVALID_REQUEST: ningún identificador
No se dio ningún identificador para la referencia. Vizion inicia el seguimiento desde un identificador (un número de contenedor (container_id), de conocimiento de embarque o de reserva) y, sin ninguno de los tres, no hay nada para lo que abrir una referencia.
Inicie el seguimiento de nuevo con uno de los tres números de ese envío, y recuerde la regla de combinación: si usa el conocimiento de embarque, no añada también el número de reserva. Añada el código del transportista (SCAC) cuando lo tenga, para que Vizion no tenga que identificar al transportista automáticamente.
La prueba falla con CONNECTION_FAILED, o vence a los 12 segundos
La solicitud de solo lectura a prod.vizionapi.com no pudo completarse a tiempo. Es un problema de alcance en el camino a la API de Vizion, o una lentitud temporal de Vizion: no es prueba de que la clave esté mal, porque la clave solo se juzga cuando la API responde de verdad.
Espere un poco y pruebe de nuevo sin cambiar la clave. Si sigue fallando, anote la hora del fallo de Runs / Logs cuando pida ayuda, y diga al soporte de Vizion que la solicitud va a https://prod.vizionapi.com con la clave en el encabezado X-API-Key, para que puedan revisar la misma ventana de su lado.
La hora de un hito parece incorrecta: está en el futuro, o cambió
Ese hito es muy probablemente uno planificado. En los datos de Vizion, un hito marcado planned=true lleva una hora estimada (una ETA), que por naturaleza está en el futuro y se revisa a medida que el envío avanza; un hito con planned=false lleva la hora real (una ATA), que queda fija una vez que ocurre. Que la estimación cambie es que los datos funcionan como deben, no que el seguimiento esté mal.
Lea el hito junto con su marca de planificado antes de actuar sobre la hora: planifique alrededor de las horas planificadas (ETA) y trate solo las horas reales (ATA) como historial. Si una hora marcada como real no coincide con lo que el transportista o la terminal muestran para el mismo evento, anote la referencia y el evento cuando pida a soporte de Vizion que lo revise.