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

# Convenções da API v2 do SULTS

> As regras que valem para toda a API v2: URL base, formato JSON, datas, paginação por página e limites de requisição

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

Esta página reúne as convenções que valem para **todos os endpoints da v2**. Aprenda uma vez, use em qualquer chamada.

## URL base

Os endpoints da v2 respondem em `https://api.sults.com.br/api/v2`, com uma base própria por módulo:

| Módulo | Base | Exemplo |
| - | - | - |
| Compras | `https://api.sults.com.br/api/v2/compras` | `GET /api/v2/compras/product/list` |
| Comunicados | `https://api.sults.com.br/api/v2/comunicado` | `GET /api/v2/comunicado/announcement/list` |
| Chamados | `https://api.sults.com.br/api/v2/chamados` | `GET /api/v2/chamados/ticket/list` |
| Checklist | `https://api.sults.com.br/api/v2/checklist` | `GET /api/v2/checklist/assessment/list` |

Os caminhos são padronizados por ação: `/list` para listagens, `/add` para criação, `/edit` para edição.

## Cabeçalhos

| Cabeçalho | Valor | Obrigatório |
| - | - | - |
| `Authorization` | [Token v2](/v2/criar-token) | Sim, em todas as requisições |
| `Content-Type` | `application/json;charset=UTF-8` | Nas requisições com corpo (POST e PUT) |

## Datas

Campos de data usam `yyyy-MM-dd` (por exemplo, `saleableDate` e `restockDate`). Campos de carimbo de tempo, como `createdAt` e `concludedAt`, usam **UTC ISO 8601** (`2026-05-20T02:37:52Z`). Gere e compare sempre em UTC.

## Máscaras

Campos com máscara vêm **sem máscara**, apenas dígitos: CNPJ `99999999999999`, CEP `99999999`.

## Paginação

As listagens são paginadas pelo parâmetro `page`, que **inicia em 0**, e a resposta vem como **array direto, sem envelope**. Para varrer tudo, incremente `page` até a resposta vir vazia.

## Limites de requisição

O limite é de **2 requisições por segundo, por IP**, e vale igual nas duas versões da API. O tratamento correto, com backoff exponencial e o ritmo das varreduras, está em [Limites de requisição](/geral/limites).

## Como manter os dados atualizados

A API **não oferece webhooks**, e as listagens de Compras, Comunicados e Checklist não têm filtro por data de alteração. O caminho é a varredura completa, que é leve para catálogos de milhares de registros:

1. Percorra a listagem com `page` desde 0 até a resposta vir vazia, com cerca de 500 ms entre as páginas.
2. Compare cada registro com a sua cópia e grave criando ou atualizando. Produtos se identificam pelo `id` (ou pelo `referenceCode`, se o cadastro nasce no seu sistema); preço e estoque, pela combinação `productId` + `supplierId` + `variantId` + `productAssortmentId`.
3. Preço e estoque são consultados por produto: `product/price/list` e `product/stock/list` exigem `productId` e `supplierId`.
4. Para pedidos, consulte os abertos (`status=OPEN`) com frequência e varra os encerrados com frequência menor.

Duas a quatro varreduras por dia bastam para o catálogo; pedidos abertos podem ser consultados a cada poucos minutos.

Chamados é a exceção: a listagem aceita `lastUpdatedAfter`. Guarde a data da última consulta e peça só os chamados atualizados desde então. Informe também `status` com todas as situações, porque sem esse filtro a resposta traz só os chamados em aberto.

## Permissões do token

O token da v2 acessa todos os endpoints da versão. O controle de permissão por token está no roadmap, sem data definida; veja [Autenticação](/v2/autenticacao).

## Registros e IDs

Vários endpoints da v2 recebem identificadores criados na plataforma. Onde obter cada um:

| ID | Onde encontrar |
| - | - |
| `categoryId` | **Comercial > Configuração > Categoria** |
| `supplierId` | **Comercial > Fornecedor** |
| Mix (`productAssortmentId`) | **Comercial > Configuração > Mix de produto** (é aqui também que o recurso de Mix é habilitado) |
| Etapas (`stageId`) | Pelo próprio endpoint de listagem de etapas, que retorna código, nome, cor e posição |
| `companyId` | É o código da unidade no SULTS, o mesmo `id` da listagem de unidades da API v1 |
| `variantId` | Pelo endpoint de listagem de variantes do produto |
| Modelo de checklist (`templateId`) | Pelo endpoint de listagem de modelos de checklist; as seções (`sectionId`) e as questões (`questionId`) vêm nos endpoints de seções e de questões do modelo |

<Tip>
  Alternativa universal: os objetos aninhados das próprias listagens (produto, pedido, mix, chamado, avaliação) trazem os IDs de tudo que se relaciona com eles. Uma listagem bem filtrada costuma revelar o código que você procura.
</Tip>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Erros" icon="triangle-alert" href="/v2/erros">
    O catálogo de falhas e como tratar cada uma.
  </Card>

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


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