Conceitos

Envelope de resposta, erros, datas, JSONP, saídas de arquivo e multi-tenancy na API Consultiva.

Convenções transversais a todos os endpoints da API Consultiva. Para credenciais veja Autenticação; para paginação, janela de período e limites veja Paginação e limites.

Envelope de resposta

Os formatos de sucesso mais comuns:

Lista — o corpo é o próprio array ([...]).
Objeto — alguns endpoints retornam um objeto (ex.: saldos).
Paginado — { "currentPage", "totalPages", "totalItems", "perPage", "data": [...] }.

Erros

Os endpoints de integração (/integracoes/*) usam um envelope de erro padrão, normalmente com HTTP 400:

{ "error": "DATA_INVALIDA", "error_info": "O campo \"data\" contém uma data inválida. Utilize o formato AAAA-MM-DD (ex.: 2026-06-30)." }

O campo error traz um código estável (use-o para tratar erros no seu sistema) e error_info traz a mensagem legível. Códigos possíveis:

Código	Quando ocorre
`EMPRESA_NAO_ENCONTRADA`	`cnpj`/`empresa` não localizados
`DATA_INVALIDA`	data fora do formato `AAAA-MM-DD` ou inexistente no calendário
`PERIODO_OBRIGATORIO`	`inicio_periodo`/`fim_periodo` ausentes
`PERIODO_INVALIDO`	período inconsistente (ex.: início posterior ao fim)
`PERIODO_EXCEDE_LIMITE`	intervalo acima de 180 dias
`PAGINACAO_INVALIDA`	`perPage` fora de 1–100
`TIPO_PERIODO_INVALIDO`	`tipo_periodo` não reconhecido
`ID_INVALIDO`	identificador inválido
`PARAMETRO_INVALIDO`	parâmetro ausente ou inválido (ex.: `ativo_inativo` fora do conjunto aceito)
`ERRO_INTERNO`	falha ao processar (ex.: acesso via API não contratado)

Token ausente ou inválido resulta em 401 com corpo { "error": "Unauthenticated." }.

Exceção: produtos/estoque (rota legada)

A rota legada GET /produto/estoque/busca usa um formato de erro diferente: { "message": "..." } (HTTP 400). A versão padronizada GET /integracoes/produto/estoque/busca já usa o envelope { "error", "error_info" } acima.

Datas

Salvo indicação em contrário, parâmetros de data usam YYYY-MM-DD (ex.: 2026-06-01). Datas inválidas retornam DATA_INVALIDA. Nas respostas, o formato pode variar entre YYYY-MM-DD, YYYY-MM-DD HH:mm e DD/MM/YYYY conforme o endpoint — confira o exemplo de cada um.

JSONP

Endpoints que usam o helper success() aceitam o parâmetro callback na query string. Quando presente, a resposta é envolvida como JSONP (callback({...})); sem ele, é JSON puro.

Saídas de arquivo

Alguns relatórios de vendas aceitam saida=csv (e alguns saida=xls) e respondem com download (text/csv ou .xlsx) em vez de JSON. O endpoint produtos-vendidos-periodo sempre retorna uma planilha .xlsx.

Multi-tenancy

O ssOtica é multi-tenant: Rede › Empresa › Filial. A empresa-alvo é resolvida por cnpj e/ou empresa (Código da Licença), sempre dentro da rede do usuário autenticado. A empresa precisa ter acesso via API contratado — caso contrário a resposta é ERRO_INTERNO ("Acesso via API não contratado...").

cnpj e/ou empresa

A maioria dos endpoints aceita cnpj e/ou empresa; informe ao menos um. Alguns relatórios aceitam apenas cnpj, e os relatórios "de toda a rede" (comissão e vendas por produto) não recebem nem cnpj nem empresa. A página de cada endpoint indica o comportamento exato.