osrmroute
DocumentaçãoInício rápido
Documentação da API

API de planejamento de cargas e integração 3D

Envie uma lista de carga pela API REST, obtenha as posições e etapas de carregamento e exiba o modelo 3D verificado no seu aplicativo.

Tarifas de planejamento de carga 3D

Cada operação tem um preço total em créditos comprados. Um plano completo verificado ou um plano parcial autorizado é cobrado conforme as regras da operação. A reserva é liberada quando o cálculo termina sem um resultado cobrável.

Tarifas de planejamento de carga 3D
MóduloCréditos por operação
Plano de carga padrãoPOST /api/v1/load-plans30 créditos
Revisão manual do posicionamentoPOST /api/v1/load-plans/{id}/placement-revisions5 créditos
Planeamento de paletesPOST /api/v1/load-plans/palletize30 créditos
Comparação de equipamentosPOST /api/v1/load-plans/compare40 créditos
Plano de carga com várias paradasPOST /api/v1/load-plans/multi-stop50 créditos
Lista de carga grandeDe 129 a 256 unidades por planoPOST /api/v1/load-plans/bulk50 créditos
Distribuição por vários veículosPOST /api/v1/load-plans/fleet70 créditos
Comparação de veículos e rotasPOST /api/v1/load-plans/dispatch100 créditos
Carga de paletes no caminhãoPOST /api/v1/load-plans/fulfillment60 créditos
Simulação de envios anterioresPOST /api/v1/load-plans/simulation200 créditos
Planejamento de caixasPOST /api/v1/load-plans/packaging30 créditos

A prévia do posicionamento e a exportação do resultado verificado não consomem créditos adicionais. Salvar uma revisão verificada de posicionamento tem um preço próprio.

Consulte as tarifas vigentes antes de enviar o trabalho. Para um módulo com preço próprio, envie o preço atual em créditos no cabeçalho Confirm-Load-Credits. Um preço null indica que a operação está indisponível.

GET /api/v1/load-plans/prices
curl --fail -H "Authorization: Bearer $OSRM_API_KEY" https://osrmroute.com/api/v1/load-plans/prices

Enviar um trabalho sintético

  1. Crie uma chave de API de produção vinculada ao projeto com acesso route. Envie a chave do seu servidor como token Bearer.
  2. Use unidades consistentes na lista JSON. Informe a abertura, as dimensões internas e a capacidade de carga, depois os tamanhos, os pesos, as quantidades, as orientações e as paradas.
  3. Defina Idempotency-Key antes do envio. Guarde o ID do trabalho da resposta 202. Se a resposta for perdida, repita a mesma solicitação com a mesma chave. Respeite Retry-After nas consultas de status.
POST /api/v1/load-plans
curl -i -X POST "https://osrmroute.com/api/v1/load-plans" \
  -H "Authorization: Bearer $OSRM_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: synthetic-truck-01' \
  --data-binary @truck.json
truck.json
{
  "units": {
    "length": "mm",
    "mass": "kg"
  },
  "equipment": {
    "id": "synthetic-truck",
    "kind": "truck",
    "source": "template",
    "inside": [
      6000,
      2400,
      2400
    ],
    "outside": [
      7200,
      2500,
      3600
    ],
    "door": {
      "left": 25,
      "width": 2350,
      "height": 2300
    },
    "payload": 8000,
    "tare": 6500,
    "clearance": 25,
    "obstacles": []
  },
  "stops": [
    "s1",
    "s2"
  ],
  "items": [
    {
      "id": "p1",
      "size": [
        1200,
        800,
        1100
      ],
      "mass": 350,
      "quantity": 1,
      "stopId": "s1",
      "orientations": [
        "lwh",
        "wlh"
      ],
      "stacking": "floor_only"
    },
    {
      "id": "p2",
      "size": [
        1200,
        800,
        1100
      ],
      "mass": 350,
      "quantity": 1,
      "stopId": "s2",
      "orientations": [
        "lwh",
        "wlh"
      ],
      "stacking": "floor_only"
    }
  ],
  "allowPartial": false
}
mixed-stack.json
{
  "units": {
    "length": "mm",
    "mass": "kg"
  },
  "equipment": {
    "id": "synthetic-compact-truck",
    "kind": "truck",
    "source": "template",
    "inside": [
      2400,
      1000,
      1500
    ],
    "outside": [
      3000,
      1200,
      1800
    ],
    "door": {
      "left": 0,
      "width": 1000,
      "height": 1500
    },
    "payload": 1000,
    "tare": 600,
    "clearance": 0,
    "obstacles": []
  },
  "stops": [
    "first",
    "second"
  ],
  "items": [
    {
      "id": "small",
      "size": [
        800,
        650,
        400
      ],
      "mass": 70,
      "quantity": 2,
      "stopId": "first",
      "orientations": [
        "lwh"
      ],
      "stacking": "stackable"
    },
    {
      "id": "medium",
      "size": [
        1050,
        850,
        450
      ],
      "mass": 90,
      "quantity": 2,
      "stopId": "first",
      "orientations": [
        "lwh"
      ],
      "stacking": "stackable",
      "maxTopMass": 100
    },
    {
      "id": "base",
      "size": [
        1200,
        1000,
        600
      ],
      "mass": 160,
      "quantity": 2,
      "stopId": "second",
      "orientations": [
        "lwh"
      ],
      "stacking": "floor_only",
      "maxTopMass": 180
    }
  ],
  "allowPartial": false
}

