# AGENTS.md — integração com a API do GransoftWeb

Instruções para agentes de IA (Claude Code, Cursor, Copilot, Codex…) que trabalham neste projeto.
Copie este arquivo para a raiz do projeto. Se usar Claude Code, copie também como `CLAUDE.md`.

## Fonte da verdade

- Documentação: https://www.gransoftweb.com/developers/llms.txt (leia antes de escrever código de integração).
- MCP de documentação (se estiver conectado): use `buscar_documentacao` e `obter_documento` antes de chamar um método novo.
- Swagger: http://www.server1.gepersistemas.com.br:8082/swagger/ui/index
- **Não invente métodos, campos ou números de `Acao`.** Se não estiver na documentação ou no Swagger, pergunte ao desenvolvedor.

## Regras obrigatórias

1. Use sempre o cliente `gransoft-client.js` (`GransoftClient`). Não chame `fetch` direto para a API.
2. O `userHash` e o servidor vêm de variáveis de ambiente (`GRANSOFT_USERHASH`, `GRANSOFT_SERVIDOR`). Nunca escreva o `userHash` no código, em arquivos versionados, no front-end ou em logs.
3. A API responde HTTP 200 mesmo com erro. O cliente já lança `GransoftErro` quando o campo `Erro` vem preenchido: trate essa exceção e mostre `e.message` ao usuário.
4. O `userHash` vai no corpo JSON (o cliente já faz isso). `ObterLista` é a exceção (query string), tratada por `obterLista()`.
5. Limite de 50 requisições por minuto. O cliente controla o ritmo; não dispare chamadas em paralelo em massa.
6. Datas chegam como `"/Date(ms)/"`: use `lerData()` ou `converterDatas()`.
7. Textos de busca passam por `limparBusca()`.
8. Códigos (cliente, produto, material, tabela) vêm das listas (`obterLista`) ou de consultas. Nunca fixe códigos no código.
9. Se a busca devolver mais de um cliente, produto ou material compatível, pergunte ao usuário qual usar.
10. Medidas em metros (`1.20`); acabamentos de borda em metros lineares.

## Gravações

- Toda chamada de gravação (orçamento, agenda, cadastro) grava no banco na hora. Não há "salvar" final nem desfazer.
- Teste gravações apenas com o usuário e dados de teste. Peça confirmação ao desenvolvedor antes de rodar código que grava.
- Em `AcoesDocumentoVendaMarmoraria`:
  - envie sempre `FieldsToUpdate` nas ações `3` e `21`;
  - nas ações `42`/`43` envie o endereço completo (elas substituem todos os campos);
  - pedidos (`Tipo` = 1) não podem ser alterados.

## Estilo do código de integração

- Node.js 18+ com ES modules (`import`).
- Funções pequenas por tarefa (ex.: `listarChapasDisponiveis(material)`), cada uma com tratamento de `GransoftErro`.
- Nada de segredo em `console.log`. Para depurar, use `mascarar(userHash)`.