> ## Documentation Index
> Fetch the complete documentation index at: https://developers.sults.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Como a API funciona

> Os conceitos que valem para qualquer versão da API do SULTS: REST sobre HTTPS, respostas em JSON, token no header e paginação nas listagens

A API do SULTS é REST sobre HTTPS e responde em JSON. Você chama os endpoints a partir do seu backend, e qualquer linguagem capaz de fazer uma requisição HTTP serve. Não existe SDK obrigatório.

Esta página explica o que vale para as duas versões. O que muda entre elas está em [Qual versão eu uso?](/geral/qual-versao-eu-uso).

## O SULTS tem API?

Cada chamada carrega o seu token no header `Authorization`. A API valida o token, executa a operação e devolve JSON.

```bash theme={"theme":{"light":"github-dark","dark":"github-dark"}}
curl https://api.sults.com.br/v1/empresas \
  -H "Authorization: SEU_TOKEN"
```

A resposta traz as unidades da sua rede:

```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
  "data": [
    {
      "id": 1,
      "razaoSocial": "SULTS Tecnologia LTDA",
      "nomeFantasia": "Sabor Mineiro Savassi",
      "cnpj": "12345678000190"
    }
  ],
  "start": 0,
  "limit": 100,
  "totalPage": 3,
  "size": 1
}
```

## A API é stateless

Não existe login, sessão ou refresh token. O token é validado a cada requisição, e é a única coisa que identifica a sua integração. Isso simplifica o seu código: basta montar o header e chamar.

## Como autenticar na API do SULTS?

O token nasce dentro do SULTS, criado por um usuário administrador em **Segurança > API > Gestão de Tokens**. Essa tela tem duas gestões separadas, uma para cada versão da API, e os tokens não são intercambiáveis.

Um detalhe custa muitos 401 para quem vem de outras APIs: o valor do header é o token puro. Não escreva `Bearer` antes dele.

Os detalhes estão em [Autenticação](/geral/autenticacao).

## Como paginar as listagens?

Nenhum endpoint de listagem devolve a base inteira de uma vez. Você percorre os registros página a página até chegar ao fim.

Os nomes dos parâmetros mudam conforme a versão, e o formato exato de cada uma está nas convenções da versão que você usa: [v1](/v1/convencoes) ou [v2](/v2/convencoes).

## Qual é o limite de requisições?

A API aplica um limite de 2 requisições por segundo, por IP. Ao exceder, a resposta é `429`. Em varreduras grandes isso importa mais do que parece, e o tratamento correto está em [Limites de requisição](/geral/limites).

## O que a API do SULTS não faz?

Vale saber antes de desenhar a sua integração:

* **Sem sandbox**: não existe ambiente de testes separado. As chamadas atingem os dados reais da sua operação.
* **Sem webhooks**: a API não avisa quando algo muda. Para reagir a mudanças, use polling.
* **Sem escrita de unidades e colaboradores**: esses dados são lidos pela API, nunca gravados por ela.

## Próximos passos

<CardGroup cols={2}>
  <Card title="Qual versão eu uso?" icon="git-compare" href="/geral/qual-versao-eu-uso">
    A comparação lado a lado antes de escolher.
  </Card>

  <Card title="Autenticação" icon="key" href="/geral/autenticacao">
    Como o token funciona e onde gerar o seu.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.