Registro de cambios

​

Soporte de revisiones de protocolo

​

Added

• Indicaciones de seguridad en herramientas. Cada herramienta ahora anuncia annotations de MCP — readOnlyHint, destructiveHint, idempotentHint y openWorldHint — derivadas de la misma clasificación Read/Write/Destructive que el servidor aplica, de modo que la indicación anunciada siempre coincide con la política aplicada. Los clientes las usan para decidir cuándo pedir confirmación a un humano antes de ejecutar una herramienta. La superficie beta es de solo lectura, por lo que cada herramienta actualmente visible está marcada con readOnlyHint: true y destructiveHint: false; las indicaciones importan cuando se habiliten las herramientas de escritura, y ya están en su lugar con antelación.
• Guía de uso del servidor. El servidor publica instructions en lenguaje natural que describen cómo usar la superficie — que la visibilidad de herramientas es fija por despliegue, que los parámetros desconocidos se rechazan en lugar de ignorarse, y que las búsquedas son basadas en 0 y paginadas. Los clientes que muestran las instrucciones del servidor pasarán esto al modelo automáticamente.

​

Changed

• Orden estable de herramientas. tools/list y prompts/list devuelven entradas ordenadas por nombre, de modo que el catálogo ya no varía entre solicitudes. Esto hace fiable el almacenamiento en caché del lado del cliente y mejora las tasas de acierto de caché de prompts cuando la lista de herramientas se incluye en el contexto del modelo.
• GET y DELETE en /mcp devuelven 405 Method Not Allowed. Estos eran los verbos de sesión heredados — GET abría un flujo servidor-a-cliente y DELETE finalizaba una sesión. La revisión 2026-07-28 no usa sesiones, por lo que ninguno se ofrece. Ahora responden 405 (una señal de capacidad) en lugar de 400 o 401, de modo que un cliente que sondea soporte de sesión obtiene una respuesta inequívoca sin token.
• offline_access ya no se anuncia en scopes_supported. Un token de actualización no es un requisito de este recurso, por lo que los metadatos del recurso protegido ya no lo listan. Los clientes que quieran un token de actualización siguen solicitándolo al servidor de autorización como antes. Esto acorta la pantalla de consentimiento.

​

Fixed

• Los errores de argumentos son accionables en lugar de genéricos. Un argumento obligatorio faltante, o uno del tipo incorrecto (por ejemplo page: "not-an-int"), antes devolvía An error occurred. — indistinguible de un fallo del servidor. Ahora devuelven un error estructurado [invalid_params] que nombra el parámetro, de modo que un agente puede corregir la llamada y reintentar. Esto cubre tanto herramientas como prompts.
• Errores de argumentos en prompts. prompts/get con un argumento obligatorio faltante devolvía el mismo error genérico. Ahora devuelve invalid_params nombrando el argumento.
• Las solicitudes mal formadas devuelven un cuerpo de error adecuado. Una solicitud JSON-RPC mal formada ahora devuelve 400 con un error JSON-RPC en lugar de un 500 vacío.

​

¿Qué cambió?

​

¿Qué debo hacer?

​

Herramientas MCP

• Added trips_record_arrival (Write · stop:update) — registra un evento de llegada en una parada del viaje. Envuelve PUT /api/p/v1/trips/{tripId}/stops/{stopId}/arrival.
• Added trips_record_departure (Write · stop:update) — registra un evento de salida en una parada del viaje. El servidor exige que exista primero una llegada. Envuelve PUT /api/p/v1/trips/{tripId}/stops/{stopId}/departure.
• Added trips_update_stop_appointment (Write · stop:update) — actualiza la cita (o ventana FCFS) en una parada del viaje. scheduleType debe ser APPT o FCFS; appointmentDate es obligatorio cuando scheduleType=APPT, y windowBegin es obligatorio cuando scheduleType=FCFS. Envuelve PUT /api/p/v1/trips/{tripId}/stops/{stopId}/appointment.
• Removed trips_update_stop_status — la herramienta combinada única se reemplaza por las tres herramientas específicas anteriores. Quienes llamen deben migrar a la herramienta específica de la acción que quieran realizar.
• Added trucks_events_search (Read · truck:read) — obtiene eventos de camión (mantenimiento, programación, disponibilidad) para uno o más camiones en un rango de fechas, en espejo de drivers_events_search. Pasa truckIds (ids de camión de Alvys, no números de unidad) y un startDate; endDate es opcional. Devuelve una lista plana de eventos, sin paginación — una lista vacía significa que no hubo eventos en el rango.

​

Corregido

• Los clientes MCP basados en navegador pueden completar el descubrimiento. Los endpoints de metadatos del recurso protegido y /mcp ahora responden a solicitudes cross-origin y a preflights OPTIONS, así que un cliente que ejecuta OAuth guiado en el navegador (por ejemplo MCP Inspector) puede terminar el handshake en lugar de fallar en el preflight.
• Autorización consistente para tokens con solo permisos de estados de liquidación. Un token de usuario que solo lleva permisos de estados de liquidación ya no pasa las herramientas de lectura carriers_* y drivers_* en el borde MCP para luego ser rechazado por la Public API. Esas herramientas ahora exigen los mismos permisos de lectura de transportista y conductor que aplican sus endpoints subyacentes, de modo que ambos lados coinciden en el resultado.

​

Qué cambió

• Paginación basada en 0 en cada herramienta de búsqueda. page tiene valor predeterminado 0 y las respuestas devuelven el page de la solicitud para que los agentes puedan controlar su propio paginador. pageSize sigue teniendo valor predeterminado 25 (máx. 100).
• Validación estricta de argumentos. Las claves desconocidas — en el nivel superior o anidadas dentro de un objeto de rango de fechas o elemento de arreglo — devuelven [invalid_params] nombrando las claves ofensivas y la lista completa de parámetros válidos de la herramienta.
• Filtros de arreglo, coincidiendo con la Public API. Los filtros que mapean a campos de arreglo de /search ahora se declaran como arreglos en la herramienta para que puedas pasar uno o varios valores en una sola llamada.
• Objetos estructurados de rango de fechas. Los filtros de rango de fechas ahora son objetos únicos { start, end } usando los mismos nombres de parámetros que usa la Public API. Un end sin un start se rechaza de entrada. invoices_search sigue exigiendo al menos un filtro que no sea de fecha junto con un rango (igual que la Public API); trips_search acepta un rango como su único filtro.

​

Herramientas afectadas

​

Migración

1. Renombra cualquier parámetro renombrado. En particular: unitNumber → truckNumber / trailerNumber (en trucks_search / trailers_search), truckId → truckNumber (en fuel_transactions_search), y las formas singulares mcNumber / dotNumber / loadNumber / orderNumber / tripNumber / driverId → sus formas plurales de arreglo en las herramientas de búsqueda listadas arriba.
2. Envuelve los filtros de un solo valor en un arreglo. status: "Active" → status: ["Active"], mcNumber: "12345" → mcNumbers: ["12345"], y así sucesivamente.
3. Compacta los pares de fechas en objetos { start, end } usando los nuevos nombres de parámetros (createdDateRange, pickupDateRange, deliveryDateRange, invoicedDateRange, paidDateRange, transactionRange).
4. Reduce page en uno. page=1 (antigua primera página) → page=0. Si tu código calcula page desde un índice de UI, resta 1 en el punto de llamada.
5. Elimina cualquier clave no reconocida. Si una llamada ahora devuelve [invalid_params], el mensaje de error lista tanto las claves rechazadas como el conjunto de parámetros válidos — alinea con esa lista.

​

Qué cambió

​

Cómo funciona el alcance del token

https://alvys.com/claims/app/subsidiaries

​

Qué puede ver y hacer un token con alcance

​

Entidades con alcance

​

Cambios en códigos de respuesta

