{"info":{"_postman_id":"7e207411-7624-4909-8d24-35ec0605eb45","name":"Hubii API","description":"

Integração para parceiros

Esta collection documenta a integração de parceiros com a API pública da Hubii. O fluxo foi desenhado para ERPs, PDVs e WMS que precisam aceitar pedidos, importar dados para operação, faturar, acompanhar eventos logísticos e tratar cancelamentos.

A integração usa dois pollings independentes, executados em paralelo. Eles não são alternativas entre si: cada um cobre uma etapa diferente do ciclo do pedido.

Visão rápida dos pollings

Polling 1 — Aceite de pedidos

Usado para decidir se o hub aceita ou recusa uma oferta de pedido.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Ponto	Regra
Quando usar	Sempre que o hub precisa responder pedidos novos
Rotas	`GET /hubs/{hub_uuid}/orders/to-answer` → `GET /hubs/{hub_uuid}/orders/{order_uuid}` → `POST .../answer`
O que retorna	Ofertas pendentes, ainda não aceitas
Decisão	Para cada oferta, consulte o pedido completo antes de aceitar ou recusar
Prazo	Cada oferta expira em `available_until_at`; depois disso, some da fila
Aceite via painel	Também é válido e dispara o Polling 2
Recusa / expiração	Remove a oferta de `to-answer` e não gera notificação para aquele hub

\n
A listagem de to-answer deve ser tratada como fila de ofertas. A decisão normalmente depende do pedido completo, principalmente dos itens, quantidades, preços e disponibilidade do hub.
\n

Polling 2 — Notificações de pedidos aceitos

Usado para acompanhar pedidos após o aceite: importação no ERP, entrega, NF-e, etiqueta e cancelamentos.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Ponto	Regra
Quando usar	Depois do aceite via API ou painel, em paralelo ao Polling 1
Rotas	`GET /v2/notifications` → processar → `POST /notifications/ack`
O que retorna	Eventos de pedidos aceitos, como `ORDER_CREATED`, entrega e etiqueta
`ORDER_CREATED`	Só chega após o aceite; é o gatilho para importar o pedido no ERP
ACK	Obrigatório após processar; eventos reaparecem até ACK e expiram em 2 dias

\n
Resumo: Polling 1 decide se o hub aceita a oferta. Polling 2 opera o pedido depois que ele foi aceito. Execute os dois a cada 30–60 segundos.
\n

Implementação mínima

Para uma integração funcional, implemente este caminho primeiro:

Configure base_url e envie o header apikey em todas as requisições.
\n
Chame GET /hubs e salve o uuid de cada hub.
\n
A cada 30–60 segundos, execute o Polling 1: GET /hubs/{hub_uuid}/orders/to-answer.
\n
Para cada oferta retornada, consulte o pedido completo em GET /hubs/{hub_uuid}/orders/{order_uuid}.
\n
Com base no pedido completo, principalmente nos itens, estoque e regras do hub, aceite ou recuse com POST .../answer antes de available_until_at.
\n
Em paralelo, execute o Polling 2: GET /v2/notifications.
\n
Ao receber ORDER_CREATED, busque ou reconcilie os detalhes do pedido e importe no ERP.
\n
Após processar e persistir a notificação, envie POST /notifications/ack usando notification_uuid.
\n
Quando aplicável, envie a NF-e com POST .../invoice.
\n
Ao receber SHIPPING_LABEL_AVAILABLE, baixe a etiqueta com GET .../label.
\n

Não use busy-loop. Em 429, interrompa o ciclo atual, aplique backoff e tente novamente no próximo intervalo.

Fluxo operacional

GET /hubs\n  ↓\n[Polling 1] GET .../to-answer\n  ↓ para cada order_uuid\nGET /hubs/{hub_uuid}/orders/{order_uuid}\n  ↓ decidir com base no pedido completo\nPOST .../answer\n  ↓ após aceite via API ou painel\n[Polling 2] GET /v2/notifications\n  ↓ ORDER_CREATED\nGET /hubs/{hub_uuid}/orders/{order_uuid}\n  ↓ após persistir no ERP\nPOST /notifications/ack\n  ↓ quando aplicável\nPOST .../invoice\n  ↓ SHIPPING_LABEL_AVAILABLE\nGET .../label\n\n

GET .../to-invoice está descontinuado e existe apenas por compatibilidade. Para novas integrações, use ORDER_CREATED no Polling 2.

Decisão de aceite ou recusa

A Hubii recomenda este padrão para cada oferta retornada em to-answer:

Ler order_uuid e available_until_at na listagem.
\n
Buscar o pedido completo em GET /hubs/{hub_uuid}/orders/{order_uuid}.
\n
Avaliar itens, quantidades, preços, disponibilidade, regras fiscais e operação do hub.
\n
Responder com POST .../answer antes do prazo.
\n

Essa etapa evita decisões baseadas apenas no resumo da fila e reduz recusa incorreta, aceite sem estoque ou divergência operacional.

Variáveis da collection

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Variável	Uso
`base_url`	`https://api.staging.hubii.co` em homologação ou `https://api.hubii.co` em produção
`apikey`	API Key Hubii enviada no header `apikey`
`hub_uuid`	UUID do hub retornado em `GET /hubs`
`hub_uuid_2`	Opcional; segundo hub para exemplos de filtro com múltiplos hubs
`order_uuid`	UUID do pedido retornado em `to-answer` ou em uma notificação
`notification_uuid`	UUID da notificação retornada em `GET /v2/notifications`; usar no ACK

Autenticação

Envie o header abaixo em todas as requisições:

apikey: {sua_chave}\n\n

API Key ausente, inválida ou sem permissão deve ser tratada como erro de configuração, não como falha temporária.

Rate limits

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Grupo	Limite	Rotas
Listagem	60/min por token	`/hubs`, `.../to-answer`, `.../to-invoice` legado
Detalhe	30/min por token	`.../orders/{order_uuid}`
Ação	10/min por token	`.../answer`, `.../invoice`, `/notifications/ack`, `.../cancel-accepted`
Notificações	5/min por token	`/v2/notifications`

\n
Em runtime, use os headers X-RateLimit-\\\\\\\\\\* como referência operacional. A tabela acima documenta o limite esperado/contratual.
\n

Em 429, não faça retry imediato em loop. Aguarde com backoff exponencial e retome o polling no próximo ciclo.

Idempotência e retry seguro

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Operação	Como tratar retry
`GET /hubs`	Seguro repetir
`GET .../to-answer`	Seguro repetir; a lista reflete a fila atual
`GET .../orders/{order_uuid}`	Seguro repetir; use antes de decidir aceite/recusa e para reconciliar pedido aceito
`POST .../answer`	Não é retry cego; pode retornar `422` se o pedido já foi respondido
`GET /v2/notifications`	Seguro repetir; eventos reaparecem até ACK
`POST /notifications/ack`	Enviar só depois de persistir; se falhar, retentar o ACK, não o processamento
`POST .../invoice`	Reenvio do mesmo XML é idempotente
`POST .../cancel-accepted`	Ação sensível; evitar retry automático sem checar o estado do pedido

Use notification_uuid como chave de idempotência dos eventos no ERP.

Estratégia recomendada de ACK

Buscar notificações.
\n
Processar cada evento no ERP.
\n
Persistir localmente usando notification_uuid como chave única.
\n
Enviar ACK somente após sucesso da persistência.
\n
Se o ACK falhar, retentar apenas o ACK. Não reprocessar o evento duplicado.
\n

\n
ACK cedo demais pode causar perda de evento no ERP. Sem ACK, a notificação reaparece por até 2 dias.
\n

Segurança operacional

Nunca exponha API Key em frontend, repositório, tickets públicos ou logs.
\n
Não commite environments do Postman com secrets preenchidos.
\n
Mascare credenciais em evidências de homologação.
\n
Trate 401 como configuração incorreta e acione revisão de credenciais.
\n

Homologação

Obrigatório para todos os parceiros

Smoke test: GET /hubs, 401 com key inválida e 403/404 em hub sem permissão.
\n
Polling 1: listar ofertas, consultar detalhe completo antes da decisão, aceitar pedido, recusar com motivos, tratar pedido já respondido e pedido expirado.
\n
Polling 2: buscar notificações, processar ORDER_CREATED, fazer ACK e validar reprocessamento quando não há ACK.
\n
Detalhes do pedido: importar dados completos e exibir order.id no ERP.
\n
Operação: aplicar backoff em 429, retry em 5xx/timeout e proteger credenciais nos logs.
\n

Obrigatório quando aplicável ao escopo

Envio de NF-e XML com campo multipart invoice_file.
\n
Tratamento de formatos diferentes de NF-e.
\n
Download de etiqueta após SHIPPING_LABEL_AVAILABLE.
\n
Consulta de pickup_code após ORDER_DELIVERY_PICKING_UP.
\n
Cancelamento pós-aceite antes da coleta.
\n

Evidências aceitas

Logs com credenciais mascaradas.
\n
Gravação de tela do fluxo em staging.
\n

Boas práticas

Consulte o detalhe completo de cada oferta antes de aceitar ou recusar.
\n
Exiba order.id no ERP; é o identificador usado no painel Hubii e no suporte.
\n
Armazene notification_uuid para evitar duplicidade de processamento.
\n
Execute Polling 1 e Polling 2 com o mesmo intervalo recomendado: 30–60 segundos.
\n
Cancelamentos Hubii/cliente podem chegar até 1 dia após o evento real.
\n

\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"Integração para parceiros","slug":"integracao-para-parceiros"}],"owner":"34374925","collectionId":"7e207411-7624-4909-8d24-35ec0605eb45","publishedId":"2sBXwvJoRJ","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"6348e5"},"publishDate":"2026-06-19T21:15:22.000Z"},"item":[{"name":"01 — Setup","item":[{"name":"Listagem de Hubs","id":"77a24f11-72c3-4936-b98f-54224cf8d1c8","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"apikey"},{"key":"value","value":""}]},"isInherited":false},"method":"GET","header":[{"key":"Accept","value":"application/json","type":"text"}],"url":"https://api.staging.hubii.co/hubs","description":"

Objetivo

Lista os hubs vinculados à API Key. Este é o primeiro passo da integração: use data[].uuid como hub_uuid nas demais rotas.

Quando chamar

Na configuração inicial do ERP, para mapear lojas/hubs.
Periodicamente, por exemplo 1 vez ao dia, se novos hubs puderem ser vinculados.
Antes de iniciar os dois pollings.

Posição no fluxo

GET /hubs\n  ↓ guardar hub_uuid\n[Polling 1] GET .../to-answer → POST .../answer\n[Polling 2] GET /v2/notifications → processar → ACK\n

Query params opcionais

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parâmetro	Tipo	Descrição
`search`	string	Filtra por nome do hub
`order_by`	string	Campo de ordenação; padrão: `name`
`order_direction`	`asc` ou `desc`	Direção da ordenação
`per_page`	int	Itens por página; padrão: 10
`page`	int	Página atual
`load`	string	Relacionamentos extras, por exemplo `address`

Campos relevantes

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Campo	Uso
`data[].uuid`	`hub_uuid` usado nas URLs
`data[].name`	Nome fantasia
`data[].trading_name`	Razão social
`data[].document`	CNPJ
`data[].address`	Endereço do hub, quando carregado

Exemplo cURL

curl -s \"$BASE_URL/hubs\" \\\n  -H \"Accept: application/json\" \\\n  -H \"apikey: $HUBII_API_KEY\"\n

Idempotência

GET seguro repetir a qualquer momento.

Tratamento de erros

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Status	Orientação
`401`	Não retentar automaticamente; revisar API Key
`403`	Verificar se a API Key tem acesso ao hub informado
`404`	Verificar `hub_uuid`, `order_uuid` ou se o recurso ainda está disponível
`422`	Tratar como erro de regra de negócio ou payload inválido; não fazer retry cego
`429`	Aplicar backoff exponencial e respeitar os headers de rate limit
`5xx` / timeout	Retentar com backoff exponencial e limite de tentativas

\n
Em runtime, use os headers X-RateLimit-* como referência operacional. A tabela de rate limits documenta o limite esperado/contratual.
\n

Próximo passo

Com os hubs mapeados, inicie os dois pollings em paralelo:

Polling 1: GET /hubs/{hub_uuid}/orders/to-answer.
Polling 2: GET /v2/notifications?hub_uuids={hub_uuid}.

