Skip to content

👋 Bienvenido a Automate External Tms Loads

Descripción General

GLT, una empresa de logística en Norteamérica, gestiona sus operaciones de envío a través de procedimientos denominados LOADs en la plataforma SalesForce. Una de las fuentes de información para estos LOADs es la plataforma Primus, que envía correos electrónicos con Bills of Lading (BOLs) adjuntos. Históricamente, este proceso ha sido manual, requiriendo que los operarios de GLT procesen cada correo para crear y actualizar los LOADs correspondientes.

"Automate External Tms Loads" es un microservicio que aborda esta operativa. Se encarga de monitorear la bandeja de entrada, leer los correos de Primus, extraer los BOLs adjuntos y orquestar una serie de pasos para automatizar completamente la gestión de los LOADs.

Es importante destacar que este servicio opera de forma interna dentro de un clúster de GCP (Google Cloud Platform). No está expuesto públicamente a internet y funciona como una API privada, comunicándose con otros servicios dentro de la misma red segura. Por esta razón, no implementa capas de seguridad de cara al exterior, ya que su acceso está restringido a nivel de infraestructura.

📘 Esta guía te mostrará cómo utilizar la API de IQ Invoice Server paso a paso.

🎯 Objetivo

El objetivo principal de este microservicio es eliminar la intervención manual en el procesamiento de BOLs provenientes de Primus. Al automatizar la creación y actualización de LOADs en SalesForce, se busca reducir el tiempo de operación, minimizar los errores humanos y agilizar el flujo de trabajo del equipo de logística de GLT.

🏗️ Arquitectura

El servicio es un componente dentro de una Arquitectura de Microservicios. Su diseño interno se basa en patrones de software bien definidos para organizar su lógica y comunicación. Principalmente, implementa los patrones de Orquestación de Servicios y Arquitectura Orientada a Eventos.

A continuación, se describen estos patrones y cómo se aplican en el microservicio:

  • Orquestación de Servicios: Este es el patrón central del microservicio. En lugar de tener una comunicación descentralizada, el servicio actúa como un orquestador que dirige el flujo de trabajo de principio a fin. El endpoint /fetch-dataload contiene la lógica que llama secuencialmente a otros servicios (Graph, Primus, Vertex AI, entre otros) en un orden predefinido para procesar un BOL. Este enfoque centraliza la lógica del proceso de negocio, facilitando su comprensión y mantenimiento.

  • Arquitectura Orientada a Eventos (Event-Driven): El microservicio no depende de una llamada externa para iniciar su trabajo. Utiliza un planificador de tareas (scheduler) que emite un evento basado en tiempo (cada N minutos). El servicio escucha este evento y desencadena automáticamente el proceso de orquestación. Este patrón le permite operar de manera autónoma y proactiva.

Dentro de su implementación, el servicio también incluye características importantes:

  • Capa de Transformación de Datos: Para mantener un bajo acoplamiento con los servicios externos, el microservicio cuenta con una capa de mapeo (services/mapper). Su responsabilidad es convertir los datos recibidos de las APIs externas a los modelos de datos internos de la aplicación, y viceversa.

  • Diseño Resiliente y Asíncrono: La comunicación con los servicios externos se realiza de forma asíncrona (asyncio) para no bloquear el servidor y gestionar múltiples operaciones de red eficientemente. Además, se incorporan mecanismos de resiliencia, como políticas de reintentos automáticos, para manejar fallos temporales en los servicios externos.

Servicios Externos

Para completar su flujo, la automatización interactúa con un ecosistema de servicios externos para cumplir su flujo de negocio, incluyendo:

  • Graph API: Utilizada para conectar con la cuenta de correo y descargar los archivos BOL adjuntos.
  • Primus API: Para obtener los datos iniciales del booking asociados a un BOL.
  • Vertex AI (GCP): Utiliza modelos multimodales (Gemini) para extraer información estructurada desde los documentos PDF.
  • CRM API (Salesforce): Sistema de gestión donde se crean y actualizan las entidades finales (Cuentas, Contactos, Loads, etc).
  • Megatron API: Servicio interno utilizado para realizar cálculos especializados, como los linear feet.

🔴 Endpoint

La API expone un único endpoint para iniciar el proceso de procesamiento de BOLs.

  • POST /fetch-dataload

Este endpoint recibe una fecha de inicio y desencadena el flujo completo de lectura de correos, procesamiento de documentos y creación de entidades en los sistemas externos.

💻 Tecnologías

La API está construida utilizando las siguientes tecnologías:

  • Python 3.11: Lenguaje de programación base.
  • FastAPI: Framework web para la construcción de la API.
  • Pydantic: Para la validación y serialización de datos.
  • Vertex AI SDK: Para la integración con los modelos de IA de Google Cloud.
  • Docker: Para la containerización de la aplicación.
  • Kubernetes: Para la orquestación y despliegue en los diferentes entornos.
  • Pipenv: Para la gestión de dependencias de Python.