Envíe cargas a un transportista de Alvys con la API de licitaciones

Use la API de licitaciones para enviar cargas desde su sistema a un transportista que opera en Alvys. Usted envía cada carga como una licitación en JSON. El transportista acepta la licitación, Alvys crea una carga a partir de ella y usted sigue esa carga con webhooks. No necesita una red EDI ni una identidad X12. Si ya intercambia EDI 204, los mismos endpoints transportan los mismos datos como JSON. Esta guía tiene dos lectores:

Socio: el TMS, corredor o sistema de remitente que envía las licitaciones.
Administrador del transportista: la persona que configura la conexión en la cuenta de Alvys del transportista.

Cada sección indica a qué lector está dirigida.

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.

Lo que necesita

Para el socio y el administrador del transportista.

Elemento	Quién lo proporciona	Notas
Credenciales de cliente de la API	Administrador del transportista	Se crean en la cuenta del transportista en Admin → API Access. Usted llama a la API en nombre del transportista. Consulte Autenticarse con la API pública de Alvys.
Seis ID de enrutamiento	Acordados por ambas partes	ISA ID del remitente y del receptor, calificador del ISA ID y GS ID. Consulte Enrutamiento de transportista y cliente.
SCAC del transportista	Administrador del transportista	Obligatorio en cada licitación.
Un endpoint HTTPS	Socio	Recibe los eventos de webhook. Consulte Descripción general de webhooks.

El plan del transportista debe incluir acceso a la API pública. Si no lo incluye, todas las llamadas devuelven 402.

Alcances

La credencial determina los alcances. El campo scope de la solicitud de token no puede reducirlos. Pida al administrador del transportista que asigne estos alcances:

Alcance	Le permite
`tender:create`	Crear, actualizar y cancelar licitaciones
`tender:read`	Obtener y buscar licitaciones
`tender:update`	Aceptar, rechazar, aceptar cambios y aceptar cancelaciones. Solo es necesario si usted acepta licitaciones en nombre del transportista.
`load:read`	Obtener la carga y listar sus documentos
`load:update`	Cargar documentos a la carga
`webhook:create`, `webhook:read`, `webhook:update`	Crear y administrar su suscripción de webhook
`subsidiary:read`	Listar las subsidiarias para delimitar el alcance de su webhook
`customer:read`	Buscar ubicaciones. Solo es necesario si usted acepta licitaciones a través de la API.

Actualizar y cancelar una licitación requiere tender:create, no tender:update.

Todas las rutas siguientes son relativas a la URL base https://integrations.alvys.com. Los endpoints de licitaciones, webhooks, ubicaciones y subsidiarias usan v1.0. Los endpoints de cargas usan v2.0. Consulte Versionado.

Enrutamiento de transportista y cliente

Para el socio y el administrador del transportista. Cada licitación lleva seis ID de enrutamiento. Indican a Alvys a qué conexión de transportista pertenece la licitación y, a través de esa conexión, para cuál de los clientes del transportista es la carga.

Campo de la licitación	Significado
`SenderIsaIdQualifier`, `SenderIsaId`	Su ISA ID y su calificador
`SenderGsId`	Su GS ID
`ReceiverIsaIdQualifier`, `ReceiverIsaId`	El ISA ID del transportista y su calificador
`ReceiverGsId`	El GS ID del transportista

El transportista almacena esos mismos seis valores en una conexión en Alvys. Alvys los compara como cadenas exactas. Cuentan las mayúsculas, los espacios y el relleno. ZZ y zz son valores distintos. Una conexión es de uno de dos tipos:

Conexión por cliente. La conexión nombra a un cliente. Toda licitación que coincida con sus seis ID se asigna a ese cliente.
Conexión general (catch-all). Una sola conexión recibe licitaciones de cualquier remitente. Alvys asigna cada licitación al cliente cuyo Company Number sea igual al SenderGsId de la licitación. Exactamente un cliente debe tener ese Company Number.

Alvys busca una conexión en este orden:

Una conexión cuyos seis ID sean todos iguales a los seis ID de la licitación.
Si no existe, la conexión general del transportista.
Si tampoco existe, la solicitud falla con Integration is missing.

Otros identificadores:

ShipmentId es su identificador de la licitación. Alvys lo usa para encontrar la licitación cuando usted envía una actualización o una cancelación. Se convierte en el número de orden de la carga.
SCAC se almacena en la licitación. No enruta la licitación.
Los valores IdCode de las paradas no seleccionan una ubicación. Alvys hace coincidir las ubicaciones de las paradas por dirección y nombre.

Sin EDI: elija los ID de enrutamiento

Para el socio y el administrador del transportista. No necesita una identidad X12. Acuerde seis valores con el transportista y el transportista los ingresa en la conexión. Use el calificador ZZ (definido mutuamente) y ID cortos, en mayúsculas y sin espacios.

Campo de la licitación	Ejemplo	Etiqueta en la conexión del transportista
`SenderIsaIdQualifier`	`ZZ`	Customer ISA ID Qualifier
`SenderIsaId`	`ACMESHIP`	Customer ISA ID
`SenderGsId`	`ACMESHIP`	Customer GS ID
`ReceiverIsaIdQualifier`	`ZZ`	Your ISA ID Qualifier
`ReceiverIsaId`	`FASTCARRIER`	Your ISA ID
`ReceiverGsId`	`FASTCARRIER`	Your GS ID

Si el transportista usa una conexión general, SenderGsId debe ser igual al Company Number del cliente en Alvys. Si ningún cliente tiene ese Company Number, o si lo tiene más de uno, la licitación se rechaza.

Con EDI: reutilice sus ID X12

Para socios que ya intercambian EDI 204. Envíe sus ISA ID y GS ID reales y sus calificadores. Los endpoints JSON se corresponden con los códigos de propósito del 204:

EDI 204	API de licitaciones
Original	`POST /api/p/v1.0/tenders`
Cambio	`POST /api/p/v1.0/tenders/update`
Cancelación	`POST /api/p/v1.0/tenders/cancel`

Diferencias con el X12 clásico sobre VAN o AS2:

	X12 sobre VAN o AS2	API de licitaciones
Transporte	Archivo EDI a través de su red	HTTPS y JSON
Acuse de recibo funcional	997	Ninguno. La respuesta HTTP confirma la recepción.
Tipo de parada	Código de motivo de parada S5	`Type` es `Pickup` o `Delivery`. Los códigos X12 en `Type` no se traducen.
Aceptar o rechazar	990	Webhook `tender.accepted` o `tender.rejected`
Estado del envío	214	Webhooks `load.status.changed` y `tender.stop.*`

Alvys encuentra la conexión solo por los seis ID de enrutamiento. No revisa el transporte de la conexión. Si sus ID coinciden con una conexión que usa un transporte EDI, como AS2, SFTP o una VAN, Alvys envía respuestas EDI, como los 990, por esa conexión, igual que para una licitación EDI. Pida al transportista que configure una conexión separada con el transporte Public API para su tráfico de API, con ID de enrutamiento que ninguna conexión EDI use.

Lista de verificación de configuración del transportista

Para el administrador del transportista.

Cree las credenciales de cliente de la API para el socio en Admin → API Access y asigne los alcances indicados arriba.
Cree el cliente para el que son las cargas. Si usa una conexión general, establezca el Company Number del cliente con el SenderGsId acordado.
Vaya a Manage → EDI & Visibility y agregue una conexión para el socio:
- Establezca el transporte en Public API.
- Ingrese los seis ID de enrutamiento.
- Elija el cliente, o conviértala en una conexión general.
- Elija la subsidiaria a la que pertenecen las cargas.
Decida cómo se aceptan las licitaciones. Para aceptarlas automáticamente, active Auto-Accept EDI Tenders en el cliente. Si usa flotas, establezca también la flota predeterminada del cliente.
Envíe al socio los seis ID de enrutamiento y su SCAC.

Una conexión con el transporte Public API no envía nada de vuelta por EDI. El socio recibe cada resultado mediante webhooks o consultando la API.

