# Criar Configuração Fiscal
`POST /v1/invoices/notas/config`
**Área:** Notas Fiscais

**Scopes necessários:** `nota.fiscal/write`

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._

### Request body

```json
{
  "config_name": "Matriz",
  "enabled": true,
  "razao_social": "EMPRESA EXEMPLO LTDA",
  "invoiceTiming": "IMMEDIATE",
  "daysAfterConfirmation": 1,
  "tipo_nf": "nacional",
  "descricao_servico": "Prestação de Serviços",
  "enviar_email_destinatario": true,

  "codigo_tributacao_nacional_iss": "010701",
  "tributacao_iss": 1,
  "tipo_retencao_iss": 1,
  "serie_dps": "1",

  "situacao_tributaria_pis_cofins": "01",
  "aliquota_pis": 0.65,
  "aliquota_cofins": 3,
  "aliquota_csll": 0,
  "aliquota_irrf": 0,
  "tipo_retencao_pis_cofins": 0,
  "percentual_total_tributos_federais": 5.65,
  "percentual_total_tributos_estaduais": 0,
  "percentual_total_tributos_municipais": 2,
  "percentual_total_tributos_simples_nacional": 6,
  "regime_tributario_simples_nacional": 1,

  "item_lista_servico": "07.02",
  "aliquota_iss": 2,
  "iss_retido": false,
  "natureza_operacao": "1",
  "codigo_cnae": "6201500",
  "codigo_tributario_municipio": "620150001",

  "prestador": {
    "cnpj": "99988877000108",
    "inscricao_municipal": "1234567",
    "inscricao_estadual": "",
    "nome_fantasia": "EMPRESA EXEMPLO LTDA",
    "email": "fiscal@exemplo.com.br",
    "telefone": "5548999999999",
    "codigo_municipio": "4205407",
    "codigo_municipio_prestacao": "4205407",
    "codigo_opcao_simples_nacional": 1,
    "regime_especial_tributacao": 0,
    "endereco": {
      "logradouro": "RUA DAS PALMEIRAS",
      "numero": "110",
      "complemento": "",
      "bairro": "CENTRO",
      "municipio": "Florianópolis",
      "cep": "88010000",
      "uf": "SC"
    }
  },

  "prefeitura": {
    "login": "usuario-do-portal",
    "senha": "chave-ou-senha-do-portal",
    "serie_rps": "1",
    "proximo_numero_rps": 1
  },

  "responsavel": {
    "nome": "Maria Souza",
    "cpf": "11144477735"
  },

  "certificate": {
    "pfx_base64": "MIIQ…",
    "password": "senha-do-certificado"
  }
}
```

### Campos do body

**Obrigatórios:** `codigo_tributacao_nacional_iss`, `tributacao_iss`, `tipo_retencao_iss`, `situacao_tributaria_pis_cofins`, `aliquota_pis`, `aliquota_cofins`, `percentual_total_tributos_simples_nacional`, `prestador`, `prestador.cnpj`, `prestador.codigo_municipio`, `prestador.codigo_opcao_simples_nacional`, `prestador.regime_especial_tributacao`, `certificate.pfx_base64`, `certificate.password`

| Campo | Descrição |
|---|---|
| `codigo_tributacao_nacional_iss` | NFS-en: código de tributação nacional do ISS, 6 dígitos |
| `tributacao_iss` | NFS-en: 1 tributável, 2 imunidade, 3 exportação, 4 não incidência |
| `tipo_retencao_iss` | NFS-en: 1 não retido, 2 retido pelo tomador, 3 pelo intermediário |
| `situacao_tributaria_pis_cofins` | se não optante pelo Simples - NFS-en |
| `aliquota_pis` | se não optante - Percentual aplicado sobre o valor do serviço |
| `aliquota_cofins` | se não optante - Percentual aplicado sobre o valor do serviço |
| `percentual_total_tributos_simples_nacional` | se optante pelo Simples (MEI ou ME/EPP) |
| `prestador` |  |
| `prestador.cnpj` | 14 dígitos, apenas números |
| `prestador.codigo_municipio` | Código IBGE do município, 7 dígitos; define o padrão de emissão |
| `prestador.codigo_opcao_simples_nacional` | NÚMERO, não string. 1 não optante, 2 MEI, 3 ME/EPP |
| `prestador.regime_especial_tributacao` | 0 nenhum |
| `certificate.pfx_base64` | Certificado A1 em base64; anda junto com password |
| `certificate.password` |  |

**Opcionais**

