Volver a noticias

Cómo conectar TSC con ERP, WMS o portería mediante OData y API

Pavel NOVOTNÝ
Blog
Cómo conectar TSC con ERP, WMS o portería mediante OData y API

Conectar un sistema de reservas con un ERP, WMS o una aplicación de portería no tiene por qué comenzar como un gran proyecto de integración. Para un caso práctico en el acceso bastan cuatro llamadas a la API: obtener un token Bearer, localizar la reserva por su número, registrar la llegada y, más tarde, registrar la salida.

El personal de portería no necesita conocer el identificador interno de la reserva en Time Slot Control. Trabaja con un dato que el conductor ya tiene en la confirmación o en el código QR: ReservationNumber. TSC devuelve mediante OData el registro correspondiente y su identificador Id; ese mismo identificador Id se utiliza después en las acciones de estado.

OData y API: dos partes de una misma interfaz

Time Slot Control combina el estándar OData v4 con endpoints de API convencionales. La distribución de responsabilidades es sencilla:

  • el endpoint de autenticación emite un token JWT Bearer,
  • OData permite filtrar y cargar únicamente los datos necesarios,
  • las acciones OData vinculadas ejecutan un paso concreto del proceso, por ejemplo GateArrival o GateDeparture.

Por tanto, el token no se obtiene mediante una “consulta OData”. Lo emite el endpoint de autenticación de la misma API de TSC y luego se envía en el encabezado de cada solicitud OData. ERP y WMS también pueden consultar mediante OData las empresas, los pedidos y las líneas de pedido; IntegrationId permite relacionar los identificadores de TSC con las claves del sistema de origen.

Cinco pasos para conectar la portería con Time Slot Control: número de reserva, token Bearer, consulta OData, llegada y salida

Caso práctico: la portería registra la entrada y la salida

El conductor llega a la portería y presenta el número de reserva. El personal lo escanea o lo introduce en la aplicación existente. La aplicación verifica la reserva en TSC, puede comparar la matrícula, el transportista y la hora planificada y, una vez autorizado el acceso, registra que el transportista se encuentra en las instalaciones. A la salida utiliza el mismo identificador Id y marca que el transportista ha abandonado el recinto.

Los siguientes ejemplos utilizan el sandbox disponible en https://api.tscsandbox.com. Sustituya el marcador {tenant} por el nombre de su entorno. La API de producción tiene la misma estructura en https://api.timeslotcontrol.com.

Antes de comenzar

Cree en TSC una cuenta de API dedicada. La cuenta necesita el rol de acceso a la API y únicamente los permisos que la integración utilizará de verdad—en particular, la lectura de reservas y la ejecución de las acciones de llegada y salida. No almacene la contraseña directamente en el código fuente; utilice un gestor de secretos o la configuración segura de la plataforma de integración.

1. Obtenga un token Bearer

curl -X POST "https://api.tscsandbox.com/v1/{tenant}/Token" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "Username": "api-gatehouse@example.com",
    "Password": "<secret-from-vault>"
  }'

La respuesta contiene el token:

{
  "token": "eyJhbGciOi..."
}

Utilice este valor en las llamadas posteriores como Authorization: Bearer <token>. No hace falta crear un token para cada vehículo. La integración puede conservarlo de forma segura en memoria y renovarlo cuando caduque o después de una respuesta 401 Unauthorized.

2. Consulte la reserva por ReservationNumber

Un filtro OData localiza la reserva por su número. Mediante $select, la aplicación de portería carga solo los campos que necesita:

curl --get "https://api.tscsandbox.com/odata/v1/{tenant}/Reservation" \
  -H "Authorization: Bearer ${TOKEN}" \
  --data-urlencode "\$filter=ReservationNumber eq 'R-2026-00421'" \
  --data-urlencode "\$select=Id,ReservationNumber,VehicleNumberPlate,Carrier,Start,End,RealGateVehicleArrival,RealGateVehicleDeparture" \
  --data-urlencode "\$top=2"

Una respuesta típica contiene un envoltorio OData y el arreglo value:

{
  "@odata.context": "https://api.tscsandbox.com/odata/v1/{tenant}/$metadata#Reservation(...)" ,
  "value": [
    {
      "Id": "37efcb13-f1cb-4a61-baea-adfb4337036f",
      "ReservationNumber": "R-2026-00421",
      "VehicleNumberPlate": "1AB2345",
      "Carrier": "Example Carrier",
      "Start": "2026-09-01T12:30:00Z",
      "End": "2026-09-01T13:30:00Z",
      "RealGateVehicleArrival": null,
      "RealGateVehicleDeparture": null
    }
  ]
}

En producción, continúe únicamente si la consulta devuelve exactamente un registro y este cumple las reglas operativas. Si no hay resultados, derive el caso a una revisión manual. Si la consulta devuelve varios registros, la integración no debe seleccionar automáticamente el primero. El uso de $top=2 permite detectar esta situación con poco costo.

3. Marque al transportista como presente en las instalaciones

Después de verificar la reserva, utilice el identificador devuelto Id en la acción vinculada GateArrival:

curl -X PUT \
  "https://api.tscsandbox.com/odata/v1/{tenant}/Reservation(37efcb13-f1cb-4a61-baea-adfb4337036f)/GateArrival" \
  -H "Authorization: Bearer ${TOKEN}"