Flujo de trabajo

Para el socio.

Paso	Solicitud	Lo que obtiene
1	`POST /oauth/token`	Un token de portador
2	`POST /api/p/v1.0/webhooks`	Una suscripción y su secreto de firma
3	`POST /api/p/v1.0/tenders`	`201` y la ubicación de la licitación
4	Webhook `tender.created`, o `POST /api/p/v1.0/tenders/search`	El id de la licitación
5	El transportista acepta, o `POST /api/p/v1.0/tenders/{tenderId}/accept`	`tender.accepted` con el número de carga
6	`GET /api/p/v2.0/loads?orderNumber={ShipmentId}`	La carga
7	`POST /api/p/v1.0/tenders/update` o `/cancel`	Una licitación modificada o cancelada
8	Webhooks y `GET /api/p/v2.0/loads/{loadNumber}/documents`	Actualizaciones de estado y documentos

Una licitación pasa por estos estados:

1. Obtenga un token

Solicite un token con el flujo de credenciales de cliente y envíelo como Authorization: Bearer <token> en cada llamada. Guarde el token en caché hasta que expire. Consulte Autenticarse con la API pública de Alvys.

curl --request POST \
  --url https://auth.alvys.com/oauth/token \
  --header 'Content-Type: application/json' \
  --data '{
    "client_id": "<client_id>",
    "client_secret": "<client_secret>",
    "audience": "https://api.alvys.com/public/",
    "grant_type": "client_credentials"
  }'

2. Suscríbase a los eventos de licitaciones y cargas

Cree la suscripción antes de enviar la primera licitación, para no perder tender.created.

Liste cada evento por su nombre exacto. No hay comodines.
Envíe exactamente uno de SubsidiaryIds o AllSubsidiaries. SubsidiaryId está obsoleto. Obtenga los id de subsidiaria en List subsidiaries.
Una suscripción puede contener hasta 50 eventos.

POST /api/p/v1.0/webhooks
Authorization: Bearer <token>
Content-Type: application/json

{
  "Name": "Tender sync",
  "Url": "https://tms.example.com/alvys/webhooks",
  "AllSubsidiaries": true,
  "IncludePreviousAttributes": false,
  "Events": [
    "tender.created",
    "tender.accepted",
    "tender.rejected",
    "tender.cancelled",
    "tender.change.created",
    "tender.change.accepted",
    "load.status.changed",
    "load.document.uploaded",
    "load.document.deleted"
  ]
}

La respuesta 201 incluye Secret. Guárdelo. Las llamadas de obtención y listado lo devuelven enmascarado. Úselo para verificar las firmas.

{
  "Id": "5b1f0c3e-8a2d-4f6b-9e71-2c4d8a0b6f13",
  "Name": "Tender sync",
  "Url": "https://tms.example.com/alvys/webhooks",
  "Secret": "whsec_...",
  "AllSubsidiaries": true,
  "SubsidiaryIds": [],
  "Events": ["tender.created", "tender.accepted", "..."],
  "IncludePreviousAttributes": false
}

La respuesta anterior está abreviada. Consulte Create webhook subscription para ver todos los campos.

3. Cree una licitación

POST /api/p/v1.0/tenders crea una licitación en la cuenta del transportista. La licitación válida más pequeña tiene los ID de enrutamiento, SCAC, ShipmentId y dos paradas:

POST /api/p/v1.0/tenders
Authorization: Bearer <token>
Content-Type: application/json

{
  "SenderIsaIdQualifier": "ZZ",
  "SenderIsaId": "ACMESHIP",
  "SenderGsId": "ACMESHIP",
  "ReceiverIsaIdQualifier": "ZZ",
  "ReceiverIsaId": "FASTCARRIER",
  "ReceiverGsId": "FASTCARRIER",
  "SCAC": "FSTC",
  "ShipmentId": "SHP-100234",
  "Stops": [
    {
      "Type": "Pickup",
      "Entity": {
        "Name": "Acme DC Dallas",
        "Street": "100 Main St",
        "City": "Dallas",
        "State": "TX",
        "PostalCode": "75201",
        "CountryCode": "US"
      },
      "ScheduledArrivalStart": "2026-11-10T08:00:00-06:00"
    },
    {
      "Type": "Delivery",
      "Entity": {
        "Name": "Acme Store 12",
        "Street": "200 Oak Ave",
        "City": "Houston",
        "State": "TX",
        "PostalCode": "77002",
        "CountryCode": "US"
      },
      "ScheduledArrivalStart": "2026-11-11T14:00:00-06:00"
    }
  ]
}

