> ## 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 v2 do SULTS

> Gere o token da v2, liste os produtos do módulo de Compras e confirme a primeira resposta, com exemplos em cinco linguagens

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

Em cinco minutos você gera o token da v2, faz a primeira chamada e vê os produtos do seu catálogo 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 v2

Na plataforma, vá em **Segurança > API > Gestão de Tokens v2** e crie um token.

<Warning>
  O token da v2 é exibido **uma única vez**, na criação. Copie na hora e guarde em local seguro. Um token da gestão v1 recebe `401` nos endpoints desta versão.
</Warning>

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

## Passo 2: liste os produtos do catálogo

`GET /api/v2/compras/product/list` devolve os produtos cadastrados. É uma chamada leve e sem efeito colateral.

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/api/v2/compras/product/list?page=0&active=true" \
    -H "Authorization: SEU_TOKEN"
  ```

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

  resposta = requests.get(
      "https://api.sults.com.br/api/v2/compras/product/list",
      headers={"Authorization": "SEU_TOKEN"},
      params={"page": 0, "active": True},
  )
  resposta.raise_for_status()

  for produto in resposta.json():
      print(produto["id"], produto["name"])
  ```

  ```javascript Node theme={"theme":{"light":"github-dark","dark":"github-dark"}}
  const url = new URL("https://api.sults.com.br/api/v2/compras/product/list");
  url.searchParams.set("page", "0");
  url.searchParams.set("active", "true");

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

  const produtos = await resposta.json();
  produtos.forEach((p) => console.log(p.id, p.name));
  ```

  ```php PHP theme={"theme":{"light":"github-dark","dark":"github-dark"}}
  <?php
  $url = "https://api.sults.com.br/api/v2/compras/product/list?page=0&active=true";

  $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 $produto) {
      echo $produto["id"] . " " . $produto["name"] . 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/api/v2/compras/product/list?page=0&active=true");

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

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

## Passo 3: confira a resposta

Você deve receber `200` e um array com os produtos do seu catálogo:

```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
[
  {
    "id": 1,
    "name": "Café Aurora Torrado 250g",
    "barcode": 1223334,
    "referenceCode": "1a2b3c4d",
    "category": { "id": 1, "name": "Cafés especiais" },
    "supplier": { "id": 5, "name": "Aurora Distribuidora", "active": true },
    "saleableDate": "2027-01-01",
    "inventoryScope": "ON_PRODUCT",
    "active": true
  }
]
```

Se apareceu o `name` de pelo menos um produto seu, a integração está autenticada e funcionando.

Repare que a v2 devolve um **array direto**, sem envelope. Quem vem da v1 costuma tropeçar aqui, porque lá a listagem vem dentro de `data`.

## 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 v2**, não na v1.

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

## Próximos passos

<CardGroup cols={3}>
  <Card title="Convenções" icon="ruler" href="/v2/convencoes">
    Paginação por `page`, datas e o formato das listagens.
  </Card>

  <Card title="Mantenha os dados atualizados" icon="refresh-cw" href="/v2/convencoes#como-manter-os-dados-atualizados">
    O padrão de polling para manter o seu ERP atualizado.
  </Card>

  <Card title="Referência da API" icon="code" href="/v2/api-reference/produtos/listar-produtos">
    Os 45 endpoints da v2, com playground.
  </Card>
</CardGroup>


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