​

Compatibilidad hacia atrás

​

Crear una credencial con alcance

1. Vaya a Settings → API Keys
2. Haga clic en New credential
3. Seleccione permissions y elija las subsidiaries a las que la credencial puede acceder — hasta 3 filiales específicas, o All subsidiaries para acceso a todo el tenant
4. Haga clic en Generate y almacene el Client ID y Secret de forma segura

​

Public API + MCP: acceso con token de usuario a endpoints de lectura

• Fixed los tokens interactivos (user-PKCE) fallaban en load:read, stop:read, trip:read, visibility:read y carrier:read en la Public API y MCP para usuarios que de otro modo tenían privilegios. Estos endpoints comprobaban permisos internos (ViewLoads, Carrier base) que ningún registro de usuario real lleva. Cualquier usuario autenticado del tenant ahora pasa la mitad de token de usuario de esas comprobaciones de lectura, coincidiendo con el gating de roles en la app. Los tokens machine-to-machine no cambian — siguen requiriendo el alcance OAuth correspondiente. Cada endpoint de escritura conserva su comprobación real de permisos.

​

POST /api/p/v{version}/driver-settlement-statements/search y GET /api/p/v{version}/driver-settlement-statements/{number}

• Added TransactionType en la respuesta LineItems[]. Solo se rellena cuando Category es Escrow; null para cualquier otro ítem de línea.
  • "Deposit" — dinero movido hacia la cuenta de escrow del conductor. Aparece como un Amount negativo.
  • "Withdrawal" — dinero movido fuera de la cuenta de escrow. Aparece como un Amount positivo.
• Aditivo y no breaking. Los consumidores existentes ven un campo nullable nuevo. Los totales y todos los demás campos no cambian. Esta es hoy la única superficie de la Public API que devuelve ítems de línea de escrow; POST /api/p/v{version}/deductions/search no lo hace.

​

POST /api/p/v{version}/invoices/carrier-payments

• Se eliminó MarkAsPaid del cuerpo de la solicitud. El campo solo existía para forzar un estado de viaje Paid, que Alvys no usa. Los llamadores existentes que aún envían markAsPaid no se ven afectados — el campo se ignora.
• Se corrigió el estado del viaje en la respuesta: cuando los pagos registrados cubren totalmente el importe a pagar al transportista, el viaje ahora transiciona a Completed en lugar de Paid. Los pagos parciales dejan el estado del viaje sin cambios.
• El campo Status de la respuesta refleja el estado actual del viaje después de aplicar el pago.

​

MCP: invoices_record_carrier_payment

• Se eliminó el parámetro markAsPaid (mismo comportamiento que el cambio en la API pública anterior).

• data.diff.changes — un arreglo de tipos de cambio con nombres de dominio (por ejemplo StatusChanged, RateChanged, StopReordered, AppointmentChanged). Se entrega a todos los suscriptores cuando algo significativo cambió. Los cambios de subentidad llevan un target — { "type": "Stop" | "Field", "id": "<stableId>" }.
• data.diff.previousAttributes — el valor anterior de cada campo cambiado visible en la respuesta pública, con claves 1:1 con la instantánea. Las colecciones con clave (paradas, referencias, líneas de cargo) difieren por id estable. Opcional por suscripción.

{
  "type": "load.changed",
  "data": {
    "load": { "...": "instantánea actual completa" },
    "diff": {
      "changes": [
        { "kind": "StatusChanged" },
        { "kind": "AppointmentChanged", "target": { "type": "Stop", "id": "abc123" } }
      ],
      "previousAttributes": { "...": "valores anteriores (opcional)" }
    }
  }
}

• Dashboard: active Include previous values en el webhook.
• API: establezca IncludePreviousAttributes: true al crear o actualizar la suscripción (predeterminado false).

​

¿Qué hay de nuevo?

​

¿Qué cambió?

GET  /api/p/v{version}/trips/{tripId}/check-calls
POST /api/p/v{version}/trips/{tripId}/check-calls

• List trip check calls — devuelve cada check call registrado en el viaje.
• Log a trip check call — registra un nuevo check call con un description obligatorio más activity, driverId, location estructurada (coordenadas incluidas) y setpointTemperature / returnTemperature de reefer opcionales.

​

El cuerpo de respuesta incluye

• Core: Id, LoadNumber, TripId, TripNumber, Description
• Status: Activity, ResponseType, DriverName
• Location: dirección estructurada con coordenadas
• Reefer: SetpointTemperature, ReturnTemperature
• Audit: CreatedAt, CreatedBy

​

¿Por qué?

​

Qué hay de nuevo

• Buscar estados de liquidación finalizados de conductores y owner-operators con paginación, partidas y totales.
• Buscar estados de liquidación finalizados de transportistas con paginación, desgloses por viaje, partidas, pagos y totales.
• Obtener un único estado de liquidación de conductor, owner-operator o transportista por número de estado.
• Filtrar búsquedas de estados por rango de fechas del estado, tipo de conductor, transportista y subsidiaria.

​

Qué cambia

• Esta versión es aditiva y retrocompatible.
• Solo se devuelven estados finalizados de la pestaña Statements. Se excluyen los estados Open y Draft.
• Los estados de liquidación de conductor pueden incluir estados Failed; se identifican mediante el campo Status.
• Los estados de liquidación de transportista excluyen estados Failed y Deleted.
• StatementDateRange es obligatorio para las solicitudes de búsqueda. Tanto Start como End deben proporcionarse y se interpretan como días de calendario UTC inclusivos.
• El filtro DriverType de conductor acepta COMPANY, OWNER_OPERATOR o CONTRACTOR, sin distinguir mayúsculas/minúsculas, coincidiendo con el endpoint /drivers.
• Los valores monetarios se devuelven como objetos { Amount, Currency }.
• El acceso usa los alcances existentes:
  • driver:read para estados de liquidación de conductor
  • carrier:read para estados de liquidación de transportista

​

Endpoints afectados

• POST /p/v1.0/driver-settlement-statements/search (nuevo) — busca estados de liquidación finalizados de conductores y owner-operators.
• GET /p/v1.0/driver-settlement-statements/{number} (nuevo) — obtiene un único estado de liquidación de conductor u owner-operator por número de estado.
• POST /p/v1.0/carrier-settlement-statements/search (nuevo) — busca estados de liquidación finalizados de transportistas.
• GET /p/v1.0/carrier-settlement-statements/{number} (nuevo) — obtiene un único estado de liquidación de transportista por número de estado.

​

Qué hay de nuevo

• Asignar un transportista a un viaje — asigna un transportista y, opcionalmente, un conductor, camión y remolque a un viaje.
• Despachar un viaje — despacha un viaje cubierto para que el despacho pueda dispararse desde tu propio flujo.
• Filtrar viajes por conductor, camión o remolque — acota la búsqueda de viajes a un conductor específico o pieza de equipo.
• Actualizar el estado de un transportista — establece el estado de un transportista (por ejemplo, Active, Do Not Load) para mantener los registros sincronizados con tus sistemas de cumplimiento y evaluación.
• Contactos de transportista en la respuesta de transportista — lee los datos de contacto del transportista sin llamadas adicionales.

​

Qué cambia

• Todos los cambios son aditivos y retrocompatibles.
• Los nuevos filtros de viaje (driverId, truckId, trailerId) son opcionales. Cada uno es válido por sí mismo o junto con los parámetros de búsqueda existentes; driverId coincide con asignaciones primarias, secundarias y de owner-operator.
• Las respuestas de transportista ahora incluyen una colección Contacts (nombre, correo, teléfono, móvil, título y una marca de contacto principal) tanto en las respuestas de get-by-id como de búsqueda.
• Asignar un transportista requiere carrierId y dispatcherId; driver2Id no se puede enviar sin driver1Id. Los activos se referencian por id — resuélvelos primero mediante sus endpoints de búsqueda.
• El despacho requiere que el viaje esté Covered (transportista y activos asignados); de lo contrario, la solicitud se rechaza.
• Actualizar el estado de un transportista admite concurrencia optimista mediante el encabezado If-Match y devuelve un nuevo ETag para la siguiente actualización.

