# Início rápido: API do GransoftWeb

Este guia mostra o mínimo para fazer a primeira chamada à API do GransoftWeb e as regras que valem para todos os métodos.

## 1. O que você precisa

- **Um acesso ao GransoftWeb.** Toda chamada é feita em nome de um usuário. Para testar, peça ao administrador da sua empresa que crie um **usuário só para a integração**, com as permissões necessárias e, se possível, sobre dados de teste.
- **O `userHash` desse usuário.** É a chave que identifica o usuário nas chamadas. Há duas formas de obtê-lo:
  - entrar no GransoftWeb com o usuário da integração, abrir `https://www.server1.gransoftweb.com/API/` e copiar a **chave de teste** exibida na página; ou
  - chamar o método de autenticação com e-mail e senha (veja [Autenticação](autenticacao.md)).
- **O endereço do servidor da empresa** (`Servidor`), por exemplo `https://www.server1.gransoftweb.com`. Ele vem na resposta da autenticação e aparece como "URL base" na página do catálogo de APIs.
- **Node.js 18 ou superior**, se for usar o kit pronto.

> Trate o `userHash` como uma senha. Quem tem o `userHash` acessa o sistema com as permissões daquele usuário. Guarde-o em variável de ambiente, nunca no código, no navegador ou em logs.

## 2. Primeira chamada

Consulta de chapas em estoque do material "branco":

```bash
curl -X POST "https://www.server1.gransoftweb.com/API/ListaEstoqueChapas" \
  -H "Content-Type: application/json" \
  -d '{
        "userHash": "SEU_USERHASH",
        "Search": { "Keyword": "branco", "Status": 0, "Reserva": 0, "MaxResult": 50 }
      }'
```

Resposta (resumida, valores fictícios):

```json
{
  "Erro": "",
  "Chapas": [
    {
      "Codigo": 3512,
      "Material": { "Descricao": "GRANITO BRANCO ITAÚNAS POLIDO" },
      "Dimensoes": { "ComprLiq": 3.10, "AltLiq": 1.85, "QtdLiqM2": 5.735 },
      "txtStatusChapa": "Em estoque",
      "Reservado": false
    }
  ]
}
```

A mesma consulta com o kit em Node.js:

```js
import { GransoftClient } from "./gransoft-client.js";

const gs = new GransoftClient({
  userHash: process.env.GRANSOFT_USERHASH,
  servidor: process.env.GRANSOFT_SERVIDOR, // ex.: https://www.server1.gransoftweb.com
});

const r = await gs.chamar("ListaEstoqueChapas", {
  Search: { Keyword: "branco", Status: 0, Reserva: 0, MaxResult: 50 },
});
console.log(r.Chapas.length, "chapas");
```

## 3. Regras que valem para todos os métodos

| Regra | Detalhe |
|---|---|
| Método HTTP | `POST {Servidor}/API/{Metodo}` com corpo JSON (`Content-Type: application/json`). |
| `userHash` | **No corpo JSON**, no campo `userHash`. Exceção: `ObterLista` lê o `userHash` da query string. Não use o header `Authorization`: os métodos de vendas o ignoram. |
| Erros | A API responde **HTTP 200 mesmo quando falha**. Sempre verifique o campo `Erro` antes de usar os dados. |
| Limite | **50 requisições por minuto** por usuário. Acima disso, `Erro` volta com "Limite de requisições excedido". |
| Datas | Vêm como texto `"/Date(1731283200000)/"` (milissegundos desde 1970). Converta antes de usar. |
| Enums | Vêm e vão como **número** (ex.: `"Acao": 1`, `"Status": 0`). |
| Servidor | Leia o `Servidor` da autenticação. Não fixe o endereço no código: ele muda de uma empresa para outra. |

Detalhes em [Convenções](convencoes.md).

## 4. Próximos passos

- [Consultar estoque de chapas](guias/consultar-estoque-chapas.md)
- [Consultar clientes](guias/consultar-clientes.md)
- [Criar orçamento](guias/criar-orcamento.md)
- [Kit em Node.js](kit/README.md)
- [Referência: Swagger e catálogo de métodos](referencia.md)