\n","urlObject":{"path":["hubs"],"host":["https://api.staging.hubii.co"],"query":[],"variable":[]}},"response":[{"id":"a87a5409-4c95-434e-bf8e-4f98a29ab09e","name":"[200] Listagem de Hubs","originalRequest":{"method":"GET","header":[],"url":"https://api.staging.hubii.co/hubs"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"RateLimit-Reset","value":"58"},{"key":"X-RateLimit-Limit-Minute","value":"10"},{"key":"X-RateLimit-Remaining-Minute","value":"9"},{"key":"RateLimit-Limit","value":"10"},{"key":"RateLimit-Remaining","value":"9"},{"key":"Host","value":"api.staging.hubii.co"},{"key":"X-Powered-By","value":"PHP/8.1.29"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"Date","value":"Thu, 21 Nov 2024 14:00:02 GMT"},{"key":"X-RateLimit-Limit","value":"60"},{"key":"X-RateLimit-Remaining","value":"59"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Server","value":"kong/3.8.0"},{"key":"X-Kong-Upstream-Latency","value":"530"},{"key":"X-Kong-Proxy-Latency","value":"3"},{"key":"Via","value":"1.1 kong/3.8.0"},{"key":"X-Kong-Request-Id","value":"fb00546bf610dd0d360cc12a3cbd5545"}],"cookie":[],"responseTime":null,"body":"{\n \"data\": [\n {\n \"uuid\": \"fabb88b2-0954-43db-b32a-e482d5406183\",\n \"name\": \"Nome do Seu Hub\",\n \"trading_name\": \"Seu Hub LTDA\",\n \"document\": \"00000000000100\",\n \"address\": {\n \"street_name\": \"Rua do Seu Hub\",\n \"address_number\": \"000\",\n \"complement\": \"loja 1 e 2\",\n \"postal_code\": \"00000-000\",\n \"neighborhood_name\": \"bairro\",\n \"city_name\": \"cidade\",\n \"province_code\": \"UF\",\n \"country_code\": \"BR\"\n }\n }\n ],\n \"links\": {\n \"first\": \"https://api.staging.hubii.co/hubs?search=&order_by=name&order_direction=asc&per_page=10&load=address&page=1\",\n \"last\": \"https://api.staging.hubii.co/hubs?search=&order_by=name&order_direction=asc&per_page=10&load=address&page=1\",\n \"prev\": null,\n \"next\": null\n },\n \"meta\": {\n \"current_page\": 1,\n \"from\": 1,\n \"last_page\": 1,\n \"links\": [\n {\n \"url\": null,\n \"label\": \"« Previous\",\n \"active\": false\n },\n {\n \"url\": \"https://api.staging.hubii.co/hubs?search=&order_by=name&order_direction=asc&per_page=10&load=address&page=1\",\n \"label\": \"1\",\n \"active\": true\n },\n {\n \"url\": null,\n \"label\": \"Next »\",\n \"active\": false\n }\n ],\n \"path\": \"https://api.staging.hubii.co/hubs\",\n \"per_page\": 10,\n \"to\": 6,\n \"total\": 6\n }\n}"}],"_postman_id":"77a24f11-72c3-4936-b98f-54224cf8d1c8"}],"id":"8c934f25-50e9-4597-b1b5-71659418c22e","_postman_id":"8c934f25-50e9-4597-b1b5-71659418c22e","description":"","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"apikey"},{"key":"value","value":""}]},"isInherited":true,"source":{"_postman_id":"7e207411-7624-4909-8d24-35ec0605eb45","id":"7e207411-7624-4909-8d24-35ec0605eb45","name":"Hubii API","type":"collection"}}},{"name":"02 — Polling 1: Aceite de pedidos","item":[{"name":"Listagem de pedidos para resposta","id":"5ba35a9c-54f0-4076-aa01-9d604092d2bb","protocolProfileBehavior":{"disabledSystemHeaders":{"accept":true},"disableBodyPruning":true},"request":{"auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"apikey"},{"key":"value","value":""}]},"isInherited":false},"method":"GET","header":[{"key":"Accept","value":"application/json","type":"text"}],"url":"https://api.staging.hubii.co/hubs/:hub_uuid/orders/to-answer","description":"

Objetivo

Polling 1 — Aceite. Lista ofertas de pedidos pendentes para um hub. Esses pedidos ainda não foram aceitos e precisam de resposta antes de available_until_at.

\n
A listagem deve ser tratada como uma fila de ofertas. Para cada pedido retornado, consulte o detalhe completo em GET /hubs/{hub_uuid}/orders/{order_uuid} antes de aceitar ou recusar.
\n

Quando chamar

A cada 30–60 segundos.
\n
Em paralelo ao Polling 2.
\n
Para cada hub_uuid vinculado à API Key.
\n

Fluxo recomendado

GET /hubs/{hub_uuid}/orders/to-answer\n  ↓ para cada data[].uuid\nGET /hubs/{hub_uuid}/orders/{order_uuid}\n  ↓ avaliar itens, quantidades, preço, disponibilidade e regras do hub\nPOST /hubs/{hub_uuid}/orders/{order_uuid}/answer\n  ↓ se aceito\nGET /v2/notifications → ORDER_CREATED\n\n

Por que consultar o pedido completo

O hub normalmente decide aceitar ou recusar com base no pedido completo, principalmente:

itens do pedido;
\n
quantidades solicitadas;
\n
disponibilidade de estoque;
\n
preço/repasse;
\n
regras fiscais e operacionais;
\n
endereço e condições de atendimento.
\n

A resposta de to-answer é útil para identificar as ofertas pendentes e o prazo de resposta, mas não deve ser a única base da decisão.

Path params

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Param	Obrigatório	Descrição
`hub_uuid`	Sim	UUID do hub retornado em `GET /hubs`

Campos relevantes

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Campo	Uso
`data[].uuid`	`order_uuid` usado para consultar detalhes e aceitar ou recusar
`data[].id`	ID numérico; exiba no ERP para suporte operacional
`data[].total`	Valor total resumido da oferta
`data[].available_until_at`	Prazo máximo para resposta; depois disso, a oferta expira

Regras importantes

Consulte o pedido completo antes de responder.
\n
Responda antes de available_until_at.
\n
Após expirar, a oferta some da fila e pode ser repassada a outro hub.
\n
Expiração e recusa não geram notificação para este hub.
\n
Aceite pelo painel Hubii também é válido e gera ORDER_CREATED no Polling 2.
\n

Exemplo cURL

curl -s \"$BASE_URL/hubs/$HUB_UUID/orders/to-answer\" \\\n  -H \"Accept: application/json\" \\\n  -H \"apikey: $HUBII_API_KEY\"\n\n

Diagrama de sequência

\n\n

Idempotência

GET seguro repetir. A resposta sempre representa o estado atual da fila.

Tratamento de erros

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Status	Orientação
`401`	Não retentar automaticamente; revisar API Key
`403`	Verificar se a API Key tem acesso ao hub informado
`404`	Verificar `hub_uuid`, `order_uuid` ou se o recurso ainda está disponível
`422`	Tratar como erro de regra de negócio ou payload inválido; não fazer retry cego
`429`	Aplicar backoff exponencial e respeitar os headers de rate limit
`5xx` / timeout	Retentar com backoff exponencial e limite de tentativas

\n
Em runtime, use os headers X-RateLimit-\\\\* como referência operacional. A tabela de rate limits documenta o limite esperado/contratual.
\n

Próximo passo

Para cada order_uuid, chame GET /hubs/{hub_uuid}/orders/{order_uuid} e só então use POST /hubs/{hub_uuid}/orders/{order_uuid}/answer para aceitar ou recusar.

\n","urlObject":{"path":["hubs",":hub_uuid","orders","to-answer"],"host":["https://api.staging.hubii.co"],"query":[],"variable":[{"id":"2607de8e-1837-4a5b-94e6-0e5891177065","description":{"content":"

UUID do hub retornado em GET /hubs

\n","type":"text/plain"},"type":"any","value":"","key":"hub_uuid"}]}},"response":[{"id":"1a63a9d6-d26a-4c26-84f0-dd7f02839e61","name":"[200] Listagem de pedidos para resposta","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.staging.hubii.co/hubs/:hub_uuid/orders/to-answer","host":["https://api.staging.hubii.co"],"path":["hubs",":hub_uuid","orders","to-answer"],"variable":[{"key":"hub_uuid","value":"b6f2eefa-da34-4daa-ae2b-98c3bd7b29c2"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"RateLimit-Reset","value":"55"},{"key":"X-RateLimit-Limit-Minute","value":"10"},{"key":"X-RateLimit-Remaining-Minute","value":"9"},{"key":"RateLimit-Limit","value":"10"},{"key":"RateLimit-Remaining","value":"9"},{"key":"Host","value":"api.staging.hubii.co"},{"key":"X-Powered-By","value":"PHP/8.1.29"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"Date","value":"Thu, 21 Nov 2024 14:17:05 GMT"},{"key":"X-RateLimit-Limit","value":"60"},{"key":"X-RateLimit-Remaining","value":"59"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Server","value":"kong/3.8.0"},{"key":"X-Kong-Upstream-Latency","value":"273"},{"key":"X-Kong-Proxy-Latency","value":"184"},{"key":"Via","value":"1.1 kong/3.8.0"},{"key":"X-Kong-Request-Id","value":"ee558d06e231553a42fbd973c1e83a0d"}],"cookie":[],"responseTime":null,"body":"{\n \"data\": [\n {\n \"id\": 102656,\n \"uuid\": \"71402839-ecb5-4ee0-b73a-331e7bef74f5\",\n \"available_until_at\": \"2024-12-20T10:55:20+00:00\",\n \"total\": 50.55\n },\n {\n \"id\": 102864,\n \"uuid\": \"bccf34dd-5501-4070-a846-926fb9fa02d6\",\n \"available_until_at\": \"2024-12-20T10:55:20+00:00\",\n \"total\": 63.33\n }\n ]\n}"}],"_postman_id":"5ba35a9c-54f0-4076-aa01-9d604092d2bb"},{"name":"Responder pedido","id":"14070808-d799-44fa-a76e-b0d56660583a","protocolProfileBehavior":{"disabledSystemHeaders":{"accept":true},"disableBodyPruning":true},"request":{"auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"apikey"},{"key":"value","value":""}]},"isInherited":false},"method":"POST","header":[{"key":"Accept","value":"application/json","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"accept\": false,\n \"details\": [\n {\n \"type\": \"out_of_portfolio\",\n \"message\": null,\n \"item\": \"7fa6c19c-063e-4670-b825-asd\"\n }\n ]\n}","options":{"raw":{"language":"json"}}},"url":"https://api.staging.hubii.co/hubs/:hub_uuid/orders/:order_uuid/answer","description":"

Objetivo

Polling 1 — Aceite. Registra a decisão do hub sobre uma oferta retornada em to-answer: aceitar ou recusar.

Antes de chamar

Para cada oferta retornada em GET .../to-answer, consulte primeiro GET /hubs/{hub_uuid}/orders/{order_uuid}. A decisão normalmente depende do pedido completo, especialmente dos itens, quantidades, disponibilidade, preço e regras operacionais do hub.

Relação com os dois pollings

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Situação	Polling 1	Polling 2
Oferta pendente	Aparece em `to-answer`	Não aparece
Consulta de detalhes	Use antes de decidir aceite/recusa	Também pode ser usada após `ORDER_CREATED`
Aceite pela API	Some de `to-answer`	Gera `ORDER_CREATED`
Aceite pelo painel Hubii	Não exige esta chamada	Gera `ORDER_CREATED`
Recusa ou expiração	Some de `to-answer`	Não gera notificação para este hub

Path params

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Param	Obrigatório	Descrição
`hub_uuid`	Sim	UUID do hub
`order_uuid`	Sim	UUID da oferta retornada em `to-answer`

Body para aceitar