​

Endpoints afectados

• POST /p/v1.0/trips/{tripId}/assign (nuevo) — asigna un transportista y activos opcionales; devuelve el viaje actualizado.
• POST /p/v1.0/trips/{tripId}/dispatch (nuevo) — despacha un viaje cubierto; devuelve el viaje actualizado.
• POST /p/v1.0/trips/search (actualizado) — ahora acepta los filtros driverId, truckId y trailerId.
• PATCH /p/v1.0/carriers/{carrierId}/status (nuevo) — actualiza el estado de un transportista; devuelve 204 No Content con un nuevo ETag.
• GET /p/v1.0/carriers/{id} y POST /p/v1.0/carriers/search (actualizados) — las respuestas ahora incluyen Contacts.

​

¿Qué hay de nuevo?

​

¿Qué cambió?

POST /api/p/v{version}/tenders/search
GET  /api/p/v{version}/tenders/{tenderId}
POST /api/p/v{version}/tenders
POST /api/p/v{version}/tenders/update
POST /api/p/v{version}/tenders/cancel
POST /api/p/v{version}/tenders/{tenderId}/accept
POST /api/p/v{version}/tenders/{tenderId}/accept-updates
POST /api/p/v{version}/tenders/{tenderId}/accept-cancel
POST /api/p/v{version}/tenders/{tenderId}/reject

• Buscar y obtener — consulte tenders y recupere el detalle completo del tender.
• Crear / actualizar / cancelar — ingiera tenders de carga (incluidos los originados en EDI 204) de forma programática.
• Aceptar / rechazar — responda a un tender; aceptar crea la carga correspondiente en Alvys.
• Aceptar actualizaciones / aceptar cancelación — aplique una actualización o cancelación de tender entrante a la carga vinculada.

​

¿Por qué?

​

¿Qué hay de nuevo?

​

¿Qué cambió?

curl --location --request PATCH 'https://integrations.alvys.com/api/p/v1.0/loads/3039979' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--header 'If-Match: "8DBAC1F2E3..."' \
 --data-raw '{
  "orderNumber": "2026-00471"
}'

​

Cómo prevenir sobrescrituras accidentales

​

Validación e historial

• Un Order Number en blanco o vacío se rechaza con 400 Bad Request — la misma regla que la actualización interna del Order Number.
• Cada cambio se escribe en el historial de la carga (la misma pista de auditoría que la ruta de la UI).
• Las cargas originadas por EDI se rechazan. El Order Number en una carga EDI está bloqueado al valor recibido en el tender entrante y no se puede cambiar a través de este endpoint.

​

Endpoints afectados

​

Códigos de respuesta

​

¿Qué hay de nuevo?

​

¿Qué cambió?

• Herramientas de lectura en entidades principales — cargas, viajes, transportistas, clientes, conductores, camiones, tráilers, facturas, deducciones, transacciones de combustible, tenders, historial de visibilidad y documentos.
• Herramientas de escritura (opcional) — crear/aceptar/rechazar tenders, registrar pagos de transportista y cliente, registrar financiación, asignar y despachar viajes, actualizar estado de transportista, subir documentos, registrar llegadas/salidas de paradas y actualizar citas de paradas.
• Prompts curados (v1) — flujos guiados de varios pasos como find_and_cover_load, dispatch_driver, carrier_onboarding, settlement_reconciliation y track_shipment.

​

Autenticación

• Máquina a máquina — tokens client-credentials de Auth0, igual que Public API.
• Inicio de sesión de usuario — OAuth 2.1 con PKCE según la especificación MCP, incluido descubrimiento de recurso protegido (RFC 9728) e indicadores de recurso (RFC 8707), para que clientes interactivos como Claude puedan iniciar sesión como usuario.

​

Gobernanza y seguridad

• El aislamiento por tenant se aplica desde el token — nunca desde el cuerpo de la solicitud.
• Cada herramienta se clasifica Read / Write / Destructive con compuertas en tiempo de ejecución; las herramientas de escritura están deshabilitadas salvo que se habiliten explícitamente.
• Cada herramienta requiere un permiso API granular coincidente (por ejemplo tender:read, invoice:update).
• Todas las llamadas tienen límite de velocidad, tope de tamaño y registro de auditoría.

​

¿Por qué?

​

Qué hay de nuevo

​

Por qué importa

• Sincronización de CRM en tiempo real — empuja los registros de clientes directamente a Alvys desde tu TMS, ERP o CRM en lugar de ingresarlos a mano.
• Ediciones seguras ante conflictos — la concurrencia optimista con ETag / If-Match significa que dos ediciones simultáneas nunca se sobrescriben silenciosamente.

​

Crear

POST /api/p/v1.0/customers
Authorization: Bearer <token with customer:create>
Content-Type: application/json

{
  "Name": "Acme Logistics",
  "Type": "Customer",
  "CompanyNumber": "ACME-1",
  "Status": "Active",
  "BillingAddress": { "Street": "1 Main", "City": "City", "State": "NY", "Zip": "10001" },
  "Email": ["billing@acme.example"],
  "Phone": ["555-1234"]
}

​

Actualizar (parcial)

PATCH /api/p/v1.0/customers/{id}
Authorization: Bearer <token with customer:update>
If-Match: "etag-from-prior-read"

{ "Status": "Inactive" }

​

Eliminar

DELETE /api/p/v1.0/customers/{id}
Authorization: Bearer <token with customer:delete>
If-Match: "etag-from-prior-read"

​

Campos escribibles soportados

​

Validación de campos

​

Comportamiento de solicitud

​

Respuestas de escritura y lectura

​

Acceso

• customer:read — GET / search
• customer:create — POST
• customer:update — PATCH
• customer:delete — DELETE

​

Preguntas frecuentes

​

¿Qué hay de nuevo?

​

¿Qué cambió?

• load.changed
• trip.changed

​

Envoltorio del evento

{
  "id": "93d579d3-6b50-4f97-8764-1ad07c3efd97-d900dc51-...-0",
  "type": "load.changed",
  "timestamp": "2026-05-22T09:19:52.652Z",
  "version": "v1",
  "data": { /* event-specific payload - see below */ }
  // Other envelope fields are omitted from this example for brevity.
}

​

load.changed

{
  "load": {
    "id": "93d579d3-6b50-4f97-8764-1ad07c3efd97",
    "loadNumber": "3039979",
    "orderNumber": "ABC-12-007",
    "status": "Open",
    "loadType": "Revenue",
    "customerRate": {
      "amount": 1749.06,
      "currency": 840
    }
    // Full Public-API load object - same fields as GET /p/v1.0/loads/{loadNumber}.
    // Other fields (stops, charges, references, etc.) omitted here for brevity.
  }
}

​

trip.changed

{
  "trip": {
    "id": "dd5ba174abe845568f5e5c2a850db8ca",
    "tripNumber": "3039979",
    "status": "Open",
    "loadNumber": "3039979",
    "orderNumber": "ABC-12-007",
    "tripValue": {
      "amount": 1599.06,
      "currency": 840
    }
    // Full Public-API trip object - same fields as GET /p/v1.0/trips/{tripId}.
    // Other fields (driver, truck, stops, accessorials, etc.) omitted here for brevity.
  }
}

​

Endpoints afectados

• GET /p/v1.0/webhooks/event-types ahora devuelve load.changed y trip.changed.
• POST /p/v1.0/webhooks / PUT /p/v1.0/webhooks/{id} aceptan los nuevos valores de tipo de evento en el array eventTypes.

