Saltar a contenido

API: Lockers

El API público permite consultar casilleros (lockers) y registrar un almacenamiento con códigos para depositar y retirar un paquete. Un conjunto de casilleros se identifica mediante bay_id; cada casillero tiene su propio id.

Se utiliza HTTPS y la autenticación del API: API key como usuario y contraseña del usuario como password.

Flujo de integración

  1. Consultar los lockers con status=available, aplicando los filtros de ubicación y dimensiones necesarios.
  2. Registrar el almacenamiento con el locker_id seleccionado. Se pueden enviar códigos propios o dejar que el sistema los genere.
  3. Conservar los códigos devueltos: dropoff_code permite depositar el paquete y pickup_code permite retirarlo.

Registrar un almacenamiento marca el locker como unavailable. Al completarse el retiro mediante el sistema de lockers, vuelve a available.

Esta página describe únicamente las operaciones del API público; no incluye rutas internas de administración o apertura.

M: Listar lockers

HTTP GET:
https://<hostname>/api/locker

Devuelve los lockers de la cuenta del usuario autenticado. Por defecto, no incluye lockers desactivados.

URL PARAMETERS:

Todos los parámetros son opcionales. Los filtros enviados se combinan: un locker debe cumplir todas las condiciones indicadas.

Campo Tipo Descripción
status string available (disponible) o unavailable (no disponible).
bay_ids Lista de números Identificadores de conjuntos de lockers, separados por coma. Ejemplo: 12,13.
imei string IMEI del dispositivo del conjunto de lockers.
poi_ids Lista de números Identificadores de las geocercas asociadas a los conjuntos, separados por coma.
min_height_cm Numérico Altura mínima del locker, en centímetros. Incluye el valor indicado.
min_width_cm Numérico Ancho mínimo del locker, en centímetros. Incluye el valor indicado.
min_depth_cm Numérico Profundidad mínima del locker, en centímetros. Incluye el valor indicado.
page Entero Número de página, comenzando en 1. Si se omite, no se activa la paginación por número de página.
page_size Entero Cantidad de elementos por página. Se utiliza junto con page; su valor predeterminado es 10. Enviar solo page_size no activa la paginación.
sort_by string Campos de ordenamiento separados por coma. Por ejemplo: id o height_cm,width_cm.
sort_direction string Dirección del ordenamiento: asc o desc.
changed_since_datetime_iso Fecha y hora ISO 8601 Devuelve lockers modificados desde la fecha indicada, inclusive. Si se envía, incluye desactivados salvo que se indique include_deactivated=false.
include_deactivated boolean true para incluir lockers desactivados; false para excluirlos.

Parámetros de esta operación

Esta operación utiliza page y sort_direction, no page_num ni sort_dir. Los filtros se envían directamente con los nombres de esta tabla; no utiliza los parámetros genéricos filter_by, filter_values o filter_comp.

OUTPUT:

La respuesta contiene la lista de la página solicitada, sin un total de resultados ni metadatos de paginación.

EJEMPLO CON CURL:
curl -u '<api_key>:<password>' \
  --get 'https://<hostname>/api/locker' \
  --data-urlencode 'status=available' \
  --data-urlencode 'bay_ids=12,13' \
  --data-urlencode 'min_height_cm=30' \
  --data-urlencode 'min_width_cm=20' \
  --data-urlencode 'min_depth_cm=40' \
  --data-urlencode 'page=1' \
  --data-urlencode 'page_size=20' \
  --data-urlencode 'sort_by=id' \
  --data-urlencode 'sort_direction=asc'
RESPUESTA:
{
  "success": true,
  "data": [
    {
      "id": 101,
      "height_cm": 40,
      "width_cm": 30,
      "depth_cm": 50,
      "channel": 1,
      "address": 2,
      "bay_id": 12,
      "status": "available",
      "is_deactivated": false
    }
  ]
}

M: Registrar un almacenamiento

HTTP POST:
https://<hostname>/api/locker-storage

Registra los códigos de depósito y retiro para un locker de la cuenta del usuario autenticado.

BODY PARAMETERS:

Enviar Content-Type: application/json. El cuerpo puede ser un objeto o una lista de objetos.

