> ## 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.

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

> Envíe licitaciones de carga desde su TMS o sistema de remitente a un transportista que opera en Alvys, con o sin EDI. Configure los ID de enrutamiento, cree, actualice y cancele licitaciones, acéptelas y siga la carga resultante con webhooks.

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.

> [!NOTE]
>
> **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](https://docs.alvys.com/es/api/guides/authentication-1.md). |
| 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](#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](https://docs.alvys.com/en/api/reference/webhooks/overview.md). |

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. |

> [!WARNING]
>
> Actualizar y cancelar una licitación requiere `tender:create`, no `tender:update`.

Todas las rutas siguientes son relativas a la [URL base](https://docs.alvys.com/es/api/guides/base-url.md) `https://integrations.alvys.com`. Los endpoints de licitaciones, webhooks, ubicaciones y subsidiarias usan `v1.0`. Los endpoints de cargas usan `v2.0`. Consulte [Versionado](https://docs.alvys.com/es/api/guides/versioning.md).

## 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:

1. Una conexión cuyos seis ID sean todos iguales a los seis ID de la licitación.
2. Si no existe, la conexión general del transportista.
3. 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** |

> [!WARNING]
>
> 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.*` |

> [!WARNING]
>
> 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.*

1. Cree las credenciales de cliente de la API para el socio en **Admin → API Access** y asigne los [alcances](#alcances) indicados arriba.
2. 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.
3. 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.
4. 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.
5. 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:

```mermaid theme={null}
stateDiagram-v2
    direction LR
    New --> Accepted: carrier accepts
    New --> Rejected: carrier rejects
    New --> Cancelled: you cancel
    Accepted --> Rejected: carrier rejects
    Accepted --> Cancelled: you cancel, carrier confirms
```

### 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](https://docs.alvys.com/es/api/guides/authentication-1.md).

```bash theme={null}
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](https://docs.alvys.com/en/api/reference/subsidiaries/list-subsidiaries.md).
* Una suscripción puede contener hasta 50 eventos.

```http theme={null}
POST /api/p/v1.0/webhooks
Authorization: Bearer <token>
Content-Type: application/json
```

```json theme={null}
{
  "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](https://docs.alvys.com/en/api/reference/webhooks/security-signature-verification.md).

```json theme={null}
{
  "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](https://docs.alvys.com/en/api/reference/webhooks/create-webhook-subscription.md) 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:

```http theme={null}
POST /api/p/v1.0/tenders
Authorization: Bearer <token>
Content-Type: application/json
```

```json theme={null}
{
  "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 theme={null}
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:

```json theme={null}
{
  "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](https://docs.alvys.com/en/api/reference/tenders/create-tender.md) 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`:

```http theme={null}
POST /api/p/v1.0/tenders/search
Authorization: Bearer <token>
Content-Type: application/json
```

```json theme={null}
{
  "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.

> [!WARNING]
>
> 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`:

```json theme={null}
{
  "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](https://docs.alvys.com/en/api/reference/tenders/get-tender.md), en camelCase. Consulte [Tender events](https://docs.alvys.com/en/api/reference/webhooks/tender-events.md).

> [!WARNING]
>
> 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`.

> [!NOTE]
>
> 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

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

   ```http theme={null}
   GET /api/p/v1.0/tenders/8d0c3b8e-2f51-4c1e-9a77-0e5b6a1f9c42
   Authorization: Bearer <token>
   ```

   ```json theme={null}
   {
     "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" }
     ]
   }
   ```

2. Encuentre el id de ubicación de Alvys de cada parada con [Get location](https://docs.alvys.com/en/api/reference/locations/get-location.md) o [Search locations](https://docs.alvys.com/en/api/reference/locations/search-locations.md). La ubicación ya debe existir. Aceptar a través de la API no crea ubicaciones.

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

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

   ```json theme={null}
   {
     "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.

```http theme={null}
GET /api/p/v2.0/loads?orderNumber=SHP-100234
Authorization: Bearer <token>
```

```json theme={null}
{
  "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](https://docs.alvys.com/en/api/reference/loads/get-load.md) 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`.

> [!WARNING]
>
> 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.

```json theme={null}
{
  "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](https://docs.alvys.com/en/api/reference/webhooks/load-events.md).
* **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](https://docs.alvys.com/en/api/reference/webhooks/tender-events.md).
* **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](https://docs.alvys.com/en/api/reference/webhooks/document-events.md).
* **Cargar documentos.** `POST /api/p/v2.0/loads/{loadNumber}/document` carga un archivo a la carga. Consulte [Upload load document](https://docs.alvys.com/en/api/reference/loads/upload-load-document.md).

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](https://docs.alvys.com/en/api/reference/loads/get-load.md) y la lista de documentos. Consulte [Event delivery reliability](https://docs.alvys.com/en/api/reference/webhooks/event-delivery-reliability.md).

> [!NOTE]
>
> 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](mailto: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](https://docs.alvys.com/en/api/reference/tenders/create-tender.md)
* [Tender events](https://docs.alvys.com/en/api/reference/webhooks/tender-events.md)
* [Load events](https://docs.alvys.com/en/api/reference/webhooks/load-events.md)
* [Document events](https://docs.alvys.com/en/api/reference/webhooks/document-events.md)
* [Verificación de firmas de webhook](https://docs.alvys.com/en/api/reference/webhooks/security-signature-verification.md)
* [Integraciones EDI](https://docs.alvys.com/es/api/guides/edi-integrations.md): mapee las transacciones EDI propias de un transportista a la API
* [Versionado](https://docs.alvys.com/es/api/guides/versioning.md)