Una llamada correcta devuelve 204 No Content. TSC guarda la hora real de llegada y el cambio aparece de inmediato en la reserva. Los flujos de trabajo, notificaciones e integraciones posteriores pueden seguir la configuración habitual del entorno del cliente.

4. Marque la salida del transportista

En la salida, la aplicación utiliza el mismo identificador Id. El valor null indica a TSC que debe utilizar la hora actual del servidor:

curl -X PUT \
  "https://api.tscsandbox.com/odata/v1/{tenant}/Reservation(37efcb13-f1cb-4a61-baea-adfb4337036f)/GateDeparture" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "GateDepartureDateTime": null }'

Si el dispositivo de integración dispone de una hora de evento propia y confiable, puede enviar un valor UTC en formato ISO 8601 en lugar de null, por ejemplo 2026-09-01T14:32:00Z. Una llamada correcta vuelve a devolver 204 No Content.

Ejemplo mínimo completo en PowerShell

El mismo procedimiento puede expresarse en un script breve. En la práctica, las llamadas de llegada y salida se ejecutan en momentos distintos, pero ambas utilizan el mismo identificador de reserva Id:

$baseUri = 'https://api.tscsandbox.com'
$tenant = '<tenant>'
$reservationNumber = 'R-2026-00421'

$tokenResponse = Invoke-RestMethod `
  -Method Post `
  -Uri "$baseUri/v1/$tenant/Token" `
  -ContentType 'application/json' `
  -Body (@{
    Username = 'api-gatehouse@example.com'
    Password = '<secret-from-vault>'
  } | ConvertTo-Json)

$headers = @{
  Authorization = "Bearer $($tokenResponse.token)"
}

$safeNumber = $reservationNumber.Replace("'", "''")
$filter = [Uri]::EscapeDataString("ReservationNumber eq '$safeNumber'")
$select = 'Id,ReservationNumber,VehicleNumberPlate,Carrier,RealGateVehicleArrival,RealGateVehicleDeparture'
$queryUri = "$baseUri/odata/v1/$tenant/Reservation?`$filter=$filter&`$select=$select&`$top=2"
$result = Invoke-RestMethod -Method Get -Uri $queryUri -Headers $headers
$reservations = @($result.value)

if ($reservations.Count -ne 1) {
  throw "Expected exactly one reservation, returned: $($reservations.Count)."
}

$reservationId = $reservations[0].Id

# When entry is permitted
Invoke-RestMethod `
  -Method Put `
  -Uri "$baseUri/odata/v1/$tenant/Reservation($reservationId)/GateArrival" `
  -Headers $headers

# Later, at the exit
Invoke-RestMethod `
  -Method Put `
  -Uri "$baseUri/odata/v1/$tenant/Reservation($reservationId)/GateDeparture" `
  -Headers $headers `
  -ContentType 'application/json' `
  -Body (@{ GateDepartureDateTime = $null } | ConvertTo-Json)

El ejemplo no contiene deliberadamente una contraseña real, un tenant concreto ni datos de clientes. Una aplicación de producción también debe incorporar almacenamiento seguro de secretos, tiempos de espera, reintentos controlados, registro del identificador de correlación y tratamiento de 401, 403, 404, 429 y otras respuestas de error.

Por qué el mismo patrón funciona para ERP y WMS

La portería es un ejemplo claro porque el resultado se ve de inmediato. El mismo principio también funciona dentro de un ERP o WMS:

  • el ERP puede sincronizar empresas, pedidos y líneas de pedido mediante OData,
  • el WMS puede cargar la reserva actual y preparar un muelle o una operación de almacén,
  • la portería puede registrar llegada y salida sin cambiar a otra aplicación,
  • las herramientas de BI pueden leer horas planificadas y reales para analizar esperas y capacidad de paso por las instalaciones,
  • los webhooks salientes pueden informar de los cambios a los sistemas posteriores sin consultas periódicas.

La integración no necesita copiar todo el modelo de datos. Cada sistema carga únicamente la información necesaria para su paso, mientras TSC sigue siendo la fuente autorizada de la reserva y sus hitos logísticos.

Del prototipo a una operación segura

Valide la primera versión en el sandbox. La documentación interactiva de la API en api.tscsandbox.com permite explorar endpoints, introducir un token Bearer y obtener ejemplos de llamadas al instante. El procedimiento exacto de acceso se describe en la referencia de autenticación, y la guía de OData explica las opciones de filtrado.

Para producción, siga algunas reglas: una cuenta dedicada por integración, los permisos mínimos necesarios, la contraseña en un almacén seguro, reutilización del token mientras sea válido, exigencia de un único resultado y tratamiento explícito de cada error. Diseñe las llamadas de llegada y salida para que puedan repetirse de forma segura—tras el éxito, guarde el identificador Id; si el resultado es incierto, consulte primero el estado actual de la reserva.

Un número de reserva, un estado actual en todo el proceso

El mayor beneficio no son las cuatro solicitudes HTTP en sí. Lo importante es que la portería, el almacén, el equipo de planificación y el ERP trabajan con la misma reserva y las mismas marcas de tiempo. Desaparecen la transcripción manual, la verificación telefónica y las actualizaciones tardías de estado.

Descubra más opciones en la página API & Integraciones de Time Slot Control. Para probar un caso similar con su ERP, WMS, escáner o portería, empiece por un proceso concreto en el sandbox. La primera conexión funcional suele requerir solo unas pocas llamadas a la API claramente definidas.

Volver a noticias