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/ordersnã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 |