API Docs v1 api.hubiss.com.br

Fluxo completo de integração

O caminho de ponta a ponta, do token ao pedido entregue, com o que fazer em cada etapa e como saber que deu certo.

Esta página é o mapa. Cada etapa abaixo diz o que você faz, o que a Hubiss faz e como confirmar que funcionou. Se algo falhar, a seção de erros de cada etapa aponta o próximo passo.

Regra de ouro
A integração é uma cadeia: loja → categoria → produto → foto. Pular etapa gera 422 e retrabalho. Pedidos são o caminho inverso: a Hubiss te avisa, você consulta e atualiza o status.

Visão geral

Seu sistema ERP, planilha ou app API Hubiss v1 validação · catálogo · pedidos Marketplaces ML · Shopee Fornecedor / fábrica estoque e despacho cadastro pedidos

Você envia cadastro para a Hubiss e recebe pedidos de volta — por webhook ou por consulta.

Etapa 1 · Autenticação

O que fazer O que acontece
Gerar o token no painel e guardá-lo em variável de ambiente Toda chamada passa a ser identificada
Exemplo em linha de comandobash
curl --request GET \
     --url 'https://api.hubiss.com.br/v1/languages' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer SEU_TOKEN'

Deu certo se a resposta for 200 com pt_BR na lista (ou data com as linguagens). Falhou com 401 → token inválido ou antigo. Gere outro e atualize o sistema.

Etapa 2 · Criar a loja

A loja é a raiz do seu catálogo. Sem ela não existe categoria, produto nem pedido.

Exemplo em linha de comandobash
curl --request POST \
     --url 'https://api.hubiss.com.br/v1/stores' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer SEU_TOKEN' \
     --header 'Content-Type: application/json' \
     --data '{"name":"Minha Loja","country":"BR","languages":["pt_BR"],"status":"active"}'

Deu certo se vier 201/200 com o id da loja. Guarde esse id: ele aparece em todas as rotas seguintes. Falhou com 422 → falta campo obrigatório; leia data.<campo> na resposta.

Etapa 3 · Montar as categorias

Categorias pertencem a uma loja e podem ter categoria pai. Cadastre do topo para baixo.

Exemplo em linha de comandobash
curl --request POST \
     --url 'https://api.hubiss.com.br/v1/stores/123/categories' \
     --header 'Authorization: Bearer SEU_TOKEN' \
     --header 'Content-Type: application/json' \
     --data '{"name":"Calçados"}'

Deu certo se a categoria voltar com id. Use esse id no produto. Falhou com 404 → a loja do caminho não existe (ou não é sua).

Etapa 4 · Cadastrar o produto

Quanto mais completo o produto, melhor o anúncio. Informe categoria, marca (por nome) e variações quando houver.

Exemplo em linha de comandobash
curl --request POST \
     --url 'https://api.hubiss.com.br/v1/stores/123/products' \
     --header 'Authorization: Bearer SEU_TOKEN' \
     --header 'Content-Type: application/json' \
     --data '{"name":"Tênis Runner","sku":"TEN-RUN-01","category_id":45,"brand":"MinhaMarca","price":199.9}'

Deu certo se vier o id do produto e status ativo. Falhou com 422 → normalmente category_id inválido ou SKU repetido.

Etapa 5 · Enviar as fotos

Fotos podem ir por URL (mais simples) ou base64. Envie as principais primeiro.

Exemplo em linha de comandobash
curl --request POST \
     --url 'https://api.hubiss.com.br/v1/stores/123/products/789/pictures/url' \
     --header 'Authorization: Bearer SEU_TOKEN' \
     --header 'Content-Type: application/json' \
     --data '{"url":"https://meucdn.com/tenis-runner-1.jpg"}'

Deu certo se a foto aparecer em GET .../pictures. Falhou com 422 → URL inacessível ou imagem acima do limite (2 MB).

Etapa 6 · Configurar o webhook

Sem webhook você precisa consultar pedidos em loop. Com webhook, a Hubiss avisa.

Exemplo em linha de comandobash
curl --request POST \
     --url 'https://api.hubiss.com.br/v1/webhooks' \
     --header 'Authorization: Bearer SEU_TOKEN' \
     --header 'Content-Type: application/json' \
     --data '{"url":"https://meusistema.com/webhooks/hubiss","topic":"orders"}'

Sua URL deve responder 2xx em até 2 segundos. Processe o evento depois, em fila.

Etapa 7 · Ciclo do pedido

Saída esperadatext
payment → você consulta GET /orders/{id} → fatura → informa envio → conclui
Ação Rota Resultado esperado
Consultar GET /orders/{id} Dados completos, incluindo shipping
Faturar PUT /orders/{id}/invoiced status = invoiced
Enviado PUT /orders/{id}/sent status = paid_waiting_delivery
Entregue PUT /orders/{id}/concluded status = concluded
Antes de cada mudança de status
Consulte o pedido atual. Mudar status fora de ordem devolve 422 com "Cannot change status now, check documentation".

Checklist de integração concluída

  • Token em variável de ambiente, nunca no código
  • Loja criada e id armazenado
  • Categorias criadas com hierarquia correta
  • Produtos com SKU único e marca
  • Fotos cadastradas e visíveis
  • Webhook respondendo 2xx e com deduplicação por resource
  • Paginação consumida até links.next = null
  • Retry com backoff para 429 e 5xx
  • Erros 422 registrados por campo, sem repetir a chamada idêntica

Erros mais comuns na primeira integração

Sintoma Causa provável Correção
401 em tudo Token não enviado ou revogado Reenviar Authorization: Bearer
404 em /stores/{id}/... id de outra conta ou inexistente Usar o id retornado no cadastro
422 no produto category_id de outra loja Usar categoria da mesma loja
Lista sempre na página 1 Não leu links.next Paginar até next ser null
Pedidos duplicados no ERP Webhook reprocessado Deduplicar por resource + attempt
429 em lote grande Teto imposto pela sua infraestrutura (proxy/gateway) Backoff exponencial e pausas
Próximo passo
Quer automatizar com agente de IA? Use os prompts de Integração com agentes de IA. Precisa do detalhe de um campo? Abra a página do recurso em Lojas, Produtos ou Pedidos.