Indústrias com divisões

Algumas contas de indústria são organizadas em divisões: unidades de negócio que dividem o cadastro da
empresa. Nessas contas, cada produto, tabela de preço, promoção e pedido pertence a uma divisão. O cliente é
o caso diferente: ele não pertence a uma divisão, ele é vinculado a uma ou mais divisões das quais pode
comprar.

A conta continua com um único par de tokens. Você não gera um token por divisão: a mesma
ApplicationToken + CompanyToken enxerga todas as divisões, e é a requisição que diz de qual divisão
você quer os dados.

Se a conta que você integra não trabalha com divisões, nada nesta página se aplica — o comportamento da
API é o de sempre.

O campo muda de nome conforme a conta

O identificador da unidade de negócio aparece no JSON com dois nomes diferentes, e o que decide é o tipo da conta:

Tipo de conta	Campo no JSON
Indústria com divisões	`divisao_id` / `divisoes_ids`
Demais contas	`representada_id` / `representadas_ids`

Isso vale nos três lugares: no corpo que você envia (POST/PUT), no corpo que a API devolve (GET) e no filtro
de consulta. Nos endpoints em que os dois nomes aparecem documentados, os exemplos estão separados por tipo de
conta — confira o seletor de exemplos de cada operação.

⚠️
Em uma conta que trabalha com divisões, enviar representada_id responde 412 pedindo que você use
divisao_id no lugar dele. Não existe período de compatibilidade entre os dois nomes: em cada conta vale
um deles.
Isso vale nos endpoints que têm divisão. Nos de escopo global da conta — os que não têm divisão nenhuma,
como /v1/formas_pagamento, /v1/redes e /v1/transportadoras — o campo não faz parte do contrato: uns
descartam em silêncio, outros recusam como chave desconhecida. Não conte com o 412 fora da lista.

Filtrando uma consulta por divisão

Nas consultas GET você pode informar ?divisao_id=X para receber apenas os registros daquela divisão.
O filtro é opcional: sem ele, a consulta devolve os registros de todas as divisões da conta.

GET /api/v1/produtos/?divisao_id=987

Os endpoints abaixo filtram por divisão:

/v1/produtos
/v1/categorias
/v1/variacoes
/v1/tabelas_preco
/v1/produtos_tabela_preco
/v1/condicoes_pagamento
/v1/promocoes
/v1/politicas_comerciais
/v1/configuracoes_icms_st
/v1/pedidos e /v2/pedidos
/v1/divisoes_clientes — aceita também o filtro cliente_id
/v1/saldo_flex — aqui o divisao_id é obrigatório; sem ele a consulta responde 422

Endpoints que não filtram por divisão

Em alguns endpoints o divisao_id é aceito e validado, mas não altera o resultado — a resposta sai igual
com e sem o filtro. É o caso de /v1/clientes, /v1/pagamentos, /v1/metas e /v1/comissoes.

Nesses casos, use o campo divisao_id (ou divisoes_ids) que vem em cada registro da resposta para saber a
qual divisão ele pertence.

🧠
Explicando pra dev entender:

o divisao_id é sempre validado, em qualquer GET — valor inválido responde 412 mesmo onde o filtro não
tem efeito;

receber 200 não garante que a lista foi filtrada. Confie no campo do registro, não no filtro que você enviou.

Consultando e criando as divisões

As divisões da conta têm endpoints próprios:

/v1/divisoes — lista e cadastra as divisões da conta;
/v1/divisoes_clientes — controla de quais
divisões cada cliente pode comprar;
/v1/divisoes_clientes/liberar_todas — remove os
vínculos de um cliente, liberando todas as divisões para ele.

Os dois são exclusivos das contas de indústria com divisões. Em qualquer outra conta, todos os verbos desses
dois endpoints respondem 412 com a mensagem Recurso disponível apenas para indústrias com divisões..

Erros relacionados à divisão

Situação	Código	Corpo
Filtro `?representada_id=` em conta com divisões	`412`	`erros[].campo` = `divisao_id`, mensagem indicando o nome correto
`divisao_id` inexistente ou de outra conta	`412`	`erros[].campo` = `divisao_id`, mensagem `Divisão inexistente.`
`divisao_id` em formato inválido (ex: texto)	`412`	`erros[].campo` = `divisao_id`, mensagem indicando o tipo esperado
`/v1/divisoes` ou `/v1/divisoes_clientes` em conta sem divisões	`412`	`mensagem` explicando que o recurso é exclusivo
Erro de validação no corpo de um POST/PUT	`422`	`mensagem` + `erros` com o campo problemático

Repare que o 412 é sobre a divisão informada na consulta, e o 422 é sobre o conteúdo que você enviou no
corpo da requisição. Os dois seguem valendo, cada um no seu contexto.