API Docs v1 api.hubiss.com.br

Integração com agentes de IA

Prompts prontos para um agente construir e manter a integração com a Hubiss de forma automática.

Esta página reúne prompts para usar com agentes de código (Claude Code, Codex, Cursor, Copilot) ou agentes de API, de modo que a integração seja escrita, testada e mantida automaticamente.

Dica
Sempre entregue ao agente o índice https://api.hubiss.com.br/llms.txt e a página do endpoint que ele vai usar. Quanto mais específico o contexto, menor a chance de alucinação de campos.

1. Prompt de descoberta e contrato

Cole isto no agente para ele mapear a API antes de escrever código:

Saída esperadatext
Você vai implementar um cliente para a API da Hubiss (v1).

Leia a documentação em https://api.hubiss.com.br/llms.txt e as páginas
/bem-vindo, /autenticacao, /lojas, /categorias, /marcas, /produtos,
/pedidos e /webhooks.

Antes de escrever código, produza um documento `hubiss-api-contract.md` com:
1. lista de endpoints que vou precisar, com método, caminho e propósito;
2. campos obrigatórios de cada payload, com tipo e exemplo;
3. quais chamadas têm dependência de ordem (loja antes de categoria, etc.);
4. formato de erro por status (401, 404, 405, 422, 429, 5xx), copiando a
   tabela "Erros possíveis" de cada endpoint;
5. estratégia de retry apenas para 429 e 5xx (backoff exponencial com jitter).

Regras do contrato atual: `per_page` vem 20 por página e o máximo também é 20;
não existe limite de requisições por token (o 429, se aparecer, vem da sua
infraestrutura); a API não emite 403.

Não invente campos. Se algo não estiver documentado, marque como "PENDENTE"
e liste a dúvida no final.

2. Prompt de implementação do cliente HTTP

Saída esperadatext
Implemente um cliente PHP (Laravel HTTP client) para a API da Hubiss v1.

Requisitos:
- base URL configurável por ambiente (API_URL), nunca hard-coded;
- token Bearer lido de variável de ambiente, nunca versionado;
- métodos: listStores, createStore, listCategories, createCategory,
  listBrands, createProduct, uploadProductPictureUrl, listOrders,
  updateOrderStatus, createWebhook;
- paginação: leia `links.next` e pare quando for null (`per_page` máximo 20);
- retry automático apenas em 429 e 5xx, com backoff exponencial (máx 5 tentativas);
- tratar 422 lendo `data.<campo>` e devolvendo a mensagem por campo;
- tratar 404 como registro inexistente ou de outra conta (não repetir);
- tratar 401 como problema de token/conta (não repetir sem corrigir);
- logging sem o token e sem dados pessoais do cliente final;
- testes com Http::fake cobrindo 200/201, 401, 404 e 422.

Ao final, rode os testes e mostre a saída.

3. Prompt de sincronização de catálogo

Saída esperadatext
Crie um job de sincronização de catálogo com a API da Hubiss:

1. leia os produtos do meu banco;
2. para cada produto, garanta que a loja e a categoria existam (cache local do id);
3. crie ou atualize o produto, usando o SKU como chave de idempotência;
4. envie as fotos por URL, no máximo 10 por produto;
5. registre em log o id retornado pela Hubiss para cada SKU;
6. em caso de 422, não repita a chamada: grave o erro por campo e siga;
7. em caso de 422, registre o campo recusado e siga para o próximo item;
8. pagine com `per_page=20` (teto da API) e processe em lotes para não sobrecarregar o seu ambiente.

Gere também um comando artisan `hubiss:catalog-sync --dry-run`.

4. Prompt de recebimento de pedidos por webhook

Saída esperadatext
Implemente o recebimento de webhooks da Hubiss:

- rota POST /webhooks/hubiss sem CSRF, idempotente;
- valide o corpo { userId, topic, resource, attempt };
- responda 200 em até 2 segundos e processe o evento na fila;
- use `resource` para buscar o pedido em GET /v1/orders/{id} antes de atualizar;
- deduplique por (resource + attempt) para tolerar reenvios;
- grave log estruturado com topic, resource e attempt, sem dados pessoais;
- teste com payload real de exemplo e simule 3 tentativas do mesmo evento.

5. Prompt de auditoria da integração

Saída esperadatext
Audite o cliente Hubiss existente contra a documentação oficial:

1. compare os payloads enviados com os campos documentados;
2. aponte campos obrigatórios ausentes e campos inexistentes;
3. verifique tratamento de 401, 404, 422, 429 e timeouts;
4. verifique se o token aparece em logs ou no código-fonte;
5. verifique se a paginação para ao chegar em `links.next = null` e se usa `per_page` até 20.

Entregue uma tabela: arquivo, linha, problema, severidade, correção sugerida.

6. Contrato de erros para o agente

Cada endpoint documenta sua própria tabela Erros possíveis. Os formatos são fixos:

JSONjson
// 401 (token, conta inativa, cadastro incompleto ou sem assinatura)
{ "error": "Unauthorized" }

// 404 (id inexistente ou de outra conta)
{ "error": "Resource 123 not found" }

// 422 (validação ou transição de status bloqueada)
{
    "success": false,
    "message": "Validation errors",
    "data": { "status": ["Cannot change status now, check documentation"] }
}
  • 405: verbo não suportado naquela rota (ex.: POST /v1/orders não existe).
  • 429: vem de proxy/CDN/gateway, não da API.
  • 5xx: falha interna; repetir com backoff (máx. 5 tentativas).

7. Regras que todo agente deve seguir

Regra Motivo
Nunca inventar campos A API responde 422 e quebra a sincronização
Não existe limite por token O 429 só aparece se a sua infraestrutura impuser teto
per_page máximo é 20 Valores maiores são reduzidos a 20; use links.next
Idempotência por SKU e por resource Evita duplicidade em retentativas
Token só em variável de ambiente Token rotacionado invalida o anterior
Respeitar a ordem loja → categoria → produto → foto Dependência real de dados
Paginar até next ser null Sem isso a sincronização fica incompleta