​

¿Por qué?

• Reaccionar a los cambios operativos de cargas y viajes en tiempo real, sin sondeo.
• Reducir el volumen total de llamadas a la API en /loads y /trips.
• Impulsar automatizaciones descendentes (factoring, seguimiento, facturación) en el momento en que cambia un estado operativo.
• Mantener consistentes las pistas de auditoría a través de la UI existente de Delivery Logs de webhook.

​

¿Qué hay de nuevo?

​

¿Qué cambió?

​

Suscripción

​

Envelope (estructura general)

​

Payload de *.document.uploaded (estructura general)

{
  "id": "00000000-0000-0000-0000-000000000000-00000000-0000-0000-0000-000000000000",
  "type": "trip.document.uploaded",
  "timestamp": "2026-05-13T09:16:30.9797738+00:00",
  "version": "v1",
  "etag": "00000000-0000-0000-0000-000000000000",
  "data": {
    "tripId": "00000000000000000000000000000000",
    "document": {
      "id": "00000000-0000-0000-0000-000000000000",
      "attachmentPath": "bol.pdf",
      "attachmentType": "Bill of Lading",
      "attachmentSize": 10000,
      "uploadedAt": "2026-05-13T09:16:30.9797738+00:00",
      "parentId": "1000000",
      "parentType": "Trip",
      "uploadedBy": "00000000000000000000000000000000",
      "downloadUrl": "{url}",
      "expiresAt": "2026-05-13T09:26:35.3227049+00:00"
    }
  }
}

• data.tripId es el GUID del viaje (el identificador público natural devuelto por GET /p/v1.0/trips/{tripId}).
• data.document.parentId en un documento de viaje es el número de carga ("1000000"), coincidiendo con la forma en que los documentos de viaje se almacenan internamente y se devuelven por GET /loads/{loadNumber}/documents.
• attachmentType es un tipo de documento de Alvys legible por humanos (por ejemplo, "Bill of Lading", "Proof of Delivery", "Rate Confirmation"), el mismo valor devuelto por los endpoints de la API pública de documentos.
• uploadedBy es el id de usuario (GUID) de quien realizó la subida.

​

Payload de *.document.deleted (estructura general)

// load.document.deleted
{
  "id": "00000000-0000-0000-0000-000000000000-00000000-0000-0000-0000-000000000000",
  "type": "load.document.deleted",
  "timestamp": "2026-05-13T16:05:22.118+00:00",
  "version": "v1",
  "etag": "00000000-0000-0000-0000-000000000000",
  "data": {
    "loadNumber": "1000000",
    "document": {
      "id": "00000000-0000-0000-0000-000000000000",
      "attachmentPath": "bol.pdf",
      "attachmentType": "Bill of Lading",
      "attachmentSize": 10000,
      "uploadedAt": "2026-05-13T09:16:30.9797738+00:00",
      "uploadedBy": "00000000000000000000000000000000",
      "parentId": "1000000",
      "parentType": "Load"
    }
  }
}

​

Notas de comportamiento

• Un evento se dispara solo cuando un documento se crea o se elimina lógicamente: renombrar, cambiar de tipo y otras ediciones solo de metadatos no generan entregas.
• El downloadUrl prefirmado es de corta duración (≤ 15 minutos). Descargue el archivo con prontitud, o recurra a GET /p/v1.0/{parent}/{parentId}/documents/{documentId} si expira.

​

Endpoints afectados

​

Gestión de suscripciones de webhook

• GET /p/v1.0/webhooks/event-types: devuelve el catálogo completo incluyendo los nuevos tipos de eventos de documento.
• POST /p/v1.0/webhooks: crea una suscripción que selecciona cualquier combinación de los nuevos eventos.
• PUT /p/v1.0/webhooks/{id}: actualiza una suscripción existente para agregar o eliminar eventos de documento.
• GET /p/v1.0/webhooks/{id}: inspecciona qué eventos está seleccionando una suscripción.
• GET /p/v1.0/webhooks/{id}/deliveries: el historial de entregas para los nuevos eventos fluye a través de la misma superficie de logs que tender.* y *.status.changed.

​

Endpoints de documento que impulsan los eventos

​

Obtención de reserva (si un downloadUrl expira)

GET /p/v1.0/{parent}/{parentId}/documents/{documentId}

​

¿Por qué?

• ⚡ Automatización de documentos en tiempo real: la automatización de facturación basada en POD, el factoring, la gestión documental y la validación de facturas EDI 210 ya no dependen de un bucle de sondeo.
• 🔁 Menor carga en la API: elimina el tráfico de sondeo contra seis endpoints padre diferentes.
• 🎯 Suscríbase de forma acotada: los eventos están delimitados por entidad (load.* vs driver.* vs carrier.* …). Una integración de factoring que solo se interesa por documentos del lado de la carga no recibirá actualizaciones de tarjetas médicas de conductores.
• 🧾 Rastro de auditoría incorporado: cada intento de entrega se registra y es visible en la página de detalles del Webhook.
• 🔗 Descarga directa: cada evento *.uploaded lleva una URL de descarga prefirmada.

​

¿Quién tiene acceso?

​

Preguntas Frecuentes (FAQ)

​

¿Qué hay de nuevo?

​

¿Qué cambió?

load.status.changed
trip.status.changed

GET /p/v1.0/webhooks/event-types

​

Envelope del evento

{
  "id": "…",
  "type": "load.status.changed",
  "timestamp": "2026-05-04T14:32:11.482Z",
  "version": "1",
  "data": { /* payload específico del evento — ver abajo */ }
  // Otros campos del envelope se omiten en este ejemplo por brevedad.
}

​

load.status.changed

{
  "previousStatus": "Covered",
  "status": "Dispatched",
  "load": {
    "id": "…",
    "loadNumber": "1006321",
    "status": "Dispatched"
    // Objeto completo de carga de la API pública — mismos campos que GET /p/v1.0/loads/{loadNumber}.
    // Otros campos (customer, stops, charges, references, etc.) se omiten aquí por brevedad.
  }
}

​

trip.status.changed

{
  "previousStatus": "Dispatched",
  "status": "InTransit",
  "trip": {
    "id": "…",
    "tripNumber": "T-1006321-1",
    "status": "InTransit"
    // Objeto completo de viaje de la API pública — mismos campos que GET /p/v1.0/trips/{tripId}.
    // Otros campos (driver, truck, stops, accessorials, etc.) se omiten aquí por brevedad.
  }
}

​

Comportamiento

• Los eventos se emiten solo en transiciones reales, cuando status difiere de previousStatus. Las escrituras sin efecto no generan entregas.
• load / trip pueden ser null si la lectura de la instantánea falla o si el payload excedió el límite de tamaño y fue eliminado. Los campos previousStatus y status siempre están presentes para que los consumidores puedan reaccionar a la transición y volver a consultar mediante GET /loads/{id} o GET /trips/{id} si es necesario.
• Las entregas están firmadas (X-Alvys-Signature), se reintentan con retroceso exponencial y las suscripciones se desactivan automáticamente tras fallos sostenidos, de forma idéntica a los eventos tender.* existentes.

​

Endpoints afectados

• GET /p/v1.0/webhooks/event-types: ahora devuelve load.status.changed y trip.status.changed
• POST /p/v1.0/webhooks / PUT /p/v1.0/webhooks/{id}: aceptan los nuevos valores de tipo de evento en el arreglo eventTypes

​

¿Por qué?

• Reaccionar a cambios de estado de cargas y viajes en tiempo real, sin sondeo
• Reducir el volumen general de llamadas a la API en /loads y /trips
• Impulsar automatizaciones descendentes (factoring, seguimiento, facturación) en el momento en que cambia un estado operativo
• Mantener los rastros de auditoría consistentes a través de la interfaz existente de Logs de entrega de webhooks

