Configurações de CBS

A entidade Configuração de CBS define as regras de alíquota da CBS (Contribuição sobre Bens e Serviços), tributo criado pela Reforma Tributária, utilizadas no cálculo dos impostos dos pedidos no Mercos.

Cada regra pode ser identificada pelo seu id no Mercos ou pelo codigo_cbs_integracao, o código da regra no sistema que está integrando. O endpoint está disponível para todos os planos.

Observações:

O cadastro é feito em lote: o POST recebe uma lista de regras e devolve as regras criadas.

Para excluir uma regra, utilize o método PUT e envie o campo excluido = true no corpo da requisição. Uma regra excluída não pode mais ser alterada.

Filtros disponíveis

Você pode aplicar os seguintes filtros na consulta GET, de forma independente ou combinada. Sem filtros, a consulta retorna todas as regras da conta.

alterado_apos: retorna apenas as regras alteradas após a data e hora informadas, no formato AAAA-MM-DD HH:MM:SS. Sem este filtro, as regras excluídas não são retornadas.
ultimo_id: usado junto com alterado_apos para percorrer as páginas da consulta. Veja o guia Paginação.
divisao_id: retorna apenas as regras da divisão informada. Disponível apenas nas contas de indústria com divisões.
ativa: retorna apenas as regras ativas (?ativa=true) ou inativas (?ativa=false). Também aceita 1 e 0.

Exemplo: ?ativa=true

Estrutura de Retorno (GET)

Campo	Tipo	Descrição
id	Integer	Identificador único da regra no Mercos.
codigo_cbs_integracao	String: 60	Código da regra de CBS no sistema que está integrando ao Mercos. Único entre as regras não excluídas da conta. `null` quando não informado.
ativa	Boolean	Indica se a regra está ativa. Regras inativas não são usadas no cálculo dos pedidos, mas continuam valendo nas validações de conflito entre regras.
nome_regra	String: 100	Nome que identifica a regra. Único entre as regras não excluídas da conta. Gerado pelo Mercos quando não informado (ver Nome automático da regra).
aliquota	Double	Alíquota de CBS, em percentual, com até 4 casas decimais.
reducao_aliquota	Double	Percentual de redução da alíquota, com até 4 casas decimais. `0` quando não informado.
ncms	List de String	Códigos NCM aos quais a regra se aplica. Lista vazia quando a regra não está vinculada a NCMs.
produtos	List de Integer	IDs dos produtos do Mercos aos quais a regra se aplica. Lista vazia quando a regra não está vinculada a produtos.
excluido	Boolean	Indica se a regra está excluída.
ultima_alteracao	DateTime	Data e hora da última modificação da regra.
representada_id	Integer	Identificador da representada do registro. Retornado quando a sua conta não é uma indústria com divisões.
divisao_id	Integer	Identificador da divisão do registro. Retornado no lugar de `representada_id` quando a sua conta é uma indústria com divisões.

💡
Quando ncms e produtos vêm vazios, a regra é válida para todos os NCMs e produtos cadastrados na conta ou divisão.

Parâmetros de Envio (POST / PUT)

O POST requer um JSON com uma lista de objetos no body, em que cada objeto representa uma regra de CBS. A quantidade máxima de regras por requisição é 300. Caso aconteça algum erro em qualquer item, nenhuma regra é criada.

Campo	Tipo	Descrição
codigo_cbs_integracao	String: 60	Código da regra de CBS no seu sistema. Quando informado, precisa ser único entre as regras não excluídas da conta. A comparação não distingue maiúsculas, minúsculas nem acentos.
ativa	Boolean	Indica se a regra está ativa. Valor padrão: `true`.
nome_regra	String: 100	Nome que identifica a regra. Quando informado, precisa ser único entre as regras não excluídas da conta. Quando não informado, o Mercos gera um nome no padrão `Regra X` (ver Nome automático da regra).
aliquota (obrigatório)	Double	Alíquota de CBS, em percentual, de `0` a `100`, com até 4 casas decimais.
reducao_aliquota	Double	Percentual de redução da alíquota, de `0` a `100`, com até 4 casas decimais. Valor padrão: `0`.
ncms	List de String: 20	Códigos NCM aos quais a regra se aplica. Até 300 códigos por regra. O NCM não precisa estar vinculado a um produto cadastrado no Mercos.
produtos	List de Integer	IDs dos produtos do Mercos aos quais a regra se aplica. Até 300 produtos por regra. Os produtos precisam existir e pertencer à mesma divisão/representada da regra.
divisao_id	Integer	Identificador da divisão à qual a regra pertence. Disponível apenas nas contas de indústria com divisões: nas demais contas o campo responde `422`. Opcional: quando não informado, o Mercos usa a divisão associada à integração. Itens do mesmo lote podem informar divisões diferentes.

⚠️
Regra de preenchimento de ncms e produtos
Os dois campos são opcionais e podem ser usados ao mesmo tempo. Quando nenhum dos dois é informado, a regra passa a valer
para todos os NCMs e produtos cadastrados na conta ou divisão.

Nome automático da regra

Quando nome_regra não é informado no POST, o Mercos nomeia a regra no padrão Regra X, em que X é o menor número livre entre os nomes já usados na conta:

