Guias
Conceitos
Formato das respostas, erros, datas e identificação da loja na API Consultiva.
Formato das respostas
- Lista: o corpo da resposta é a própria lista (
[...]). - Objeto: alguns endpoints retornam um objeto (por exemplo, saldos).
- Paginado:
{ "currentPage", "totalPages", "totalItems", "perPage", "data": [...] }. Consulte Paginação e limites.
Erros
Os erros de parâmetro retornam HTTP 400 no seguinte formato:
{ "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 fixo, indicado para o tratamento do erro na sua integração. O campo
error_info descreve o motivo.
| Código | Situação |
|---|---|
EMPRESA_NAO_ENCONTRADA | cnpj ou empresa não localizados na rede |
API_NAO_CONTRATADA | a loja não possui a API em contrato |
CONTRATO_ILEGIVEL | falha temporária na verificação do contrato; repita a requisição |
DATA_INVALIDA | data fora do formato AAAA-MM-DD ou inexistente |
PERIODO_OBRIGATORIO | inicio_periodo ou fim_periodo não informado |
PERIODO_INVALIDO | data inicial posterior à data final |
PERIODO_EXCEDE_LIMITE | intervalo superior a 180 dias |
PAGINACAO_INVALIDA | perPage fora do intervalo de 1 a 100 |
TIPO_PERIODO_INVALIDO | tipo_periodo não reconhecido |
ID_INVALIDO | identificador inválido |
PARAMETRO_INVALIDO | outro parâmetro ausente ou inválido |
ERRO_INTERNO | falha inesperada no processamento |
Outras respostas possíveis:
401com o textoUnauthorized.(fora do formato JSON): chave de acesso ausente ou inválida. Consulte Autenticação.429: limite de 60 requisições por minuto da loja excedido. Consulte Paginação e limites.
Datas
Os parâmetros de data seguem o formato AAAA-MM-DD (por exemplo, 2026-06-01). Nas respostas, o
formato varia conforme o endpoint (AAAA-MM-DD, AAAA-MM-DD HH:mm ou DD/MM/AAAA); consulte o exemplo
de resposta de cada um.
Identificação da loja
Cada requisição consulta uma loja, identificada por cnpj ou empresa (Código da Licença),
sempre dentro da rede do usuário vinculado à chave. Há duas exceções:
- alguns relatórios de vendedores aceitam somente
cnpj; - os relatórios de toda a rede (comissão e vendas por produto) não recebem
cnpjnemempresa.
A página de cada endpoint informa os parâmetros aceitos.
Outros formatos de resposta
- Arquivo: alguns relatórios de vendas aceitam
saida=csv(e alguns tambémsaida=xls) e retornam um arquivo em vez de JSON. O relatório de produtos vendidos retorna sempre uma planilha.xlsx. - JSONP: diversos endpoints aceitam o parâmetro
callback; quando informado, a resposta é retornada no formatocallback({...}).