Integraciones EDI

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

Recursos relacionados

Referencia de la API de licitaciones — los puntos finales REST referenciados en la tabla de mapeo anterior
Descripción general de webhooks — suscríbase a los eventos de ciclo de vida que confirman cada cambio de estado

​Guía de flujo de trabajo de la API (mapeo EDI → Alvys)

​Principios de diseño

​Solución de problemas

​Recursos relacionados

Guía de flujo de trabajo de la API (mapeo EDI → Alvys)

Principios de diseño

Solución de problemas

Recursos relacionados