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.
\nA 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.
\nUsado para decidir se o hub aceita ou recusa uma oferta de pedido.
\n\n\nA listagem de
\nto-answerdeve ser tratada como fila de ofertas. A decisão normalmente depende do pedido completo, principalmente dos itens, quantidades, preços e disponibilidade do hub.
Usado para acompanhar pedidos após o aceite: importação no ERP, entrega, NF-e, etiqueta e cancelamentos.
\n\n\nResumo: 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
Para uma integração funcional, implemente este caminho primeiro:
\nConfigure base_url e envie o header apikey em todas as requisições.
Chame GET /hubs e salve o uuid de cada hub.
A cada 30–60 segundos, execute o Polling 1: GET /hubs/{hub_uuid}/orders/to-answer.
Para cada oferta retornada, consulte o pedido completo em GET /hubs/{hub_uuid}/orders/{order_uuid}.
Com base no pedido completo, principalmente nos itens, estoque e regras do hub, aceite ou recuse com POST .../answer antes de available_until_at.
Em paralelo, execute o Polling 2: GET /v2/notifications.
Ao receber ORDER_CREATED, busque ou reconcilie os detalhes do pedido e importe no ERP.
Após processar e persistir a notificação, envie POST /notifications/ack usando notification_uuid.
Quando aplicável, envie a NF-e com POST .../invoice.
Ao receber SHIPPING_LABEL_AVAILABLE, baixe a etiqueta com GET .../label.
Não use busy-loop. Em 429, interrompa o ciclo atual, aplique backoff e tente novamente no próximo intervalo.
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\nGET .../to-invoice está descontinuado e existe apenas por compatibilidade. Para novas integrações, use ORDER_CREATED no Polling 2.
A Hubii recomenda este padrão para cada oferta retornada em to-answer:
Ler order_uuid e available_until_at na listagem.
Buscar o pedido completo em GET /hubs/{hub_uuid}/orders/{order_uuid}.
Avaliar itens, quantidades, preços, disponibilidade, regras fiscais e operação do hub.
\nResponder com POST .../answer antes do prazo.
Essa etapa evita decisões baseadas apenas no resumo da fila e reduz recusa incorreta, aceite sem estoque ou divergência operacional.
\n\n\nPara informar à Hubii o estoque atual dos produtos de cada hub, use a seção 06 — Envio de estoque desta collection:
\nPOST /stocking/{hub_uuid}faz upsert em lote (até 500 itens) usandoexternal_idcomo chave por hub.
Envie o header abaixo em todas as requisições:
\napikey: {sua_chave}\n\nAPI Key ausente, inválida ou sem permissão deve ser tratada como erro de configuração, não como falha temporária.
\n\n\nEm runtime, use os headers
\nX-RateLimit-\\\\\\\\\\\\*como referência operacional. A tabela acima documenta o limite esperado/contratual.
Em 429, não faça retry imediato em loop. Aguarde com backoff exponencial e retome o polling no próximo ciclo.
Use notification_uuid como chave de idempotência dos eventos no ERP.
Buscar notificações.
\nProcessar cada evento no ERP.
\nPersistir localmente usando notification_uuid como chave única.
Enviar ACK somente após sucesso da persistência.
\nSe o ACK falhar, retentar apenas o ACK. Não reprocessar o evento duplicado.
\n\n\nACK cedo demais pode causar perda de evento no ERP. Sem ACK, a notificação reaparece por até 2 dias.
\n
Nunca exponha API Key em frontend, repositório, tickets públicos ou logs.
\nNão commite environments do Postman com secrets preenchidos.
\nMascare credenciais em evidências de homologação.
\nTrate 401 como configuração incorreta e acione revisão de credenciais.
\n\nPara criar pedidos de teste, listar o catálogo sandbox e gerar XML de NF-e fake em staging, use a seção 07 — Homologação desta collection (rotas do
\npartner-homologation-service, disponíveis somente emhttps://api.staging.hubii.co; não existem em produção).
Smoke test: GET /hubs, 401 com key inválida e 403/404 em hub sem permissão.
Polling 1: listar ofertas, consultar detalhe completo antes da decisão, aceitar pedido, recusar com motivos, tratar pedido já respondido e pedido expirado.
\nPolling 2: buscar notificações, processar ORDER_CREATED, fazer ACK e validar reprocessamento quando não há ACK.
Detalhes do pedido: importar dados completos e exibir order.id no ERP.
Operação: aplicar backoff em 429, retry em 5xx/timeout e proteger credenciais nos logs.
Envio de NF-e XML com campo multipart invoice_file.
Tratamento de formatos diferentes de NF-e.
\nDownload de etiqueta após SHIPPING_LABEL_AVAILABLE.
Consulta de pickup_code após ORDER_DELIVERY_PICKING_UP.
Cancelamento pós-aceite antes da coleta.
\nLogs com credenciais mascaradas.
\nGravação de tela do fluxo em staging.
\nConsulte o detalhe completo de cada oferta antes de aceitar ou recusar.
\nExiba order.id no ERP; é o identificador usado no painel Hubii e no suporte.
Armazene notification_uuid para evitar duplicidade de processamento.
Execute Polling 1 e Polling 2 com o mesmo intervalo recomendado: 30–60 segundos.
\nCancelamentos Hubii/cliente podem chegar até 1 dia após o evento real.
\nLista os hubs vinculados à API Key. Este é o primeiro passo da integração: use data[].uuid como hub_uuid nas demais rotas.
Na configuração inicial do ERP, para mapear lojas/hubs.
\nPeriodicamente, por exemplo 1 vez ao dia, se novos hubs puderem ser vinculados.
\nAntes de iniciar os dois pollings.
\nGET /hubs\n ↓ guardar hub_uuid\n[Polling 1] GET .../to-answer → POST .../answer\n[Polling 2] GET /v2/notifications → processar → ACK\n\ncurl -s \"$BASE_URL/hubs\" \\\n -H \"Accept: application/json\" \\\n -H \"apikey: $HUBII_API_KEY\"\n\nGET seguro repetir a qualquer momento.
\n\nEm runtime, use os headers
\nX-RateLimit-\\*como referência operacional. A tabela de rate limits documenta o limite esperado/contratual.
Com os hubs mapeados, inicie os dois pollings em paralelo:
\nPolling 1: GET /hubs/{hub_uuid}/orders/to-answer.
Polling 2: GET /v2/notifications?hub_uuids={hub_uuid}.
Polling 1 — Aceite. Registra a decisão do hub sobre uma oferta retornada em to-answer: aceitar ou recusar.
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.
{\n \"accept\": true\n}\nPara 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}\nAceitar:
\ncurl -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}'\nRecusar:
\ncurl -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\"}]}'\nNã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.
\n\nEm runtime, use os headers
\nX-RateLimit-*como referência operacional. A tabela de rate limits documenta o limite esperado/contratual.
Continue o Polling 2. Aguarde ORDER_CREATED, reconcilie os detalhes do pedido no ERP e só depois envie ACK da notificação processada.
UUID do hub retornado em GET /hubs
\n","type":"text/plain"},"type":"any","value":"","key":"hub_uuid"},{"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"},{"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":"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\nA listagem deve ser tratada como uma fila de ofertas. Para cada pedido retornado, consulte o detalhe completo em
\nGET /hubs/{hub_uuid}/orders/{order_uuid}antes de aceitar ou recusar.
A cada 30–60 segundos.
\nEm paralelo ao Polling 2.
\nPara cada hub_uuid vinculado à API Key.
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\nO hub normalmente decide aceitar ou recusar com base no pedido completo, principalmente:
\nitens do pedido;
\nquantidades solicitadas;
\ndisponibilidade de estoque;
\npreço/repasse;
\nregras fiscais e operacionais;
\nendereço e condições de atendimento.
\nA 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.
Consulte o pedido completo antes de responder.
\nResponda antes de available_until_at.
Após expirar, a oferta some da fila e pode ser repassada a outro hub.
\nExpiração e recusa não geram notificação para este hub.
\nAceite pelo painel Hubii também é válido e gera ORDER_CREATED no Polling 2.
curl -s \"$BASE_URL/hubs/$HUB_UUID/orders/to-answer\" \\\n -H \"Accept: application/json\" \\\n -H \"apikey: $HUBII_API_KEY\"\n\nGET seguro repetir. A resposta sempre representa o estado atual da fila.
\n\nEm runtime, use os headers
\nX-RateLimit-\\\\\\*como referência operacional. A tabela de rate limits documenta o limite esperado/contratual.
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.
UUID do hub retornado em GET /hubs
\n","type":"text/plain"},"type":"any","value":"","key":"hub_uuid"}]}},"response":[{"id":"196a6b72-da69-44c4-8c5f-a449a8fc50cc","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"}],"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":"Polling 2 — Notificações. Lista eventos de pedidos já aceitos pelo hub, seja por API ou pelo painel Hubii.
\n\n\nEsta rota não mostra ofertas pendentes. Pedido ainda não aceito, recusado ou expirado não aparece aqui para este hub.
\n
A cada 30–60 segundos, em paralelo ao Polling 1.
\nDepois de processar e persistir cada evento, chame POST /notifications/ack.
[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\nFormato oficial documentado nesta collection: repetir o mesmo parâmetro para múltiplos valores.
\n\n\nSe a implementação do parceiro usar biblioteca que converte arrays para
\nhub_uuids[], valide com o time Hubii antes da homologação. A collection usahub_uuidsetypessem colchetes.
A resposta é um objeto paginado. Itere page até page >= last_page quando houver mais eventos.
data[]\n\nA necessidade de etiqueta depende do pedido, não apenas do canal de venda.
\n
Registre e envie ACK, mas não exigem lógica operacional específica no ERP.
\nBuscar notificações.
\nProcessar uma a uma no ERP.
\nPersistir localmente usando notification_uuid.
Enviar ACK somente após sucesso.
\nSe o ACK falhar, retentar o ACK e não reprocessar o evento duplicado.
\n\n\nACK cedo demais pode causar perda de evento. Sem ACK, a notificação reaparece por até 2 dias.
\n
ORDER_CREATED é o gatilho recomendado para importar ou reconciliar o pedido aceito.
Notificações expiram em 2 dias sem ACK.
\nCancelamentos podem chegar até 1 dia após o cancelamento real.
\nPedido recusado ou expirado no Polling 1 não gera evento neste polling para o hub.
\nSem filtro:
\ncurl -s \"$BASE_URL/v2/notifications\" \\\n -H \"Accept: application/json\" \\\n -H \"apikey: $HUBII_API_KEY\"\n\nCom filtros:
\ncurl -s \"$BASE_URL/v2/notifications?hub_uuids=$HUB_UUID&types=ORDER_CREATED\" \\\n -H \"Accept: application/json\" \\\n -H \"apikey: $HUBII_API_KEY\"\n\nGET seguro repetir. O mesmo notification_uuid retorna até receber ACK.
\n\nEm runtime, use os headers
\nX-RateLimit-\\\\\\\\*como referência operacional. A tabela de rate limits documenta o limite esperado/contratual.
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":"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.
\nSomente depois de processar e persistir o evento localmente. Não envie ACK antes de gravar o resultado no ERP.
\nGET /v2/notifications.notification_uuid como chave única.O campo uuids recebe uma lista de notification_uuid.
{\n \"uuids\": [\n \"notification-uuid-1\",\n \"notification-uuid-2\"\n ]\n}\ncurl -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\"]}'\nNo ERP, trate notification_uuid como chave única. Se a mesma notificação reaparecer, não duplique o processamento; apenas tente confirmar o ACK novamente.
\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":"Em runtime, use os headers
\nX-RateLimit-*como referência operacional. A tabela de rate limits documenta o limite esperado/contratual.
\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":"Descontinuação:
\nGET /notificationsfoi substituído porGET /v2/notifications(resposta paginada compageelimit). O endpoint legado permanece disponível apenas por compatibilidade e retorna os headersX-API-Deprecated: trueeX-API-Replacement: /v2/notifications. Novas integrações devem usar apenas a v2. O endpoint legado está documentado na pasta[Descontinuado].
Retorna os dados completos de um pedido. Use este endpoint em dois momentos principais:
\nAntes 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.
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.
\nApós ORDER_DELIVERY_PICKING_UP, quando for necessário obter pickup_code.
Sempre que o ERP precisar reconciliar o estado atual do pedido.
\nA 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:
\nse os itens fazem parte do portfólio do hub;
\nse há estoque suficiente;
\nse os valores brutos e líquidos (transfer_total e transfer_amount) são aceitáveis e cobrem os custos;
se há alguma restrição operacional ou fiscal;
\nse o pedido pode ser atendido dentro do fluxo esperado.
\ncurl -s \"$BASE_URL/hubs/$HUB_UUID/orders/$ORDER_UUID\" \\\n -H \"Accept: application/json\" \\\n -H \"apikey: $HUBII_API_KEY\"\n\nUUID do hub retornado em GET /hubs
\n","type":"text/plain"},"type":"any","value":"4cff2462-412f-4868-8b60-620c2efb8292","key":"hub_uuid"},{"description":{"content":"UUID do pedido
\n","type":"text/plain"},"type":"any","value":"2f91d2a6-4856-4c3a-b248-4e15f1b07486","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":""},{"key":"order_uuid","value":""}]}},"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":"{\r\n \"data\": {\r\n \"id\": 1000001,\r\n \"uuid\": \"00000000-0000-4000-8000-000000000001\",\r\n \"subtotal\": 62.99,\r\n \"discount\": 0,\r\n \"delivery_cost\": 9.9,\r\n \"total\": 72.89,\r\n \"transfer_subtotal\": 55.49,\r\n \"transfer_delivery_cost\": null,\r\n \"transfer_freight_fee\": 0,\r\n \"transfer_total\": 55.49,\r\n \"invoice_allowed\": [\r\n 55,\r\n 65\r\n ],\r\n \"delivery_status\": \"delivered\",\r\n \"estimated_delivery_at\": \"2026-08-05 18:55:05\",\r\n \"pickup_code\": \"0000\",\r\n \"customer\": {\r\n \"name\": \"Maria da Silva\",\r\n \"document\": \"12345678909\"\r\n },\r\n \"delivery_address\": {\r\n \"street_name\": \"R. das Flores\",\r\n \"address_number\": \"100\",\r\n \"complement\": \"Bl A Ap 11\",\r\n \"postal_code\": \"13000000\",\r\n \"neighborhood_name\": \"Centro\",\r\n \"city_name\": \"Campinas\",\r\n \"province_code\": \"SP\",\r\n \"country_code\": \"BR\"\r\n },\r\n \"invoice_address\": {\r\n \"street_name\": \"R. das Flores\",\r\n \"address_number\": \"100\",\r\n \"complement\": \"Bl A Ap 11\",\r\n \"postal_code\": \"13000000\",\r\n \"neighborhood_name\": \"Centro\",\r\n \"city_name\": \"Campinas\",\r\n \"province_code\": \"SP\",\r\n \"country_code\": \"BR\"\r\n },\r\n \"invoice_details\": {\r\n \"item_amount_adjustment\": {\r\n \"method\": \"net_adjustment_proportional_by_subtotal\",\r\n \"base_amount\": 62.99,\r\n \"discount\": 0,\r\n \"delivery_cost\": 9.9,\r\n \"net_amount\": 9.9,\r\n \"order_total\": 72.89,\r\n \"items\": [\r\n {\r\n \"id\": \"00000000-0000-4000-8000-000000000002\",\r\n \"quantity\": 1,\r\n \"unit_price\": 72.89,\r\n \"total\": 72.89\r\n }\r\n ]\r\n }\r\n },\r\n \"carrier\": {\r\n \"name\": null,\r\n \"document\": null\r\n },\r\n \"courier\": {\r\n \"name\": \"JOAO PEREIRA\",\r\n \"document\": \"+5519900000000\",\r\n \"document_type\": \"phone\"\r\n },\r\n \"items\": [\r\n {\r\n \"uuid\": \"00000000-0000-4000-8000-000000000002\",\r\n \"quantity\": 1,\r\n \"unit_price\": 62.99,\r\n \"total\": 62.99,\r\n \"transfer_amount\": 55.49,\r\n \"ean\": \"7898724630084\",\r\n \"product\": \"Tapete Hig. Super Secao C/14\"\r\n }\r\n ]\r\n }\r\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":"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.
\nEsta rota não possui body.
\ncurl -s -X POST \"$BASE_URL/hubs/$HUB_UUID/orders/$ORDER_UUID/cancel-accepted\" \\\n -H \"Accept: application/json\" \\\n -H \"apikey: $HUBII_API_KEY\"\nAçã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.
\n\n\nEm runtime, use os headers
\nX-RateLimit-*como referência operacional. A tabela de rate limits documenta o limite esperado/contratual.
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":[{"description":{"content":"UUID do hub retornado em GET /hubs
\n","type":"text/plain"},"type":"any","value":"","key":"hub_uuid"},{"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":"Envia o XML da NF-e de um pedido aceito e importado no ERP.
\nORDER_CREATED no Polling 2.Envie apenas XML. PDF não é aceito neste endpoint.
\ninvoice_address nos detalhes do pedido.invoice_allowed.invoice_file.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\"\nReenvio do mesmo XML é idempotente e seguro em caso de timeout ou falha temporária antes da confirmação.
\n\n\n","urlObject":{"path":["hubs",":hub_uuid","orders",":order_uuid","invoice"],"host":["https://api.staging.hubii.co"],"query":[],"variable":[{"description":{"content":"Em runtime, use os headers
\nX-RateLimit-*como referência operacional. A tabela de rate limits documenta o limite esperado/contratual.
UUID do hub retornado em GET /hubs
\n","type":"text/plain"},"type":"any","value":"","key":"hub_uuid"},{"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":"Retorna uma URL temporária para baixar a etiqueta de envio em PDF.
\nChame somente após receber SHIPPING_LABEL_AVAILABLE no Polling 2 para o pedido.
\n\nA necessidade de etiqueta depende do pedido. Não assuma apenas pelo canal de venda.
\n
curl -s \"$BASE_URL/hubs/$HUB_UUID/orders/$ORDER_UUID/label\" \\\n -H \"Accept: application/json\" \\\n -H \"apikey: $HUBII_API_KEY\"\nGET seguro repetir. A URL é temporária; solicite uma nova URL quando expirar.
\n\n","urlObject":{"path":["hubs",":hub_uuid","orders",":order_uuid","label"],"host":["https://api.staging.hubii.co"],"query":[],"variable":[{"description":{"content":"Em runtime, use os headers
\nX-RateLimit-*como referência operacional. A tabela de rate limits documenta o limite esperado/contratual.
UUID do hub retornado em GET /hubs
\n","type":"text/plain"},"type":"any","value":"","key":"hub_uuid"},{"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":"06 — Envio de estoque","item":[{"name":"Enviar estoque do hub (upsert em lote)","id":"f58d4b1c-8bae-bda8-752f-05a169250da7","request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{}","options":{"raw":{"language":"json"}}},"url":"https://api.staging.hubii.co/hubs/:hub_uuid/products/stock","description":"Envia o estoque atual de até 500 produtos de um hub. A operação é upsert: cria o item se ele não existir para o hub (chave: hub + external_id) ou atualiza o existente.
Campos obrigatórios — todos os campos de cada item de items são obrigatórios; não há campos opcionais neste endpoint.
200{\n \"success\": true,\n \"created\": 2,\n \"updated\": 1,\n \"failed\": []\n}\n\n400 — validação do body ou hub_uuid fora do formato UUID v4.
404 — Hub not found.
Esta seção documenta o endpoint de envio de estoque (hub-stock-service), usado pelo parceiro (ERP/PDV/WMS) para informar à Hubii o estoque atual dos produtos de cada hub.
A operação é um upsert em lote: para cada item enviado, a Hubii cria o registro de estoque se ele ainda não existir para o hub, ou atualiza o registro existente.
\nA chave de identificação de cada item é o par (hub, external_id****) — o external_id é o identificador do produto no sistema do parceiro. Envie sempre o mesmo external_id para o mesmo produto.
O vínculo com o catálogo Hubii é feito automaticamente pelo ean: se houver um produto no catálogo com aquele EAN, o item é associado a ele; se não houver, o item é gravado mesmo assim, sem vínculo.
O processamento é parcial e tolerante a falhas: se um item falhar, os demais são processados normalmente. A resposta informa quantos itens foram criados (created), atualizados (updated) e quais falharam (failed, com externalId e reason).
A quantidade enviada é absoluta (snapshot do estoque atual), não um delta.
\nMáximo de 500 itens por requisição.
\nexternal_id não pode se repetir dentro do mesmo array items.
Para catálogos maiores que 500 itens, divida em múltiplas requisições.
\nGET /hubs\n ↓ obter hub_uuid\nPOST /stocking/{hub_uuid} { items: [...] }\n ↓ ler created / updated / failed\nreprocessar apenas os itens em failed\n\nRetorna a visão consolidada dos valores a receber do hub, separando pedidos ainda pendentes de processamento e pedidos já processados com data de repasse agendada.
\ndata)financial — resumo geralpending — pedidos sem data de repasse (presente quando filter = pending ou all)processed — pedidos com repasse agendado, agrupados por data (presente quando filter = processed ou all)pending, processed ou all (padrão: all)
\n","type":"text/plain"},"key":"filter","value":"all"},{"description":{"content":"Página da listagem de processados (padrão: 1)
\n","type":"text/plain"},"key":"page","value":"1"},{"description":{"content":"Itens por página, de 1 a 100 (padrão: 10)
\n","type":"text/plain"},"key":"per_page","value":"10"}],"variable":[{"type":"any","value":"45e2a1cc-509b-4e33-bdc5-8ed255caf8a5","key":"hub_uuid"}]}},"response":[{"id":"990f1972-7e66-e066-8db3-c3a490a93ee4","name":"200 — Sucesso","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.staging.hubii.co/hubs/:hub_uuid/financial/to-receive?filter=all&page=1&per_page=10","host":["https://api.staging.hubii.co"],"path":["hubs",":hub_uuid","financial","to-receive"],"query":[{"key":"filter","value":"all","description":"pending, processed ou all (padrão: all)"},{"key":"page","value":"1","description":"Página da listagem de processados (padrão: 1)"},{"key":"per_page","value":"10","description":"Itens por página, de 1 a 100 (padrão: 10)"}],"variable":[{"key":"hub_uuid","value":"45e2a1cc-509b-4e33-bdc5-8ed255caf8a5"}]},"description":"Retorna a visão consolidada dos valores **a receber** do hub, separando pedidos ainda pendentes de processamento e pedidos já processados com data de repasse agendada.\n\n## Parâmetros de rota\n\n| Parâmetro | Tipo | Descrição |\n| --- | --- | --- |\n| `hub_uuid` | uuid | UUID do hub retornado em `GET /hubs`. Deve pertencer à sua conta |\n\n## Query params\n\n| Parâmetro | Tipo | Obrigatório | Descrição |\n| --- | --- | --- | --- |\n| `filter` | string | Não | `pending` (somente pendentes), `processed` (somente processados) ou `all` (padrão, retorna ambos) |\n| `page` | inteiro | Não | Página da listagem de processados. Padrão: `1` |\n| `per_page` | inteiro | Não | Itens por página (1 a 100). Padrão: `10` |\n\n## Campos da resposta (`data`)\n\n### `financial` — resumo geral\n\n| Campo | Tipo | Descrição |\n| --- | --- | --- |\n| `delivered` | decimal | Valor a receber de pedidos já entregues (com data de repasse agendada) |\n| `delivering` | decimal | Valor a receber de pedidos ainda em andamento (sem data de repasse) |\n| `total` | decimal | Soma de `delivered` + `delivering` |\n| `delivered_orders_amount` | inteiro | Quantidade de pedidos entregues |\n| `delivering_orders_amount` | inteiro | Quantidade de pedidos em andamento |\n| `total_orders_amount` | inteiro | Quantidade total de pedidos |\n\n### `pending` — pedidos sem data de repasse (presente quando `filter` = `pending` ou `all`)\n\n| Campo | Tipo | Descrição |\n| --- | --- | --- |\n| `due_date` | string | Sempre `\"-\"`, pois ainda não há data de repasse definida |\n| `orders_amount` | inteiro | Quantidade de pedidos no grupo |\n| `gross_value` | decimal | Valor bruto (subtotal + custo de entrega − taxa de frete) |\n| `anticipation_fee` | decimal | Taxa de antecipação descontada |\n| `to_receive` | decimal | Valor líquido a receber |\n\n### `processed` — pedidos com repasse agendado, agrupados por data (presente quando `filter` = `processed` ou `all`)\n\n| Campo | Tipo | Descrição |\n| --- | --- | --- |\n| `orders[]` | array | Grupos por data de repasse, cada um com `due_date` (`YYYY-MM-DD`), `orders_amount`, `gross_value`, `anticipation_fee` e `to_receive` |\n| `per_page` | inteiro | Itens por página |\n| `total` | inteiro | Total de grupos (datas) |\n| `last_page` | inteiro | Última página disponível |\n| `current_page` | inteiro | Página atual |"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"value":"application/json","key":"Content-Type"}],"cookie":[],"responseTime":null,"body":"{\n \"data\": {\n \"financial\": {\n \"delivered\": 1520.75,\n \"delivering\": 830.4,\n \"total\": 2351.15,\n \"delivering_orders_amount\": 12,\n \"delivered_orders_amount\": 25,\n \"total_orders_amount\": 37\n },\n \"pending\": {\n \"due_date\": \"-\",\n \"orders_amount\": 12,\n \"gross_value\": 905.1,\n \"anticipation_fee\": 74.7,\n \"to_receive\": 830.4\n },\n \"processed\": {\n \"orders\": [\n {\n \"due_date\": \"2026-08-14\",\n \"orders_amount\": 10,\n \"gross_value\": 650.3,\n \"anticipation_fee\": 48.25,\n \"to_receive\": 602.05\n },\n {\n \"due_date\": \"2026-08-15\",\n \"orders_amount\": 15,\n \"gross_value\": 990.8,\n \"anticipation_fee\": 72.1,\n \"to_receive\": 918.7\n }\n ],\n \"per_page\": 10,\n \"total\": 2,\n \"last_page\": 1,\n \"current_page\": 1\n }\n }\n}"},{"id":"98df7866-539b-08da-3ad5-057e1d80c6da","name":"422 — Erro ao consultar dados","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.staging.hubii.co/hubs/:hub_uuid/financial/to-receive?filter=all&page=1&per_page=10","host":["https://api.staging.hubii.co"],"path":["hubs",":hub_uuid","financial","to-receive"],"query":[{"key":"filter","value":"all","description":"pending, processed ou all (padrão: all)"},{"key":"page","value":"1","description":"Página da listagem de processados (padrão: 1)"},{"key":"per_page","value":"10","description":"Itens por página, de 1 a 100 (padrão: 10)"}],"variable":[{"key":"hub_uuid","value":"45e2a1cc-509b-4e33-bdc5-8ed255caf8a5"}]},"description":"Retorna a visão consolidada dos valores **a receber** do hub, separando pedidos ainda pendentes de processamento e pedidos já processados com data de repasse agendada.\n\n## Parâmetros de rota\n\n| Parâmetro | Tipo | Descrição |\n| --- | --- | --- |\n| `hub_uuid` | uuid | UUID do hub retornado em `GET /hubs`. Deve pertencer à sua conta |\n\n## Query params\n\n| Parâmetro | Tipo | Obrigatório | Descrição |\n| --- | --- | --- | --- |\n| `filter` | string | Não | `pending` (somente pendentes), `processed` (somente processados) ou `all` (padrão, retorna ambos) |\n| `page` | inteiro | Não | Página da listagem de processados. Padrão: `1` |\n| `per_page` | inteiro | Não | Itens por página (1 a 100). Padrão: `10` |\n\n## Campos da resposta (`data`)\n\n### `financial` — resumo geral\n\n| Campo | Tipo | Descrição |\n| --- | --- | --- |\n| `delivered` | decimal | Valor a receber de pedidos já entregues (com data de repasse agendada) |\n| `delivering` | decimal | Valor a receber de pedidos ainda em andamento (sem data de repasse) |\n| `total` | decimal | Soma de `delivered` + `delivering` |\n| `delivered_orders_amount` | inteiro | Quantidade de pedidos entregues |\n| `delivering_orders_amount` | inteiro | Quantidade de pedidos em andamento |\n| `total_orders_amount` | inteiro | Quantidade total de pedidos |\n\n### `pending` — pedidos sem data de repasse (presente quando `filter` = `pending` ou `all`)\n\n| Campo | Tipo | Descrição |\n| --- | --- | --- |\n| `due_date` | string | Sempre `\"-\"`, pois ainda não há data de repasse definida |\n| `orders_amount` | inteiro | Quantidade de pedidos no grupo |\n| `gross_value` | decimal | Valor bruto (subtotal + custo de entrega − taxa de frete) |\n| `anticipation_fee` | decimal | Taxa de antecipação descontada |\n| `to_receive` | decimal | Valor líquido a receber |\n\n### `processed` — pedidos com repasse agendado, agrupados por data (presente quando `filter` = `processed` ou `all`)\n\n| Campo | Tipo | Descrição |\n| --- | --- | --- |\n| `orders[]` | array | Grupos por data de repasse, cada um com `due_date` (`YYYY-MM-DD`), `orders_amount`, `gross_value`, `anticipation_fee` e `to_receive` |\n| `per_page` | inteiro | Itens por página |\n| `total` | inteiro | Total de grupos (datas) |\n| `last_page` | inteiro | Última página disponível |\n| `current_page` | inteiro | Página atual |"},"status":"Unprocessable Entity","code":422,"_postman_previewlanguage":"json","header":[{"value":"application/json","key":"Content-Type"}],"cookie":[],"responseTime":null,"body":"{\n \"data\": {\n \"success\": false,\n \"error\": \"Unable to fetch financial data.\"\n }\n}"}],"_postman_id":"1b226982-3399-07c8-3ec2-d4fb3a17f943"},{"name":"Valores recebidos","id":"9ef8d6ff-973c-c3fd-e62b-4f4ea8fb7dfd","request":{"method":"GET","header":[],"url":"https://api.staging.hubii.co/hubs/:hub_uuid/financial/received?last_days=30&page=1&per_page=10","description":"Retorna os valores já repassados ao hub nos últimos dias, agrupados por data de repasse. Considera apenas pedidos entregues (ou extraviados) cujo repasse já foi processado.
\ndata)financial — resumo do períodoorders — repasses agrupados por dataJanela de dias a considerar, de 1 a 90 (padrão: 30)
\n","type":"text/plain"},"key":"last_days","value":"30"},{"description":{"content":"Página da listagem (padrão: 1)
\n","type":"text/plain"},"key":"page","value":"1"},{"description":{"content":"Itens por página, de 1 a 100 (padrão: 10)
\n","type":"text/plain"},"key":"per_page","value":"10"}],"variable":[{"type":"any","value":"","key":"hub_uuid"}]}},"response":[{"id":"802496cc-4d3b-a156-5987-8033d092dd71","name":"200 — Sucesso","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.staging.hubii.co/hubs/:hub_uuid/financial/received?last_days=30&page=1&per_page=10","host":["https://api.staging.hubii.co"],"path":["hubs",":hub_uuid","financial","received"],"query":[{"key":"last_days","value":"30","description":"Janela de dias a considerar, de 1 a 90 (padrão: 30)"},{"key":"page","value":"1","description":"Página da listagem (padrão: 1)"},{"key":"per_page","value":"10","description":"Itens por página, de 1 a 100 (padrão: 10)"}],"variable":[{"key":"hub_uuid","value":""}]},"description":"Retorna os valores **já repassados** ao hub nos últimos dias, agrupados por data de repasse. Considera apenas pedidos entregues (ou extraviados) cujo repasse já foi processado.\n\n## Parâmetros de rota\n\n| Parâmetro | Tipo | Descrição |\n| --- | --- | --- |\n| `hub_uuid` | uuid | UUID do hub retornado em `GET /hubs`. Deve pertencer à sua conta |\n\n## Query params\n\n| Parâmetro | Tipo | Obrigatório | Descrição |\n| --- | --- | --- | --- |\n| `last_days` | inteiro | Não | Janela de dias a considerar, de 1 a 90. Padrão: `30` |\n| `page` | inteiro | Não | Página da listagem. Padrão: `1` |\n| `per_page` | inteiro | Não | Itens por página (1 a 100). Padrão: `10` |\n\n## Campos da resposta (`data`)\n\n### `financial` — resumo do período\n\n| Campo | Tipo | Descrição |\n| --- | --- | --- |\n| `orders_amount` | inteiro | Quantidade de pedidos com repasse concluído no período |\n| `received` | decimal | Valor total recebido no período |\n\n### `orders` — repasses agrupados por data\n\n| Campo | Tipo | Descrição |\n| --- | --- | --- |\n| `data[]` | array | Grupos por data de repasse |\n| `data[].due_date` | string | Data do repasse (`YYYY-MM-DD`) |\n| `data[].orders_amount` | inteiro | Quantidade de pedidos repassados na data |\n| `data[].gross_value` | decimal | Valor bruto (subtotal + custo de entrega − taxa de frete) |\n| `data[].anticipation_fee` | decimal | Taxa de antecipação descontada |\n| `data[].to_receive` | decimal | Valor líquido repassado |\n| `per_page` | inteiro | Itens por página |\n| `total` | inteiro | Total de grupos (datas) |\n| `last_page` | inteiro | Última página disponível |\n| `current_page` | inteiro | Página atual |"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"data\": {\n \"financial\": {\n \"orders_amount\": 25,\n \"received\": 2351.15\n },\n \"orders\": {\n \"data\": [\n {\n \"due_date\": \"2026-07-28\",\n \"orders_amount\": 10,\n \"gross_value\": 650.3,\n \"anticipation_fee\": 48.25,\n \"to_receive\": 602.05\n },\n {\n \"due_date\": \"2026-08-04\",\n \"orders_amount\": 15,\n \"gross_value\": 1868.55,\n \"anticipation_fee\": 119.45,\n \"to_receive\": 1749.1\n }\n ],\n \"per_page\": 10,\n \"total\": 2,\n \"last_page\": 1,\n \"current_page\": 1\n }\n }\n}"},{"id":"47f176de-09cb-434f-f7df-8d57dd7e1fc5","name":"422 — Erro ao consultar dados","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.staging.hubii.co/hubs/:hub_uuid/financial/received?last_days=30&page=1&per_page=10","host":["https://api.staging.hubii.co"],"path":["hubs",":hub_uuid","financial","received"],"query":[{"key":"last_days","value":"30","description":"Janela de dias a considerar, de 1 a 90 (padrão: 30)"},{"key":"page","value":"1","description":"Página da listagem (padrão: 1)"},{"key":"per_page","value":"10","description":"Itens por página, de 1 a 100 (padrão: 10)"}],"variable":[{"key":"hub_uuid","value":""}]},"description":"Retorna os valores **já repassados** ao hub nos últimos dias, agrupados por data de repasse. Considera apenas pedidos entregues (ou extraviados) cujo repasse já foi processado.\n\n## Parâmetros de rota\n\n| Parâmetro | Tipo | Descrição |\n| --- | --- | --- |\n| `hub_uuid` | uuid | UUID do hub retornado em `GET /hubs`. Deve pertencer à sua conta |\n\n## Query params\n\n| Parâmetro | Tipo | Obrigatório | Descrição |\n| --- | --- | --- | --- |\n| `last_days` | inteiro | Não | Janela de dias a considerar, de 1 a 90. Padrão: `30` |\n| `page` | inteiro | Não | Página da listagem. Padrão: `1` |\n| `per_page` | inteiro | Não | Itens por página (1 a 100). Padrão: `10` |\n\n## Campos da resposta (`data`)\n\n### `financial` — resumo do período\n\n| Campo | Tipo | Descrição |\n| --- | --- | --- |\n| `orders_amount` | inteiro | Quantidade de pedidos com repasse concluído no período |\n| `received` | decimal | Valor total recebido no período |\n\n### `orders` — repasses agrupados por data\n\n| Campo | Tipo | Descrição |\n| --- | --- | --- |\n| `data[]` | array | Grupos por data de repasse |\n| `data[].due_date` | string | Data do repasse (`YYYY-MM-DD`) |\n| `data[].orders_amount` | inteiro | Quantidade de pedidos repassados na data |\n| `data[].gross_value` | decimal | Valor bruto (subtotal + custo de entrega − taxa de frete) |\n| `data[].anticipation_fee` | decimal | Taxa de antecipação descontada |\n| `data[].to_receive` | decimal | Valor líquido repassado |\n| `per_page` | inteiro | Itens por página |\n| `total` | inteiro | Total de grupos (datas) |\n| `last_page` | inteiro | Última página disponível |\n| `current_page` | inteiro | Página atual |"},"status":"Unprocessable Entity","code":422,"_postman_previewlanguage":"json","header":[{"value":"application/json","key":"Content-Type"}],"cookie":[],"responseTime":null,"body":"{\n \"data\": {\n \"success\": false,\n \"error\": \"Unable to fetch financial data.\"\n }\n}"}],"_postman_id":"9ef8d6ff-973c-c3fd-e62b-4f4ea8fb7dfd"},{"name":"Detalhamento por data de repasse","id":"f900db14-e546-7698-236e-f86e39d32701","request":{"method":"GET","header":[],"url":"https://api.staging.hubii.co/hubs/:hub_uuid/financial/detailed/:date","description":"Retorna o detalhamento pedido a pedido dos repasses de uma data específica, com valores brutos, taxas de antecipação e total líquido de cada pedido. Útil para conciliar o extrato bancário com os pedidos individuais.
\ndata)financial — resumo da dataorders[] — pedidos individuaisEsta seção documenta os endpoints de consulta financeira dos repasses de pedidos do hub. Eles permitem que o parceiro concilie os valores a receber e já recebidos, agrupados por data de repasse, e consulte o detalhamento pedido a pedido de uma data específica.
\nA receber (GET .../financial/to-receive): visão consolidada dos valores pendentes de repasse, separados entre pedidos ainda em processamento (sem data de repasse definida) e pedidos já processados (com data de repasse agendada).
Recebidos (GET .../financial/received): valores já repassados ao hub nos últimos dias, agrupados por data de repasse.
Detalhado por data (GET .../financial/detailed/{date}): lista pedido a pedido os repasses de uma data específica, com valores brutos, taxas de antecipação e total.
Use o header apikey como nas demais rotas. O hub_uuid informado precisa pertencer à sua conta; caso contrário a requisição é rejeitada.
Essas rotas seguem o grupo de Listagem (60/min por token).
\n","_postman_id":"cbde5d29-b3a5-bd93-c372-8ca197a94f6d","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":"08 — Homologação","item":[{"name":"Listar produtos para pedidos de teste","id":"1cb49bcd-f9ae-4615-90be-18a0d4348099","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/homologation/v1/products","description":"Lista o catálogo de produtos de teste (EANs sintéticos) provisionado para a sua homologação. Os pedidos de teste (POST .../test-orders) já vêm com itens pré-configurados por modelo; esta rota serve principalmente para conferência do escopo provisionado.
Mesma API Key de homologação, enviada no header apikey, contra base_url = https://api.staging.hubii.co.
Se a homologação não tiver produtos provisionados, products retorna lista vazia.
curl -s \"$BASE_URL/homologation/v1/products\" \\\n -H \"Accept: application/json\" \\\n -H \"apikey: $HUBII_STAGING_API_KEY\"\n\nGET seguro repetir a qualquer momento.
Crie um pedido de teste com POST /homologation/v1/test-orders.
Cria um pedido de teste em staging a partir de um modelo pronto (lista fechada de 9 modelos). O checkout interno é feito automaticamente pelo serviço de homologação; a resposta traz o order_uuid real, que deve ser usado a partir daí na API pública (https://doc.hubii.io/) para aceitar/recusar, faturar, expedir e cancelar — exatamente como um pedido real do dia a dia.
\n\nModelos legados (
\noffer_*,accepted_*,marketplace_express) foram descontinuados e retornam422.
Após o aceite (POST .../answer na API pública), o serviço de homologação avança automaticamente o fluxo logístico simulado (busca de courier, coleta, entrega ou cancelamento, conforme o modelo). Não é necessário — e não é possível — chamar rotas internas de avanço de status.
application/json)201{\n \"test_order_uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"order_uuid\": \"6ba7b810-9dad-11d1-80b4-00c04fd430c8\",\n \"model\": \"quick_default\"\n}\n\n\nAtenção:
\ntest_order_uuideorder_uuidsão UUIDs diferentes, com usos diferentes.test_order_uuidsó serve para consultar o registro de teste nesta API de homologação;order_uuidé o identificador usado em praticamente todo o resto do fluxo, incluindo a API pública e a rota de XML de NF-e.
Esta rota não retorna hub_uuid, delivery_flow_profile nem available_until_at. Para o hub alocado e o prazo de aceite, consulte GET /hubs/{hub_uuid}/orders/{order_uuid} na API pública, após o pedido aparecer em to-answer.
curl -s -X POST \"$BASE_URL/homologation/v1/test-orders\" \\\n -H \"Accept: application/json\" \\\n -H \"Content-Type: application/json\" \\\n -H \"apikey: $HUBII_STAGING_API_KEY\" \\\n -d '{\"model\": \"quick_default\", \"external_reference\": \"meu-teste-1\"}'\nNão é idempotente: cada chamada cria um novo pedido de teste. Não faça retry automático sem confirmar se o pedido anterior já foi criado.
\nUse order_uuid na API pública: GET /hubs/{hub_uuid}/orders/to-answer → GET /hubs/{hub_uuid}/orders/{order_uuid} → POST .../answer.
Consulta o registro de um pedido de teste criado nesta homologação, pelo test_order_uuid retornado no POST /homologation/v1/test-orders.
order_uuid e model foram associados a um test_order_uuid específico.POST original não tenha sido persistida.200Mesmo formato do POST:
{\n \"test_order_uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"order_uuid\": \"6ba7b810-9dad-11d1-80b4-00c04fd430c8\",\n \"model\": \"marketplace_default\"\n}\ncurl -s \"$BASE_URL/homologation/v1/test-orders/$TEST_ORDER_UUID\" \\\n -H \"Accept: application/json\" \\\n -H \"apikey: $HUBII_STAGING_API_KEY\"\nGET seguro repetir a qualquer momento.
UUID retornado em test_order_uuid no POST /homologation/v1/test-orders
\n","type":"text/plain"},"type":"any","value":"","key":"test_order_uuid"}]}},"response":[{"id":"2c528b82-3cce-4bd3-82b6-3342e172977d","name":"[200] Consultar pedido de teste","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.staging.hubii.co/homologation/v1/test-orders/:test_order_uuid","host":["https://api.staging.hubii.co"],"path":["homologation","v1","test-orders",":test_order_uuid"],"variable":[{"key":"test_order_uuid","value":"550e8400-e29b-41d4-a716-446655440000"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"test_order_uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"order_uuid\": \"6ba7b810-9dad-11d1-80b4-00c04fd430c8\",\n \"model\": \"marketplace_default\"\n}"},{"id":"590d6f36-d1c7-4b29-9d54-5a4b509dc114","name":"[403] Pedido de outra homologação","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.staging.hubii.co/homologation/v1/test-orders/:test_order_uuid","host":["https://api.staging.hubii.co"],"path":["homologation","v1","test-orders",":test_order_uuid"],"variable":[{"key":"test_order_uuid","value":"550e8400-e29b-41d4-a716-446655440000"}]}},"status":"Forbidden","code":403,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"error\": \"Forbidden.\"\n}"}],"_postman_id":"648d86d5-d633-4236-92df-016b76032e9a"},{"name":"Gerar XML de NF-e fake para pedido de teste","id":"b9f6663c-9eb9-4def-94cf-b709e01a6f93","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/xml","type":"text"}],"url":"https://api.staging.hubii.co/homologation/v1/test-orders/:order_uuid/invoice-xml?variant=valid","description":"Gera um XML de NF-e sintético para um pedido de teste, pronto para ser enviado à API pública em POST /hubs/{hub_uuid}/orders/{order_uuid}/invoice. Use esta rota para homologar o fluxo de faturamento sem depender de um emissor fiscal real.
Apenas para pedidos criados com modelo marketplace_*, que exigem envio de NF-e antes de disponibilizar a etiqueta. Modelos quick_* e scheduled_* não passam por esta etapa.
200Content-Type: application/xml. Corpo é o XML da NF-e (nfeProc):
<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<nfeProc xmlns=\"http://www.portalfiscal.inf.br/nfe\">\n <NFe>\n <infNFe Id=\"NFe6ba7b810-9dad-11d1-80b4-00c04fd430c8\">\n <ide>\n <cUF>35</cUF>\n <natOp>Homologacao Hubii API</natOp>\n <mod>55</mod>\n <serie>1</serie>\n <nNF>1</nNF>\n </ide>\n <dest>\n <CPF>00000000000</CPF>\n <xNome>Cliente de Teste</xNome>\n <enderDest>\n <CEP>01310100</CEP>\n <xLgr>Rua Homologacao</xLgr>\n <nro>100</nro>\n <xBairro>Centro</xBairro>\n <xMun>Sao Paulo</xMun>\n <UF>SP</UF>\n </enderDest>\n </dest>\n <det>\n <prod>\n <cProd>HOMOLOG-6ba7b810-9dad-11d1-80b4-00c04fd430c8</cProd>\n <xProd>Produto de teste homologacao</xProd>\n <qCom>1.0000</qCom>\n </prod>\n </det>\n <total>\n <ICMSTot>\n <vNF>150.75</vNF>\n </ICMSTot>\n </total>\n <infAdic>\n <infCpl>order_uuid=6ba7b810-9dad-11d1-80b4-00c04fd430c8;variant=valid</infCpl>\n </infAdic>\n </infNFe>\n </NFe>\n <protNFe>\n <infProt>\n <tpAmb>2</tpAmb>\n <chNFe>35260700000000000155550010000000011000000015</chNFe>\n <dhRecbto>2026-07-27T14:00:00-03:00</dhRecbto>\n <nProt>135260000000001</nProt>\n <cStat>100</cStat>\n <xMotivo>Autorizado o uso da NF-e</xMotivo>\n </infProt>\n </protNFe>\n</nfeProc>\ncurl -s \"$BASE_URL/homologation/v1/test-orders/$ORDER_UUID/invoice-xml?variant=valid\" \\\n -H \"apikey: $HUBII_STAGING_API_KEY\" \\\n -o nota-teste.xml\nEnvie o arquivo baixado para a API pública:
\ncurl -s -X POST \"$BASE_URL_PUBLICA/hubs/$HUB_UUID/orders/$ORDER_UUID/invoice\" \\\n -H \"Accept: application/json\" \\\n -H \"apikey: $HUBII_API_KEY\" \\\n -F \"invoice_file=@nota-teste.xml\"\nGET seguro repetir; cada chamada gera um novo XML equivalente (o horário de recebimento simulado muda a cada geração; o restante do conteúdo é estável para o mesmo pedido e variante).
valid | cep_mismatch
\n","type":"text/plain"},"key":"variant","value":"valid"}],"variable":[{"id":"5580eb58-ca81-46be-a64d-663cc953f9ea","description":{"content":"order_uuid retornado em POST/GET .../test-orders (não é o test_order_uuid)
\n","type":"text/plain"},"type":"any","value":"","key":"order_uuid"}]}},"response":[{"id":"064448e5-acca-47a0-941e-7e74b3044362","name":"[200] XML válido (variant=valid)","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.staging.hubii.co/homologation/v1/test-orders/:order_uuid/invoice-xml?variant=valid","host":["https://api.staging.hubii.co"],"path":["homologation","v1","test-orders",":order_uuid","invoice-xml"],"query":[{"key":"variant","value":"valid"}],"variable":[{"key":"order_uuid","value":"6ba7b810-9dad-11d1-80b4-00c04fd430c8"}]}},"status":"OK","code":200,"_postman_previewlanguage":"xml","header":[{"key":"Content-Type","value":"application/xml; charset=UTF-8"}],"cookie":[],"responseTime":null,"body":"\nEsta seção documenta o serviço partner-homologation-service, uma API auxiliar disponível somente em staging, criada para o parceiro montar cenários de teste durante a homologação. Ela não substitui a API pública documentada em https://doc.hubii.io/ — serve apenas para:
Consultar produtos de teste vinculados à sua homologação.
\nCriar pedidos de teste (test-orders) por modelo pronto, sem montar um checkout completo.
Gerar um XML de NF-e sintético para exercitar o fluxo de faturamento.
\n\n\nAs rotas deste módulo não existem em produção. Em
\nhttps://api.hubii.co,/homologation/v1/...retorna404.
GET /homologation/v1/products\n ↓ (opcional; conferir o catálogo sandbox)\nPOST /homologation/v1/test-orders { model }\n ↓ retorna { test_order_uuid, order_uuid, model }\n[API pública] GET .../to-answer → GET .../orders/{order_uuid} → POST .../answer\n ↓ pedido aceito; fluxo logístico avança automaticamente\n[somente marketplace_*] GET /homologation/v1/test-orders/{order_uuid}/invoice-xml\n ↓\n[API pública] POST .../orders/{order_uuid}/invoice\n\nEndpoint legado de listagem de notificações, sem paginação. Mantido apenas por compatibilidade com integrações antigas. Novas integrações devem usar:
\nGET /v2/notifications\n ↓ data[]\nPOST /notifications/ack\nGET /v2/notifications retorna o mesmo conteúdo em data[], com page, limit, total e last_page.X-API-Deprecated: true e X-API-Replacement: /v2/notifications.Planeje migração para GET /v2/notifications. Enquanto isso, trate a resposta como array e mantenha POST /notifications/ack inalterado.
5 req/min por token, no grupo de notificações.
\n\n\n","urlObject":{"path":["notifications"],"host":["https://api.staging.hubii.co"],"query":[{"disabled":true,"description":{"content":"Em runtime, use os headers
\nX-RateLimit-*como referência operacional. A tabela de rate limits documenta o limite esperado/contratual.
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":"Endpoint legado mantido apenas por compatibilidade com integrações antigas. Novas integrações devem usar o Polling 2:
\nGET /v2/notifications\n ↓ ORDER_CREATED\nGET /hubs/{hub_uuid}/orders/{order_uuid}\nORDER_CREATED chega após aceite via API ou painel e deve disparar a importação no ERP.Planeje migração para Polling 2 + ORDER_CREATED. Enquanto isso, mantenha retry e rate limit conforme o grupo de listagem.
60 req/min por token, no grupo de listagem.
\n\n\n","urlObject":{"path":["hubs",":hub_uuid","orders","to-invoice"],"host":["https://api.staging.hubii.co"],"query":[{"description":{"content":"Em runtime, use os headers
\nX-RateLimit-*como referência operacional. A tabela de rate limits documenta o limite esperado/contratual.
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":""},{"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":""}],"variable":[{"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"},{"key":"test_order_uuid","value":"","description":"UUID do pedido de teste retornado em POST /homologation/v1/test-orders (campo test_order_uuid)"}]}