Ler o resultado

Um trabalho concluído pode devolver um plano verificado, uma prova de impossibilidade, nenhum plano encontrado ou um limite de pesquisa. A carga parcial exige consentimento explícito.

Verifique result.status e billing.status separadamente. Um trabalho concluído pode não ter um posicionamento utilizável. Se permitir um resultado parcial, revise as unidades não alocadas antes do despacho.

Consulte o estado com GET e o identificador retornado. Cancel solicita o cancelamento de um trabalho em fila ou em execução. DELETE exclui a entrada e o resultado armazenados de um trabalho em estado terminal.

GET /api/v1/load-plans/{id}
curl --include -H "Authorization: Bearer $OSRM_API_KEY" \
  "https://osrmroute.com/api/v1/load-plans/$JOB_ID"
  • GET /api/v1/load-plans/{id}
  • POST /api/v1/load-plans/{id}/cancel
  • DELETE /api/v1/load-plans/{id}

A exportação exige um plano verificado e permissão para exportar. A ficha é baixada em HTML, a tabela em CSV e o modelo 3D em GLB.

  • GET /api/v1/load-plans/{id}/worksheet
  • GET /api/v1/load-plans/{id}/csv

Para rever um trabalho terminado, envie o manifesto atualizado com Revises-Load-Plan e uma nova chave de idempotência. A revisão verificada mais recente pode ser exportada.

O cálculo usa as medidas e restrições informadas. Antes de movimentar a carga, confirme com o operador as dimensões reais, as folgas, a amarração, os limites por eixo e as regras aplicáveis.

Comparação de equipamentos, frota e paletes

O servidor da empresa usa a chave do projeto, consulta o preço e coloca o pedido confirmado em fila.

  • GET /api/v1/load-plans/prices
  • POST /api/v1/load-plans/import-preview
  • POST /api/v1/load-plans/compare
  • POST /api/v1/load-plans/fleet
  • POST /api/v1/load-plans/palletize
  • POST /api/v1/load-plans/multi-stop
  • POST /api/v1/load-plans/bulk
  • POST /api/v1/load-plans/packaging
  • POST /api/v1/load-plans/dispatch · Comparação de veículos e rotas
  • POST /api/v1/load-plans/fulfillment · Carga de paletes no caminhão
  • GET, POST /api/v1/load-plans/{id}/warehouse · Operação de armazém
  • POST /api/v1/load-plans/simulation · Simulação de envios anteriores
  • GET /api/v1/load-plans/{id}/simulation-report · CSV
  • GET /api/v1/load-plans/partner · Projeto de parceiro
  • POST /api/v1/load-plans/{id}/axle-estimate
  • GET /api/v1/load-plans/webhook/events
  • POST /api/v1/load-plans/{id}/placement-preview
  • POST /api/v1/load-plans/{id}/placement-revisions
  • GET /api/v1/load-plans/{id}/pdf
  • GET /api/v1/load-plans/{id}/xlsx
  • POST /api/v1/load-plans/{id}/share
  • GET /api/v1/load-plans/workspace/{kind}

Planejamento de caixas

Envie as dimensões e os pesos dos itens do pedido. Escolha uma caixa do catálogo, sugira novas medidas ou calcule quantas unidades iguais cabem.

Consulte as tarifas vigentes antes de enviar o trabalho. Para um módulo com preço próprio, envie o preço atual em créditos no cabeçalho Confirm-Load-Credits. Um preço null indica que a operação está indisponível.

POST /api/v1/load-plans/packaging
curl --fail-with-body -X POST "https://osrmroute.com/api/v1/load-plans/packaging" \
  -H "Authorization: Bearer $OSRM_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Confirm-Load-Credits: $CONFIRMED_CREDITS" \
  --data-binary @packaging.json
