Pular para o conteúdo
notemnotemDocumentação

Referência da API › Configuração fiscal

Gravar configuração fiscal

Grava como a empresa é tributada e recusa combinações que o governo não aceita.

PUT/api/v1/empresas/{id}/configuracao-fiscal

Envie a configuração completa: situação no Simples Nacional, regime de apuração, regime especial e forma de informar os tributos aproximados. O campo serie_dps é ignorado, porque a série de numeração é atribuída pela notem.

A notem recusa com 422, indicando o campo e a regra, as combinações que o governo rejeitaria depois, na emissão. Por exemplo, empresa fora do Simples Nacional precisa informar os tributos aproximados por esfera (federal, estadual e municipal), e MEI não pode ter regime especial. As regras completas estão no guia Configuração fiscal.

Parâmetros

idtextono caminhoobrigatório
Empresa da organização da chave (de outra organização → 404). UUID (RFC 9562); fora do padrão → 400 REQUISICAO_INVALIDA com campo id. · UUID
Idempotency-Keytextono cabeçalho
Chave de idempotência (até 100 caracteres) aceita em POST, PATCH, PUT e DELETE; vale 24 h por integração e ambiente, exceto emissão, cancelamento, análise e substituição de notas (associação duradoura ao pedido). Mesmo conteúdo devolve a mesma resposta (cabeçalho Idempotent-Replayed true); conteúdo diferente devolve 409 IDEMPOTENCIA_CONFLITO. Obrigatória em emissão, cancelamento e substituição. · até 100 caracteres

Corpo da requisição

A forma de informar os tributos aproximados depende da situação no Simples Nacional, porque o governo recusa a nota quando elas não combinam.

Empresa fora do Simples (nao_optante) usa só percentual_por_esfera.

MEI usa percentual_por_esfera ou nao_informar, nunca percentual_simples.

ME/EPP usa percentual_simples ou percentual_por_esfera, nunca nao_informar.

Por esfera exige os três percentuais (federal, estadual e municipal); zero é permitido. Campos ausentes valem null.

O regime especial deve ser nenhum para MEI, para ME/EPP com apuração dentro do Simples e para empresas com serviço ativo imune, de exportação ou sem incidência do ISS.

Configurações antigas que não seguem essas regras não são alteradas automaticamente: ficam incompletas e a emissão é recusada, com a regra a corrigir, antes de gerar o número da nota.

simples_nacionaltextoobrigatório
Valores: nao_optante, mei, me_epp
regime_apuracao_simplestexto ou null
Valores: dentro_do_simples, iss_fora_do_simples, tudo_fora_do_simples
regime_especialtextoobrigatório
Valores: nenhum, ato_cooperado, estimativa, microempresa_municipal, notario_registrador, profissional_autonomo, sociedade_profissionais, outros
tributos_aproximadosobjetoobrigatório
tributos_aproximados.modotextoobrigatório
Valores: percentual_simples, percentual_por_esfera, nao_informar
tributos_aproximados.percentual_simplestexto ou null
tributos_aproximados.federaltexto ou null
tributos_aproximados.estadualtexto ou null
tributos_aproximados.municipaltexto ou null
aliquota_iss_simplestexto ou null
regime_apuracao_ibscbstexto ou null
Somente ME/EPP (regApIBSCBSSN). Com ISS dentro do Simples: pelo_simples (padrão) ou regime_regular. Com ISS fora do Simples: cbs_simples_ibs_regular (padrão) ou regime_regular. Ausente ou null usa o padrão; ao mudar regime_apuracao_simples o padrão é reaplicado. Guardado agora e enviado a partir do próximo leiaute da NT 009. · Valores: pelo_simples, cbs_simples_ibs_regular, regime_regular
imprimir_canhoto_danfsebooleano
Ausente no PUT preserva valor atual · Padrão: false

Respostas

200 Configuração gravada

Campos da resposta
simples_nacionaltexto
Valores: nao_optante, mei, me_epp
regime_apuracao_simplestexto ou null
Valores: dentro_do_simples, iss_fora_do_simples, tudo_fora_do_simples
regime_especialtexto
Valores: nenhum, ato_cooperado, estimativa, microempresa_municipal, notario_registrador, profissional_autonomo, sociedade_profissionais, outros
tributos_aproximadosobjeto
tributos_aproximados.modotexto
Valores: percentual_simples, percentual_por_esfera, nao_informar
tributos_aproximados.percentual_simplestexto ou null
tributos_aproximados.federaltexto ou null
tributos_aproximados.estadualtexto ou null
tributos_aproximados.municipaltexto ou null
aliquota_iss_simplestexto ou null
regime_apuracao_ibscbstexto ou null
Somente ME/EPP (regApIBSCBSSN). Com ISS dentro do Simples: pelo_simples (padrão) ou regime_regular. Com ISS fora do Simples: cbs_simples_ibs_regular (padrão) ou regime_regular. Ausente ou null usa o padrão; ao mudar regime_apuracao_simples o padrão é reaplicado. Guardado agora e enviado a partir do próximo leiaute da NT 009. · Valores: pelo_simples, cbs_simples_ibs_regular, regime_regular
imprimir_canhoto_danfsebooleano
Ausente no PUT preserva valor atual · Padrão: false
serie_dpstexto ou null

400 Erro no formato padrão

404 Erro no formato padrão

422 REGRA_DE_NEGOCIO com o campo e a regra (ex.: forma de informar os tributos aproximados que não combina com a situação no Simples, alíquota do ISS no Simples)

Limites

Valem também os limites gerais da chave. Veja Limites de uso.