Una llamada exitosa devuelve 201 Created con un cuerpo vacío. El encabezado Location apunta a la nueva licitación:

HTTP/1.1 201 Created
Location: https://integrations.alvys.com/api/p/v1.0/tenders/8d0c3b8e-2f51-4c1e-9a77-0e5b6a1f9c42

Una licitación más completa agrega equipo, peso, tarifa, referencias y notas:

{
  "SenderIsaIdQualifier": "ZZ",
  "SenderIsaId": "ACMESHIP",
  "SenderGsId": "ACMESHIP",
  "ReceiverIsaIdQualifier": "ZZ",
  "ReceiverIsaId": "FASTCARRIER",
  "ReceiverGsId": "FASTCARRIER",
  "SCAC": "FSTC",
  "ShipmentId": "SHP-100234",
  "PoNumber": "PO-55821",
  "Rate": 1850.00,
  "ExpirationDate": "2026-11-09T17:00:00-06:00",
  "QtyPallets": "22",
  "Weight": "38000",
  "WeightUnitCode": "L",
  "Equipment": { "Length": "53", "Type": "TV" },
  "Entities": [
    { "Type": "Shipper", "Name": "Acme Corp", "City": "Dallas", "State": "TX" },
    {
      "Type": "BillTo",
      "Name": "Acme Corp AP",
      "Street": "1 Finance Way",
      "City": "Dallas",
      "State": "TX",
      "PostalCode": "75201",
      "CountryCode": "US",
      "Email": "ap@acme.example"
    }
  ],
  "References": [
    { "Qualifier": "BM", "Id": "BOL-778812", "Type": "BOL Number" }
  ],
  "Notes": ["Driver must check in at gate 3"],
  "Stops": [
    {
      "Type": "Pickup",
      "SequenceNumber": "1",
      "Entity": {
        "Name": "Acme DC Dallas",
        "Street": "100 Main St",
        "City": "Dallas",
        "State": "TX",
        "PostalCode": "75201",
        "CountryCode": "US",
        "Phone": "2145550100"
      },
      "ScheduledArrivalStart": "2026-11-10T08:00:00-06:00",
      "ScheduledArrivalEnd": "2026-11-10T10:00:00-06:00",
      "Orders": [
        { "Quantity": "22", "Weight": "38000", "WeightUnitCode": "L", "PoNumber": "PO-55821", "Description": "Packaged goods" }
      ],
      "References": [
        { "Qualifier": "PU", "Id": "PU-9981", "Type": "Pickup Number" }
      ],
      "Notes": ["Live load"]
    },
    {
      "Type": "Delivery",
      "SequenceNumber": "2",
      "Entity": {
        "Name": "Acme Store 12",
        "Street": "200 Oak Ave",
        "City": "Houston",
        "State": "TX",
        "PostalCode": "77002",
        "CountryCode": "US"
      },
      "ScheduledAppointment": "2026-11-11T14:00:00-06:00",
      "References": [
        { "Qualifier": "DO", "Id": "DEL-4471", "Type": "Delivery Number" }
      ]
    }
  ]
}

Los códigos de calificador y de unidad de este ejemplo (L, TV, BM, PU, DO) son valores X12 comunes. Alvys no los valida. Reglas para el cuerpo de la licitación:

Envíe al menos dos paradas. El Type de cada parada es Pickup o Delivery.
Incluya al menos una recogida y una entrega cuyo Entity tenga ciudad y estado. Si no, Alvys igualmente devuelve 201, pero la licitación no se puede aceptar hasta que el transportista la corrija en Alvys.
Establezca Type en cada referencia con el nombre de referencia que usa el transportista, por ejemplo BOL Number. El nombre se convierte en el nombre de la referencia en la carga. Una referencia sin Type puede descartarse.
Rate se convierte en la tarifa de línea y de facturación de la carga. No puede enviar recargo por combustible ni cargos accesorios en una licitación.
La respuesta no incluye la licitación. Léala en el paso siguiente.

Consulte Create tender para ver todos los campos.

Fechas y zonas horarias

Envíe cada fecha como la hora local de reloj en la parada o en el cliente. Alvys conserva la hora de reloj que usted envía y aplica la zona horaria que resuelve para la licitación. Por lo tanto, una marca de tiempo UTC, como una que termina en Z, puede desplazarse varias horas. Alvys ignora el desfase de sus marcas de tiempo. El -06:00 de los ejemplos de esta página no tiene efecto. Si Alvys no puede resolver una zona horaria para la licitación, descarta ExpirationDate, y la licitación no muestra un plazo de respuesta.

4. Encuentre el id de su licitación

Necesita el id de la licitación para leerla y para aceptarla o rechazarla. Obténgalo de una de tres maneras:

El encabezado Location de la respuesta de creación.
data.tenderId en el webhook tender.created.
Una búsqueda por ShipmentId:

POST /api/p/v1.0/tenders/search
Authorization: Bearer <token>
Content-Type: application/json

{
  "Page": 0,
  "PageSize": 25,
  "Filter": { "ShipmentId": "SHP-100234" }
}

La respuesta es una página con Items, Total, Page y PageSize. Cada elemento es una licitación con su Id, Status, ShipmentId y paradas.

El id de la licitación normalmente no cambia. Puede cambiar si Alvys vincula la licitación a una carga existente. Tome el id del webhook más reciente, o busque por ShipmentId, antes de actuar sobre una licitación.

5. Acepte la licitación

Una licitación se acepta de una de tres maneras. El transportista elige cuál.

Vía	Quién actúa	Qué sucede
Aceptación automática	Alvys	Cuando llega la licitación, Alvys hace coincidir cada parada con una ubicación por dirección, o crea la ubicación. Luego crea la carga.
Aceptar en Alvys	Transportista	Un despachador revisa la licitación en Alvys, elige una ubicación para cada parada y acepta.
Aceptar a través de la API	Socio o transportista	Usted envía un id de ubicación para cada parada. Use esta vía solo si actúa en nombre del transportista.

Cuando Alvys crea una carga a partir de la licitación, envía tender.accepted con el loadId y el loadNumber de la nueva carga. La nueva carga recibe el id de la licitación, por lo que loadId es igual a tenderId:

{
  "id": "8d0c3b8e-2f51-4c1e-9a77-0e5b6a1f9c42-2",
  "type": "tender.accepted",
  "timestamp": "2026-11-05T15:10:02+00:00",
  "version": "v2",
  "etag": "0b00a1c2-0000-0700-0000-6729f1a30000",
  "subsidiaryId": "2d7e4c19-5a3b-4f8e-b1d6-7c9a0e3f5b42",
  "data": {
    "tenderId": "8d0c3b8e-2f51-4c1e-9a77-0e5b6a1f9c42",
    "loadId": "8d0c3b8e-2f51-4c1e-9a77-0e5b6a1f9c42",
    "loadNumber": "100457",
    "tender": {
      "id": "8d0c3b8e-2f51-4c1e-9a77-0e5b6a1f9c42",
      "status": "Accepted",
      "shipmentId": "SHP-100234",
      "loadNumber": "100457"
    }
  }
}

La instantánea data.tender anterior está abreviada. Tiene los mismos campos que Get tender, en camelCase. Consulte Tender events.

Si el transportista ya tiene una carga cuyo número de orden es igual a su ShipmentId, Alvys vincula la licitación a esa carga y no crea una carga nueva. La licitación toma el id de esa carga. Luego Alvys envía tender.created para el nuevo id de la licitación, con data.tender.status igual a Accepted, y no envía tender.accepted. Trate un tender.created con estado Accepted como una aceptación, y asócielo con su licitación por shipmentId.

