API de Integração OnBlox

Envie cadastros e documentos do seu ERP para o OnBlox WMS: produtos, embalagens, clientes, fornecedores, motoristas, veículos, pedidos de venda, cargas e notas fiscais de entrada.

A API segue o estilo REST, recebe e devolve JSON em UTF-8 e usa os códigos HTTP padrão. Cada chamada de envio recebe um lote, isto é, uma lista de registros. O WMS cria ou atualiza cada registro pelo código de integração que o seu sistema atribuiu a ele. Um registro com problema não impede a gravação dos outros, e a resposta informa o que entrou e o que foi recusado, item a item.

Início rápido

São três passos até o primeiro lote gravado. Use uma instância de homologação enquanto desenvolve.

1. Gere um token no WMS

   Um usuário administrador da sua empresa acessa Configurações de Conta → API → Tokens e gera um token com permissão Leitura e escrita e modo de gravação Estrito. O valor começa com onbx_ e aparece uma única vez. Guarde-o num cofre de segredos.

2. Confirme a conexão

   Consulte as referências da instância. A resposta 200 confirma que o token, o subdomínio e o HTTPS estão corretos. Confira também se modoGravacao veio ESTRITO.

3. Envie o primeiro lote

   Comece pelo topo da hierarquia de cadastros, por exemplo um departamento. Confira sucesso e erro na resposta.

URL base e ambientes

Cada empresa cliente tem a sua própria instância do OnBlox, identificada pelo subdomínio. Todas as rotas desta documentação partem de:

Troque suaempresa pelo subdomínio informado pela OnBlox. O campo Sua instância, no topo da página, atualiza todos os exemplos.

A OnBlox informa a URL da instância de homologação na liberação do acesso. Use os mesmos caminhos nela e em produção.

Autenticação

Envie o token no cabeçalho X-API-Token de toda requisição. Não há fluxo de login nem renovação de sessão: o token é a credencial.

X-API-Token: onbx_•••••••••••••••••••••••••••••••••••••••••••
Content-Type: application/json

• HTTPS obrigatório. Requisições em HTTP simples são recusadas com 401 e a mensagem Esta API exige HTTPS.
• Formato: onbx_ seguido de 43 caracteres (48 no total). O WMS guarda apenas o hash do token. Se o valor for perdido, gere outro.
• Dono: o token pertence ao usuário que o gerou. Se esse usuário for desativado, o token deixa de funcionar. Prefira um usuário técnico dedicado à integração.

Permissão do token

Modo de gravação do token

Gere o token com o modo de gravação Estrito, o modo descrito nesta documentação: atualização parcial, referência não encontrada recusa o registro, erros citam o código de integração e exclusões vindas do ERP são aceitas. Veja Modo de gravação Estrito. Para conferir o modo de um token, consulte Referências: o campo modoGravacao deve vir ESTRITO.

Validade, rotação e revogação

• A validade é definida em dias na geração. Zero significa sem vencimento. Recomendamos de 180 a 365 dias.
• Cada usuário pode ter até 5 tokens ativos. Gerar um token novo não revoga os anteriores, então a troca pode ser feita sem parar a integração: gere o novo, publique-o no seu sistema e revogue o antigo.
• Token revogado ou vencido responde 401, cada caso com a sua mensagem (Token de API revogado… e Token de API vencido…).

Lotes e código de integração

Todo envio recebe um array JSON, mesmo quando há um só registro. O WMS processa os itens um a um, na ordem recebida.

• Código de integração (integracao): é a chave do registro no seu ERP, como código do produto, CODEMP ou NUNOTA. O WMS procura um registro com esse código. Se encontrar, atualiza; se não, cria. Use um valor estável, que nunca muda para o mesmo registro.
• Upsert idempotente: enviar o mesmo lote duas vezes produz o mesmo resultado. Por isso é seguro reenviar depois de um timeout ou de uma falha de rede.
• Referências: para ligar um registro a outro, informe o código de integração do registro ligado, por exemplo familiaIntegracaoId no produto ou clienteIntegracaoId no pedido. Os ids internos do WMS só são necessários para filiais e tipos de distribuição, obtidos em Referências.
• Lote vazio ([]) responde 200 com sucesso: 0.
• Campos desconhecidos são ignorados. O WMS não recusa o lote por um campo a mais.