{\n  \"accept\": true\n}\n

Body para recusar

Para recusa, details é obrigatório e deve ter pelo menos um item.

{\n  \"accept\": false,\n  \"details\": [\n    {\n      \"type\": \"out_of_stock\",\n      \"message\": null,\n      \"item\": \"uuid-do-item\"\n    }\n  ]\n}\n

Motivos de recusa

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Valor	Significado
`out_of_portfolio`	Produto fora do portfólio do hub
`out_of_stock`	Sem estoque
`quantity_not_enough`	Estoque insuficiente para a quantidade solicitada
`price`	Preço ou repasse não aceito
`hub_unavailable`	Hub indisponível para atender

Exemplos cURL

Aceitar:

curl -s -X POST \"$BASE_URL/hubs/$HUB_UUID/orders/$ORDER_UUID/answer\" \\\n  -H \"Accept: application/json\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"apikey: $HUBII_API_KEY\" \\\n  -d '{\"accept\": true}'\n

Recusar:

curl -s -X POST \"$BASE_URL/hubs/$HUB_UUID/orders/$ORDER_UUID/answer\" \\\n  -H \"Accept: application/json\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"apikey: $HUBII_API_KEY\" \\\n  -d '{\"accept\": false, \"details\": [{\"type\": \"out_of_stock\", \"message\": null, \"item\": \"uuid-do-item\"}]}'\n

Idempotência

Não faça retry cego. Se o mesmo pedido já foi respondido, a API pode retornar 422 com Order already answered. Trate isso como estado de negócio e verifique o fluxo antes de repetir a ação.

Tratamento de erros

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Status	Orientação
`401`	Não retentar automaticamente; revisar API Key
`403`	Verificar se a API Key tem acesso ao hub informado
`404`	Verificar `hub_uuid`, `order_uuid` ou se o recurso ainda está disponível
`422`	Tratar como erro de regra de negócio ou payload inválido; não fazer retry cego
`429`	Aplicar backoff exponencial e respeitar os headers de rate limit
`5xx` / timeout	Retentar com backoff exponencial e limite de tentativas

\n
Em runtime, use os headers X-RateLimit-* como referência operacional. A tabela de rate limits documenta o limite esperado/contratual.
\n

Após o aceite

Continue o Polling 2. Aguarde ORDER_CREATED, reconcilie os detalhes do pedido no ERP e só depois envie ACK da notificação processada.

\n","urlObject":{"path":["hubs",":hub_uuid","orders",":order_uuid","answer"],"host":["https://api.staging.hubii.co"],"query":[],"variable":[{"id":"80b82d14-72f6-4625-ab41-20637eaf1083","description":{"content":"

UUID do hub retornado em GET /hubs

\n","type":"text/plain"},"type":"any","value":"","key":"hub_uuid"},{"id":"cd3f4987-7359-4294-a71d-f02549b04035","description":{"content":"

UUID do pedido

\n","type":"text/plain"},"type":"any","value":"","key":"order_uuid"}]}},"response":[{"id":"4c3ee9d9-bc83-483d-920c-f2e21d4dc270","name":"[200] Responder pedido positivamente","originalRequest":{"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"accept\": true\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"https://api.staging.hubii.co/hubs/:hub_uuid/orders/:order_uuid/answer","host":["https://api.staging.hubii.co"],"path":["hubs",":hub_uuid","orders",":order_uuid","answer"],"variable":[{"key":"hub_uuid","value":"b6f2eefa-da34-4daa-ae2b-98c3bd7b29c2"},{"key":"order_uuid","value":"71402839-ecb5-4ee0-b73a-331e7bef74f5"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"RateLimit-Reset","value":"22"},{"key":"RateLimit-Limit","value":"10"},{"key":"X-RateLimit-Remaining-Minute","value":"8"},{"key":"X-RateLimit-Limit-Minute","value":"10"},{"key":"RateLimit-Remaining","value":"8"},{"key":"Host","value":"api.staging.hubii.co"},{"key":"X-Powered-By","value":"PHP/8.1.29"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"Date","value":"Thu, 21 Nov 2024 14:37:39 GMT"},{"key":"X-RateLimit-Limit","value":"60"},{"key":"X-RateLimit-Remaining","value":"58"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Server","value":"kong/3.8.0"},{"key":"X-Kong-Upstream-Latency","value":"1261"},{"key":"X-Kong-Proxy-Latency","value":"3"},{"key":"Via","value":"1.1 kong/3.8.0"},{"key":"X-Kong-Request-Id","value":"c3d55a45ab449b4958b37255173f7c63"}],"cookie":[],"responseTime":null,"body":"{\n \"data\": {\n \"success\": true,\n \"message\": \"Order answered\"\n }\n}"},{"id":"e75ed151-f4e4-4911-9edc-69aabcbc7edf","name":"[200] Responder pedido negativamente por não trabalhar com um dos items","originalRequest":{"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"accept\": false,\n \"details\": [\n {\n \"type\": \"out_of_portfolio\",\n \"message\": null,\n \"item\": \"a933aab6-c880-470b-b3be-2cc5af040263\"\n }\n ]\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"https://api.staging.hubii.co/hubs/:hub_uuid/orders/:order_uuid/answer","host":["https://api.staging.hubii.co"],"path":["hubs",":hub_uuid","orders",":order_uuid","answer"],"variable":[{"key":"hub_uuid","value":"b6f2eefa-da34-4daa-ae2b-98c3bd7b29c2"},{"key":"order_uuid","value":"71402839-ecb5-4ee0-b73a-331e7bef74f5"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"RateLimit-Reset","value":"22"},{"key":"RateLimit-Limit","value":"10"},{"key":"X-RateLimit-Remaining-Minute","value":"8"},{"key":"X-RateLimit-Limit-Minute","value":"10"},{"key":"RateLimit-Remaining","value":"8"},{"key":"Host","value":"api.staging.hubii.co"},{"key":"X-Powered-By","value":"PHP/8.1.29"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"Date","value":"Thu, 21 Nov 2024 14:37:39 GMT"},{"key":"X-RateLimit-Limit","value":"60"},{"key":"X-RateLimit-Remaining","value":"58"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Server","value":"kong/3.8.0"},{"key":"X-Kong-Upstream-Latency","value":"1261"},{"key":"X-Kong-Proxy-Latency","value":"3"},{"key":"Via","value":"1.1 kong/3.8.0"},{"key":"X-Kong-Request-Id","value":"c3d55a45ab449b4958b37255173f7c63"}],"cookie":[],"responseTime":null,"body":"{\n \"data\": {\n \"success\": true,\n \"message\": \"Order answered\"\n }\n}"},{"id":"594878c9-c02f-47f4-b902-f9e7a9904011","name":"[200] Responder pedido negativamente por não ter em estoque um dos items","originalRequest":{"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"accept\": false,\n \"details\": [\n {\n \"type\": \"out_of_stock\",\n \"message\": null,\n \"item\": \"a933aab6-c880-470b-b3be-2cc5af040263\"\n }\n ]\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"https://api.staging.hubii.co/hubs/:hub_uuid/orders/:order_uuid/answer","host":["https://api.staging.hubii.co"],"path":["hubs",":hub_uuid","orders",":order_uuid","answer"],"variable":[{"key":"hub_uuid","value":"b6f2eefa-da34-4daa-ae2b-98c3bd7b29c2"},{"key":"order_uuid","value":"71402839-ecb5-4ee0-b73a-331e7bef74f5"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"RateLimit-Reset","value":"22"},{"key":"RateLimit-Limit","value":"10"},{"key":"X-RateLimit-Remaining-Minute","value":"8"},{"key":"X-RateLimit-Limit-Minute","value":"10"},{"key":"RateLimit-Remaining","value":"8"},{"key":"Host","value":"api.staging.hubii.co"},{"key":"X-Powered-By","value":"PHP/8.1.29"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"Date","value":"Thu, 21 Nov 2024 14:37:39 GMT"},{"key":"X-RateLimit-Limit","value":"60"},{"key":"X-RateLimit-Remaining","value":"58"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Server","value":"kong/3.8.0"},{"key":"X-Kong-Upstream-Latency","value":"1261"},{"key":"X-Kong-Proxy-Latency","value":"3"},{"key":"Via","value":"1.1 kong/3.8.0"},{"key":"X-Kong-Request-Id","value":"c3d55a45ab449b4958b37255173f7c63"}],"cookie":[],"responseTime":null,"body":"{\n \"data\": {\n \"success\": true,\n \"message\": \"Order answered\"\n }\n}"},{"id":"535a9edd-3799-434f-9813-aaa914e0aaf1","name":"[200] Responder pedido negativamente por estoque insuficiente","originalRequest":{"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"accept\": false,\n \"details\": [\n {\n \"type\": \"quantity_not_enough\",\n \"message\": null,\n \"item\": \"a933aab6-c880-470b-b3be-2cc5af040263\"\n }\n ]\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"https://api.staging.hubii.co/hubs/:hub_uuid/orders/:order_uuid/answer","host":["https://api.staging.hubii.co"],"path":["hubs",":hub_uuid","orders",":order_uuid","answer"],"variable":[{"key":"hub_uuid","value":"b6f2eefa-da34-4daa-ae2b-98c3bd7b29c2"},{"key":"order_uuid","value":"71402839-ecb5-4ee0-b73a-331e7bef74f5"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"RateLimit-Reset","value":"22"},{"key":"RateLimit-Limit","value":"10"},{"key":"X-RateLimit-Remaining-Minute","value":"8"},{"key":"X-RateLimit-Limit-Minute","value":"10"},{"key":"RateLimit-Remaining","value":"8"},{"key":"Host","value":"api.staging.hubii.co"},{"key":"X-Powered-By","value":"PHP/8.1.29"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"Date","value":"Thu, 21 Nov 2024 14:37:39 GMT"},{"key":"X-RateLimit-Limit","value":"60"},{"key":"X-RateLimit-Remaining","value":"58"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Server","value":"kong/3.8.0"},{"key":"X-Kong-Upstream-Latency","value":"1261"},{"key":"X-Kong-Proxy-Latency","value":"3"},{"key":"Via","value":"1.1 kong/3.8.0"},{"key":"X-Kong-Request-Id","value":"c3d55a45ab449b4958b37255173f7c63"}],"cookie":[],"responseTime":null,"body":"{\n \"data\": {\n \"success\": true,\n \"message\": \"Order answered\"\n }\n}"},{"id":"cea6ebf3-78da-466b-8fee-6fa45dea028a","name":"[200] Responder pedido negativamente por não aceitar o valor do repasse de um dos itens","originalRequest":{"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"accept\": false,\n \"details\": [\n {\n \"type\": \"price\",\n \"message\": null,\n \"item\": \"a933aab6-c880-470b-b3be-2cc5af040263\"\n }\n ]\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"https://api.staging.hubii.co/hubs/:hub_uuid/orders/:order_uuid/answer","host":["https://api.staging.hubii.co"],"path":["hubs",":hub_uuid","orders",":order_uuid","answer"],"variable":[{"key":"hub_uuid","value":"b6f2eefa-da34-4daa-ae2b-98c3bd7b29c2"},{"key":"order_uuid","value":"71402839-ecb5-4ee0-b73a-331e7bef74f5"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"RateLimit-Reset","value":"22"},{"key":"RateLimit-Limit","value":"10"},{"key":"X-RateLimit-Remaining-Minute","value":"8"},{"key":"X-RateLimit-Limit-Minute","value":"10"},{"key":"RateLimit-Remaining","value":"8"},{"key":"Host","value":"api.staging.hubii.co"},{"key":"X-Powered-By","value":"PHP/8.1.29"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"Date","value":"Thu, 21 Nov 2024 14:37:39 GMT"},{"key":"X-RateLimit-Limit","value":"60"},{"key":"X-RateLimit-Remaining","value":"58"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Server","value":"kong/3.8.0"},{"key":"X-Kong-Upstream-Latency","value":"1261"},{"key":"X-Kong-Proxy-Latency","value":"3"},{"key":"Via","value":"1.1 kong/3.8.0"},{"key":"X-Kong-Request-Id","value":"c3d55a45ab449b4958b37255173f7c63"}],"cookie":[],"responseTime":null,"body":"{\n \"data\": {\n \"success\": true,\n \"message\": \"Order answered\"\n }\n}"},{"id":"ead0b8c6-f0b3-4119-a715-63d8a8bb2ed7","name":"[422] Responder pedido","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"accept\": false,\r\n \"details\": [\r\n {\r\n \"type\": \"price\",\r\n \"message\": null,\r\n \"item\": \"a933aab6-c880-470b-b3be-2cc5af040263\"\r\n }\r\n ]\r\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"https://api.staging.hubii.co/hubs/:hub_uuid/orders/:order_uuid/answer","host":["https://api.staging.hubii.co"],"path":["hubs",":hub_uuid","orders",":order_uuid","answer"],"variable":[{"key":"hub_uuid","value":"b6f2eefa-da34-4daa-ae2b-98c3bd7b29c2"},{"key":"order_uuid","value":"71402839-ecb5-4ee0-b73a-331e7bef74f5"}]}},"status":"Unprocessable Content","code":422,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"RateLimit-Reset","value":"21"},{"key":"RateLimit-Limit","value":"10"},{"key":"X-RateLimit-Remaining-Minute","value":"9"},{"key":"X-RateLimit-Limit-Minute","value":"10"},{"key":"RateLimit-Remaining","value":"9"},{"key":"Host","value":"api.staging.hubii.co"},{"key":"X-Powered-By","value":"PHP/8.1.29"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"Date","value":"Thu, 21 Nov 2024 14:35:40 GMT"},{"key":"X-RateLimit-Limit","value":"60"},{"key":"X-RateLimit-Remaining","value":"59"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Server","value":"kong/3.8.0"},{"key":"X-Kong-Upstream-Latency","value":"258"},{"key":"X-Kong-Proxy-Latency","value":"3"},{"key":"Via","value":"1.1 kong/3.8.0"},{"key":"X-Kong-Request-Id","value":"26954260301cc67ab1c5237a1a2f3d24"}],"cookie":[],"responseTime":null,"body":"{\n \"data\": {\n \"success\": false,\n \"error\": \"Order already answered\"\n }\n}"}],"_postman_id":"14070808-d799-44fa-a76e-b0d56660583a"}],"id":"40a6ae6d-be81-4ce0-a1c5-001b00bc5a19","_postman_id":"40a6ae6d-be81-4ce0-a1c5-001b00bc5a19","description":"","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"apikey"},{"key":"value","value":""}]},"isInherited":true,"source":{"_postman_id":"7e207411-7624-4909-8d24-35ec0605eb45","id":"7e207411-7624-4909-8d24-35ec0605eb45","name":"Hubii API","type":"collection"}}},{"name":"03 — Polling 2: Notificações (pedidos aceitos)","item":[{"name":"Notificações de Eventos","id":"3f651bb4-3c68-45e2-81e1-3eea7185abf6","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"apikey"},{"key":"value","value":""}]},"isInherited":false},"method":"GET","header":[{"key":"Accept","value":"application/json","type":"text"}],"url":"https://api.staging.hubii.co/v2/notifications","description":"

Objetivo

Polling 2 — Notificações. Lista eventos de pedidos já aceitos pelo hub, seja por API ou pelo painel Hubii.

\n
Esta rota não mostra ofertas pendentes. Pedido ainda não aceito, recusado ou expirado não aparece aqui para este hub.
\n

Quando chamar

A cada 30–60 segundos, em paralelo ao Polling 1.
\n
Depois de processar e persistir cada evento, chame POST /notifications/ack.
\n

Fluxo

[Polling 1] aceite via API ou painel\n  ↓\nGET /v2/notifications\n  ↓ ORDER_CREATED\nGET /hubs/{hub_uuid}/orders/{order_uuid}\n  ↓ persistir no ERP\nPOST /notifications/ack\n\n

Filtros opcionais

Formato oficial documentado nesta collection: repetir o mesmo parâmetro para múltiplos valores.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Param	Exemplo	Descrição
`hub_uuids`	`?hub_uuids={hub_uuid}`	Filtra por um hub
`hub_uuids`	`?hub_uuids={hub_uuid}&hub_uuids={hub_uuid_2}`	Filtra por vários hubs
`types`	`?types=ORDER_CREATED`	Filtra por um tipo
`types`	`?types=ORDER_CREATED&types=ORDER_CANCELLED`	Filtra por vários tipos

\n
Se a implementação do parceiro usar biblioteca que converte arrays para hub_uuids[], valide com o time Hubii antes da homologação. A collection usa hub_uuids e types sem colchetes.
\n

Paginação

A resposta é um objeto paginado. Itere page até page >= last_page quando houver mais eventos.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Campo	Uso
`data`	Lista de notificações da página atual
`total`	Total de notificações no filtro
`page`	Página atual
`last_page`	Última página disponível
`per_page`	Tamanho da página (equivale a `limit`)

Query params de paginação

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Param	Padrão	Descrição
`page`	`1`	Página atual
`limit`	`15`	Itens por página (máx. `100`)

Campos de cada item em `data[]`

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Campo	Uso
`notification_uuid`	Chave de idempotência no ERP e valor usado no ACK
`type` / `subtype`	Tipo e subtipo do evento
`order_uuid` / `order_id`	Identificadores do pedido
`hub_uuid`	Hub relacionado ao evento
`date`	Data/hora do evento

Matriz de eventos

Eventos que exigem ação no ERP

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

type	subtype	Quando acontece	Ação esperada	Buscar detalhes do pedido?
`ORDER_CREATED`	—	Após aceite via API ou painel	Importar/reconciliar pedido	Sim
`ORDER_DELIVERY_UPDATED`	`ORDER_DELIVERY_SEARCHING_COURIER`	Buscando entregador	Atualizar status logístico	Opcional
`ORDER_DELIVERY_UPDATED`	`ORDER_DELIVERY_COURIER_NOT_FOUND`	Entregador não encontrado	Atualizar status logístico	Opcional
`ORDER_DELIVERY_UPDATED`	`ORDER_DELIVERY_COURIER_FOUND`	Entregador atribuído	Atualizar status logístico	Opcional
`ORDER_DELIVERY_UPDATED`	`ORDER_DELIVERY_PICKING_UP`	Coleta iniciada	Atualizar status e buscar `pickup_code`	Sim
`ORDER_DELIVERY_UPDATED`	`ORDER_DELIVERY_PICKED_UP`	Pedido coletado	Atualizar status logístico	Opcional
`ORDER_DELIVERY_UPDATED`	`ORDER_DELIVERY_DELIVERING`	Em rota	Atualizar status logístico	Opcional
`ORDER_DELIVERY_UPDATED`	`ORDER_DELIVERY_FAILED_TO_DELIVERY`	Falha na entrega	Atualizar status logístico	Opcional
`ORDER_DELIVERY_UPDATED`	`ORDER_DELIVERY_DELIVERED`	Pedido entregue	Atualizar status logístico	Opcional
`ORDER_DELIVERY_UPDATED`	`ORDER_DELIVERY_LOST`	Extravio	Atualizar status logístico	Opcional
`ORDER_CANCELLED`	`ORDER_CANCELLED`	Cancelamento pelo cliente/plataforma	Cancelar ou inutilizar NF se aplicável	Opcional
`ORDER_CANCELLED`	`ORDER_CANCELLED_BY_HUB`	Cancelamento pelo hub	Atualizar pedido e NF se aplicável	Opcional
`SHIPPING_LABEL_AVAILABLE`	—	Etiqueta disponível para o pedido	Baixar etiqueta em `GET .../label`	Opcional

\n
A necessidade de etiqueta depende do pedido, não apenas do canal de venda.
\n

Eventos informativos

Registre e envie ACK, mas não exigem lógica operacional específica no ERP.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

type	Observação
`INVOICE_PENDING`	Informativo; não substitui o envio de NF quando aplicável
`ORDER_UPDATED`	Informativo; use apenas se o escopo do parceiro exigir

Estratégia de ACK

Buscar notificações.
\n
Processar uma a uma no ERP.
\n
Persistir localmente usando notification_uuid.
\n
Enviar ACK somente após sucesso.
\n
Se o ACK falhar, retentar o ACK e não reprocessar o evento duplicado.
\n

\n
ACK cedo demais pode causar perda de evento. Sem ACK, a notificação reaparece por até 2 dias.
\n

Regras críticas

ORDER_CREATED é o gatilho recomendado para importar ou reconciliar o pedido aceito.
\n
Notificações expiram em 2 dias sem ACK.
\n
Cancelamentos podem chegar até 1 dia após o cancelamento real.
\n
Pedido recusado ou expirado no Polling 1 não gera evento neste polling para o hub.
\n

Exemplos cURL

Sem filtro:

curl -s \"$BASE_URL/v2/notifications\" \\\n  -H \"Accept: application/json\" \\\n  -H \"apikey: $HUBII_API_KEY\"\n\n

Com filtros:

curl -s \"$BASE_URL/v2/notifications?hub_uuids=$HUB_UUID&types=ORDER_CREATED\" \\\n  -H \"Accept: application/json\" \\\n  -H \"apikey: $HUBII_API_KEY\"\n\n

Idempotência

GET seguro repetir. O mesmo notification_uuid retorna até receber ACK.

Tratamento de erros

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Status	Orientação
`401`	Não retentar automaticamente; revisar API Key
`403`	Verificar se a API Key tem acesso ao hub informado
`404`	Verificar `hub_uuid`, `order_uuid` ou se o recurso ainda está disponível
`422`	Tratar como erro de regra de negócio ou payload inválido; não fazer retry cego
`429`	Aplicar backoff exponencial e respeitar os headers de rate limit
`5xx` / timeout	Retentar com backoff exponencial e limite de tentativas

\n
Em runtime, use os headers X-RateLimit-\\\\\\\\* como referência operacional. A tabela de rate limits documenta o limite esperado/contratual.
\n

Diagramas

Importação e faturamento

\n\n

Atualizações de entrega

\n\n

Sequência de eventos

","urlObject":{"path":["v2","notifications"],"host":["https://api.staging.hubii.co"],"query":[{"disabled":true,"description":{"content":"

Página atual; padrão: 1

\n","type":"text/plain"},"key":"page","value":"1"},{"disabled":true,"description":{"content":"

Itens por página; padrão: 15; máximo: 100

\n","type":"text/plain"},"key":"limit","value":"15"},{"disabled":true,"description":{"content":"

Filtrar por hub

\n","type":"text/plain"},"key":"hub_uuid","value":""},{"disabled":true,"description":{"content":"

Segundo hub opcional; repetir o parâmetro para múltiplos hubs

\n","type":"text/plain"},"key":"hub_uuids[0]","value":""},{"disabled":true,"description":{"content":"

Filtrar por tipo de evento

\n","type":"text/plain"},"key":"types","value":"ORDER_CREATED"},{"disabled":true,"description":{"content":"

Segundo tipo opcional; repetir o parâmetro para múltiplos tipos

\n","type":"text/plain"},"key":"types","value":"ORDER_CANCELLED"}],"variable":[]}},"response":[{"id":"ef79a613-555b-40e6-8c3a-5f60d108395f","name":"Notificações paginadas sem filtros","originalRequest":{"method":"GET","header":[{"key":"Accept","value":"application/json","type":"text"}],"url":{"raw":"https://api.staging.hubii.co/v2/notifications","host":["https://api.staging.hubii.co"],"path":["v2","notifications"],"query":[{"key":"hub_uuids","value":"a93dd09b-4c47-479a-9dca-9fb8026301a6","description":"Utilize o UUID's dos hubs para filtrar notificações referentes a eles. Para mais de 1 hub envie com separação por virgula","disabled":true},{"key":"types[0]","value":"ORDER_CREATED,ORDER_DELIVERY_UPDATE,ORDER_CANCELLED","description":"Filtre as notificações pelo seu tipo. Para mais de 1 tipo envie com separação por virgula.","disabled":true}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Fri, 05 Sep 2025 19:31:23 GMT"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"x-ratelimit-remaining-minute","value":"9"},{"key":"x-ratelimit-limit-minute","value":"10"},{"key":"ratelimit-remaining","value":"9"},{"key":"ratelimit-reset","value":"38"},{"key":"ratelimit-limit","value":"10"},{"key":"x-powered-by","value":"Express"},{"key":"etag","value":"W/\"f92-vQDqeTTBSMMFuOt/SQZLfa/TQ5M\""},{"key":"Server","value":"cloudflare"},{"key":"x-kong-upstream-latency","value":"39"},{"key":"x-kong-proxy-latency","value":"32"},{"key":"via","value":"1.1 kong/3.9.1"},{"key":"x-kong-request-id","value":"1e499a7323da6603dad0cd7dcfb2a278"},{"key":"cf-cache-status","value":"DYNAMIC"},{"key":"Nel","value":"{\"report_to\":\"cf-nel\",\"success_fraction\":0.0,\"max_age\":604800}"},{"key":"Report-To","value":"{\"group\":\"cf-nel\",\"max_age\":604800,\"endpoints\":[{\"url\":\"https://a.nel.cloudflare.com/report/v4?s=RWjTNpOyWLU2jx1FVJVpG4maaZC0x3YyEPxwkFJVD%2BMl7WI4eWzRVENHZmHsjrmiKJwlmvTm6fyvI0S6E5aiHZ5XBqKG61a15Ri%2FXwRJsfgP4J4%3D\"}]}"},{"key":"Content-Encoding","value":"br"},{"key":"CF-RAY","value":"97a825824f821ce5-GRU"}],"cookie":[],"responseTime":null,"body":"{\n \"data\": [\n {\n \"notification_uuid\": \"066d19b9-4aef-4b40-941b-d104ab158cd2\",\n \"type\": \"ORDER_CREATED\",\n \"subtype\": null,\n \"order_uuid\": \"356a4241-456b-49a6-8bdc-93f92ddec7f2\",\n \"order_id\": \"146167\",\n \"order_delivery_id\": \"119758\",\n \"hub_uuid\": \"a93dd09b-4c47-479a-9dca-9fb8026301a6\",\n \"date\": \"2025-09-03T21:46:59.000Z\"\n },\n {\n \"notification_uuid\": \"c3bc1f55-fe65-49c5-ac89-fcef38827d41\",\n \"type\": \"ORDER_DELIVERY_UPDATED\",\n \"subtype\": \"ORDER_DELIVERY_SEARCHING_COURIER\",\n \"order_uuid\": \"356a4241-456b-49a6-8bdc-93f92ddec7f2\",\n \"order_id\": \"146167\",\n \"order_delivery_id\": \"119758\",\n \"hub_uuid\": \"a93dd09b-4c47-479a-9dca-9fb8026301a6\",\n \"date\": \"2025-09-03T21:47:29.000Z\"\n },\n {\n \"notification_uuid\": \"636b4abf-2458-4e5e-a285-4184af2ffdfd\",\n \"type\": \"ORDER_CREATED\",\n \"subtype\": null,\n \"order_uuid\": \"c71af0ac-6d96-4d1f-a59f-a651ce2c4eb8\",\n \"order_id\": \"146199\",\n \"order_delivery_id\": \"119790\",\n \"hub_uuid\": \"a93dd09b-4c47-479a-9dca-9fb8026301a6\",\n \"date\": \"2025-09-04T12:49:40.000Z\"\n },\n {\n \"notification_uuid\": \"09d0613e-50de-4ed0-9383-184a93429275\",\n \"type\": \"ORDER_DELIVERY_UPDATED\",\n \"subtype\": \"ORDER_DELIVERY_SEARCHING_COURIER\",\n \"order_uuid\": \"c71af0ac-6d96-4d1f-a59f-a651ce2c4eb8\",\n \"order_id\": \"146199\",\n \"order_delivery_id\": \"119790\",\n \"hub_uuid\": \"a93dd09b-4c47-479a-9dca-9fb8026301a6\",\n \"date\": \"2025-09-04T12:49:44.000Z\"\n },\n {\n \"notification_uuid\": \"f8bb9ca5-961c-4bc3-9bf5-2b47452b2f81\",\n \"type\": \"ORDER_CREATED\",\n \"subtype\": null,\n \"order_uuid\": \"571cdfbe-ba9a-4cf2-aaea-45c67b064c88\",\n \"order_id\": \"146265\",\n \"order_delivery_id\": \"119856\",\n \"hub_uuid\": \"a93dd09b-4c47-479a-9dca-9fb8026301a6\",\n \"date\": \"2025-09-04T16:18:40.000Z\"\n },\n {\n \"notification_uuid\": \"d987097a-a097-49c8-8c57-cf302f3efabd\",\n \"type\": \"ORDER_DELIVERY_UPDATED\",\n \"subtype\": \"ORDER_DELIVERY_COURIER_NOT_FOUND\",\n \"order_uuid\": \"c71af0ac-6d96-4d1f-a59f-a651ce2c4eb8\",\n \"order_id\": \"146199\",\n \"order_delivery_id\": \"119790\",\n \"hub_uuid\": \"a93dd09b-4c47-479a-9dca-9fb8026301a6\",\n \"date\": \"2025-09-04T12:50:59.000Z\"\n },\n {\n \"notification_uuid\": \"35f09ebf-94e4-440f-902e-f74c1f89670c\",\n \"type\": \"ORDER_DELIVERY_UPDATED\",\n \"subtype\": \"ORDER_DELIVERY_SEARCHING_COURIER\",\n \"order_uuid\": \"571cdfbe-ba9a-4cf2-aaea-45c67b064c88\",\n \"order_id\": \"146265\",\n \"order_delivery_id\": \"119856\",\n \"hub_uuid\": \"a93dd09b-4c47-479a-9dca-9fb8026301a6\",\n \"date\": \"2025-09-04T16:18:44.000Z\"\n },\n {\n \"notification_uuid\": \"07451006-152c-4406-8ae1-f755bff7bdca\",\n \"type\": \"ORDER_CREATED\",\n \"subtype\": null,\n \"order_uuid\": \"b3372551-01d4-4de8-9f1b-d3e0c912992f\",\n \"order_id\": \"146390\",\n \"order_delivery_id\": \"119981\",\n \"hub_uuid\": \"dbe03cf0-c04b-458c-9b68-16af9faaa9ea\",\n \"date\": \"2025-09-05T18:57:59.000Z\"\n },\n {\n \"notification_uuid\": \"883596c5-dbdd-4720-9178-68b13f428e30\",\n \"type\": \"ORDER_CREATED\",\n \"subtype\": null,\n \"order_uuid\": \"b3372551-01d4-4de8-9f1b-d3e0c912992f\",\n \"order_id\": \"146390\",\n \"order_delivery_id\": \"119981\",\n \"hub_uuid\": \"dbe03cf0-c04b-458c-9b68-16af9faaa9ea\",\n \"date\": \"2025-09-05T19:06:53.000Z\"\n },\n {\n \"notification_uuid\": \"0cdd2ae7-4a0e-4480-b1e9-950141be78dd\",\n \"type\": \"ORDER_DELIVERY_UPDATED\",\n \"subtype\": \"ORDER_DELIVERY_SEARCHING_COURIER\",\n \"order_uuid\": \"b3372551-01d4-4de8-9f1b-d3e0c912992f\",\n \"order_id\": \"146390\",\n \"order_delivery_id\": \"119981\",\n \"hub_uuid\": \"dbe03cf0-c04b-458c-9b68-16af9faaa9ea\",\n \"date\": \"2025-09-05T19:07:35.000Z\"\n },\n {\n \"notification_uuid\": \"95af8726-3833-424d-bb18-0d0c716b4ffa\",\n \"type\": \"ORDER_DELIVERY_UPDATED\",\n \"subtype\": \"ORDER_DELIVERY_COURIER_FOUND\",\n \"order_uuid\": \"b3372551-01d4-4de8-9f1b-d3e0c912992f\",\n \"order_id\": \"146390\",\n \"order_delivery_id\": \"119981\",\n \"hub_uuid\": \"dbe03cf0-c04b-458c-9b68-16af9faaa9ea\",\n \"date\": \"2025-09-05T19:07:51.000Z\"\n },\n {\n \"notification_uuid\": \"1766ae9b-b06d-4486-8c41-37add23fe872\",\n \"type\": \"ORDER_DELIVERY_UPDATED\",\n \"subtype\": \"ORDER_DELIVERY_DELIVERING\",\n \"order_uuid\": \"b3372551-01d4-4de8-9f1b-d3e0c912992f\",\n \"order_id\": \"146390\",\n \"order_delivery_id\": \"119981\",\n \"hub_uuid\": \"dbe03cf0-c04b-458c-9b68-16af9faaa9ea\",\n \"date\": \"2025-09-05T19:08:03.000Z\"\n },\n {\n \"notification_uuid\": \"7d122bff-d184-4a19-bd62-b30e03fee07f\",\n \"type\": \"ORDER_DELIVERY_UPDATED\",\n \"subtype\": \"ORDER_DELIVERY_DELIVERED\",\n \"order_uuid\": \"b3372551-01d4-4de8-9f1b-d3e0c912992f\",\n \"order_id\": \"146390\",\n \"order_delivery_id\": \"119981\",\n \"hub_uuid\": \"dbe03cf0-c04b-458c-9b68-16af9faaa9ea\",\n \"date\": \"2025-09-05T19:08:11.000Z\"\n }\n ],\n \"total\": 13,\n \"page\": 1,\n \"last_page\": 1,\n \"per_page\": 13\n}"}],"_postman_id":"3f651bb4-3c68-45e2-81e1-3eea7185abf6"},{"name":"Reconhecimento de Notificação em Massa","id":"301bfd7e-ba77-454c-9e0f-f31a2c186825","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"apikey"},{"key":"value","value":""}]},"isInherited":false},"method":"POST","header":[{"key":"Accept","value":"application/json","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"uuids\": [\n \"9018e5d3-f653-443b-b64e-c45d475f0189\",\n \"4996dc47-1832-47da-82b9-04468e2696bf\"\n ]\n}","options":{"raw":{"language":"json"}}},"url":"https://api.staging.hubii.co/notifications/ack","description":"

Objetivo

Confirma que uma ou mais notificações do Polling 2 foram processadas com sucesso no ERP. Após o ACK, elas deixam de aparecer na fila.

Quando chamar

Somente depois de processar e persistir o evento localmente. Não envie ACK antes de gravar o resultado no ERP.

Fluxo recomendado

GET /v2/notifications.
Processar cada evento no ERP.
Persistir notification_uuid como chave única.
Enviar ACK para os eventos concluídos.
Se o ACK falhar, retentar apenas o ACK.

Body

O campo uuids recebe uma lista de notification_uuid.

{\n  \"uuids\": [\n    \"notification-uuid-1\",\n    \"notification-uuid-2\"\n  ]\n}\n

Comportamento esperado

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Situação	Efeito
Sem ACK	A notificação reaparece no próximo poll, por até 2 dias
ACK após processamento	A notificação é removida da fila
ACK antes da persistência	Risco de perda do evento se o ERP falhar depois
ACK falhou por timeout ou `5xx`	Retentar ACK; não reprocessar o evento

Exemplo cURL

curl -s -X POST \"$BASE_URL/notifications/ack\" \\\n  -H \"Accept: application/json\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"apikey: $HUBII_API_KEY\" \\\n  -d '{\"uuids\": [\"NOTIFICATION_UUID\"]}'\n

Idempotência

No ERP, trate notification_uuid como chave única. Se a mesma notificação reaparecer, não duplique o processamento; apenas tente confirmar o ACK novamente.

Tratamento de erros

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Status	Orientação
`401`	Não retentar automaticamente; revisar API Key
`403`	Verificar se a API Key tem acesso ao hub informado
`404`	Verificar `hub_uuid`, `order_uuid` ou se o recurso ainda está disponível
`422`	Tratar como erro de regra de negócio ou payload inválido; não fazer retry cego
`429`	Aplicar backoff exponencial e respeitar os headers de rate limit
`5xx` / timeout	Retentar com backoff exponencial e limite de tentativas

\n
Em runtime, use os headers X-RateLimit-* como referência operacional. A tabela de rate limits documenta o limite esperado/contratual.
\n

\n","urlObject":{"path":["notifications","ack"],"host":["https://api.staging.hubii.co"],"query":[],"variable":[]}},"response":[],"_postman_id":"301bfd7e-ba77-454c-9e0f-f31a2c186825"}],"id":"e74c0a81-e8cc-4c6d-83c8-2d975bcec6a5","description":"

\n
Descontinuação: GET /notifications foi substituído por GET /v2/notifications (resposta paginada com page e limit). O endpoint legado permanece disponível apenas por compatibilidade e retorna os headers X-API-Deprecated: true e X-API-Replacement: /v2/notifications. Novas integrações devem usar apenas a v2. O endpoint legado está documentado na pasta [Descontinuado].
\n

\n","_postman_id":"e74c0a81-e8cc-4c6d-83c8-2d975bcec6a5","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"apikey"},{"key":"value","value":""}]},"isInherited":true,"source":{"_postman_id":"7e207411-7624-4909-8d24-35ec0605eb45","id":"7e207411-7624-4909-8d24-35ec0605eb45","name":"Hubii API","type":"collection"}}},{"name":"04 — Pedidos","item":[{"name":"Detalhes do pedido","id":"8b997ef8-e0ce-4b2f-ac17-628322e3e8d7","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"apikey"},{"key":"value","value":""}]},"isInherited":false},"method":"GET","header":[{"key":"Accept","value":"application/json","type":"text"}],"url":"https://api.staging.hubii.co/hubs/:hub_uuid/orders/:order_uuid","description":"

Objetivo

Retorna os dados completos de um pedido. Use este endpoint em dois momentos principais:

Antes de aceitar ou recusar uma oferta retornada em to-answer, para avaliar itens, quantidades, preços, disponibilidade e regras do hub.
Depois do aceite, ao receber ORDER_CREATED, para importar ou reconciliar o pedido no ERP.

Quando chamar

Para cada pedido recebido em GET .../to-answer, antes de POST .../answer.
Após receber ORDER_CREATED no Polling 2.
Antes de emitir ou enviar NF-e.
Após ORDER_DELIVERY_PICKING_UP, quando for necessário obter pickup_code.
Sempre que o ERP precisar reconciliar o estado atual do pedido.

Path params

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Param	Descrição
`hub_uuid`	UUID do hub
`order_uuid`	UUID do pedido

Campos principais

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Campo	Uso
`id`	ID numérico; exiba no ERP e use em suporte Hubii
`uuid`	UUID do pedido
`subtotal`, `discount`, `delivery_cost`, `total`	Valores financeiros
`invoice_allowed`	Formatos permitidos para NF-e (55 ou 65)
`delivery_status`	Status logístico atual
`estimated_delivery_at`	Previsão de entrega
`pickup_code`	`null` até `ORDER_DELIVERY_PICKING_UP`; depois do evento, consulte novamente
`customer`	Dados do comprador
`delivery_address` / `invoice_address`	Endereços de entrega e faturamento
`items[]`	Itens do pedido, incluindo `uuid`, produto, EAN, quantidade e preços
`courier` / `carrier`	Entregador ou transportadora, quando disponível

Uso na decisão de aceite

A decisão do hub normalmente depende dos itens e condições do pedido completo. Antes de responder uma oferta, use os dados deste endpoint para validar:

se os itens fazem parte do portfólio do hub;
se há estoque suficiente;
se preço/repasse é aceitável;
se há alguma restrição operacional ou fiscal;
se o pedido pode ser atendido dentro do fluxo esperado.

Exemplo cURL

curl -s \"$BASE_URL/hubs/$HUB_UUID/orders/$ORDER_UUID\" \\\n  -H \"Accept: application/json\" \\\n  -H \"apikey: $HUBII_API_KEY\"\n

Idempotência

GET seguro repetir.

Tratamento de erros

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Status	Orientação
`401`	Não retentar automaticamente; revisar API Key
`403`	Verificar se a API Key tem acesso ao hub informado
`404`	Verificar `hub_uuid`, `order_uuid` ou se o recurso ainda está disponível
`422`	Tratar como erro de regra de negócio ou payload inválido; não fazer retry cego
`429`	Aplicar backoff exponencial e respeitar os headers de rate limit
`5xx` / timeout	Retentar com backoff exponencial e limite de tentativas

\n
Em runtime, use os headers X-RateLimit-* como referência operacional. A tabela de rate limits documenta o limite esperado/contratual.
\n

Próximo passo

Se a consulta veio a partir de to-answer, responda a oferta com POST .../answer antes de available_until_at.
Se a consulta veio a partir de ORDER_CREATED, importe ou reconcilie o pedido no ERP e depois envie ACK da notificação processada.

\n","urlObject":{"path":["hubs",":hub_uuid","orders",":order_uuid"],"host":["https://api.staging.hubii.co"],"query":[],"variable":[{"id":"dd9b13f8-fe72-4be2-99ff-727f8d246ecd","description":{"content":"

UUID do hub retornado em GET /hubs

\n","type":"text/plain"},"type":"any","value":"","key":"hub_uuid"},{"id":"8d957234-31c1-406e-be36-eee7b95cc2ab","description":{"content":"

UUID do pedido

\n","type":"text/plain"},"type":"any","value":"","key":"order_uuid"}]}},"response":[{"id":"ae84feb1-41d2-48d5-9a0a-b31b76799a84","name":"[200] Detalhes do pedido","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.staging.hubii.co/hubs/:hub_uuid/orders/:order_uuid","host":["https://api.staging.hubii.co"],"path":["hubs",":hub_uuid","orders",":order_uuid"],"variable":[{"key":"hub_uuid","value":"dbe03cf0-c04b-458c-9b68-16af9faaa9ea"},{"key":"order_uuid","value":"e43a1dac-6a3b-40ff-88cb-296ef253c344"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":":status","value":200},{"key":"date","value":"Tue, 02 Jun 2026 13:04:13 GMT"},{"key":"Content-Type","value":"application/json","description":"","type":"text"},{"key":"ratelimit-reset","value":"48"},{"key":"x-ratelimit-remaining-minute","value":"299"},{"key":"ratelimit-limit","value":"300"},{"key":"x-ratelimit-limit-minute","value":"300"},{"key":"ratelimit-remaining","value":"299"},{"key":"server","value":"cloudflare"},{"key":"vary","value":"Accept-Encoding"},{"key":"x-powered-by","value":"PHP/8.2.31"},{"key":"cache-control","value":"no-cache, private"},{"key":"x-ratelimit-limit","value":"60"},{"key":"x-ratelimit-remaining","value":"59"},{"key":"access-control-allow-origin","value":"*"},{"key":"x-frame-options","value":"SAMEORIGIN"},{"key":"x-xss-protection","value":"1; mode=block"},{"key":"x-content-type-options","value":"nosniff"},{"key":"content-encoding","value":"gzip"},{"key":"x-kong-upstream-latency","value":"1112"},{"key":"x-kong-proxy-latency","value":"3"},{"key":"via","value":"1.1 kong/3.9.1"},{"key":"x-kong-request-id","value":"9771364eb10892350cd59d33b696df33"},{"key":"cf-cache-status","value":"DYNAMIC"},{"key":"nel","value":"{\"report_to\":\"cf-nel\",\"success_fraction\":0.0,\"max_age\":604800}"},{"key":"report-to","value":"{\"group\":\"cf-nel\",\"max_age\":604800,\"endpoints\":[{\"url\":\"https://a.nel.cloudflare.com/report/v4?s=OoLxjchW%2F3qXCK%2FhYJmY6tLtWS4Sea2e0tnnL6htY4fWV1wEbBd6f2O6szshWgiui%2FpxGEYzPLU8sdyZKlMZXvtdhzRUehJOM05%2FZInxpio6v03e4NaHDvacUHDv6P9%2BLiQfe%2B8QwVdQ9Aw98zyAQbO5\"}]}"},{"key":"cf-ray","value":"a056a99cf987b559-GRU"}],"cookie":[],"responseTime":null,"body":"{\n \"data\": {\n \"id\": 162422,\n \"uuid\": \"e43a1dac-6a3b-40ff-88cb-296ef253c344\",\n \"subtotal\": 169.6,\n \"discount\": 0,\n \"delivery_cost\": 0,\n \"total\": 169.6,\n \"invoice_allowed\": [\n 55\n ],\n \"delivery_status\": \"searching_courier\",\n \"estimated_delivery_at\": \"2027-01-05 02:59:59\",\n \"pickup_code\": null,\n \"customer\": {\n \"name\": \"Jonathan Sauer\",\n \"document\": \"51423502868\"\n },\n \"delivery_address\": {\n \"street_name\": \"R. Marechal José Bernardino Bormann\",\n \"address_number\": \"101\",\n \"complement\": \"AP 01\",\n \"postal_code\": \"80730-350\",\n \"neighborhood_name\": \"Bigorrilho\",\n \"city_name\": \"Curitiba\",\n \"province_code\": \"PR\",\n \"country_code\": \"BR\"\n },\n \"invoice_address\": {\n \"street_name\": \"R. Marechal José Bernardino Bormann\",\n \"address_number\": \"101\",\n \"complement\": \"AP 01\",\n \"postal_code\": \"80730-350\",\n \"neighborhood_name\": \"Bigorrilho\",\n \"city_name\": \"Curitiba\",\n \"province_code\": \"PR\",\n \"country_code\": \"BR\"\n },\n \"carrier\": {\n \"name\": null,\n \"document\": null\n },\n \"courier\": {\n \"name\": \"JOÃO ENTREGADOR\",\n \"document\": \"+5581999999999\",\n \"document_type\": \"phone\"\n },\n \"items\": [\n {\n \"uuid\": \"f3c763fa-0b9c-4c25-a90a-cc6b1a540d0c\",\n \"quantity\": 1,\n \"unit_price\": 29.9,\n \"total\": 29.9,\n \"ean\": \"7899598360602\",\n \"product\": \"Teste auto\"\n },\n {\n \"uuid\": \"d9d68530-e6ac-4cd4-bc76-895739891980\",\n \"quantity\": 2,\n \"unit_price\": 49.9,\n \"total\": 99.8,\n \"ean\": \"7892270821064\",\n \"product\": \"Produto\"\n },\n {\n \"uuid\": \"0e9a2c01-402b-4b33-94c6-0236a0819225\",\n \"quantity\": 1,\n \"unit_price\": 39.9,\n \"total\": 39.9,\n \"ean\": \"7891234995261\",\n \"product\": \"Produto\"\n }\n ]\n }\n}"}],"_postman_id":"8b997ef8-e0ce-4b2f-ac17-628322e3e8d7"},{"name":"Cancelamento do Pedido","id":"be9ee595-9edc-4a3a-91b5-eafdea8e51a7","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"apikey"},{"key":"value","value":""}]},"isInherited":false},"method":"POST","header":[{"key":"Accept","value":"application/json","type":"text"}],"url":"https://api.staging.hubii.co/hubs/:hub_uuid/orders/:order_uuid/cancel-accepted","description":"

Objetivo

Permite que o hub desista de um pedido já aceito antes da coleta. O pedido é redirecionado dentro da rede Hubii; esta ação não cancela automaticamente o pedido para o cliente final.

Quando chamar

Quando o hub não consegue atender um pedido que já havia aceitado.
Apenas antes da coleta pelo entregador/transportadora.
Quando este cenário fizer parte do escopo de homologação do parceiro.

Path params

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Param	Descrição
`hub_uuid`	UUID do hub
`order_uuid`	UUID do pedido

Esta rota não possui body.

Exemplo cURL

curl -s -X POST \"$BASE_URL/hubs/$HUB_UUID/orders/$ORDER_UUID/cancel-accepted\" \\\n  -H \"Accept: application/json\" \\\n  -H \"apikey: $HUBII_API_KEY\"\n

Idempotência

Ação de negócio sensível. Evite retry automático sem consultar o estado do pedido, porque a situação operacional pode mudar entre tentativas. Após a coleta, a operação deve falhar.

Tratamento de erros

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Status	Orientação
`401`	Não retentar automaticamente; revisar API Key
`403`	Verificar se a API Key tem acesso ao hub informado
`404`	Verificar `hub_uuid`, `order_uuid` ou se o recurso ainda está disponível
`422`	Tratar como erro de regra de negócio ou payload inválido; não fazer retry cego
`429`	Aplicar backoff exponencial e respeitar os headers de rate limit
`5xx` / timeout	Retentar com backoff exponencial e limite de tentativas

\n
Em runtime, use os headers X-RateLimit-* como referência operacional. A tabela de rate limits documenta o limite esperado/contratual.
\n

Rate limit

10 req/min por token, no grupo de ações.

\n","urlObject":{"path":["hubs",":hub_uuid","orders",":order_uuid","cancel-accepted"],"host":["https://api.staging.hubii.co"],"query":[],"variable":[{"id":"bb5262af-366f-41e9-95dc-d3c77ad8cd14","description":{"content":"

UUID do hub retornado em GET /hubs

\n","type":"text/plain"},"type":"any","value":"","key":"hub_uuid"},{"id":"c0d9df62-ad6d-46d9-bb8f-fa5117127c77","description":{"content":"

UUID do pedido

\n","type":"text/plain"},"type":"any","value":"","key":"order_uuid"}]}},"response":[],"_postman_id":"be9ee595-9edc-4a3a-91b5-eafdea8e51a7"}],"id":"5ed24ac5-4e83-461e-a6b9-4f36d18476b3","_postman_id":"5ed24ac5-4e83-461e-a6b9-4f36d18476b3","description":"","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"apikey"},{"key":"value","value":""}]},"isInherited":true,"source":{"_postman_id":"7e207411-7624-4909-8d24-35ec0605eb45","id":"7e207411-7624-4909-8d24-35ec0605eb45","name":"Hubii API","type":"collection"}}},{"name":"05 — Faturamento e expedição","item":[{"name":"Enviar nota fiscal para o pedido","id":"5faecefb-0073-464d-932a-895056ba9198","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"apikey"},{"key":"value","value":""}]},"isInherited":false},"method":"POST","header":[{"key":"Accept","value":"application/json","type":"text"}],"body":{"mode":"formdata","formdata":[{"key":"invoice_file","type":"file","value":null}]},"url":"https://api.staging.hubii.co/hubs/:hub_uuid/orders/:order_uuid/invoice","description":"

Objetivo

Envia o XML da NF-e de um pedido aceito e importado no ERP.

Pré-requisitos

Pedido aceito no Polling 1, via API ou painel.
Pedido importado no ERP a partir de ORDER_CREATED no Polling 2.
NF-e emitida com dados compatíveis com os detalhes do pedido.

Body multipart/form-data

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Campo	Tipo	Obrigatório	Descrição
`invoice_file`	file	Sim	Arquivo XML da NF-e

Envie apenas XML. PDF não é aceito neste endpoint.

Validações relevantes

CEP do destinatário na NF-e deve ser igual ao CEP de invoice_address nos detalhes do pedido.
CFOP deve ser compatível com invoice_allowed.
O campo multipart deve se chamar exatamente invoice_file.

Exemplo cURL

curl -s -X POST \"$BASE_URL/hubs/$HUB_UUID/orders/$ORDER_UUID/invoice\" \\\n  -H \"Accept: application/json\" \\\n  -H \"apikey: $HUBII_API_KEY\" \\\n  -F \"invoice_file=@/caminho/nota.xml\"\n

Idempotência

Reenvio do mesmo XML é idempotente e seguro em caso de timeout ou falha temporária antes da confirmação.

Tratamento de erros

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Status	Orientação
`401`	Não retentar automaticamente; revisar API Key
`403`	Verificar se a API Key tem acesso ao hub informado
`404`	Verificar `hub_uuid`, `order_uuid` ou se o recurso ainda está disponível
`422`	Tratar como erro de regra de negócio ou payload inválido; não fazer retry cego
`429`	Aplicar backoff exponencial e respeitar os headers de rate limit
`5xx` / timeout	Retentar com backoff exponencial e limite de tentativas

\n
Em runtime, use os headers X-RateLimit-* como referência operacional. A tabela de rate limits documenta o limite esperado/contratual.
\n

\n","urlObject":{"path":["hubs",":hub_uuid","orders",":order_uuid","invoice"],"host":["https://api.staging.hubii.co"],"query":[],"variable":[{"id":"71997bd6-d469-4c40-bb57-6a4cb909cc78","description":{"content":"

UUID do hub retornado em GET /hubs

\n","type":"text/plain"},"type":"any","value":"","key":"hub_uuid"},{"id":"4c24076d-3c3e-451b-b8a1-f6bd43f995cf","description":{"content":"

UUID do pedido

\n","type":"text/plain"},"type":"any","value":"","key":"order_uuid"}]}},"response":[{"id":"6f0604da-e921-443b-b32f-10da1e381075","name":"[200] Enviar nota fiscal para o pedido","originalRequest":{"method":"POST","header":[],"body":{"mode":"formdata","formdata":[{"key":"invoice_file","type":"file","src":[]}]},"url":{"raw":"https://api.staging.hubii.co/hubs/:hub_uuid/orders/:order_uuid/invoice","host":["https://api.staging.hubii.co"],"path":["hubs",":hub_uuid","orders",":order_uuid","invoice"],"variable":[{"key":"hub_uuid","value":"b6f2eefa-da34-4daa-ae2b-98c3bd7b29c2"},{"key":"order_uuid","value":"71402839-ecb5-4ee0-b73a-331e7bef74f5"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"RateLimit-Reset","value":"22"},{"key":"RateLimit-Limit","value":"10"},{"key":"X-RateLimit-Remaining-Minute","value":"8"},{"key":"X-RateLimit-Limit-Minute","value":"10"},{"key":"RateLimit-Remaining","value":"8"},{"key":"Host","value":"api.staging.hubii.co"},{"key":"X-Powered-By","value":"PHP/8.1.29"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"Date","value":"Thu, 21 Nov 2024 14:37:39 GMT"},{"key":"X-RateLimit-Limit","value":"60"},{"key":"X-RateLimit-Remaining","value":"58"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Server","value":"kong/3.8.0"},{"key":"X-Kong-Upstream-Latency","value":"1261"},{"key":"X-Kong-Proxy-Latency","value":"3"},{"key":"Via","value":"1.1 kong/3.8.0"},{"key":"X-Kong-Request-Id","value":"c3d55a45ab449b4958b37255173f7c63"}],"cookie":[],"responseTime":null,"body":"{\n \"data\": {\n \"success\": true,\n \"message\": \"Invoice set successfully\"\n }\n}"},{"id":"0cc038b9-1e25-42d4-b22e-097a47e3110a","name":"[422] Enviar nota fiscal para o pedido","originalRequest":{"method":"POST","header":[],"body":{"mode":"formdata","formdata":[{"key":"invoice_file","type":"file","src":[]}]},"url":{"raw":"https://api.staging.hubii.co/hubs/:hub_uuid/orders/:order_uuid/invoice","host":["https://api.staging.hubii.co"],"path":["hubs",":hub_uuid","orders",":order_uuid","invoice"],"variable":[{"key":"hub_uuid","value":"b6f2eefa-da34-4daa-ae2b-98c3bd7b29c2"},{"key":"order_uuid","value":"71402839-ecb5-4ee0-b73a-331e7bef74f5"}]}},"status":"Unprocessable Content","code":422,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"RateLimit-Reset","value":"21"},{"key":"RateLimit-Limit","value":"10"},{"key":"X-RateLimit-Remaining-Minute","value":"9"},{"key":"X-RateLimit-Limit-Minute","value":"10"},{"key":"RateLimit-Remaining","value":"9"},{"key":"Host","value":"api.staging.hubii.co"},{"key":"X-Powered-By","value":"PHP/8.1.29"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"Date","value":"Thu, 21 Nov 2024 14:35:40 GMT"},{"key":"X-RateLimit-Limit","value":"60"},{"key":"X-RateLimit-Remaining","value":"59"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Server","value":"kong/3.8.0"},{"key":"X-Kong-Upstream-Latency","value":"258"},{"key":"X-Kong-Proxy-Latency","value":"3"},{"key":"Via","value":"1.1 kong/3.8.0"},{"key":"X-Kong-Request-Id","value":"26954260301cc67ab1c5237a1a2f3d24"}],"cookie":[],"responseTime":null,"body":"{\n \"data\": {\n \"success\": false,\n \"error\": \"O Cep do comprador da nota fiscal precisa ser a mesma da venda. Cep Nota: 00000000 Cep Venda: 00000001\"\n }\n}"}],"_postman_id":"5faecefb-0073-464d-932a-895056ba9198"},{"name":"Download etiqueta de despacho de pedido","id":"e6f5b301-9fff-481b-ba8f-7b8ac144b977","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"apikey"},{"key":"value","value":""}]},"isInherited":false},"method":"GET","header":[{"key":"Accept","value":"application/json","type":"text"}],"url":"https://api.staging.hubii.co/hubs/:hub_uuid/orders/:order_uuid/label","description":"

Objetivo

Retorna uma URL temporária para baixar a etiqueta de envio em PDF.

Quando chamar

Chame somente após receber SHIPPING_LABEL_AVAILABLE no Polling 2 para o pedido.

\n
A necessidade de etiqueta depende do pedido. Não assuma apenas pelo canal de venda.
\n

Path params

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Param	Descrição
`hub_uuid`	UUID do hub
`order_uuid`	UUID do pedido

Exemplo cURL

curl -s \"$BASE_URL/hubs/$HUB_UUID/orders/$ORDER_UUID/label\" \\\n  -H \"Accept: application/json\" \\\n  -H \"apikey: $HUBII_API_KEY\"\n

Idempotência

GET seguro repetir. A URL é temporária; solicite uma nova URL quando expirar.

Tratamento de erros

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Status	Orientação
`401`	Não retentar automaticamente; revisar API Key
`403`	Verificar se a API Key tem acesso ao hub informado
`404`	Verificar `hub_uuid`, `order_uuid` ou se o recurso ainda está disponível
`422`	Tratar como erro de regra de negócio ou payload inválido; não fazer retry cego
`429`	Aplicar backoff exponencial e respeitar os headers de rate limit
`5xx` / timeout	Retentar com backoff exponencial e limite de tentativas

\n
Em runtime, use os headers X-RateLimit-* como referência operacional. A tabela de rate limits documenta o limite esperado/contratual.
\n

\n","urlObject":{"path":["hubs",":hub_uuid","orders",":order_uuid","label"],"host":["https://api.staging.hubii.co"],"query":[],"variable":[{"id":"59a06623-3148-4eab-aac0-4dd9a96ac3d9","description":{"content":"

UUID do hub retornado em GET /hubs

\n","type":"text/plain"},"type":"any","value":"","key":"hub_uuid"},{"id":"3c09d8b3-371c-4e1f-a80c-b1dd0a359e7c","description":{"content":"

UUID do pedido

\n","type":"text/plain"},"type":"any","value":"","key":"order_uuid"}]}},"response":[{"id":"0554fca7-405f-4102-b984-d1e4e2d89754","name":"Download etiqueta de despacho de pedido","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.staging.hubii.co/hubs/:hub_uuid/orders/:order_uuid/label","host":["https://api.staging.hubii.co"],"path":["hubs",":hub_uuid","orders",":order_uuid","label"],"variable":[{"key":"hub_uuid","value":"c6a276b6-ad59-498f-83b6-ee12234a513f"},{"key":"order_uuid","value":"f8aabd66-ee42-4e9e-9415-1ff0935610d7"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":":status","value":200},{"key":"date","value":"Tue, 17 Mar 2026 18:41:32 GMT"},{"key":"Content-Type","value":"application/json","description":"","type":"text"},{"key":"x-ratelimit-remaining-minute","value":"299"},{"key":"x-ratelimit-limit-minute","value":"300"},{"key":"ratelimit-remaining","value":"299"},{"key":"ratelimit-reset","value":"29"},{"key":"ratelimit-limit","value":"300"},{"key":"server","value":"cloudflare"},{"key":"vary","value":"Accept-Encoding"},{"key":"x-powered-by","value":"PHP/8.2.29"},{"key":"cache-control","value":"no-cache, private"},{"key":"x-ratelimit-limit","value":"60"},{"key":"x-ratelimit-remaining","value":"59"},{"key":"access-control-allow-origin","value":"*"},{"key":"x-frame-options","value":"SAMEORIGIN"},{"key":"x-xss-protection","value":"1; mode=block"},{"key":"x-content-type-options","value":"nosniff"},{"key":"content-encoding","value":"gzip"},{"key":"x-kong-upstream-latency","value":"1034"},{"key":"x-kong-proxy-latency","value":"3"},{"key":"via","value":"1.1 kong/3.9.1"},{"key":"x-kong-request-id","value":"ac03a46cadc78b492b0a6e6824cf4256"},{"key":"cf-cache-status","value":"DYNAMIC"},{"key":"nel","value":"{\"report_to\":\"cf-nel\",\"success_fraction\":0.0,\"max_age\":604800}"},{"key":"report-to","value":"{\"group\":\"cf-nel\",\"max_age\":604800,\"endpoints\":[{\"url\":\"https://a.nel.cloudflare.com/report/v4?s=T70xSrp7pP4Y7w%2FH0wTkIVjUNoRYDx3zQsZ1sVXmlPU2%2BcNS6tidu5whD%2FcFLUvGw3fvFewho9POIzCSBHWivuhuDk5xUwO%2FSX6b5fvuluHGnxgSpyNEe0P72UUKqc4%3D\"}]}"},{"key":"cf-ray","value":"9dde21dbfd0ae6c8-GIG"}],"cookie":[],"responseTime":null,"body":"{\n \"url\": \"https://etiquetas-hubii.s3.amazonaws.com/precode-0000-000000.pdf?X-Amz-Expires=300&X-Amz-Signature=REDACTED\"\n}"}],"_postman_id":"e6f5b301-9fff-481b-ba8f-7b8ac144b977"}],"id":"c723d121-037a-48b8-b8d0-e0090ceee44a","_postman_id":"c723d121-037a-48b8-b8d0-e0090ceee44a","description":"","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"apikey"},{"key":"value","value":""}]},"isInherited":true,"source":{"_postman_id":"7e207411-7624-4909-8d24-35ec0605eb45","id":"7e207411-7624-4909-8d24-35ec0605eb45","name":"Hubii API","type":"collection"}}},{"name":"[Descontinuado]","item":[{"name":"[Descontinuado] Listagem de notificações","id":"4b9f518f-9b54-4e8b-b191-73208aaba8a3","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"apikey"},{"key":"value","value":""}]},"isInherited":false},"method":"GET","header":[{"key":"Accept","value":"application/json","type":"text"}],"url":"https://api.staging.hubii.co/notifications","description":"

DESCONTINUADO — não usar em novas integrações

Endpoint legado de listagem de notificações, sem paginação. Mantido apenas por compatibilidade com integrações antigas. Novas integrações devem usar:

GET /v2/notifications\n  ↓ data[]\nPOST /notifications/ack\n

Por que foi descontinuado

A listagem sem paginação não escala para hubs com alto volume de eventos.
GET /v2/notifications retorna o mesmo conteúdo em data[], com page, limit, total e last_page.
A API sinaliza depreciação com X-API-Deprecated: true e X-API-Replacement: /v2/notifications.

Diferenças em relação à v2

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Aspecto	`GET /notifications` (legado)	`GET /v2/notifications`
Resposta	Array direto `[...]`	Objeto paginado `{ data, total, page, last_page, per_page }`
Paginação	Não suportada	`page` (padrão `1`) e `limit` (padrão `15`, máx. `100`)
Filtros	`hub_uuids`, `types`	`hub_uuids`, `types` (mesmos filtros)

Se você já usa este endpoint

Planeje migração para GET /v2/notifications. Enquanto isso, trate a resposta como array e mantenha POST /notifications/ack inalterado.

Rate limit

5 req/min por token, no grupo de notificações.

Tratamento de erros

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Status	Orientação
`401`	Não retentar automaticamente; revisar API Key
`403`	Verificar se a API Key tem acesso ao hub informado
`404`	Verificar `hub_uuid`, `order_uuid` ou se o recurso ainda está disponível
`422`	Tratar como erro de regra de negócio ou payload inválido; não fazer retry cego
`429`	Aplicar backoff exponencial e respeitar os headers de rate limit
`5xx` / timeout	Retentar com backoff exponencial e limite de tentativas

\n
Em runtime, use os headers X-RateLimit-* como referência operacional. A tabela de rate limits documenta o limite esperado/contratual.
\n

\n","urlObject":{"path":["notifications"],"host":["https://api.staging.hubii.co"],"query":[{"disabled":true,"description":{"content":"

Filtrar por hub

\n","type":"text/plain"},"key":"hub_uuids","value":""},{"disabled":true,"description":{"content":"

Filtrar por tipo de evento

\n","type":"text/plain"},"key":"types","value":"ORDER_CREATED"}],"variable":[]}},"response":[{"id":"bfe074a4-941c-47c0-bdd9-6b745c166180","name":"200 OK — array legado","originalRequest":{"method":"GET","header":[{"key":"Accept","value":"application/json","type":"text"}],"url":"https://api.staging.hubii.co/notifications"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"X-API-Deprecated","value":"true"},{"key":"X-API-Replacement","value":"/v2/notifications"},{"key":"Content-Type","value":"application/json; charset=utf-8"}],"cookie":[],"responseTime":null,"body":"[\n {\n \"notification_uuid\": \"066d19b9-4aef-4b40-941b-d104ab158cd2\",\n \"type\": \"ORDER_CREATED\",\n \"subtype\": null,\n \"order_uuid\": \"356a4241-456b-49a6-8bdc-93f92ddec7f2\",\n \"order_id\": \"146167\",\n \"order_delivery_id\": \"119758\",\n \"hub_uuid\": \"a93dd09b-4c47-479a-9dca-9fb8026301a6\",\n \"date\": \"2025-09-03T21:46:59.000Z\"\n },\n {\n \"notification_uuid\": \"c3bc1f55-fe65-49c5-ac89-fcef38827d41\",\n \"type\": \"ORDER_DELIVERY_UPDATED\",\n \"subtype\": \"ORDER_DELIVERY_SEARCHING_COURIER\",\n \"order_uuid\": \"356a4241-456b-49a6-8bdc-93f92ddec7f2\",\n \"order_id\": \"146167\",\n \"order_delivery_id\": \"119758\",\n \"hub_uuid\": \"a93dd09b-4c47-479a-9dca-9fb8026301a6\",\n \"date\": \"2025-09-03T21:47:29.000Z\"\n },\n {\n \"notification_uuid\": \"636b4abf-2458-4e5e-a285-4184af2ffdfd\",\n \"type\": \"ORDER_CREATED\",\n \"subtype\": null,\n \"order_uuid\": \"c71af0ac-6d96-4d1f-a59f-a651ce2c4eb8\",\n \"order_id\": \"146199\",\n \"order_delivery_id\": \"119790\",\n \"hub_uuid\": \"a93dd09b-4c47-479a-9dca-9fb8026301a6\",\n \"date\": \"2025-09-04T12:49:40.000Z\"\n },\n {\n \"notification_uuid\": \"09d0613e-50de-4ed0-9383-184a93429275\",\n \"type\": \"ORDER_DELIVERY_UPDATED\",\n \"subtype\": \"ORDER_DELIVERY_SEARCHING_COURIER\",\n \"order_uuid\": \"c71af0ac-6d96-4d1f-a59f-a651ce2c4eb8\",\n \"order_id\": \"146199\",\n \"order_delivery_id\": \"119790\",\n \"hub_uuid\": \"a93dd09b-4c47-479a-9dca-9fb8026301a6\",\n \"date\": \"2025-09-04T12:49:44.000Z\"\n },\n {\n \"notification_uuid\": \"f8bb9ca5-961c-4bc3-9bf5-2b47452b2f81\",\n \"type\": \"ORDER_CREATED\",\n \"subtype\": null,\n \"order_uuid\": \"571cdfbe-ba9a-4cf2-aaea-45c67b064c88\",\n \"order_id\": \"146265\",\n \"order_delivery_id\": \"119856\",\n \"hub_uuid\": \"a93dd09b-4c47-479a-9dca-9fb8026301a6\",\n \"date\": \"2025-09-04T16:18:40.000Z\"\n },\n {\n \"notification_uuid\": \"d987097a-a097-49c8-8c57-cf302f3efabd\",\n \"type\": \"ORDER_DELIVERY_UPDATED\",\n \"subtype\": \"ORDER_DELIVERY_COURIER_NOT_FOUND\",\n \"order_uuid\": \"c71af0ac-6d96-4d1f-a59f-a651ce2c4eb8\",\n \"order_id\": \"146199\",\n \"order_delivery_id\": \"119790\",\n \"hub_uuid\": \"a93dd09b-4c47-479a-9dca-9fb8026301a6\",\n \"date\": \"2025-09-04T12:50:59.000Z\"\n },\n {\n \"notification_uuid\": \"35f09ebf-94e4-440f-902e-f74c1f89670c\",\n \"type\": \"ORDER_DELIVERY_UPDATED\",\n \"subtype\": \"ORDER_DELIVERY_SEARCHING_COURIER\",\n \"order_uuid\": \"571cdfbe-ba9a-4cf2-aaea-45c67b064c88\",\n \"order_id\": \"146265\",\n \"order_delivery_id\": \"119856\",\n \"hub_uuid\": \"a93dd09b-4c47-479a-9dca-9fb8026301a6\",\n \"date\": \"2025-09-04T16:18:44.000Z\"\n },\n {\n \"notification_uuid\": \"07451006-152c-4406-8ae1-f755bff7bdca\",\n \"type\": \"ORDER_CREATED\",\n \"subtype\": null,\n \"order_uuid\": \"b3372551-01d4-4de8-9f1b-d3e0c912992f\",\n \"order_id\": \"146390\",\n \"order_delivery_id\": \"119981\",\n \"hub_uuid\": \"dbe03cf0-c04b-458c-9b68-16af9faaa9ea\",\n \"date\": \"2025-09-05T18:57:59.000Z\"\n },\n {\n \"notification_uuid\": \"883596c5-dbdd-4720-9178-68b13f428e30\",\n \"type\": \"ORDER_CREATED\",\n \"subtype\": null,\n \"order_uuid\": \"b3372551-01d4-4de8-9f1b-d3e0c912992f\",\n \"order_id\": \"146390\",\n \"order_delivery_id\": \"119981\",\n \"hub_uuid\": \"dbe03cf0-c04b-458c-9b68-16af9faaa9ea\",\n \"date\": \"2025-09-05T19:06:53.000Z\"\n },\n {\n \"notification_uuid\": \"0cdd2ae7-4a0e-4480-b1e9-950141be78dd\",\n \"type\": \"ORDER_DELIVERY_UPDATED\",\n \"subtype\": \"ORDER_DELIVERY_SEARCHING_COURIER\",\n \"order_uuid\": \"b3372551-01d4-4de8-9f1b-d3e0c912992f\",\n \"order_id\": \"146390\",\n \"order_delivery_id\": \"119981\",\n \"hub_uuid\": \"dbe03cf0-c04b-458c-9b68-16af9faaa9ea\",\n \"date\": \"2025-09-05T19:07:35.000Z\"\n },\n {\n \"notification_uuid\": \"95af8726-3833-424d-bb18-0d0c716b4ffa\",\n \"type\": \"ORDER_DELIVERY_UPDATED\",\n \"subtype\": \"ORDER_DELIVERY_COURIER_FOUND\",\n \"order_uuid\": \"b3372551-01d4-4de8-9f1b-d3e0c912992f\",\n \"order_id\": \"146390\",\n \"order_delivery_id\": \"119981\",\n \"hub_uuid\": \"dbe03cf0-c04b-458c-9b68-16af9faaa9ea\",\n \"date\": \"2025-09-05T19:07:51.000Z\"\n },\n {\n \"notification_uuid\": \"1766ae9b-b06d-4486-8c41-37add23fe872\",\n \"type\": \"ORDER_DELIVERY_UPDATED\",\n \"subtype\": \"ORDER_DELIVERY_DELIVERING\",\n \"order_uuid\": \"b3372551-01d4-4de8-9f1b-d3e0c912992f\",\n \"order_id\": \"146390\",\n \"order_delivery_id\": \"119981\",\n \"hub_uuid\": \"dbe03cf0-c04b-458c-9b68-16af9faaa9ea\",\n \"date\": \"2025-09-05T19:08:03.000Z\"\n },\n {\n \"notification_uuid\": \"7d122bff-d184-4a19-bd62-b30e03fee07f\",\n \"type\": \"ORDER_DELIVERY_UPDATED\",\n \"subtype\": \"ORDER_DELIVERY_DELIVERED\",\n \"order_uuid\": \"b3372551-01d4-4de8-9f1b-d3e0c912992f\",\n \"order_id\": \"146390\",\n \"order_delivery_id\": \"119981\",\n \"hub_uuid\": \"dbe03cf0-c04b-458c-9b68-16af9faaa9ea\",\n \"date\": \"2025-09-05T19:08:11.000Z\"\n }\n]"}],"_postman_id":"4b9f518f-9b54-4e8b-b191-73208aaba8a3"},{"name":"[Descontinuado] Pedidos esperando faturamento","id":"29938c03-ec78-4efa-9d0e-5f5af8555463","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"apikey"},{"key":"value","value":""}]},"isInherited":false},"method":"GET","header":[{"key":"Accept","value":"application/json","type":"text"}],"url":"https://api.staging.hubii.co/hubs/:hub_uuid/orders/to-invoice?blocks_shipping=&date_from&accepted_from","description":"

DESCONTINUADO — não usar em novas integrações

Endpoint legado mantido apenas por compatibilidade com integrações antigas. Novas integrações devem usar o Polling 2:

GET /v2/notifications\n  ↓ ORDER_CREATED\nGET /hubs/{hub_uuid}/orders/{order_uuid}\n

Por que foi descontinuado

O fluxo atual centraliza pedidos aceitos em notificações.
ORDER_CREATED chega após aceite via API ou painel e deve disparar a importação no ERP.
Usar esta rota em novas integrações pode duplicar lógica e dificultar idempotência.

Se você já usa este endpoint

Planeje migração para Polling 2 + ORDER_CREATED. Enquanto isso, mantenha retry e rate limit conforme o grupo de listagem.

Rate limit

60 req/min por token, no grupo de listagem.

Tratamento de erros

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Status	Orientação
`401`	Não retentar automaticamente; revisar API Key
`403`	Verificar se a API Key tem acesso ao hub informado
`404`	Verificar `hub_uuid`, `order_uuid` ou se o recurso ainda está disponível
`422`	Tratar como erro de regra de negócio ou payload inválido; não fazer retry cego
`429`	Aplicar backoff exponencial e respeitar os headers de rate limit
`5xx` / timeout	Retentar com backoff exponencial e limite de tentativas

\n
Em runtime, use os headers X-RateLimit-* como referência operacional. A tabela de rate limits documenta o limite esperado/contratual.
\n

\n","urlObject":{"path":["hubs",":hub_uuid","orders","to-invoice"],"host":["https://api.staging.hubii.co"],"query":[{"description":{"content":"

Filtra os pedidos que precisam de nota fiscal obrigatoriamente para expedição do pedido

\n","type":"text/plain"},"key":"blocks_shipping","value":""},{"description":{"content":"

Filtra os pedidos pelo datetime que o cliente realizou a compra. Ex: 2026-03-20 09:00:00-03:00

\n","type":"text/plain"},"key":"date_from","value":null},{"description":{"content":"

Filtra os pedidos pela datetime que o hub aceitou. Ex: 2026-03-20 09:00:00-03:00

\n","type":"text/plain"},"key":"accepted_from","value":null}],"variable":[{"id":"df5c4776-a3ef-40af-95c3-296b31b037d1","description":{"content":"

UUID do hub retornado em GET /hubs

\n","type":"text/plain"},"type":"any","value":"","key":"hub_uuid"}]}},"response":[{"id":"6ab6047b-e281-4996-8842-ca7e23e66fe0","name":"200 OK","originalRequest":{"method":"GET","header":[{"key":"Accept","value":"application/json","type":"text"}],"url":{"raw":"https://api.staging.hubii.co/hubs/:hub_uuid/orders/to-invoice","host":["https://api.staging.hubii.co"],"path":["hubs",":hub_uuid","orders","to-invoice"],"variable":[{"key":"hub_uuid","value":"","description":"UUID único do Hub"}]}},"status":"OK","code":200,"_postman_previewlanguage":"Text","header":[{"key":"Date","value":"Fri, 20 Mar 2026 12:57:23 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"ratelimit-remaining","value":"598"},{"key":"ratelimit-reset","value":"37"},{"key":"ratelimit-limit","value":"600"},{"key":"x-ratelimit-remaining-minute","value":"598"},{"key":"x-ratelimit-limit-minute","value":"600"},{"key":"Server","value":"cloudflare"},{"key":"vary","value":"Accept-Encoding"},{"key":"x-powered-by","value":"PHP/8.2.29"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"x-ratelimit-limit","value":"60"},{"key":"x-ratelimit-remaining","value":"58"},{"key":"access-control-allow-origin","value":"*"},{"key":"x-frame-options","value":"SAMEORIGIN"},{"key":"x-xss-protection","value":"1; mode=block"},{"key":"x-content-type-options","value":"nosniff"},{"key":"Content-Encoding","value":"gzip"},{"key":"x-kong-upstream-latency","value":"337"},{"key":"x-kong-proxy-latency","value":"2"},{"key":"via","value":"1.1 kong/3.9.1"},{"key":"x-kong-request-id","value":"0ad8ae2c72e6dc7e478804580623f662"},{"key":"cf-cache-status","value":"DYNAMIC"},{"key":"Nel","value":"{\"report_to\":\"cf-nel\",\"success_fraction\":0.0,\"max_age\":604800}"},{"key":"Report-To","value":"{\"group\":\"cf-nel\",\"max_age\":604800,\"endpoints\":[{\"url\":\"https://a.nel.cloudflare.com/report/v4?s=w3hBXflqPpn%2BzSyjQDftkxMhfmihQZN5A%2F7qTG5kTI%2FiuzwFGwVU3lHUy38ZJx%2Fnd8Kq8Tm6fTtZxKYbJxGZM5r0S95NOyT5bv4p9VE3X01dN3PzmA%3D%3D\"}]}"},{"key":"CF-RAY","value":"9df4e1e04b7581d6-GRU"}],"cookie":[],"responseTime":null,"body":"{\n \"current_page\": 1,\n \"data\": [\n {\n \"id\": 620969,\n \"uuid\": \"c8bd105e-9f01-47e8-98e9-6f26cd463dc3\",\n \"total\": 76.64\n }\n ],\n \"next_page_url\": \"https://api.staging.hubii.co/hubs/orders/to-invoice?per_page=20&page=2\",\n \"path\": \"https://api.staging.hubii.co/hubs/orders/to-invoice\",\n \"per_page\": 20,\n \"prev_page_url\": null,\n \"to\": 20,\n \"total\": 1\n}"}],"_postman_id":"29938c03-ec78-4efa-9d0e-5f5af8555463"}],"id":"0f484384-57d2-4290-a3a5-c7641765126c","_postman_id":"0f484384-57d2-4290-a3a5-c7641765126c","description":"","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"apikey"},{"key":"value","value":""}]},"isInherited":true,"source":{"_postman_id":"7e207411-7624-4909-8d24-35ec0605eb45","id":"7e207411-7624-4909-8d24-35ec0605eb45","name":"Hubii API","type":"collection"}}}],"auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"apikey"},{"key":"value","value":""}]}},"event":[{"listen":"prerequest","script":{"type":"text/javascript","requests":{},"exec":[""],"id":"28706e55-5f61-4349-b463-8ca45b125125"}},{"listen":"test","script":{"type":"text/javascript","requests":{},"exec":[""],"id":"798c75d2-df07-45bf-9f09-3ed499fd0e78"}}],"variable":[{"key":"base_url","value":"https://api.staging.hubii.co","description":"Homologação: https://api.staging.hubii.co | Produção: https://api.hubii.co"},{"key":"apikey","value":"","description":"API Key Hubii usada no header apikey. Nunca preencher com segredo real em arquivo versionado."},{"key":"hub_uuid","value":"","description":"UUID do hub retornado em GET /hubs"},{"key":"hub_uuid_2","value":"","description":"Opcional: segundo hub para exemplos de filtros com múltiplos hubs"},{"key":"order_uuid","value":"","description":"UUID do pedido retornado em to-answer ou notifications"},{"key":"notification_uuid","value":"","description":"UUID da notificação retornada em GET /v2/notifications (campo notification_uuid em data[]); usar em POST /notifications/ack"}]}

Integração para parceiros

Visão rápida dos pollings

Polling 1 — Aceite de pedidos

Polling 2 — Notificações de pedidos aceitos

Implementação mínima

Fluxo operacional

Decisão de aceite ou recusa

Variáveis da collection

Autenticação

Rate limits

Idempotência e retry seguro

Estratégia recomendada de ACK

Segurança operacional

Homologação

Obrigatório para todos os parceiros

Obrigatório quando aplicável ao escopo

Evidências aceitas

Boas práticas

Objetivo

Quando chamar

Posição no fluxo

Query params opcionais

Campos relevantes

Exemplo cURL

Idempotência

Tratamento de erros

Próximo passo

Objetivo

Quando chamar

Fluxo recomendado

Por que consultar o pedido completo

Path params

Campos relevantes

Regras importantes

Exemplo cURL

Diagrama de sequência

Idempotência

Tratamento de erros

Próximo passo

Objetivo

Antes de chamar

Relação com os dois pollings

Path params

Body para aceitar

Body para recusar

Motivos de recusa

Exemplos cURL

Idempotência

Tratamento de erros

Após o aceite

Objetivo

Quando chamar

Fluxo

Filtros opcionais

Paginação

Query params de paginação

Campos de cada item em data[]

Matriz de eventos

Eventos que exigem ação no ERP

Eventos informativos

Estratégia de ACK

Regras críticas

Exemplos cURL

Idempotência

Tratamento de erros

Diagramas

Importação e faturamento

Atualizações de entrega

Sequência de eventos

Objetivo

Quando chamar

Fluxo recomendado

Body

Comportamento esperado

Exemplo cURL

Idempotência

Tratamento de erros

Objetivo

Quando chamar

Path params

Campos de cada item em `data[]`