Si la aceptación automática falla, por ejemplo porque no se puede hacer coincidir la ubicación de una parada o porque el cliente no tiene flota predeterminada, la licitación permanece en New. El motivo se muestra al transportista en Alvys. No aparece en la respuesta de la API.

Aceptar a través de la API

Obtenga la licitación y lea el StopId de cada parada:

GET /api/p/v1.0/tenders/8d0c3b8e-2f51-4c1e-9a77-0e5b6a1f9c42
Authorization: Bearer <token>

{
  "Id": "8d0c3b8e-2f51-4c1e-9a77-0e5b6a1f9c42",
  "Status": "New",
  "ShipmentId": "SHP-100234",
  "Stops": [
    { "StopId": "3f1c9a52-6d0e-4a9b-9c1e-2b7f0d4e8a11", "Type": "Pickup", "SequenceNumber": "1" },
    { "StopId": "9b2e7d10-1a4c-4f3e-8b6d-5c9a0e1f2d33", "Type": "Delivery", "SequenceNumber": "2" }
  ]
}

Encuentre el id de ubicación de Alvys de cada parada con Get location o Search locations. La ubicación ya debe existir. Aceptar a través de la API no crea ubicaciones.

Acepte con un vínculo para cada parada de la licitación. FleetId es opcional.

POST /api/p/v1.0/tenders/8d0c3b8e-2f51-4c1e-9a77-0e5b6a1f9c42/accept
Authorization: Bearer <token>
Content-Type: application/json

{
  "StopCompanyLinks": [
    { "StopId": "3f1c9a52-6d0e-4a9b-9c1e-2b7f0d4e8a11", "CompanyId": "c0a8e1f2-4b7e-4d3a-9a1e-2f3b4c5d6e7f" },
    { "StopId": "9b2e7d10-1a4c-4f3e-8b6d-5c9a0e1f2d33", "CompanyId": "d4b2c3a1-4e2f-4a9b-8c1d-2e3f4a5b6c7d" }
  ],
  "FleetId": "<fleetId>"
}

La respuesta es 200 con la licitación. Status es Accepted y LoadNumber está establecido. Si acepta una licitación que ya está aceptada, Alvys la devuelve sin cambios.

6. Lea la carga

Después de la aceptación, la licitación tiene una carga. Obtenga la carga por su número de orden, que es su ShipmentId, o por el loadNumber de tender.accepted. Envíe exactamente un parámetro de consulta.

GET /api/p/v2.0/loads?orderNumber=SHP-100234
Authorization: Bearer <token>

{
  "Id": "8d0c3b8e-2f51-4c1e-9a77-0e5b6a1f9c42",
  "LoadNumber": "100457",
  "OrderNumber": "SHP-100234",
  "PONumber": "PO-55821",
  "CustomerName": "Acme Corp",
  "Status": "<status>",
  "TenderId": "8d0c3b8e-2f51-4c1e-9a77-0e5b6a1f9c42",
  "Stops": ["..."],
  "References": ["..."]
}

La respuesta anterior está abreviada. Consulte Get load para ver todos los campos.

7. Envíe cambios y cancelaciones

Envíe un cambio a POST /api/p/v1.0/tenders/update y una cancelación a POST /api/p/v1.0/tenders/cancel.

Envíe el cuerpo completo de la licitación cada vez, con los mismos ID de enrutamiento y ShipmentId, y la lista completa de paradas. Para una cancelación, envíe el cuerpo de la última licitación que envió.
Ambos devuelven 201 con un cuerpo vacío, igual que la creación.
Si no existe una licitación para el ShipmentId, o la última licitación fue cancelada, una actualización crea una licitación nueva.
Si no existe una licitación para el ShipmentId, una cancelación crea una licitación y la cancela, para que el transportista vea la cancelación en Alvys.
Si vuelve a enviar una creación para un ShipmentId cuya última licitación no está cancelada ni rechazada, Alvys la trata como una actualización. Esto incluye una licitación que ya fue aceptada. Si la última licitación fue cancelada o rechazada, o su carga fue cancelada, Alvys crea una licitación nueva.

