# Kit GransoftWeb para Node.js

Cliente pronto e exemplos para consumir a API do GransoftWeb. Requer **Node.js 18 ou superior**. Não tem dependências.

A IA pode usar este código como base também em outras linguagens: as regras estão comentadas em `gransoft-client.js`.

## Arquivos

| Arquivo | O que é |
|---|---|
| [gransoft-client.js](gransoft-client.js) | Cliente: `userHash`, verificação do `Erro`, limite de requisições, datas. |
| [exemplo-estoque.js](exemplo-estoque.js) | Chapas disponíveis de um material, com totais por material. |
| [exemplo-clientes.js](exemplo-clientes.js) | Busca de clientes pelo nome e dados completos. |
| [exemplo-orcamento.js](exemplo-orcamento.js) | Cria um orçamento com uma peça sob medida (grava; use dados de teste). |
| [AGENTS.md](AGENTS.md) | Regras para o agente de IA que vai trabalhar no projeto. |
| [package.json](package.json) | Configuração mínima (ES modules). |
| [env.example](env.example) | Modelo das variáveis de ambiente. |

## Instalação

1. Crie uma pasta e baixe os arquivos:

   ```bash
   mkdir minha-integracao && cd minha-integracao
   for f in gransoft-client.js exemplo-estoque.js exemplo-clientes.js exemplo-orcamento.js AGENTS.md package.json env.example; do
     curl -fsSO "https://www.gransoftweb.com/developers/kit/$f"
   done
   ```

   No Windows (PowerShell):

   ```powershell
   mkdir minha-integracao; cd minha-integracao
   "gransoft-client.js","exemplo-estoque.js","exemplo-clientes.js","exemplo-orcamento.js","AGENTS.md","package.json","env.example" |
     ForEach-Object { Invoke-WebRequest "https://www.gransoftweb.com/developers/kit/$_" -OutFile $_ }
   ```

2. Copie `env.example` para `.env` e preencha:
   - `GRANSOFT_USERHASH`: a chave de teste do catálogo de APIs (`https://www.server1.gransoftweb.com/API/`, entrando com o usuário da integração);
   - `GRANSOFT_SERVIDOR`: a "URL base" da mesma página, sem o `/API/` (ex.: `https://www.server1.gransoftweb.com`).

3. Rode um exemplo:

   ```bash
   node --env-file=.env exemplo-estoque.js "branco"
   node --env-file=.env exemplo-clientes.js "maria"
   node --env-file=.env exemplo-orcamento.js --cliente 1523 --produto 55 --material 120 --pecas "Tampo 1,20 x 0,60"
   ```

   `--env-file` existe a partir do Node.js 20.6. No Node.js 18, defina as variáveis no terminal antes de rodar.

   O exemplo de orçamento só grava com `--gravar`.

**Não versione o `.env`.** Inclua-o no `.gitignore`.

## Uso do cliente

```js
import { GransoftClient, GransoftErro, limparBusca, converterDatas } from "./gransoft-client.js";

const gs = new GransoftClient({
  userHash: process.env.GRANSOFT_USERHASH,
  servidor: process.env.GRANSOFT_SERVIDOR,
});

try {
  // Qualquer método: POST {servidor}/API/{metodo}, userHash incluído automaticamente.
  const r = await gs.chamar("ListaEstoqueChapas", { Search: { Keyword: limparBusca("branco"), MaxResult: 100 } });

  // Vendas: atalho para AcoesDocumentoVendaMarmoraria.
  const ultimos = await gs.venda(45);

  // Listas de apoio: devolve [{ Codigo, Descricao }].
  const tabelas = await gs.obterLista(8);

  console.log(converterDatas(ultimos.Documentos));
} catch (e) {
  if (e instanceof GransoftErro) console.error(e.tipo, e.message);  // "api", "limite", "indisponivel"…
  else throw e;
}
```

## Pedir à IA para criar a integração

Abra o projeto no seu editor com IA e peça, por exemplo:

> Leia o AGENTS.md e https://www.gransoftweb.com/developers/llms.txt. Usando o gransoft-client.js, crie um script que liste os orçamentos dos últimos 7 dias com cliente e valor total e salve em um CSV.

Mais exemplos de pedidos em https://www.gransoftweb.com/developers/usar-com-ia.md