​

¿Qué hay de nuevo?

​

¿Qué cambió?

POST /p/v1.0/invoices/carrier-payments
POST /p/v1.0/invoices/customer-payments
POST /p/v1.0/invoices/financing

​

Pagos a transportistas

{
  "tripId": "string",
  "amount": {
    "value": 1000.00,
    "currency": "USD"
  }
}

​

Pagos de clientes

{
  "loadId": "string",
  "amount": {
    "value": 2500.00,
    "currency": "USD"
  }
}

• paidAt
• totalPaid
• payments[]

​

Financiamiento

{
  "loadId": "string",
  "reserveAmount": {
    "value": 500.00,
    "currency": "USD"
  },
  "escrowAmount": {
    "value": 200.00,
    "currency": "USD"
  }
}

​

Endpoints afectados:

• POST /p/v1.0/invoices/carrier-payments
• POST /p/v1.0/invoices/customer-payments
• POST /p/v1.0/invoices/financing

​

¿Por qué?

• Integración más rápida con plataformas de pago y finanzas
• Mejor automatización para cuentas por cobrar y por pagar
• Soporte para flujos de trabajo de factoring y escrow
• Menor entrada manual de transacciones financieras
• Mejor visibilidad contable a través de cargas y viajes

​

¿Qué hay de nuevo?

​

¿Qué cambió?

• cuando se omite includeDeleted, Trip Search devuelve únicamente viajes visibles y no eliminados
• cuando includeDeleted=false, Trip Search también devuelve únicamente viajes visibles y no eliminados

• viajes base reemplazados
• legs hijos ocultos de splits encadenados
• legs hijos ocultos de escenarios split-cancel / unsplit / restore

​

Qué significa isDeleted

• isDeleted=true significa que el viaje está eliminado o ya no es visible y debe considerarse inactivo para la sincronización
• isDeleted=false significa que el viaje es un leg visible actual

​

Escenarios comunes

​

Ejemplo

​

Endpoint afectado

POST /p/v1.0/trips/search

​

¿Por qué?

• detección confiable de tombstones para viajes invisibles y reemplazados
• mejor soporte para el sondeo con updatedSince y updatedAtRange
• sincronización más consistente para escenarios de split, re-split, cancel-split y restore

​

¿Qué hay de nuevo?

​

¿Qué cambió?

GET /p/v{version}/webhooks/{webhookId}/delivery-logs/export

​

Encabezado de intento de entrega

​

statusReason añadido a los payloads de webhook

{
  "statusReason": "Normal Status"
}

​

Exportación de logs de entrega

​

Parámetros de consulta

​

Comportamiento de exportación

1. Format=csv o Format=json en la cadena de consulta tiene precedencia cuando se proporciona.
2. De lo contrario, se utiliza el encabezado Accept.
3. De lo contrario, la respuesta usa JSON por defecto.

​

Cambio incompatible: los filtros de logs de entrega ahora aceptan arreglos

​

Antes

{
  "status": "failed",
  "eventType": "load.updated"
}

​

Después

{
  "status": ["failed"],
  "eventType": ["load.updated"]
}

​

Endpoints afectados

• GET /p/v{version}/webhooks/{webhookId}/delivery-logs
• GET /p/v{version}/webhooks/{webhookId}/delivery-logs/export

​

¿Por qué?

• mejor visibilidad de reintentos para los consumidores de webhooks
• contexto de estado más claro en los payloads salientes
• exportación y auditoría más sencillas del historial de entregas de webhooks
• filtrado más flexible para consultas y exportaciones de logs de entrega

​

¿Qué hay de nuevo?

​

¿Qué cambió?

​

Cargas

{
  "tenderId": "string | null",
  "requiredEquipment": [
    "Reefer"
  ]
}

• las cargas huérfanas ahora se tratan como inexistentes
• los totales de búsqueda de cargas excluyen las cargas abandonadas sin viajes
• las operaciones de documentos y notas de carga ahora devuelven 404 para cargas huérfanas

​

Viajes

{
  "orderNumber": "string | null"
}

• los viajes divididos o invisibles ahora pueden devolverse como isDeleted: true cuando includeDeleted=true
• GET /p/v{version}/trips ahora soporta includeDeleted
• POST /p/v{version}/trips/search ahora permite updatedAtRange como único filtro
• las referencias de carga de tipo service_exception ahora están expuestas
• los payloads de transportista están alineados entre la obtención de un solo viaje y la búsqueda de viajes

​

Transportistas

​

Tenders

​

Actualizaciones adicionales del esquema de respuesta

• CarrierResponse ahora incluye:
  • PaymentMethod
  • ExternalIds
  • FactoringCompany
• DriverResponse, TruckResponse y TrailerResponse ahora incluyen:
  • LicenseCountry
• FuelResponse ahora incluye:
  • Description
• FuelResponsePumpLocation ahora incluye:
  • State

​

Actualizaciones del esquema de tarifas de viaje

• DriverRatePolicyResponse ahora incluye:
  • CustomerLineHaulDeductionRate
  • PerMileRate
  • PerMileDeductionRate
• PerLoadRate ahora utiliza un PerLoadRateDto dedicado
• MileageRateDto ahora incluye:
  • UseHighestTier
• PerTripRateDto ahora incluye:
  • Tiers
  • MileageType
• PerTripRateDto.Rate ahora está marcado como obsoleto en el esquema

​

Actualizaciones de documentación de respuestas de error

• 401 Unauthorized
• 403 Forbidden
• 429 Too Many Requests

​

¿Por qué?

• mejor fiabilidad de sincronización de cargas y viajes para integraciones de sondeo
• identificación más clara de las cargas originadas por tender
• mejor visibilidad del vínculo con la orden a nivel de viaje
• resultados de búsqueda de transportistas más completos
• mayor consistencia entre endpoints de viaje relacionados
• payloads de datos maestros más ricos para transportistas, conductores, camiones, remolques y registros de combustible
• esquemas de tarifas de viaje más expresivos

​

¿Qué hay de nuevo?

​

¿Qué cambió?

GET    /api/p/v{version}/trips/{tripId}/stops
GET    /api/p/v{version}/trips/{tripId}/stops/{stopId}
PUT    /api/p/v{version}/trips/{tripId}/stops/{stopId}/arrival
DELETE /api/p/v{version}/trips/{tripId}/stops/{stopId}/arrival
PUT    /api/p/v{version}/trips/{tripId}/stops/{stopId}/departure
PUT    /api/p/v{version}/trips/{tripId}/stops/{stopId}/appointment

• Record stop arrival — el cuerpo toma una marca de tiempo arrivedAt obligatoria; devuelve la parada actualizada.
• Clear stop arrival — elimina una llegada registrada previamente.
• Record stop departure — el cuerpo toma una marca de tiempo departedAt obligatoria; devuelve 422 si la parada no está en un estado que permita salida.
• Set stop appointment — actualiza scheduleType, loadingType y la ventana de cita de la parada.

​

¿Por qué?

​

¿Qué hay de nuevo?

​

¿Qué cambió?

GET    /api/p/v1/loads/{loadNumber}/notes
POST   /api/p/v1/loads/{loadNumber}/notes
DELETE /api/p/v1/loads/{loadNumber}/notes/{noteId}

• List load notes — devuelve todas las notas de la carga.
• Create load note — el cuerpo toma description, noteType y un id opcional proporcionado por el cliente; devuelve 201 con la nota creada.
• Delete load note — devuelve 204 en caso de éxito.

​

El cuerpo de respuesta incluye

• Id, Description, NoteType
• CreatedAt, CreatedBy
• CreatedById — el identificador único del usuario que creó la nota (añadido en abril de 2026), de modo que las integraciones pueden atribuir notas a un usuario por id en lugar de analizar nombres para mostrar.

