Criar Configuração Fiscal

Cadastra a empresa emissora: CNPJ, regime tributário, certificado digital e os tributos que entram na nota.

O id devolvido aqui é o configId da emissão avulsa e o nfConfigId de cobranças, produtos e assinaturas. Uma conta pode ter mais de uma configuração — o CNPJ do prestador define de qual empresa a nota sai.

O que não for enviado é preenchido a partir do cadastro da conta: CNPJ, endereço, contato e código IBGE do município. Enviar explicitamente evita depender desses dados.

A criação valida e registra a empresa emissora, incluindo o certificado. Se essa etapa falhar, nada é gravado e o certificado enviado é descartado — não sobra configuração pela metade.

Não envie id no corpo: com ele a chamada vira atualização da configuração existente.

Municipal ou nacional: quem decide é o município

O código IBGE em prestador.codigo_municipio determina por qual padrão a nota sai, e isso muda quais campos tributários são lidos:

• NFS-en nacional — padrão nacional da NFS-e, adotado pela maior parte dos municípios. Usa codigo_tributacao_nacional_iss, tributacao_iss, tipo_retencao_iss, serie_dps e os campos de PIS/COFINS ou do Simples, conforme o regime.
• NFS-e municipal — municípios com sistema próprio. Usa item_lista_servico, aliquota_iss, iss_retido, natureza_operacao e, quando o município exige, codigo_cnae e codigo_tributario_municipio.

Você não precisa escolher: a rota é resolvida na emissão, a partir do município do prestador. tipo_nf força um dos dois padrões e só faz sentido quando o município aceita ambos.

Na dúvida sobre em qual padrão o seu município está, preencha os dois conjuntos — o que não se aplica é ignorado.

Credencial da prefeitura e numeração do RPS

O certificado digital A1 basta na maior parte dos municípios. Os que têm sistema próprio podem exigir também uma credencial do portal, enviada em prefeitura — nem todos pedem login, e há municípios em que só a senha é necessária.

Confira o portal do seu município antes de preencher. Em parte deles o que vai em senha é uma chave digital gerada no perfil do usuário, e não a senha de acesso ao portal — usar a senha errada só aparece como falha de autenticação na primeira emissão.

Numeração

Cada padrão tem a sua, e as duas continuam a sequência que a prefeitura já registrou para a empresa — em branco, a numeração começa do início.

• NFS-e municipal — prefeitura.serie_rps e prefeitura.proximo_numero_rps.
• NFS-en nacional — serie_dps, no primeiro nível do corpo. A série declarada no cadastro é a mesma que vai em cada emissão e precisa bater com a registrada na prefeitura; a sequência dos números é mantida pela ValidaPay.

Quando a nota é emitida

invoiceTiming define o momento da emissão das notas geradas por cobrança:

• IMMEDIATE — junto com a cobrança. É o padrão.
• AFTER_CONFIRMATION — somente após a confirmação do pagamento.
• DAYS_AFTER_CONFIRMATION — daysAfterConfirmation dias depois da confirmação (padrão 1).

A emissão avulsa por POST /v1/invoices/notas sai sempre na hora, qualquer que seja o valor configurado.

⚠️ Atenção: configurações criadas pelo painel trazem também quando_emitir, com os mesmos três valores. Ele é apenas o espelho gravado pela tela — quem define o agendamento é invoiceTiming.

Campos exigidos pelo regime

O regime vem de prestador.codigo_opcao_simples_nacional:

• 1, não optante — exige situacao_tributaria_pis_cofins, aliquota_pis e aliquota_cofins.
• 2 (MEI) e 3 (ME/EPP) — exigem percentual_total_tributos_simples_nacional.

Faltando um deles, a configuração não é gravada e a resposta traz a mensagem da validação com o código INTERNAL_ERROR.

Case de uso:

Como plataforma, quero cadastrar a empresa emissora e o certificado digital por API, para habilitar a emissão de notas sem passar pelo painel.