Qué sucede a continuación:

Actualización. Alvys envía tender.change.created. Si queuedForReview es true, el transportista revisa el cambio en Alvys y usted recibe tender.change.accepted cuando se aplica. Si es false, el cambio se aplicó directamente.
Cancelación, licitación aún no aceptada. La licitación se cancela. Usted recibe tender.cancelled.
Cancelación, licitación aceptada. De forma predeterminada, el transportista confirma la cancelación y luego la carga se cancela. Algunas conexiones cancelan la carga de inmediato, sin la confirmación del transportista. Usted recibe tender.cancelled.
Cancelación, sin licitación para el ShipmentId. Alvys crea una licitación y la cancela. Usted recibe tender.created y luego tender.cancelled.

Use un ShipmentId que sea único dentro de la cuenta del transportista, por ejemplo con un prefijo para su sistema. Alvys encuentra la licitación que se va a actualizar o cancelar por ShipmentId.

8. Rechace una licitación

Para el transportista, o un socio que actúa en nombre del transportista. POST /api/p/v1.0/tenders/{tenderId}/reject rechaza una licitación. Establezca CancelLinkedLoad en true para cancelar también una carga que ya se haya creado a partir de ella.

{
  "ReasonCode": "EQU",
  "ReasonDescription": "No Equipment Available",
  "CancelLinkedLoad": false
}

Los códigos de motivo son texto libre. Los valores comunes son A13 (otros motivos), EQU (sin equipo disponible), CPU (capacidad acordada excedida), LL1 (la carga no nos pertenece) y LL2 (no se puede completar la carga). El socio recibe tender.rejected.

9. Siga el estado y los documentos

Estado. load.status.changed incluye previousStatus, status y la carga. Consulte Load events.
Actualizaciones de parada. tender.stop.arrived, tender.stop.departed y tender.stop.eta_updated informan el progreso de las paradas respecto a la licitación. Consulte Tender events.
Documentos. load.document.uploaded incluye el número de carga y un document con un downloadUrl. El enlace es válido por 10 minutos. Para obtener un enlace nuevo, llame a GET /api/p/v2.0/loads/{loadNumber}/documents. Consulte Document events.
Cargar documentos. POST /api/p/v2.0/loads/{loadNumber}/document carga un archivo a la carga. Consulte Upload load document.

Los webhooks pueden llegar más de una vez y fuera de orden. Use X-Alvys-Event-Id para ignorar duplicados. Para recuperar eventos perdidos, consulte periódicamente Get load y la lista de documentos. Consulte Event delivery reliability.

La API REST usa nombres de propiedad en PascalCase, por ejemplo LoadNumber. Los payloads de webhook usan camelCase, por ejemplo loadNumber, y omiten las propiedades que no tienen valor.

Errores comunes

Los errores se listan con los más frecuentes primero. Los errores de “conflicto” devuelven 400, no 409. Algunos errores devuelven una cadena JSON simple en lugar de un objeto de problema.

