> ## 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.
# Listar produtos na API v2 do SULTS
> Lista os produtos cadastrados na plataforma do SULTS. Por padrão, somente produtos **ativos** são retornados.
## OpenAPI
````yaml /api-reference/openapi-v2.json get /api/v2/compras/product/list
openapi: 3.1.0
info:
title: API do SULTS v2
version: '2.0'
description: >-
A nova geração da API do SULTS, em migração módulo a módulo (Compras
primeiro). Autenticação por token v2 no cabeçalho `Authorization`; tokens v1
não funcionam aqui. Nas requisições com corpo, envie `Content-Type:
application/json;charset=UTF-8`.
contact:
name: Suporte SULTS
url: https://ajuda.sults.com.br
servers:
- url: https://api.sults.com.br
security:
- apiKeyAuth: []
tags:
- name: Produtos
description: >-
Cadastro, preço, estoque, variações e variantes de produto no módulo de
Compras da v2. A API do SULTS é REST sobre HTTPS e responde em JSON. Cada
requisição leva o token no cabeçalho `Authorization`, enviado puro, sem o
prefixo `Bearer`. O token é gerado por um administrador na plataforma, em
Segurança > API > Gestão de Tokens v2. O limite é de 2 requisições por
segundo, por IP.
- name: Mix de produtos
description: >-
Sortimento de produtos por empresa. Disponível apenas quando o recurso de
mix está habilitado na plataforma, em Comercial > Configuração > Mix de
produto. A API do SULTS é REST sobre HTTPS e responde em JSON. Cada
requisição leva o token no cabeçalho `Authorization`, enviado puro, sem o
prefixo `Bearer`. O token é gerado por um administrador na plataforma, em
Segurança > API > Gestão de Tokens v2. O limite é de 2 requisições por
segundo, por IP.
- name: Pedidos e etapas
description: >-
Pedidos de compra da v2 e o fluxo de etapas, que é configurável por
operação. A API do SULTS é REST sobre HTTPS e responde em JSON. Cada
requisição leva o token no cabeçalho `Authorization`, enviado puro, sem o
prefixo `Bearer`. O token é gerado por um administrador na plataforma, em
Segurança > API > Gestão de Tokens v2. O limite é de 2 requisições por
segundo, por IP.
- name: Comunicados
description: >-
Comunicados publicados na plataforma, com o público de cada um, a
confirmação de leitura e o conteúdo publicado. A API do SULTS é REST sobre
HTTPS e responde em JSON. Cada requisição leva o token no cabeçalho
`Authorization`, enviado puro, sem o prefixo `Bearer`. O token é gerado
por um administrador na plataforma, em Segurança > API > Gestão de Tokens
v2. O limite é de 2 requisições por segundo, por IP.
- name: Chamados
description: >-
Chamados da plataforma: abertura, timeline, interações, apoios, etiquetas,
prazo e conclusão. A API do SULTS é REST sobre HTTPS e responde em JSON.
Cada requisição leva o token no cabeçalho `Authorization`, enviado puro,
sem o prefixo `Bearer`. O token é gerado por um administrador na
plataforma, em Segurança > API > Gestão de Tokens v2. O limite é de 2
requisições por segundo, por IP.
- name: Checklist
description: >-
Avaliações de checklist com respostas, check-in e check-out, os modelos
com seções e questões, e os planos de ação com a timeline. A API do SULTS
é REST sobre HTTPS e responde em JSON. Cada requisição leva o token no
cabeçalho `Authorization`, enviado puro, sem o prefixo `Bearer`. O token é
gerado por um administrador na plataforma, em Segurança > API > Gestão de
Tokens v2. O limite é de 2 requisições por segundo, por IP.
paths:
/api/v2/compras/product/list:
get:
tags:
- Produtos
summary: Listar produtos
description: >-
Lista os produtos cadastrados na plataforma do SULTS. Por padrão,
somente produtos **ativos** são retornados.
operationId: listarProdutosV2
parameters:
- name: id
in: query
schema:
type: integer
description: Código do produto.
example: 1
- name: referenceCode
in: query
schema:
type: string
description: Código externo do produto (referência do sistema do cliente).
example: ERP-4471
- name: barcode
in: query
schema:
type: integer
description: Código de barras do produto.
example: 7891234567890
- name: active
in: query
schema:
type: boolean
default: true
description: '`true` (padrão): produtos ativos. `false`: produtos inativos.'
example: true
- name: categoryId
in: query
schema:
type: integer
description: Código da categoria do produto.
example: 3
- name: supplierId
in: query
schema:
type: integer
description: Código do fornecedor do produto.
example: 5
- name: saleableAfter
in: query
schema:
type: string
description: 'Produtos publicados a partir desta data. Exemplo: `2027-05-29`.'
example: '2026-07-01'
- name: saleableBefore
in: query
schema:
type: string
description: 'Produtos publicados antes desta data. Exemplo: `2027-05-29`.'
example: '2026-07-31'
- $ref: '#/components/parameters/Page'
responses:
'200':
description: Lista de produtos.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ProdutoV2'
example:
- id: 1
name: Café Aurora Torrado 250g
barcode: 1223334
referenceCode: 1a2b3c4d
category:
id: 1
name: Cafés especiais
supplier:
id: 5
name: Aurora Distribuidora
legalName: Aurora Distribuidora Ltda
active: true
saleableDate: '2027-01-01'
inventoryScope: ON_PRODUCT
active: true
variation:
- id: 8
name: Moagem
active: true
index: 0
option:
- id: 18
name: Grãos
active: true
index: 0
- id: 19
name: Moído
active: true
index: 1
image:
- id: 1
name: cafe-aurora.png
url: https://link/cafe-aurora.png
fileLength: 615324
shortDescription: Café torrado especial Aurora
htmlDescription: Café torrado especial Aurora
'400':
$ref: '#/components/responses/ErroValidacao'
'401':
$ref: '#/components/responses/TokenInvalido'
'404':
$ref: '#/components/responses/NaoEncontrado'
'429':
$ref: '#/components/responses/LimiteDeRequisicoes'
5XX:
$ref: '#/components/responses/ErroDoServidor'
components:
parameters:
Page:
name: page
in: query
description: >-
Número da página da listagem, começando em `0`. Incremente até a
resposta vir vazia.
schema:
type: integer
minimum: 0
default: 0
example: 0
schemas:
ProdutoV2:
type: object
properties:
id:
type: integer
description: Código do produto.
example: 1
name:
type: string
description: Nome do produto.
example: Café Especial 500 g
barcode:
type: integer
description: Código de barras do produto.
example: 7891234567890
referenceCode:
type: string
description: >-
Código do produto no sistema externo (código de referência do
cliente).
example: ERP-4471
category:
$ref: '#/components/schemas/CategoriaProdutoV2'
description: Categoria do produto.
supplier:
$ref: '#/components/schemas/FornecedorProdutoV2'
description: Fornecedor do produto.
saleableDate:
type: string
description: >-
Data em que o produto fica disponível para compra. Formato
`yyyy-MM-dd`.
example: '2026-07-01'
inventoryScope:
type: string
description: >-
Escopo do controle de estoque: define em que nível o saldo é
mantido.
| Valor | O estoque é controlado por |
| ----- | -------------------------- |
| ON_PRODUCT | Produto |
| ON_VARIANT | Variante do produto |
| ON_PRODUCT_ASSORTMENT | Mix |
| ON_PRODUCT_ASSORTMENT_VARIANT | Mix e variante |
enum:
- ON_PRODUCT
- ON_VARIANT
- ON_PRODUCT_ASSORTMENT
- ON_PRODUCT_ASSORTMENT_VARIANT
example: ON_PRODUCT
active:
type: boolean
description: '`true`: produto ativo.'
example: true
variation:
type:
- array
- 'null'
description: Variações do produto e suas opções.
items:
$ref: '#/components/schemas/VariacaoProdutoV2'
image:
type: array
description: Imagens do produto.
items:
$ref: '#/components/schemas/ImagemProdutoV2'
shortDescription:
type: string
description: Descrição curta do produto.
example: Café torrado e moído, pacote de 500 g
htmlDescription:
type: string
description: Descrição completa em HTML.
example: Café torrado e moído, pacote de 500 g.
CategoriaProdutoV2:
type: object
properties:
id:
type: integer
description: Código da categoria.
example: 1
name:
type: string
description: Nome da categoria.
example: Café Especial 500 g
FornecedorProdutoV2:
type: object
properties:
id:
type: integer
description: Código do fornecedor.
example: 1
name:
type: string
description: Nome fantasia do fornecedor.
example: Café Especial 500 g
legalName:
type: string
description: Razão social do fornecedor.
example: SULTS Tecnologia LTDA
active:
type: boolean
description: '`true`: fornecedor ativo.'
example: true
VariacaoProdutoV2:
type: object
properties:
id:
type: integer
description: Código da variação.
example: 1
name:
type: string
description: Nome da variação (por exemplo, Sabor ou Tamanho).
example: Café Especial 500 g
active:
type: boolean
description: '`true`: variação ativa.'
example: true
index:
type: integer
description: Posição de exibição da variação.
example: 0
option:
type: array
description: Opções da variação.
items:
$ref: '#/components/schemas/VariacaoOpcaoV2'
ImagemProdutoV2:
type: object
properties:
id:
type: integer
description: Código da imagem.
example: 1
name:
type: string
description: Nome do arquivo.
example: Café Especial 500 g
url:
type: string
description: URL pública da imagem.
example: https://api.sults.com.br
fileLength:
type: integer
description: Tamanho do arquivo em bytes.
example: 1
Erro:
type: object
description: >-
Corpo padrão de erro da API. Não existe código de erro interno: decida a
sua lógica pelo status HTTP e use a mensagem apenas para logs e
diagnóstico.
required:
- error
properties:
error:
type: string
description: >-
Mensagem legível, em português, descrevendo a falha. O texto pode
mudar: nunca o use como condição de código.
example: Campo supplierId não pode ser vazio ou nulo.
VariacaoOpcaoV2:
type: object
properties:
id:
type: integer
description: Código da opção.
example: 1
name:
type: string
description: Nome da opção (por exemplo, um sabor ou tamanho).
example: Café Especial 500 g
active:
type: boolean
description: '`true`: opção ativa.'
example: true
index:
type: integer
description: Posição de exibição da opção.
example: 0
responses:
ErroValidacao:
description: >-
Erro de validação ou formato errado nos dados de entrada. A API aponta
**um campo por vez**: corrija o campo indicado na mensagem, reenvie e
repita até o 200.
content:
application/json:
schema:
$ref: '#/components/schemas/Erro'
example:
error: Campo supplierId não pode ser vazio ou nulo.
TokenInvalido:
description: >-
Token ausente ou inválido. Confira: copiado por completo, cabeçalho
`Authorization` com o nome exato, valor sem o prefixo `Bearer` e gerado
na **Gestão de Tokens v2** (tokens v1 não funcionam aqui). Sem retry
automático. O corpo real é `{"error": "Acesso não autorizado."}`.
content:
application/json:
schema:
$ref: '#/components/schemas/Erro'
example:
error: Acesso não autorizado.
NaoEncontrado:
description: >-
Recurso inexistente, ou recurso condicionado desabilitado (por exemplo,
endpoints de Mix sem o recurso de mix habilitado na operação). Reenviar
sem corrigir devolve o mesmo erro.
content:
application/json:
schema:
$ref: '#/components/schemas/Erro'
LimiteDeRequisicoes:
description: >-
Limite de requisições excedido: **2 requisições por segundo, por IP**. A
resposta é a página HTML padrão do servidor, não JSON, e não há o header
`Retry-After`: trate pelo status 429, sem fazer parse do corpo, com
espera crescente a partir de 1 segundo.
content:
text/html:
schema:
type: string
description: >-
Página HTML padrão do servidor. Não faça parse; decida pelo
status.
ErroDoServidor:
description: >-
Falha inesperada do servidor (raro). Repita com espera crescente;
persistindo, acione o suporte com data, hora e endpoint.
content:
application/json:
schema:
$ref: '#/components/schemas/Erro'
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: Authorization
description: >-
Token gerado na Gestão de Tokens v2 do SULTS. Deve ser enviado no
cabeçalho `Authorization` de todas as requisições.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.