Configurações de IBS

A entidade Configuração de IBS define as regras de alíquota do IBS (Imposto 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_ibs_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.
uf: retorna apenas as regras com a UF de destino informada (?uf=SC). Não distingue maiúsculas e minúsculas. Regras válidas para todos os estados não são retornadas por este filtro.

Exemplo: ?ativa=true&uf=SC

Estrutura de Retorno (GET)

Campo	Tipo	Descrição
id	Integer	Identificador único da regra no Mercos.
codigo_ibs_integracao	String: 60	Código da regra de IBS 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.
uf_destino	String: 2	UF de destino dos clientes aos quais a regra se aplica. Ex: `"SC"`. `null` indica que a regra vale para todos os estados.
aliquota_estadual	Double	Alíquota estadual do IBS, em percentual, com até 4 casas decimais.
aliquota_municipal	Double	Alíquota municipal do IBS, 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 IBS. 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_ibs_integracao	String: 60	Código da regra de IBS 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`.
uf_destino	String: 2	Sigla da UF de destino dos clientes aos quais a regra se aplica. Ex: `"SC"`. Aceita minúsculas. Quando não informado, a regra vale para todos os estados.
aliquota_estadual (obrigatório)	Double	Alíquota estadual do IBS, em percentual, de `0` a `100`, com até 4 casas decimais.
aliquota_municipal (obrigatório)	Double	Alíquota municipal do IBS, 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.

Conflitos entre regras

As regras de IBS são comparadas entre si pela UF de destino dentro da mesma divisão/representada. Uma regra sem uf_destino ocupa a posição "todos os estados", que é tratada como um valor de UF a mais. Valem as seguintes restrições:

Só pode existir uma regra válida para todos os NCMs e produtos (sem ncms nem produtos) por UF de destino. Isso inclui a UF "todos os estados": só pode existir uma regra sem UF e sem vínculos.
Um mesmo produto ou NCM não pode estar vinculado a duas regras com a mesma UF de destino (UF não informada conta como o valor "todos os estados").
Regras com UFs de destino diferentes convivem, mesmo compartilhando produtos ou NCMs. No cálculo, o Mercos usa a regra com o estado mais específico.
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 para todos os estados; nova regra para todos os estados com o produto 123	`422` – produto já cadastrado
Produto 123 em uma regra para todos os estados; nova regra para SC com o produto 123	Permitido
Produto 123 em uma regra para SC; nova regra para SC com o produto 123	`422` – produto já cadastrado
Produto 123 em uma regra para SC; nova regra para PR com o produto 123	Permitido
Regra sem NCMs e produtos para SC; nova regra sem NCMs e produtos para SC	`422` – regra duplicada
Regra sem NCMs e produtos para SC; nova regra para SC 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_ibs/{id}) ou pelo código da regra no seu sistema (/v1/configuracoes_ibs/integracao/{codigo_ibs_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.
uf_destino enviado como null faz a regra passar a valer para todos os estados.
excluido = true exclui a regra; os demais campos do corpo são ignorados. O codigo_ibs_integracao de uma regra excluída fica livre 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_ibs/integracao/{codigo_ibs_integracao} retorna a regra não excluída que possui o código informado. A consulta por id (GET /v1/configuracoes_ibs/{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": "RegraIBS 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_ibs_integracao`.
Já existe uma regra de IBS com o código abc para esta empresa.	O `codigo_ibs_integracao` 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 IBS válida para todos os NCMs e produtos com a mesma UF de destino.	Segunda regra sem `ncms` e `produtos` para a mesma UF (ou para todos os estados).
Produto 123 já está cadastrado em outra regra de IBS com a mesma UF de destino.	Conflito de produto entre regras da mesma UF. 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.