> ## Documentation Index > Fetch the complete documentation index at: https://docs.alvys.com/llms.txt > Use this file to discover all available pages before exploring further. # Integraciones EDI > Conecte proveedores de EDI externos y construya integraciones TMS bidireccionales mapeando las transacciones EDI 204, 214, 210 y 990 a las API REST de licitaciones de Alvys y a los eventos webhook. Esta guía muestra a los proveedores de EDI, proveedores de middleware y clientes avanzados cómo construir integraciones bidireccionales entre una conexión EDI externa y el TMS de Alvys. Explica cómo traducir las transacciones EDI clásicas (204, 990, 214, 210) en llamadas REST de Alvys y eventos de ciclo de vida impulsados por webhooks, y describe los patrones de integración necesarios para construir integraciones EDI confiables y de grado de producción con Alvys. Alvys proporciona un conjunto de API REST públicas y webhooks impulsados por eventos diseñados para ayudar a proveedores de EDI externos, plataformas de middleware y clientes a construir integraciones EDI personalizadas con el TMS de Alvys. Estas interfaces le permiten, de forma programática: * Crear y gestionar licitaciones entrantes (EDI 204) a través de REST * Recibir actualizaciones del ciclo de vida del envío casi en tiempo real (EDI 214) vía webhooks * Obtener detalles de facturas después de la presentación (EDI 210) vía REST + eventos de facturación Estas API están destinadas a permitir que los socios traduzcan entre las transacciones EDI clásicas (204/214/210/990/997) y los objetos y flujos de trabajo nativos de Alvys (licitaciones, actualizaciones de licitaciones, cancelaciones, flujos de trabajo de aceptación, eventos de estado y facturas). **Obtener acceso a la API** * Los clientes existentes de Alvys pueden conseguir acceso a la API contactando a su representante de cuenta. * Los proveedores independientes de software (ISV) deben ponerse en contacto con el equipo de asociación de Alvys. ## Guía de flujo de trabajo de la API (mapeo EDI → Alvys) Esta sección mapea los flujos de trabajo EDI comunes a los puntos finales correspondientes de la API pública de Alvys. Está destinada a proveedores de EDI y proveedores de middleware que traducen transacciones EDI entrantes y salientes en operaciones de licitación y envío nativas de Alvys. Utilice esta guía como tabla de decisiones cuando implemente integraciones: * Identifique la transacción EDI o la intención comercial (por ejemplo, nueva licitación, actualización, cancelación, aceptación). * Llame al punto final REST apropiado para expresar esa intención a Alvys. * Confíe en los webhooks de Alvys para confirmar el resultado autorizado de la operación. * Emita EDI saliente (990/214/210/997) solo después de que se confirme el cambio de estado correspondiente en Alvys. ### Principios de diseño * **REST expresa la intención; los webhooks confirman el resultado.** Una respuesta REST exitosa indica que se recibió la solicitud, no que el flujo de trabajo esté completo. * **Espere reintentos y duplicados.** Las redes EDI reenvían con frecuencia las transacciones. Siempre use Idempotency-Key para POST no seguros y deduplique las entregas de webhooks por EventId. * **Modele el estado explícitamente.** Las licitaciones pueden estar pendientes, aceptadas, rechazadas, canceladas, expiradas o esperando la aprobación de una actualización. No asuma transiciones de estado inmediatas. * **Trate a Alvys como el sistema de registro.** Cuando surjan conflictos, reconcilie consultando la licitación (GET /tenders/:tenderId) y respetando el estado devuelto y el ETag. En el cuadro que figura a continuación se describe el mapeo canónico entre los flujos de trabajo EDI y las operaciones de la API pública de Alvys, junto con importantes consideraciones de integración para cada paso. | Flujo de trabajo EDI (común) | Dirección típica | Cuándo llamar (disparador) | Punto(s) final(es) de la API pública de Alvys | Propósito principal en Alvys | Notas de integración (idempotencia / concurrencia) | | ------------------------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **204\_00 — Nueva licitación de carga** | Remitente → Transportista (a través del proveedor) | Recibe un nuevo 204 y quiere que sea representado como una licitación entrante en Alvys | `POST /api/p/v{version}/tenders` | Crear un registro de licitación entrante | Utilice `Idempotency-Key` para prevenir creaciones duplicadas (los reenvíos EDI son comunes). Valide los campos requeridos antes de llamar. | | **204\_04 — Cambio / actualización de licitación** | Remitente → Transportista | Recibe una actualización 204 (citas, paradas, tarifa, equipo, referencias) para una licitación existente | `POST /api/p/v{version}/tenders/update` | Presentar un conjunto de cambios contra una licitación existente | Trate las actualizaciones como “pendientes” hasta que se apliquen/acepten (dependiente de la implementación). Use `Idempotency-Key` para un reintento seguro. Si la ruta requiere concurrencia, incluya `If-Match` con el `ETag` actual. | | **204\_01 — Cancelar licitación** | Remitente → Transportista | Recibe una cancelación para una licitación existente | `POST /api/p/v{version}/tenders/cancel` | Solicitar la cancelación de una licitación | Use `Idempotency-Key` para evitar solicitudes de cancelación duplicadas. Si la cancelación debe estar protegida por concurrencia, incluya `If-Match` con el `ETag` actual. | | **990 — Aceptar licitación (aceptación del transportista)** | Transportista → Remitente | La aceptación del transportista ocurre en Alvys y usted necesita reflejar/confirmar la aceptación en su integración | `POST /api/p/v{version}/tenders/{tenderId}/accept` | Marcar la licitación como aceptada (opcionalmente adjuntar/vincular a una carga) | **Requiere** el `ETag` actual + `If-Match` (concurrencia optimista) si está habilitado. Un proveedor solo debe “conducir” la aceptación a través de la API si el flujo de trabajo está diseñado para ello (frente a que la aceptación ocurra solo en la interfaz de usuario). | | **990 — Rechazar licitación** | Transportista → Remitente | El transportista rechaza la licitación y usted debe registrar esa disposición | `POST /api/p/v{version}/tenders/{tenderId}/reject` | Marcar la licitación como rechazada con un motivo | Típicamente **requiere** `ETag` + `If-Match`. Asegúrese de que el mapeo del motivo de rechazo coincida con las expectativas de la guía de implementación del remitente. | | **Aceptación 204\_04 — Aplicar/aceptar actualizaciones pendientes** | Transportista → Remitente | Una licitación tiene actualizaciones pendientes que deben ser aplicadas o aceptadas | `POST /api/p/v{version}/tenders/{tenderId}/accept-updates` | Aplicar el/los conjunto(s) de cambios pendientes a la licitación | Típicamente **requiere** `ETag` + `If-Match`. Si las actualizaciones son parciales/seleccionadas, asegúrese de pasar los identificadores de cambio previstos (si es compatible). | | **Confirmación 204\_01 — Aceptar/confirmar cancelación** | Transportista → Remitente | Se solicita la cancelación y debe ser confirmada/aceptada en el flujo de trabajo | `POST /api/p/v{version}/tenders/{tenderId}/accept-cancel` | Confirmar la cancelación de la licitación (dependiente del flujo de trabajo) | Típicamente **requiere** `ETag` + `If-Match`. Solo aplicable si la cancelación es un flujo de trabajo de dos pasos (solicitud → confirmación). | | **Consulta — Obtener licitación por ID** | Utilidad interna del proveedor | Necesita el estado canónico completo de la licitación (o reconciliar después de reintentos/conflictos) | `GET /api/p/v{version}/tenders/{tenderId}` | Recuperar la licitación (opcionalmente con inclusiones) | Capture el `ETag` para cambios de estado posteriores (`If-Match`). Use `If-None-Match` para sondeos/reconciliaciones compatibles con caché si se admite. | | **Consulta — Buscar licitaciones** | Utilidad interna del proveedor | Necesita encontrar licitaciones por referencia externa, estado o ventana de tiempo | `POST /api/p/v{version}/tenders/search` | Buscar licitaciones usando filtros enriquecidos | Prefiera buscar por su **identificador de licitación externo** para correlacionar EDI → Alvys. Útil para trabajos de reproducción/recuperación y paneles operativos. | ### Solución de problemas * Verifique su `client_id`, `client_secret` y `audience` * Asegúrese de que los alcances estén correctamente asignados en **API Access** en el Portal de administración * Valide que el cliente esté activo y no haya expirado * Use solo tipos de contenido compatibles: `application/json` o `application/x-www-form-urlencoded` * Para soporte técnico: [support@alvys.com](mailto:support@alvys.com) ## Recursos relacionados * [Referencia de la API de licitaciones](/reference/tenders/get-tender) — los puntos finales REST referenciados en la tabla de mapeo anterior * [Descripción general de webhooks](/reference/webhooks/overview) — suscríbase a los eventos de ciclo de vida que confirman cada cambio de estado