Campo Tipo Requerido Descripción
locker_id Numérico sí Identificador del locker obtenido al listar lockers. No es el bay_id.
job_id Numérico no Identificador de una tarea asociada al almacenamiento.
dropoff_code string no Código de depósito, de hasta 31 caracteres alfanuméricos. Si se omite o está vacío, se genera automáticamente.
pickup_code string no Código de retiro, de hasta 31 caracteres alfanuméricos. Si se omite o está vacío, se genera automáticamente.
notes string no Notas del almacenamiento.

Los códigos generados contienen 10 caracteres hexadecimales en mayúsculas. Al enviar códigos propios, utilizar códigos distintos para depósito y retiro y evitar códigos que ya estén en uso en almacenamientos activos del mismo conjunto de lockers. Si un código enviado ya está en uso, la operación reporta el error duplicated_code en el campo correspondiente.

Reemplazo del almacenamiento anterior

Registrar un almacenamiento desactiva los almacenamientos activos anteriores del mismo locker y lo marca como unavailable. No es una operación que rechace automáticamente un locker ocupado: comprobar la disponibilidad antes de registrar y evitar registros duplicados o reintentos ciegos, ya que cada solicitud crea un nuevo almacenamiento.

OUTPUT:
EJEMPLO CON CURL:

Registrar un almacenamiento y generar ambos códigos automáticamente:

curl -u '<api_key>:<password>' \
  -X POST 'https://<hostname>/api/locker-storage' \
  -H 'Content-Type: application/json' \
  --data '{"locker_id":101,"job_id":5001,"notes":"Pedido 12345"}'
RESPUESTA:
{
  "success": true,
  "data": [
    {
      "id": 701,
      "locker_id": 101,
      "job_id": 5001,
      "dropoff_code": "A1B2C3D4E5",
      "pickup_code": "F6A7B8C9D0",
      "notes": "Pedido 12345",
      "dropoff_datetime_iso": null,
      "pickup_datetime_iso": null,
      "is_deactivated": false
    }
  ]
}

Registro de múltiples almacenamientos

Enviar una lista JSON para registrar varios almacenamientos en una solicitud:

curl -u '<api_key>:<password>' \
  -X POST 'https://<hostname>/api/locker-storage' \
  -H 'Content-Type: application/json' \
  --data '[
    {"locker_id":101,"dropoff_code":"DEPOSITO101","pickup_code":"RETIRO101","notes":"Pedido 12345"},
    {"locker_id":102,"notes":"Pedido 12346"}
  ]'

Cada elemento se procesa en su propia transacción. Si alguno falla, otros elementos pueden haber quedado registrados aunque la respuesta indique un error. Revisar los detalles por índice antes de reintentar; no asumir que se revirtió toda la lista.

O: Locker Data Object

Todos los campos son de solo lectura en el API público.

Campo Tipo Descripción
id Numérico Identificador del locker. Se utiliza como locker_id al registrar un almacenamiento.
height_cm Numérico Altura en centímetros.
width_cm Numérico Ancho en centímetros.
depth_cm Numérico Profundidad en centímetros.
channel Numérico Canal del locker dentro del conjunto.
address Numérico Dirección del locker dentro del conjunto.
bay_id Numérico Identificador del conjunto al que pertenece el locker.
status string available o unavailable.
is_deactivated boolean Indica si el locker está desactivado. Es independiente de su disponibilidad.

O: Locker Storage Data Object

Campo Tipo Solo lectura Descripción
id Numérico sí Identificador del almacenamiento creado.
locker_id Numérico no Identificador del locker.
job_id Numérico o null no Identificador de la tarea asociada, si se indicó.
dropoff_code string no Código para depositar el paquete.
pickup_code string no Código para retirar el paquete.
notes string o null no Notas del almacenamiento.
dropoff_datetime_iso Fecha y hora ISO 8601 o null sí Fecha del depósito; inicialmente null.
pickup_datetime_iso Fecha y hora ISO 8601 o null sí Fecha del retiro; inicialmente null.
is_deactivated boolean sí Indica si el almacenamiento dejó de estar activo.

Los ejemplos de respuesta son ilustrativos. Los identificadores y códigos reales se obtienen de cada respuesta; no utilizar los códigos de ejemplo para una integración.