API de Carregamento

Comece rapidamente

1. Faça login → clique no seu nome → API → gere uma chave.
2. Envie um trabalho de carregamento (este é executado no sandbox — gratuito em todos os planos):

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

Consulte o status_url (com o mesmo cabeçalho de autenticação) até que status seja "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 da resposta

O objeto result de um trabalho concluído:

Versionamento e estabilidade

O contrato é versionado no caminho (/api/v1/). Dentro da v1, as alterações são apenas aditivas — novos campos opcionais na solicitação, novos campos na resposta, novos códigos de veículos e códigos de erro podem ser adicionados, e os clientes devem ignorar campos que não reconhecem. Campos existentes nunca mudam de significado ou tipo, e nada é removido. Uma mudança incompatível resulta em um novo caminho de versão, com a v1 mantida em paralelo por pelo menos 12 meses e aviso de descontinuação enviado por e-mail para todos os workspaces com uma chave ativa.

Campos da solicitação

Campos dos itens

Códigos de veículos

Gerados a partir das especificações do mecanismo ativo. Veículos personalizados da frota do seu workspace funcionam via custom_vehicle_id.

Caminhões e reboques

Contêineres

Níveis de acesso e limites

Apenas carregamentos bem-sucedidos são contabilizados — validações e jobs com falha nunca são cobrados na cota. Ambos os contadores são reiniciados no dia 1º (UTC). Os resultados da sandbox são completos e sem limitações — os limites são a barreira, não o resultado. Precisa de mais de 5.000 carregamentos por mês? Fale conosco sobre preços para volumes elevados e licenciamento OEM.

Webhooks

Passe callback_url para receber o resultado via POST quando o trabalho for concluído. Cada callback inclui X-Hansatic-Signature: um HMAC-SHA256 do corpo bruto com o segredo do webhook da sua chave (exibido uma vez na criação da chave). Verifique-o:

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));
}

A entrega é feita em uma única tentativa com timeout de 5s — o status_url permanece sempre como a fonte da verdade.

Erros

Todos os erros seguem o formato { "error": { "code", "message", ... } } — código legível por máquina, mensagem legível por humanos e field quando um campo específico da entrada está incorreto.