Antes de começar

Autenticação

Cadastre uma aplicação na loja e gere o token de acesso conforme Autenticação. A URL base e os headers obrigatórios (Authorization e x-api-version) estão em Visão geral e Convenções e erros.

📘
Identificação da loja
Você não informa a loja em nenhum endpoint: ela é sempre a loja à qual o token pertence. Da mesma forma, o autor das alterações registrado no histórico vem do token: para aplicações, é o client_id. Nenhum endpoint pede o usuário no corpo.

Permissões

O perfil de acesso da aplicação precisa ter as permissões abaixo no módulo de Promoções:

Permissão	Nível	Libera
Cadastro de promoções	Visualização	Todos os `GET` (exceto o histórico de alterações), a busca de clientes e a consulta de permissão de divulgação.
Cadastro de promoções	Visualização e edição	Criar, atualizar, duplicar e excluir promoções; consultar o histórico de alterações.
Ativação de promoções	Visualização e edição	Ativar e inativar promoções (`PUT …/status`).

Sem a permissão exigida, a resposta é 401 com code UNAUTHORIZED. Para usar os endpoints de catálogo indicados em Onde obter os IDs (categorias, produtos, marcas etc.), a aplicação também precisa de permissão de leitura nesses módulos.

Convenções

JSON em camelCase. Na entrada, os nomes de campos não diferenciam maiúsculas de minúsculas.
Enumerações são enviadas e retornadas como números (ex.: "accumulationScope": 2).
Datas em ISO 8601. Prefira informar o fuso: 2026-11-27T00:00:00-03:00. Datas sem fuso são interpretadas no horário de Brasília (America/Sao_Paulo).
Valores de argumentos de condições e descontos são sempre strings, mesmo quando representam números ou booleanos: "values": ["10.5"], "values": ["true"].
Argumentos numéricos e booleanos (dataType Int, Long, Decimal ou Boolean) recebem um único valor, sem vírgula. Decimais usam ponto e não levam separador de milhar: "1199.90". Vírgula ou mais de um valor resultam em 400 (MISSING_ARGUMENTS). Argumentos de lista (ListInt, ListLong, ListString) recebem um ID por item de values.
Arrays em query string: repita a chave — ?conditions=3&conditions=18.

Respostas e erros

Use o status HTTP para saber se a operação deu certo: 2xx é sucesso, 4xx e 5xx são falhas com o corpo de erro descrito abaixo.

Sucesso

Formato	Exemplo	Usado em
Envelope `data`	`{ "data": { ... } }`	Obter, criar, atualizar, ativar/inativar, duplicar e excluir promoções; estruturas; faixa de valores; permissão de divulgação.
Listagem de promoções	`{ "data": [...], "total": 42, "page": 1, "limit": 10 }`	Listar promoções.
Listagem de apoio	`{ "data": [...], "total": 10, "totalGeneral": 50, "page": 1, "limit": 10 }`	Clientes, categorias, estados, cidades, histórico.

Criar e duplicar respondem 201 com o header Location: /api/promotions/{promotionId} da nova promoção.

Erro

Toda falha nas rotas /api/promotions/* (com o header x-api-version: 2.0) usa o mesmo corpo. Exemplo de campo inválido:

{
  "code": "VALIDATION_FAILED",
  "displayMessage": "Falha na validação!",
  "details": [
    { "field": "disclosure[0].title", "code": "VALIDATION_FAILED", "issue": "Título da divulgação não pode ultrapassar 50 caracteres." }
  ],
  "traceId": "0HN7…:00000001"
}

Erros de formato (campos, tipos, limites de texto) são conferidos antes das regras de negócio e não aparecem junto delas. As regras recusadas em criar e atualizar vêm com displayMessage “A promoção não pôde ser salva”, sem field (veja o exemplo em Criar promoção).

Campo	Descrição
`code`	Categoria da falha, derivada do status (tabela abaixo).
`displayMessage`	Mensagem em português que pode ser exibida ao usuário.
`details`	Lista de problemas encontrados. Omitido quando não há detalhes. Cada item tem `code` (veja Códigos de erro), `issue` (o motivo) e, quando o problema é de um campo específico, `field` (caminho em camelCase, ex.: `disclosure[0].title`).
`traceId`	Identificador da requisição. Informe-o ao suporte.

Status	`code`	Quando acontece
`400`	`VALIDATION_FAILED`	Corpo ou parâmetros inválidos (inclusive JSON malformado e tipos errados) ou regra de negócio recusada. Os motivos vêm em `details`.
`400`	`API_VERSION_REQUIRED`	Chamada de aplicação sem o header `x-api-version`. Este corpo não traz `traceId`.
`401`	`SESSION_INVALID`	Token ausente, inválido ou expirado; aplicação não encontrada ou sem acesso à loja.
`401`	`UNAUTHORIZED`	O token não tem a permissão exigida pelo endpoint.
`404`	`NOT_FOUND`	Promoção não encontrada ou excluída.
`409`	`CONFLICT`	Conflito com o estado atual, ex.: nome já usado por outra promoção ao duplicar.
`500`	`INTERNAL_ERROR`	Erro inesperado. Tente de novo; se persistir, contate o suporte com o `traceId`.

📘
Escopo destes formatos
Os formatos de sucesso e de erro acima valem para as rotas /api/promotions/*. Os endpoints de catálogo citados em Onde obter os IDs e o endpoint de autenticação seguem os formatos documentados em suas próprias páginas.