Error	Estado	Causa	Solución
`Integration is missing`	400	Los seis ID de enrutamiento no coinciden con ninguna conexión y el transportista no tiene una conexión general.	Compare los seis valores con la conexión del transportista, carácter por carácter.
`EDI catch-all requires a single company with Company Number: '…'.`	400	Conexión general, y ningún cliente, o más de uno, tiene un Company Number igual a `SenderGsId`.	Pida al transportista que establezca el Company Number en exactamente un cliente.
`Failed to ingest tender`	400	La conexión coincidió, pero Alvys no pudo asignar la licitación, por ejemplo porque no hay un cliente establecido.	Pida al transportista que revise el cliente y la subsidiaria de la conexión.
`At least two stops are required`	400	Menos de dos paradas.	Envíe una recogida y una entrega.
`The ShipmentId field is required.` (y otros campos obligatorios)	400	Falta un campo obligatorio.	Envíe todos los ID de enrutamiento, `SCAC`, `ShipmentId` y `Stops`.
`EDI 204 has no valid pickup stop (pickup stop missing, or its address has no city/state). Tender quarantined for manual review.`	Se muestra en Alvys	La licitación se creó (`201`), pero no tiene una recogida utilizable. La entrega tiene un mensaje equivalente.	Envíe ciudad y estado en cada parada y luego envíe una actualización.
`The request has a different number of stops than the tender` (título `Stop count mismatch`)	400	La aceptación por API envió un número de vínculos distinto al de paradas de la licitación.	Envíe un vínculo por cada parada.
`At least two stop-company links are required`	400	La aceptación por API envió menos de dos vínculos.	Envíe un vínculo por cada parada.
`Company with ID '…' not found for stop '…'`	404	La aceptación por API envió un id de ubicación que no existe.	Vuelva a buscar el id de la ubicación.
`The tender cannot be accepted. It has been cancelled.`	400	La licitación fue cancelada.	Ninguna. Envíe una nueva licitación si la carga todavía se necesita.
`Duplicate tender … found. Load … already exists`	400	Existe una carga con este número de orden y no se puede vincular.	Pida al transportista que revise la carga existente.
`These changes were already accepted or rejected. Reload the changes.`	400	El cambio pendiente ya fue procesado.	Obtenga la licitación de nuevo.
`Requested Tender Not Found`	404	El id de la licitación no existe, o cambió al aceptarla.	Busque por `ShipmentId`.
Payment required	402	El plan del transportista no incluye acceso a la API pública.	Pida al transportista que contacte a Alvys.

Si ninguno coincide, contacte a support@alvys.com con el ShipmentId, la hora de la llamada y el cuerpo de la respuesta.

Recursos relacionados

Referencia de la API de licitaciones
Tender events
Load events
Document events
Verificación de firmas de webhook
Integraciones EDI: mapee las transacciones EDI propias de un transportista a la API
Versionado

Documentación

Funciones de la API

IA y agentes

Casos de uso

Envíe cargas a un transportista de Alvys con la API de licitaciones

Lo que necesita

Alcances

Enrutamiento de transportista y cliente

Sin EDI: elija los ID de enrutamiento

Con EDI: reutilice sus ID X12

Lista de verificación de configuración del transportista

Flujo de trabajo

1. Obtenga un token

2. Suscríbase a los eventos de licitaciones y cargas

3. Cree una licitación

Fechas y zonas horarias

4. Encuentre el id de su licitación

5. Acepte la licitación

Aceptar a través de la API

6. Lea la carga

7. Envíe cambios y cancelaciones

8. Rechace una licitación

9. Siga el estado y los documentos

Errores comunes

Recursos relacionados

​Lo que necesita

​Alcances

​Enrutamiento de transportista y cliente

​Sin EDI: elija los ID de enrutamiento

​Con EDI: reutilice sus ID X12

​Lista de verificación de configuración del transportista

​Flujo de trabajo

​1. Obtenga un token

​2. Suscríbase a los eventos de licitaciones y cargas

​3. Cree una licitación

​Fechas y zonas horarias

​4. Encuentre el id de su licitación

​5. Acepte la licitación

​Aceptar a través de la API

​6. Lea la carga

​7. Envíe cambios y cancelaciones

​8. Rechace una licitación

​9. Siga el estado y los documentos

​Errores comunes

​Recursos relacionados

Lo que necesita

Alcances

Enrutamiento de transportista y cliente

Sin EDI: elija los ID de enrutamiento

Con EDI: reutilice sus ID X12

Lista de verificación de configuración del transportista

Flujo de trabajo

1. Obtenga un token

2. Suscríbase a los eventos de licitaciones y cargas

3. Cree una licitación

Fechas y zonas horarias

4. Encuentre el id de su licitación

5. Acepte la licitación

Aceptar a través de la API

6. Lea la carga

7. Envíe cambios y cancelaciones

8. Rechace una licitación

9. Siga el estado y los documentos

Errores comunes

Recursos relacionados