> ## 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.

# Quickstart da API v1 do SULTS

> Gere o token da v1, liste as unidades da sua rede e confirme a primeira resposta da API do SULTS, com exemplos em cinco linguagens

<span className="badge-v1">API v1</span>

Em cinco minutos você gera o token, faz a primeira chamada e vê as unidades da sua rede em JSON.

## Pré-requisitos

* Conta no SULTS com permissão de **administrador**, necessária para gerar o token.
* Um terminal com `curl`, ou o seu editor com a linguagem de preferência.

## Passo 1: gere o token da v1

Na plataforma, vá em **Segurança > API > Gestão de Tokens v1** e crie um token. Copie o valor gerado e guarde em local seguro.

<Warning>
  Use a **Gestão de Tokens v1**. Um token criado na gestão v2 recebe `401` nos endpoints desta versão.
</Warning>

O passo a passo com prints está em [Crie seu token](/v1/criar-token).

## Passo 2: liste as unidades da sua rede

`GET /v1/empresas` devolve as unidades cadastradas. É uma chamada leve e sem efeito colateral, boa para a primeira tentativa.

Troque `SEU_TOKEN` pelo token que você acabou de gerar.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-dark","dark":"github-dark"}}
  curl "https://api.sults.com.br/v1/empresas?start=0&limit=100" \
    -H "Authorization: SEU_TOKEN"
  ```

  ```python Python theme={"theme":{"light":"github-dark","dark":"github-dark"}}
  import requests

  resposta = requests.get(
      "https://api.sults.com.br/v1/empresas",
      headers={"Authorization": "SEU_TOKEN"},
      params={"start": 0, "limit": 100},
  )
  resposta.raise_for_status()

  for unidade in resposta.json():
      print(unidade["id"], unidade["nomeFantasia"])
  ```

  ```javascript Node theme={"theme":{"light":"github-dark","dark":"github-dark"}}
  const url = new URL("https://api.sults.com.br/v1/empresas");
  url.searchParams.set("start", "0");
  url.searchParams.set("limit", "100");

  const resposta = await fetch(url, {
    headers: { Authorization: "SEU_TOKEN" },
  });
  if (!resposta.ok) throw new Error(`HTTP ${resposta.status}`);

  const unidades = await resposta.json();
  unidades.forEach((u) => console.log(u.id, u.nomeFantasia));
  ```

  ```php PHP theme={"theme":{"light":"github-dark","dark":"github-dark"}}
  <?php
  $url = "https://api.sults.com.br/v1/empresas?start=0&limit=100";

  $ch = curl_init($url);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: SEU_TOKEN"]);
  $resposta = curl_exec($ch);
  curl_close($ch);

  foreach (json_decode($resposta, true) as $unidade) {
      echo $unidade["id"] . " " . $unidade["nomeFantasia"] . PHP_EOL;
  }
  ```

  ```csharp C# theme={"theme":{"light":"github-dark","dark":"github-dark"}}
  using System.Net.Http;
  using System.Text.Json;

  var http = new HttpClient();
  http.DefaultRequestHeaders.Add("Authorization", "SEU_TOKEN");

  var json = await http.GetStringAsync(
      "https://api.sults.com.br/v1/empresas?start=0&limit=100");

  using var doc = JsonDocument.Parse(json);
  foreach (var unidade in doc.RootElement.EnumerateArray())
  {
      Console.WriteLine($"{unidade.GetProperty("id")} {unidade.GetProperty("nomeFantasia")}");
  }
  ```
</CodeGroup>

O token vai puro no header. Não escreva `Bearer` antes dele.

## Passo 3: confira a resposta

Você deve receber `200` e um JSON com as unidades da sua rede:

```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
[
  {
    "id": 1,
    "ativo": true,
    "razaoSocial": "SULTS Tecnologia LTDA",
    "nomeFantasia": "Sabor Mineiro Savassi",
    "cnpj": "12345678000190",
    "dtCadastro": "2026-07-15T14:32:08Z",
    "endereco": {
      "uf": "MG",
      "cidade": "Uberaba",
      "bairro": "Centro",
      "cep": "38026000"
    }
  }
]
```

Se apareceu o `nomeFantasia` de pelo menos uma unidade sua, a integração está autenticada e funcionando.

## Se algo der errado

A causa mais comum de falha na primeira chamada é o token. Confira, nesta ordem:

1. O token foi copiado por inteiro, sem espaço sobrando.
2. O header tem o nome exato `Authorization`.
3. O valor não tem o prefixo `Bearer`.
4. O token nasceu na **Gestão de Tokens v1**, não na v2.

Persistindo a falha, o corpo da resposta traz a mensagem. O catálogo completo está em [Erros](/v1/erros).

## Próximos passos

<CardGroup cols={3}>
  <Card title="Convenções" icon="ruler" href="/v1/convencoes">
    Paginação, datas em UTC e campos sem máscara.
  </Card>

  <Card title="Mantenha os dados atualizados" icon="refresh-cw" href="/v1/convencoes#como-manter-os-dados-atualizados">
    O padrão de polling incremental, página a página.
  </Card>

  <Card title="Referência da API" icon="code" href="/v1/api-reference/unidades/listar-unidades">
    Os endpoints dos 7 módulos, com playground.
  </Card>
</CardGroup>


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