packaging.json
{
  "operation": "choose_carton",
  "units": {
    "length": "mm",
    "mass": "g"
  },
  "stops": [
    "order"
  ],
  "items": [
    {
      "id": "sku",
      "size": [
        50,
        50,
        50
      ],
      "mass": 100,
      "quantity": 2,
      "stopId": "order",
      "orientations": [
        "lwh"
      ],
      "stacking": "floor_only"
    }
  ],
  "cartons": [
    {
      "id": "standard",
      "inside": [
        110,
        110,
        110
      ],
      "payload": 1000,
      "tare": 10
    }
  ]
}

Comparação de veículos e rotas

Compare um caminhão e uma frota para o mesmo envio. Confira o encaixe, a distância, o tempo, o custo com suas tarifas e o número de veículos. A rota depende da cobertura Truck Routing.

Consulte as tarifas vigentes antes de enviar o trabalho. Para um módulo com preço próprio, envie o preço atual em créditos no cabeçalho Confirm-Load-Credits. Um preço null indica que a operação está indisponível.

POST /api/v1/load-plans/dispatch
curl --fail-with-body -X POST "https://osrmroute.com/api/v1/load-plans/dispatch" \
  -H "Authorization: Bearer $OSRM_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Confirm-Load-Credits: $CONFIRMED_CREDITS" \
  --data-binary @dispatch.json
dispatch.json
{
  "manifest": {
    "units": {
      "length": "mm",
      "mass": "kg"
    },
    "stops": [
      "s1"
    ],
    "items": [
      {
        "id": "p1",
        "size": [
          1200,
          800,
          1100
        ],
        "mass": 350,
        "quantity": 1,
        "stopId": "s1",
        "orientations": [
          "lwh",
          "wlh"
        ],
        "stacking": "floor_only"
      }
    ],
    "allowPartial": false
  },
  "currency": "USD",
  "points": [
    [
      49.865,
      40.405
    ],
    [
      49.902,
      40.421
    ]
  ],
  "alternatives": [
    {
      "id": "standard",
      "vehicles": [
        {
          "equipment": {
            "id": "synthetic-truck",
            "kind": "truck",
            "source": "template",
            "inside": [
              6000,
              2400,
              2400
            ],
            "outside": [
              7200,
              2500,
              3600
            ],
            "door": {
              "left": 25,
              "width": 2350,
              "height": 2300
            },
            "payload": 8000,
            "tare": 6500,
            "clearance": 25,
            "obstacles": []
          },
          "vehicle": {
            "height_m": 3.6,
            "width_m": 2.5,
            "length_m": 7.2,
            "weight_t": 14.5,
            "axle_load_t": 8,
            "axle_count": 2
          },
          "baseMinor": 850,
          "perKilometerMinor": 160
        }
      ]
    }
  ]
}

Carga de paletes no caminhão

Agrupe os itens em paletes e carregue os paletes no caminhão. Veja conteúdo, cena 3D e ordem de carga. Operadores podem ler códigos de barras e registrar exceções por revisão.

Consulte as tarifas vigentes antes de enviar o trabalho. Para um módulo com preço próprio, envie o preço atual em créditos no cabeçalho Confirm-Load-Credits. Um preço null indica que a operação está indisponível.

POST /api/v1/load-plans/fulfillment
curl --fail-with-body -X POST "https://osrmroute.com/api/v1/load-plans/fulfillment" \
  -H "Authorization: Bearer $OSRM_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Confirm-Load-Credits: $CONFIRMED_CREDITS" \
  --data-binary @fulfillment.json
fulfillment.json
{
  "pallet": {
    "pallet": {
      "lengthMm": 1200,
      "widthMm": 800,
      "deckHeightMm": 145,
      "maxTotalHeightMm": 1250,
      "tareG": 20000,
      "maxCargoMassG": 1000000,
      "maxPallets": 2,
      "maxLayers": 3
    },
    "stopId": "s1",
    "items": [
      {
        "id": "carton",
        "size": [
          400,
          400,
          300
        ],
        "mass": 10000,
        "quantity": 5,
        "stopId": "s1",
        "orientations": [
          "lwh"
        ],
        "stacking": "stackable",
        "maxTopMass": 30000
      }
    ],
    "allowPartial": false
  },
  "truckEquipment": {
    "id": "synthetic-truck",
    "kind": "truck",
    "source": "template",
    "inside": [
      6000,
      2400,
      2400
    ],
    "outside": [
      7200,
      2500,
      3600
    ],
    "door": {
      "left": 25,
      "width": 2350,
      "height": 2300
    },
    "payload": 8000000,
    "tare": 6500000,
    "clearance": 25,
    "obstacles": []
  }
}

GET /api/v1/load-plans/{id}/warehouse

POST /api/v1/load-plans/{id}/warehouse
{
  "revision": 1,
  "eventId": "scan-0001",
  "unitId": "pallet-1:1"
}

Simulação de envios anteriores

Recalcule envios anteriores com a mesma carga em dois cenários. Veja veículos, ocupação, unidades não alocadas e a diferença entre custos conhecidos em JSON e CSV.