​

¿Por qué?

​

¿Qué hay de nuevo?

​

Qué puedes hacer

• Recibir eventos del ciclo de vida de tenders en tiempo real
• Activar automáticamente flujos de trabajo en tu sistema
• Mejorar la velocidad y capacidad de respuesta de la integración

​

Incluido en esta versión

​

Entrega de eventos

• Tipo de evento
• ID único del evento
• Marca de tiempo
• Firma HMAC segura

​

Reintentos automáticos

• Tu endpoint devuelve un error del servidor (5xx)
• Ocurre un timeout
• Ocurre una falla temporal de red

​

Seguridad y verificación

• Verificación de firma HMAC-SHA256
• Protección contra reenvíos mediante marcas de tiempo
• Entrega exclusivamente por HTTPS
• Verificación de propiedad del endpoint durante la configuración

​

Por qué esto es importante

• Integraciones EDI sobre API
• Flujos de trabajo automatizados de tenders
• Respuesta operativa más rápida
• Integraciones seguras con terceros

​

Documentación

• Ciclo de vida y configuración de Webhooks
• Entrega y confiabilidad de eventos
• Seguridad y verificación de firmas

​

¿Qué hay de nuevo?

​

¿Qué cambió?

"Temperature": {
  "SetpointTemperature": 70.0,
  "SetpointTemperatureMax": 75.0,
  "ControlMode": "Start/Stop"
},

"RequiredEquipment": [
  "Reefer"
]

​

Temperature

• SetpointTemperature – La temperatura objetivo requerida.
• SetpointTemperatureMax – Temperatura máxima opcional cuando se define un rango.
• ControlMode – Modo operativo esperado (Continuous o Start/Stop).

​

RequiredEquipment

"RequiredEquipment": ["Reefer", "Van"]
"RequiredEquipment": ["Van"]
"RequiredEquipment": ["Flatbed", "StepDeck"]

​

Endpoints afectados:

• POST /api/p/{version}/trips/search
• GET /api/p/{version}/trips/{id}

​

¿Por qué?

• Mejor visibilidad de los requisitos de viajes con control de temperatura
• Datos de equipo estructurados para una validación e integración más sencillas
• Mejor soporte para flujos de trabajo de cumplimiento y aplicaciones de seguimiento personalizadas

​

¿Qué hay de nuevo?

​

¿Qué cambió?

"references": [
  {
    "id": "string",
    "referenceId": "string",
    "name": "string",
    "value": "string",
    "type": "Text",
    "access": "Public",
    "origin": "string"
  }
]

​

Endpoints afectados

• GET /api/p/v{version}/trips/{id} y POST /api/p/v{version}/trips/search
• GET /api/p/v{version}/drivers/{id} y POST /api/p/v{version}/drivers/search
• GET /api/p/v{version}/trucks/{id} y POST /api/p/v{version}/trucks/search
• GET /api/p/v{version}/trailers/{id} y POST /api/p/v{version}/trailers/search

​

¿Por qué?

​

¿Qué hay de nuevo?

​

¿Qué cambió?

 "RatesV2": [
                    {
                        "PolicyId": "c00fda1001ec4a11100affdb0234de00",
                        "PolicyName": "Custom Rate",
                        "PerTripRate": {
                            "Rate": 250.0,
                            "RateId": "1",
                            "RateName": "Per Trip",
                            "LineItems": [
                                {
                                    "Description": "1 trip @ $250",
                                    "Amount": {
                                        "Amount": 250.0,
                                        "Currency": 840
                                    }
                                }
                            ]
                        }
                    },
                    {
                        "PolicyId": "a00fba1001ec4a11100aaddff0234de00",
                        "PolicyName": "Public API",
                        "TripValuePercentageRate": {
                            "Percentage": 25.0,
                            "RateId": "2",
                            "RateName": "% of Trip Value",
                            "LineItems": [
                                {
                                    "Description": "25% of $3,800",
                                    "Amount": {
                                        "Amount": 950.0,
                                        "Currency": 840
                                    }
                                }
                            ]
                        }
                    }
                ]

​

Endpoints afectados

• GET /api/p/{version}/trips
• POST /api/p/{version}/trips/search

​

¿Por qué?

• Comprender qué reglas y políticas se aplicaron para determinar cada pago.
• Alinear las integraciones de backend con el nuevo motor interno de políticas de pago para obtener reportes y conciliaciones consistentes.

​

¿Qué hay de nuevo?

​

¿Qué cambió?

• Una deducción debe incluir DriverId o TruckId — uno de ellos es obligatorio.
• OwnerOperatorId es opcional y puede utilizarse únicamente para sobrescribir el propietario actual del activo. Nunca es el sujeto principal de la deducción.
• Si se proporciona DriverId → la deducción aparece en la lista de deducciones de ese conductor.
• Si se proporciona TruckId → la deducción aparece en la lista de deducciones de ese camión.
• Para crear una deducción, el monto debe ser negativo y menor que - 1.00.
• Solo se admite la frecuencia "Once".
• Requiere un token Bearer válido con el scope apropiado (deduction:read, deduction:create o deduction:delete).

​

¿Por qué?

​

¿Qué cambió?

​

Ejemplo de respuesta

[
  {
    "id": "a314c7cd-783a-4807-8771-06406a9e490a",
    "AttachmentPath": "Loads-1759237626.pdf",
    "AttachmentType": "Customer Rate Confirmation",
    "AttachmentSize": 170225,
    "UploadedAt": "2025-09-30T13:07:07+00:00",
    "ParentId": "3022259",
    "ParentType": "Load",
    "UploadedBy": "7190175eecc3408e90d7173f4ece0e59",
    "DownloadUrl": "https://alvysqastorage.blob.core.windows.net/tl743/Loads-1759237626.pdf?...",
    "ExpiresAt": "2025-09-30T15:12:15.9506343+00:00"
  }
]

​

¿Por qué?

​

¿Qué hay de nuevo?

​

¿Qué cambió?

"OfficeId": "string",

​

Endpoints afectados:

• POST /api/p/{version}/loads/search
• GET /api/p/{version}/loads/{id}

​

¿Por qué?

​

¿Qué hay de nuevo?

​

¿Qué cambió?

• Nuevos endpoints:
  • POST /api/p/v{version}/carriers/{carrierId}/document
  • POST /api/p/v{version}/drivers/{driverId}/document
  • POST /api/p/v{version}/loads/{loadNumber}/document
  • POST /api/p/v{version}/trailers/{trailerId}/document
  • POST /api/p/v{version}/trips/{tripId}/document
  • POST /api/p/v{version}/trucks/{truckId}/document
• Validación por entidad:
  • Carrier→ Carrier Agreement, Carrier Application, Carrier Authority, Carrier Onboarding, Other Documents
  • Driver→ License, Drug Test, Medical (renombrado sugerido: Medical Card), W9 Form, Operating Authority, Other Documents
  • Truck/Trailer → Motor Vehicle Record, Vehicle Image, Inspection Certificate, Certificate of Insurance (COI), Insurance Certificate, Other Documents
  • Loads→ Customer Rate and Load Confirmation, Customer Load Confirmation, Customer Rate Confirmation, Signed Customer Rate Confirmation, Proof of Delivery, Proof of Pickup, Bill of Lading, Shipping Labels
  • Trips → Proof of Delivery (POD), Bill of Lading (BOL), Carrier Rate Confirmation, Load Manifest, Trip Report, Temperature Log, Proof of Pickup, Scale Ticket, Notice of Assignment (NOA), Shipping Labels
• Manejo de errores estandarizado: 400 DocumentType inválido o archivo demasiado grande 401 token inválido/expirado 403 scopes faltantes 404 entidad padre no encontrada/eliminada 415 tipo de contenido no soportado 429 límite de tasa excedido