| Campo | Descrição |
|---|---|
| `config_name` | Nome para diferenciar as configurações da conta |
| `enabled` | Default true; configuração desabilitada não emite |
| `razao_social` | Razão social da empresa emissora; sem ela vale o nome_fantasia |
| `invoiceTiming` | Momento da emissão nas notas geradas por cobrança. Default IMMEDIATE (valores: IMMEDIATE, AFTER_CONFIRMATION, DAYS_AFTER_CONFIRMATION) |
| `daysAfterConfirmation` | Dias após a confirmação, quando invoiceTiming for DAYS_AFTER_CONFIRMATION. Default 1 (mín.: 1) |
| `tipo_nf` | Força o padrão de emissão; por padrão quem decide é o município do prestador (valores: municipal, nacional) |
| `descricao_servico` | Discriminação padrão do serviço, usada quando a cobrança não traz o nome do item |
| `enviar_email_destinatario` | Default true; a nota é enviada ao tomador por e-mail na autorização |
| `serie_dps` | NFS-en: série da DPS, declarada no cadastro e enviada em cada emissão. Default 1 |
| `aliquota_csll` | Percentual; vira o valor de CSLL da nota |
| `aliquota_irrf` | Percentual; vira o valor de IRRF da nota |
| `tipo_retencao_pis_cofins` | 0 não retido |
| `percentual_total_tributos_federais` | Percentual informado na nota |
| `percentual_total_tributos_estaduais` | Percentual informado na nota |
| `percentual_total_tributos_municipais` | Percentual informado na nota |
| `regime_tributario_simples_nacional` | 1 federais e municipal pelo SN. Default 1 |
| `item_lista_servico` | Obrigatório na NFS-e municipal: item da lista de serviços, formato NN.NN |
| `aliquota_iss` | Obrigatório na NFS-e municipal: alíquota do ISS em percentual |
| `iss_retido` | NFS-e municipal: ISS retido pelo tomador. Default false |
| `natureza_operacao` | NFS-e municipal. Default 1 |
| `codigo_cnae` | NFS-e municipal; exigido por parte dos municípios |
| `codigo_tributario_municipio` | NFS-e municipal; exigido por parte dos municípios |
| `prestador.inscricao_municipal` |  |
| `prestador.inscricao_estadual` |  |
| `prestador.nome_fantasia` |  |
| `prestador.email` |  |
| `prestador.telefone` |  |
| `prestador.codigo_municipio_prestacao` | Default igual a codigo_municipio |
| `prestador.endereco` | Preenchido pelo cadastro da conta quando ausente |
| `prestador.endereco.logradouro` |  |
| `prestador.endereco.numero` |  |
| `prestador.endereco.complemento` |  |
| `prestador.endereco.bairro` |  |
| `prestador.endereco.municipio` |  |
| `prestador.endereco.cep` |  |
| `prestador.endereco.uf` |  |
| `prefeitura` | Credencial do portal e numeração do RPS, na NFS-e municipal |
| `prefeitura.login` | Só nos municípios que pedem login |
| `prefeitura.senha` | Em parte dos municípios é a chave digital, não a senha de acesso |
| `prefeitura.serie_rps` | Série do RPS registrada na prefeitura |
| `prefeitura.proximo_numero_rps` | Número do próximo RPS a emitir (mín.: 1) |
| `responsavel` | Guardado no cadastro; não vai para a nota |
| `responsavel.nome` |  |
| `responsavel.cpf` |  |
| `certificate` | Sem certificado a prefeitura normalmente recusa a empresa |

### Resposta 201 — 201

```json
{
  "id": "unc_1788193720141_65g0zh12p",
  "accountId": "460851686",
  "config_name": "Matriz",
  "enabled": true,
  "invoiceTiming": "IMMEDIATE",
  "codigo_tributacao_nacional_iss": "010701",
  "tributacao_iss": 1,
  "tipo_retencao_iss": 1,
  "serie_dps": "1",
  "descricao_servico": "Prestação de Serviços",
  "prestador": {
    "cnpj": "99988877000108",
    "nome_fantasia": "EMPRESA EXEMPLO LTDA",
    "inscricao_municipal": "1234567",
    "codigo_municipio": "4205407",
    "codigo_municipio_prestacao": "4205407",
    "codigo_opcao_simples_nacional": 1,
    "regime_especial_tributacao": 0
  },
  "prefeitura": {
    "login": "usuario-do-portal",
    "has_senha": true,
    "serie_rps": "1",
    "proximo_numero_rps": 145
  },
  "certificate": {
    "has_certificate": true,
    "expiry_date": "2026-11-18T11:01:15.000Z"
  },
  "createdAt": "2026-08-31T16:28:43.167Z",
  "updatedAt": "2026-08-31T16:28:43.167Z"
}
```

### Resposta 400 — 400 - sincronização

```json
{
    "error": {
        "message": "Mensagem devolvida pela prefeitura",
        "code": "NF_CONFIG_SYNC_FAILED",
        "details": null,
        "timestamp": "2026-07-14T21:39:36.322Z"
    }
}
```

### Resposta 500 — 500 - regime incompleto

```json
{
    "error": {
        "message": "aliquota_pis é obrigatório para regime Não Optante",
        "code": "INTERNAL_ERROR",
        "details": null,
        "timestamp": "2026-07-14T21:39:36.322Z"
    }
}
```

---
Página: https://docs.validapay.com.br/documentacao-validapay2/post-criar-configuracao-fiscal
Contrato OpenAPI: https://docs.validapay.com.br/openapi.json