# GransoftWeb — API para desenvolvedores

> API REST/JSON do GransoftWeb, ERP em nuvem para marmorarias. Toda chamada é feita em nome de um
> usuário, identificado pelo `userHash`. A API responde HTTP 200 mesmo quando falha: o resultado
> está no campo `Erro` da resposta. Limite: 50 requisições por minuto por usuário.

Leia nesta ordem antes de escrever código:

1. [Início rápido](https://www.gransoftweb.com/developers/inicio-rapido.md): o que é preciso, primeira chamada e regras gerais.
2. [Autenticação](https://www.gransoftweb.com/developers/autenticacao.md): obter o `userHash` e o `Servidor` da empresa.
3. [Convenções](https://www.gransoftweb.com/developers/convencoes.md): erros com HTTP 200, datas `/Date(ms)/`, enums numéricos, limites e segurança.
4. O guia da tarefa (abaixo) e o kit em Node.js.

## Guias por tarefa

- [Consultar estoque de chapas](https://www.gransoftweb.com/developers/guias/consultar-estoque-chapas.md): chapas por material, dimensões, m² e disponibilidade.
- [Consultar clientes](https://www.gransoftweb.com/developers/guias/consultar-clientes.md): busca por nome, códigos e dados completos do cliente.
- [Criar orçamento](https://www.gransoftweb.com/developers/guias/criar-orcamento.md): cliente, itens de produção (peças sob medida), revenda, serviços, desconto e PDF.

## Kit em Node.js (18 ou superior, sem dependências)

- [README do kit](https://www.gransoftweb.com/developers/kit/README.md): instalação e uso.
- [gransoft-client.js](https://www.gransoftweb.com/developers/kit/gransoft-client.js): cliente pronto (autenticação, erros, limite de requisições, datas).
- [exemplo-estoque.js](https://www.gransoftweb.com/developers/kit/exemplo-estoque.js): lista chapas disponíveis de um material.
- [exemplo-clientes.js](https://www.gransoftweb.com/developers/kit/exemplo-clientes.js): busca clientes pelo nome.
- [exemplo-orcamento.js](https://www.gransoftweb.com/developers/kit/exemplo-orcamento.js): cria um orçamento com uma peça sob medida.
- [AGENTS.md](https://www.gransoftweb.com/developers/kit/AGENTS.md): regras para o agente de IA que vai trabalhar no projeto.

## Referência

- [Referência e onde achar cada método](https://www.gransoftweb.com/developers/referencia.md): Swagger, catálogo de APIs e tabela de ações de vendas.
- [Usar com IA](https://www.gransoftweb.com/developers/usar-com-ia.md): como pedir a uma IA para criar a integração e como conectar o MCP de documentação.
- [Histórico de alterações](https://www.gransoftweb.com/developers/changelog.md)
- Swagger (contrato dos métodos): http://www.server1.gepersistemas.com.br:8082/swagger/ui/index
- Catálogo de APIs com testador: https://www.server1.gransoftweb.com/API/

## Para agentes de IA

- MCP de documentação (somente leitura, sem login): https://www.gransoftweb.com/developers/mcp
- Todo o conteúdo em um arquivo: https://www.gransoftweb.com/developers/llms-full.txt
- Não invente métodos, campos ou valores de `Acao`. Se não estiver nestes documentos ou no Swagger, diga que não encontrou.