Modo de gravação Estrito

No modo Estrito, a atualização parte do registro já gravado no WMS. Cada campo do JSON segue esta política:

Na prática, envie só o que mudou ou o registro completo, como for mais simples para o seu ERP. Os dois funcionam. Só não envie null num campo que você não quer apagar.

Ordem de envio

Uma referência só é resolvida se o registro referenciado já existir no WMS. Envie primeiro os cadastros dos quais os outros dependem:

Na carga inicial, envie cada cadastro completo antes de começar os documentos. Depois disso, envie apenas o que mudou no ERP, em intervalos curtos.

Formatos de dados

Resposta do lote

Todo envio devolve o mesmo objeto de resultado:

Códigos HTTP e erros

Erro de autenticação ou permissão

As respostas 401 e 403 trazem um objeto de erro. Use codigo para tratar o caso no seu sistema e message para exibir.

O objeto pode trazer outros campos. Ignore os campos que você não conhece.

Rastreamento

Toda resposta traz o cabeçalho X-Correlation-Id. Você pode enviar o seu próprio valor nesse cabeçalho (8 a 64 caracteres entre letras, números e . _ : -) para casar os logs do seu sistema com os da OnBlox. Se o valor não seguir esse formato, o WMS gera um novo. Registre esse código em todo envio com erro.

Limites

Lotes de 100 a 500 registros costumam equilibrar o volume enviado e o tempo de resposta. Envie os lotes de uma mesma rota em sequência. Rotas diferentes podem ser chamadas em paralelo, respeitando a ordem de dependências.

Retentativas e boas práticas

• Reenvie com espera exponencial em 429, 500, 502, 503, 504 e em falhas de rede: 1 s, 2 s, 4 s, 8 s… até 5 minutos, com uma variação aleatória somada a cada espera. Como o envio é idempotente pelo código de integração, reenviar o lote inteiro é seguro.
• Não reenvie automaticamente 400, 401 e 403. Esses casos exigem correção no lote ou no token.
• Timeout do cliente: use pelo menos 120 segundos. O lote é processado durante a requisição, e um lote grande pode levar alguns segundos.
• Registros recusados: guarde a mensagem e a posição, corrija a causa (normalmente uma referência que ainda não foi enviada) e reenvie só esses registros.
• Envio por mudança: depois da carga inicial, envie apenas o que mudou no ERP. Evite reenviar o cadastro inteiro a cada ciclo.
• Logs: registre data e hora, rota, quantidade de itens, sucesso, erro e X-Correlation-Id de cada lote. Nunca registre o token.
• Exclusões no ERP: avise o WMS pela rota Exclusões em vez de deixar o registro esquecido.

Especificação OpenAPI

A especificação OpenAPI 3 da API de integração fica disponível na própria instância e pode ser importada no Postman, no Insomnia ou num gerador de cliente:

Em caso de divergência, vale o comportamento descrito nesta página. Use apenas as rotas documentadas aqui.

Suporte e homologação

• Homologação: desenvolva e teste numa instância de homologação fornecida pela OnBlox. Antes de ir para produção, valide a carga inicial completa, um ciclo de alterações, uma exclusão e o tratamento de um registro recusado.
• Ao abrir um chamado, informe a instância, a rota, a data e hora, o X-Correlation-Id e, quando houver, o codigoOcorrencia e a referencia do item. Não envie o token.
• Mudanças no contrato: a OnBlox só acrescenta campos e rotas. Campo ou rota que deixar de existir será avisado com antecedência. Programe o seu cliente para ignorar campos novos na resposta.