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.
422 e retrabalho. Pedidos são o caminho inverso: a Hubiss te avisa, você consulta e atualiza o status.Visão geral
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 |
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.
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.
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.
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.
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.
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
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 |
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
idarmazenado - Categorias criadas com hierarquia correta
- Produtos com SKU único e marca
- Fotos cadastradas e visíveis
- Webhook respondendo
2xxe com deduplicação porresource - Paginação consumida até
links.next = null - Retry com backoff para
429e5xx - Erros
422registrados 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 |