Divisões

A entidade divisões permite consultar e criar as divisões da sua conta.

Ela é destinada às contas de indústria configuradas para trabalhar com divisões. Nessas contas, o cadastro é separado por divisão: produtos, tabelas de preço, clientes e pedidos pertencem a uma divisão específica. Nas contas que não trabalham com divisões, os endpoints desta entidade respondem 412.

Como as divisões aparecem nos outros endpoints

Nas contas que trabalham com divisões, os demais endpoints da API usam o campo divisao_id no lugar de representada_id, tanto no envio quanto no retorno. Nas demais contas, o campo continua sendo representada_id.

Por isso, nos endpoints que têm esse campo você encontra as duas versões documentadas, uma logo abaixo da outra, e os exemplos de requisição e resposta estão separados por tipo de conta.

O guia Indústrias com divisões reúne o assunto todo: onde o filtro ?divisao_id= funciona, onde ele é aceito mas não filtra, e quais erros a API devolve.

⚠️
Em uma conta que trabalha com divisões, enviar representada_id retorna 412. Utilize divisao_id.

Filtros disponíveis

Você pode aplicar os seguintes filtros na consulta GET:

alterado_apos: retorna apenas as divisões alteradas após a data e hora informadas
ultimo_id: retorna apenas as divisões com id maior que o informado, para paginar consultas grandes

Exemplo: ?alterado_apos=2026-07-01 00:00:00

Esta consulta não aceita filtro por divisão. Para obter uma divisão específica, informe o id no final da URL.

Estrutura de Retorno (GET)

Campo	Tipo	Descrição
id	Integer	Identificador único da divisão no Mercos.
nome_fantasia	String: 100	Nome fantasia da divisão.
excluido	Boolean	Indica se a divisão está excluída.
ultima_alteracao	DateTime	Data e hora da última modificação desta divisão no Mercos.

Parâmetros do JSON de envio de Divisão (POST)

Os campos obrigatórios são: razao_social e nome_fantasia.

Campo	Tipo	Descrição
razao_social (obrigatório)	String: 100	Razão social da divisão.
nome_fantasia (obrigatório)	String: 100	Nome fantasia da divisão.
cnpj	String: 18	CNPJ ou CPF da divisão. Pode ser enviado com ou sem formatação: o Mercos grava só os números.
controlar_estoque	Boolean	Indica se o estoque dos produtos será controlado nesta divisão. O padrão é `false`.

💡
A quantidade de divisões é limitada pelo seu plano. Ao atingir o limite, a criação responde 422.

Divisões dos clientes

Para definir de quais divisões um cliente pode comprar, utilize a entidade Divisões dos clientes.