Convenções da API v2 do SULTS

API v2 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: Os caminhos são padronizados por ação: /list para listagens, /add para criação, /edit para edição.

​

Cabeçalhos

​

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.

​

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.

​

Registros e IDs

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

​

Próximos passos