Consulte as tarifas vigentes antes de enviar o trabalho. Para um módulo com preço próprio, envie o preço atual em créditos no cabeçalho Confirm-Load-Credits. Um preço null indica que a operação está indisponível.

POST /api/v1/load-plans/simulation
curl --fail-with-body -X POST "https://osrmroute.com/api/v1/load-plans/simulation" \
  -H "Authorization: Bearer $OSRM_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Confirm-Load-Credits: $CONFIRMED_CREDITS" \
  --data-binary @simulation.json
simulation.json
{
  "currency": "USD",
  "shipments": [
    {
      "id": "demo-shipment",
      "manifest": {
        "units": {
          "length": "mm",
          "mass": "kg"
        },
        "stops": [
          "s1"
        ],
        "items": [
          {
            "id": "p1",
            "size": [
              1200,
              800,
              1100
            ],
            "mass": 350,
            "quantity": 1,
            "stopId": "s1",
            "orientations": [
              "lwh",
              "wlh"
            ],
            "stacking": "floor_only"
          }
        ],
        "allowPartial": false
      },
      "baseline": {
        "version": "2026-a",
        "alternatives": [
          {
            "id": "synthetic-truck",
            "kind": "truck",
            "source": "template",
            "inside": [
              6000,
              2400,
              2400
            ],
            "outside": [
              7200,
              2500,
              3600
            ],
            "door": {
              "left": 25,
              "width": 2350,
              "height": 2300
            },
            "payload": 8000,
            "tare": 6500,
            "clearance": 25,
            "obstacles": []
          }
        ],
        "vehicleCostMinor": {
          "synthetic-truck": 1500
        }
      },
      "proposed": {
        "version": "2026-b",
        "alternatives": [
          {
            "id": "synthetic-truck",
            "kind": "truck",
            "source": "template",
            "inside": [
              6000,
              2400,
              2400
            ],
            "outside": [
              7200,
              2500,
              3600
            ],
            "door": {
              "left": 25,
              "width": 2350,
              "height": 2300
            },
            "payload": 8000,
            "tare": 6500,
            "clearance": 25,
            "obstacles": []
          }
        ],
        "vehicleCostMinor": {
          "synthetic-truck": 1250
        }
      }
    }
  ]
}

GET /api/v1/load-plans/{id}/simulation-report · CSV

Projeto de parceiro

Mantenha um projeto e uma chave de API por cliente. O titular define o limite mensal de créditos, a origem HTTPS autorizada e a marca exibida no visualizador 3D.

GET /api/v1/load-plans/partner
curl --fail -H "Authorization: Bearer $OSRM_API_KEY" https://osrmroute.com/api/v1/load-plans/partner
POST /api/v1/load-plans/{id}/share
{
  "expiresInSeconds": 900,
  "partnerEmbed": true
}

Mostrar o modelo 3D na sua aplicação

A cena verificada inclui o espaço de carga, a abertura, os obstáculos e as coordenadas e dimensões orientadas das unidades alocadas em milímetros.

Confira a carga e a descarga em 3D. Exiba um plano verificado no TMS, WMS ou portal com um iframe temporário, ou abra o GLB no seu visualizador.

Descarregue o plano verificado mais recente em GLB a partir do seu servidor. A exportação não gasta créditos adicionais.

GET /api/v1/load-plans/{id}/model
curl --fail -H "Authorization: Bearer $OSRM_API_KEY" \
  "https://osrmroute.com/api/v1/load-plans/$JOB_ID/model" -o load-plan.glb

O URL /internal do exemplo representa uma rota autenticada na sua aplicação. Guarde a chave da API OSRMRoute no servidor.

Three.js · GLTFLoader
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';

const path = '/internal/load-plans/' + encodeURIComponent(jobId) + '/model';
const response = await fetch(path, { credentials: 'same-origin' });
if (!response.ok) throw new Error('Load model unavailable');
const { scene: loadModel } = await new GLTFLoader().parseAsync(await response.arrayBuffer(), '');
viewerScene.add(loadModel);
POST /api/v1/load-plans/{id}/share
{
  "expiresInSeconds": 900,
  "embedOrigin": "https://warehouse.example.com"
}
iframe
<iframe title="3D load plan" src="https://osrmroute.com{path}"
  width="100%" height="640" loading="lazy" referrerpolicy="no-referrer"
  sandbox="allow-scripts allow-same-origin"></iframe>

Suporte OSRMRoute

Escreva diretamente à nossa equipa

ESTAMOS PARA AJUDAR

Como podemos ajudar?

Envie uma mensagem. As respostas aos pedidos também são enviadas para o seu email verificado.

Suas conversas

Suas conversas aparecerão aqui.