API de Embalaje

Primeros pasos

1. Inicia sesión → haz clic en tu nombre → API → genera una clave.
2. Envía un trabajo de embalaje (este se ejecuta en el entorno de pruebas — gratuito en todos los planes):

curl -X POST https://hansatic.com/api/v1/pack \
  -H "Authorization: Bearer hk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "vehicle": "CURTAINSIDER_136",
    "objective": "ldm",
    "sandbox": true,
    "items": [{
      "name": "Machine crate",
      "length": 2300, "width": 750, "height": 1400,
      "weight": 300, "quantity": 7,
      "stackable": false, "tiltable": false
    }]
  }'

{
  "job_id": "5e3617d1-abe4-4549-b7e6-d18c6baf814f",
  "status": "queued",
  "sandbox": true,
  "status_url": "https://hansatic.com/api/v1/jobs/5e3617d1-..."
}

Consulta status_url (con el mismo encabezado de autenticación) hasta que status sea "done":

{
  "job_id": "5e3617d1-...",
  "status": "done",
  "result": {
    "placed_count": 7,
    "unplaced_count": 0,
    "units": "metric",
    "metrics": {
      "ldm_m": 5.25,
      "span_mm": 5250,
      "linear_ft": 17.2,
      "pallet_positions_eur": 14,
      "total_weight_kg": 2100,
      "overlaps": 0
    },
    "items": [
      { "id": "...", "name": "Machine crate", "placed": true,
        "x": 8370, "y": 0, "z": 0,
        "rotation_deg": 90, "tilt_deg": 0, "...": "..." }
    ],
    "plan_url": "https://hansatic.com/en/app/plans/..."
  }
}

Endpoints

Campos de respuesta

El objeto result de un trabajo finalizado:

Versionado y estabilidad

El contrato se versiona en la ruta (/api/v1/). Dentro de v1, los cambios son solo aditivos: nuevos campos opcionales en la solicitud, nuevos campos en la respuesta, nuevos códigos de vehículos y códigos de error pueden aparecer, y los clientes deben ignorar los campos que no reconozcan. Los campos existentes nunca cambian de significado o tipo, y nada se elimina. Un cambio disruptivo implica una nueva ruta de versión, con v1 mantenido en paralelo durante al menos 12 meses y notificación de obsolescencia por correo electrónico a cada espacio de trabajo con una clave activa.

Campos de solicitud

Campos de artículos

Códigos de vehículos

Generados a partir de las especificaciones del motor en tiempo real. Los vehículos personalizados de tu flota en el espacio de trabajo funcionan mediante custom_vehicle_id.

Camiones y remolques

Contenedores

Niveles de acceso y límites

Solo se contabilizan los empaques exitosos — las validaciones fallidas y los trabajos fallidos nunca se descuentan de la cuota. Ambos contadores se reinician el día 1 (UTC). Los resultados en el entorno de pruebas son completos y sin restricciones — los límites son la barrera, no el resultado. ¿Necesita más de 5.000 empaques al mes? Consulte con nosotros sobre precios por volumen y OEM.

Webhooks

Proporciona callback_url para recibir el resultado mediante POST cuando el trabajo finalice. Cada llamada incluye X-Hansatic-Signature: un HMAC-SHA256 del cuerpo sin procesar con el secreto de webhook de tu clave (mostrado una vez al crear la clave). Verifícalo:

const crypto = require('crypto');

function verify(rawBody, signatureHeader, webhookSecret) {
  const expected = crypto.createHmac('sha256', webhookSecret)
    .update(rawBody).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected), Buffer.from(signatureHeader));
}

El envío se realiza en un solo intento con un tiempo de espera de 5 s — status_url sigue siendo la fuente de verdad.

Errores

Todos los errores tienen la forma { "error": { "code", "message", ... } }: código legible por máquina, mensaje legible por humanos y field cuando un campo de entrada específico es el problema.