​

Ejemplo — Subir documento a Load

curl -X POST "{{host}}/api/p/v1/loads/1006321/document" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: multipart/form-data" \
  -F "File=@Test_File.pdf" \
  -F "DocumentType=Bill of Lading"

{
  "id": "4b5c38bd-005e-4903-a4ee-45ca5e86411a",
  "AttachmentPath": "DOC-1757343192.jpeg",
  "AttachmentType": "Bill of Lading",
  "AttachmentSize": 5245329,
  "UploadedAt": "2025-09-08T14:53:12Z",
  "ParentId": "1006321",
  "ParentType": "Load"
}

​

¿Por qué?

​

¿Qué hay de nuevo?

• Búsqueda por ID o Company Number: Recupera una sola ubicación por id único o companyNumber.
• Búsqueda flexible: Filtra por Statuses, LocationIds o CreatedDateRange.
• Detalles más ricos: Obtén el nombre de la empresa, tipo, dirección, contactos y notas directamente en la respuesta.

​

¿Qué cambió?

• Nuevos endpoints:
  • GET /api/p/v{version}/locations → Búsqueda de una sola ubicación por id o companyNumber.
  • POST /api/p/v{version}/locations/search → Buscar y paginar resultados.
• El cuerpo de la respuesta incluye:
  • Principal: Id, Name, CompanyNumber, Type, Status
  • Dirección: PhysicalAddress { Street, City, State, ZipCode }
  • Contactos: Email[], Phone[], Fax
  • Metadatos: DateCreated, ExternalId
  • Notas: [ { Id, Description, NoteType, Time, User } ]
• Compatibilidad hacia atrás: Sin cambios en los payloads existentes de load/trip stop. Las paradas continúan exponiendo companyId, pero ahora los clientes pueden resolver esos IDs a través del Locations Controller para obtener más contexto.

​

Nuevos endpoints

• GET /api/p/v{version}/locations
• POST /api/p/v{version}/locations/search

​

¿Por qué?

​

¿Qué hay de nuevo?

• TransactionDate → Ahora se incluye en todas las transacciones de combustible.
• Quantity → Cada transacción incluye la cantidad comprada con valor y unidad de medida:

"Quantity": {
  "Value": 7.799,
  "UnitOfMeasure": "Gallons"
}

​

¿Qué hay de nuevo?

• Soporte multi-entidad: Los accesoriales ahora se rastrean para clientes, transportistas, conductores y OwnerOperators.
• Integración con EChecks: Los accesoriales de conductor y OwnerOperator pueden incluir números de eCheck vinculados y montos.
• Lógica de liquidación actualizada: TotalPayable ahora se calcula como Linehaul + Accessorials – EChecks.

​

¿Qué cambió?

• /loads → Se agregó CustomerAccessorialsDetails[].
• /trips → Nuevos arreglos de detalle para:
  • Carrier.AccessorialsDetails[]
  • Driver1.AccessorialsDetails[] para conductor y OwnerOperator.
• Cada accesorial incluye:
  • Predeterminado: Id, Type, Total { Amount, Currency }, Rate { Amount, Currency }, RateType, Uom, Quantity
  • Opcional: IsPaid, ECheckNumber, StopId
  • Auditoría: CreatedAt, UpdatedAt, CreatedBy, UpdatedBy
• EChecks ahora se devuelven como parte de los datos del viaje cuando corresponde.
• Cargas/viajes cancelados → No se devuelven detalles de accesoriales.
• Compatibilidad hacia atrás → Los totales heredados siguen disponibles (CustomerAccessorials, Carrier.Accessorials, Linehaul, etc.), por lo que este cambio no es disruptivo.

​

Ejemplo — Accesoriales

{
  "Id": "acc-78901",
  "Type": "Layover Pay",
  "Total": { "Amount": 150.0, "Currency": 840 },
  "Rate": { "Amount": 75.0, "Currency": 840 },
  "RateType": "Time",
  "Uom": "Hour",
  "Quantity": 2.0,
  "ECheckNumber": "12345",
  "CreatedAt": "2024-07-11T14:30:00Z"
}

​

Endpoints afectados

• GET /api/p/v{version}/loads
• POST /api/p/v{version}/loads/search
• GET /api/p/v{version}/trips
• POST /api/p/v{version}/trips/search

​

¿Por qué?

• LoadType ahora aparece en los objetos de carga.
• Valores devueltos: "Revenue" o "Non-Revenue"

• GET /api/p/{version}/loads
• POST /api/p/{version}/loads/search

• Anteriormente, las cargas y viajes eliminados nunca se devolvían.
• Ahora puedes incluir IncludeDeleted (booleano, opcional) en el cuerpo de tu solicitud:
  • true → devuelve registros activos y eliminados.
  • omitido o false → devuelve solo registros activos.
• Cuando IncludeDeleted: true, cada registro devuelto incluye una bandera IsDeleted:
  • "IsDeleted": true para elementos eliminados
  • "IsDeleted": false para elementos activos
• Cuando IncludeDeleted se omite o es false, no aparecen banderas IsDeleted (todos los registros son activos por definición).

• POST /api/p/{version}/loads/search
• POST /api/p/{version}/trips/search

​

🔐 Nueva autenticación

• Ahora obtén el token de acceso mediante auth.alvys.com/oauth/token para mejorar la seguridad y el cumplimiento.
• El método de autenticación antiguo pronto será deshabilitado; actualiza tus credenciales usando las nuevas instrucciones de configuración.

​

🔄 Paginación automatizada

• Todas las consultas ahora gestionan la paginación automáticamente.
• Los conjuntos de datos grandes se cargan por completo, sin registros faltantes ni ajustes manuales.
• Un mecanismo de retardo integrado ayuda a evitar alcanzar los límites de tasa de la API durante las actualizaciones, mejorando la confiabilidad para grandes extracciones de datos.

​

↔️ Expansión de datos anidados

• Las consultas de datos ahora expanden automáticamente hasta 3 niveles de campos anidados.
• Todos los datos relevantes de la API son accesibles sin pasos manuales adicionales.

​

🗓️ Conversión automática de tipos de campos

• Los campos clave, como fechas y números, ahora se convierten automáticamente a los tipos de datos correctos durante la importación (por ejemplo, columnas de fecha a datetime, montos a números).
• Garantiza el filtrado, los cálculos y la visualización correctos en tus informes sin ajustes manuales.

​

📦 Mejoras en los datos de cargas

• Las cargas se importan mediante dos consultas:
  • Importación completa
  • Actualizaciones incrementales
• La deduplicación automática garantiza que solo se conserve la actualización más reciente de cada carga.

​

🧰 Estructura de consulta consistente

• Todos los endpoints (Loads, Trips, Users, etc.) ahora utilizan un patrón unificado de paginación y expansión.
• Hace que el modelo sea más fácil de entender, solucionar problemas y ampliar.

​

📊 Nuevas funciones de DAX e informes

• Se agregaron varias fórmulas DAX básicas (por ejemplo, sumas, conteos o promedios simples) para ayudar a los usuarios a analizar rápidamente y familiarizarse con sus datos.
• Se creó una tabla de informe resumen semanal de muestra: agrega métricas centrales por semana, lo que facilita detectar tendencias a lo largo del tiempo.
• Estos ejemplos están pensados como punto de partida para tu propio análisis; siéntete libre de ajustarlos o ampliarlos según sea necesario.

• Se incluyen instrucciones de configuración paso a paso para guiarte a través de la actualización de credenciales y la carga de datos. Puedes encontrar el enlace al archivo más reciente y una guía rápida de onboarding aquí.