Contam como ocupados os nomes Regra N de todas as regras de CBS da conta (inclusive excluídas e independentemente de maiúsculas e minúsculas) e os nomes dos demais itens do mesmo lote.
Se as regras Regra 1, Regra 2 e Regra 3 existem e o integrador criou uma Regra 10 manualmente, a próxima regra sem nome recebe Regra 4.
Vários itens sem nome no mesmo lote são numerados em sequência, na ordem de envio.
No PUT, enviar nome_regra vazio ou null também faz o Mercos gerar um novo nome automático.

Conflitos entre regras

As regras de CBS são comparadas entre si dentro da mesma divisão/representada. Valem as seguintes restrições:

Só pode existir uma regra válida para todos os NCMs e produtos (sem ncms nem produtos) por divisão/representada.
Um mesmo produto ou NCM não pode estar vinculado a duas regras da mesma divisão/representada.
Uma regra válida para todos os NCMs e produtos não conflita com regras que possuem vínculos: no cálculo, a regra mais específica (por produto, depois por NCM) tem prioridade.
A validação considera as regras não excluídas, inclusive as inativas, e também os itens do próprio lote.

Situação	Resultado
Produto 123 em uma regra; nova regra com o produto 123	`422` – produto já cadastrado
Regra sem NCMs e produtos; nova regra sem NCMs e produtos	`422` – regra duplicada
Regra sem NCMs e produtos; nova regra com o produto 123	Permitido

O mesmo vale para NCMs no lugar de produtos.

Alteração (PUT)

A alteração pode ser feita pelo id da regra no Mercos (/v1/configuracoes_cbs/{id}) ou pelo código da regra no seu sistema (/v1/configuracoes_cbs/integracao/{codigo_cbs_integracao}). O PUT é parcial: apenas os campos enviados são alterados e os demais são mantidos.

ncms e produtos, quando enviados, substituem a lista atual de vínculos da regra. Envie [] para remover todos os vínculos daquele tipo.
excluido = true exclui a regra; os demais campos do corpo são ignorados. O codigo_cbs_integracao e o nome_regra de uma regra excluída ficam livres para reuso.
As mesmas validações de unicidade e de conflito do POST são aplicadas ao estado final da regra.

💡
Nas contas de indústria com divisões, enviar divisao_id no PUT move a regra para a divisão informada. Os NCMs vinculados são
recriados na nova divisão automaticamente. Como um produto pertence a uma única divisão, uma regra com produtos vinculados só pode
ser movida se produtos for enviado no mesmo PUT com os produtos da nova divisão (ou []); caso contrário a resposta é 422.
Não informar divisao_id mantém a regra na divisão em que está.

Consulta por código de integração

GET /v1/configuracoes_cbs/integracao/{codigo_cbs_integracao} retorna a regra não excluída que possui o código informado. A consulta por id (GET /v1/configuracoes_cbs/{id}) retorna a regra mesmo quando excluída, com excluido = true.

Erros

Registro não encontrado (id ou código inexistente, ou regra já excluída no PUT) responde 404 com o corpo {"mensagem": "RegraCBS inexistente."}.

Erros de validação respondem 422 no formato {"mensagem": "Ocorreram erros de validação", "erros": [[campo, mensagem]], "url": "..."}. No POST, o campo vem prefixado pelo índice do item no lote, como [1].produtos. As principais mensagens são:

Mensagem	Quando ocorre
Os seguintes atributos são inválidos: "campo".	O corpo traz uma chave fora das listadas em Parâmetros de Envio. Nas contas sem divisões, `divisao_id` cai neste caso.
Formato do JSON inválido: Esperava uma lista.	O corpo do `POST` não é uma lista.
Código "abc" duplicado no lote.	Dois itens do lote com o mesmo `codigo_cbs_integracao`.
Já existe uma regra de CBS com o código abc para esta empresa.	O `codigo_cbs_integracao` já pertence a outra regra não excluída.
Nome "Regra 10" duplicado no lote.	Dois itens do lote com o mesmo `nome_regra`.
Já existe uma regra de CBS com o nome Regra 10 para esta empresa.	O `nome_regra` já pertence a outra regra não excluída.
Produto 123 não encontrado.	O produto não existe, está excluído ou pertence a outra divisão/representada.
Já existe uma regra de CBS válida para todos os NCMs e produtos nesta divisão.	Segunda regra sem `ncms` e `produtos` na mesma divisão/representada.
Produto 123 já está cadastrado em outra regra de CBS desta divisão.	Conflito de produto entre regras da mesma divisão/representada. Há a mensagem equivalente para NCM.
A regra tem produtos vinculados de outra divisão. Para movê-la, informe `produtos` com os produtos da nova divisão.	`PUT` com `divisao_id` diferente em uma regra que possui produtos vinculados, sem enviar `produtos`.
Divisão inexistente.	`divisao_id` que não pertence à conta.
Use `divisao_id` no lugar de `representada_id`.	Conta de indústria com divisões enviando `representada_id`.

Nas contas de indústria com divisões, o filtro ?divisao_id= inválido na consulta responde 412, como descrito no guia Indústrias com divisões.