❗️ Nota importante Este cambio puede afectar las métricas en tus informes actuales, como total de viajes, millaje total, tarifa total del transportista, entre otros, a partir de hoy. Si tu lógica de informes incluye filtros o scripts personalizados para excluir automáticamente el viaje original (despachado) cuando una carga se divide, esos filtros ahora pueden quedar obsoletos. Dado que el viaje original ya no se devuelve, continuar excluyéndolo puede provocar un subregistro. Por favor, revisa y actualiza cualquier lógica de informes personalizada en consecuencia para garantizar totales precisos en el futuro.

​

¿Qué hay de nuevo?

​

¿Qué cambió?

• Ahora se debe utilizar un nuevo endpoint de token para generar tokens de acceso:
  POST https://auth.alvys.com/oauth/token
• Los tokens ahora incluyen alcances de permisos (por ejemplo, load:read, trip:create) que definen a qué recursos y acciones puede acceder el cliente
• La aplicación de acceso basado en alcances está habilitada para los tokens generados a través del nuevo endpoint; las solicitudes sin el alcance adecuado devolverán 403 Forbidden
• El endpoint de token heredado {tenant_id} está en desuso y se cerrará el 31 de julio de 2025
  (los tokens de este endpoint no incluyen alcances y por ahora se tratan como de solo lectura)

​

Cómo solicitar un token

{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "audience": "https://api.alvys.com/public/",
  "grant_type": "client_credentials"
}

​

Endpoints afectados:

• ✅ Nuevo (requerido): POST https://auth.alvys.com/oauth/token
• 🛑 Próximamente en desuso: POST /authentication/{tenant_id}/token (se eliminará el 31 de julio de 2025)

❗️ Importante: El endpoint de token heredado POST /authentication/{tenant_id}/token será desactivado permanentemente el 31 de julio de 2025. Todas las integraciones que usen este flujo de autenticación deben actualizarse para utilizar el nuevo endpoint de token antes de esta fecha para evitar interrupciones.

• Linehaul — Costo base de transporte.
• Accessorials — Cargos adicionales (por ejemplo, recargos de combustible, detención).
• TotalPayable — Monto total a pagar al transportista.

❗️ Importante: El campo Rate en el objeto Carrier quedará en desuso en una versión futura. Recomendamos actualizar los reportes e integraciones para utilizar los nuevos campos Linehaul, Accessorials y TotalPayable . Este cambio no ocurrirá de inmediato: habrá un período de transición y proporcionaremos un aviso previo antes de que se elimine el campo. Por favor, revisa tu uso actual y planifica las actualizaciones en consecuencia para garantizar una transición fluida.

• ✅ true para activo
• ❌ false para inactivo.

​

¿Qué hay de nuevo?

​

¿Qué cambió?

GET  /api/p/v{version}/maintenance/{id}
POST /api/p/v{version}/maintenance/search

• Get maintenance record — recupera un único registro por id.
• Search maintenance records — busca y pagina registros.

​

El cuerpo de respuesta incluye

• Core: Id, PO, Reference, Description, Comments
• Classification: Category
• Asset: RelatedAsset (el camión o remolque al que pertenece el registro)
• Financial: Amount (valor + moneda)
• Shop: detalles de RepairShop
• Scheduling: Reminders
• Audit: CreatedAt, CreatedBy, ModifiedAt, ModifiedBy

​

¿Por qué?

• linehaul – Costo base de transporte.
• fuelSurcharge – Ajustes por costo de combustible.
• customerAccessorials – Cargos adicionales como detención o tarifas de lumper.

• Límite aumentado: El número máximo de cargas permitidas en el cuerpo de la solicitud de búsqueda ha aumentado de 50 a 150.
  • Impacto: Los usuarios ahora pueden incluir más IDs de carga en una sola operación de solicitud de búsqueda.
  • Manejo de errores: Las solicitudes que superen los 150 IDs de carga devolverán un mensaje de error.

• Campo DispatcherId: El campo DispatcherId ahora se incluye en el cuerpo de respuesta de todos los endpoints de trips.
  • Propósito: Proporciona el identificador único del despachador asignado al viaje para mejorar el seguimiento de datos y la integración.
  • Beneficios: Mejora la gestión de viajes y la generación de informes al hacer que los datos del despachador sean más accesibles a través de la API.

​

Fecha de lanzamiento: 11 de noviembre de 2024

​

¿Qué hay de nuevo?

1. Endpoints de la Visibility Public API:
   • Introduce endpoints para rastrear ubicaciones de activos y recibir actualizaciones de eventos en tiempo real.
2. Descripción general de los endpoints:
   • Visibilidad entrante (Inbound Visibility):
     • GET /api/p/v{version}/visibility/inbound/{loadNumber}/history: Recupera el historial de actualizaciones de ubicación para un número de carga específico.
   • Visibilidad saliente (Outbound Visibility):
     • GET /api/p/v{version}/visibility/outbound/{loadNumber}/history: Recupera el historial de actualizaciones de eventos enviados para un número de carga específico.
     • POST /api/p/v{version}/visibility/outbound/errors: Busca y reenvía manualmente las actualizaciones fallidas usando un filtro de rango de tiempo.

​

Uso

​

Ejemplo de Visibilidad Entrante

GET /api/p/v{version}/visibility/inbound/{{loadNumber}}/history

​

Ejemplos de Visibilidad Saliente

GET /api/p/v{version}/visibility/outbound/{{loadNumber}}/history

​

Buscar actualizaciones fallidas:

POST /api/p/v{version}/visibility/outbound/errors
{
  "page": 0,
  "pageSize": 10,
  "timeRange": {
    "start": "2024-11-05T16:58:54.450Z",
    "end": "2024-11-11T16:58:54.450Z"
  }
}

​

Recursos adicionales

• Documentación de la API
• Colección de Postman

​

Notas importantes

• Todas las configuraciones relacionadas con EDI deben realizarse dentro de la plataforma. Contacta al equipo de soporte si necesitas asistencia.

​

Fecha de lanzamiento: 08 de noviembre de 2024

​

¿Qué hay de nuevo?

1. Actualización del campocustomerRate.amount:
   • Cambio: El campo customerRate.amount ahora incluye lo siguiente:
     • CustomerLineHaul
     • FuelSurcharge
     • CustomerAccessorials
   • Impacto: Esto garantiza la alineación con el total facturable al cliente mostrado en la UI, mejorando la precisión para la facturación y los informes de ingresos.
2. Propósito:
   • Mejora la claridad y precisión de los cargos de tarifa del cliente.

​

Uso

• El campo customerRate.amount ahora refleja la tarifa total del cliente, incorporando: Linehaul, Fuel Surcharge, Accessorials).

"CustomerRate": {
                "Amount": 5168.0,
                "Currency": 840
            },

​

Endpoints afectados

• GET /api/p/v{version}/loads: Ver documentación
• POST /api/p/v{version}/loads/search: Ver documentación

​

Nota importante

​

Fecha de lanzamiento: 11 de noviembre de 2024

​

¿Qué hay de nuevo?

1. Nuevos endpoints GET y POST introducidos:
   • Endpoint GET:
     • /api/p/v{version}/customers: Recupera perfiles detallados de clientes, incluida la información de contacto y los datos asociados, por id o companyNumber.
     Ejemplo de solicitud:
     GET /api/p/v{version}/customers?id=12345
     //or
     //GET /api/p/v{version}/customers?companyNumber=12345
     
   • Endpoint POST:
     • /api/p/v{version}/customers/search: Admite búsquedas filtradas avanzadas de registros de clientes por estado o rango de fechas. Incluye paginación para un acceso optimizado a los datos.
     Ejemplo de solicitud:
     POST /api/p/v{version}/customers/search
     {
       "page": 0,
       "pageSize": 100,
       "statuses": [
         "Active"
       ],
       "createdDateRange": {
     //     "start": "2024-11-08T19:38:34.529Z",
     //     "end": "2024-11-08T19:38:34.529Z"
       }
     }