Notas Fiscais

Atualizar Configuração Fiscal

Atualiza uma configuração fiscal. Envie apenas os campos que mudam — os demais são preservados.

⚠️ Atenção: o merge é por campo do primeiro nível, não por campo aninhado. Enviar prestador com dois campos substitui o objeto prestador inteiro, apagando o que não veio. O mesmo vale para endereco e certificate: monte o objeto completo antes de enviar.

prefeitura é a exceção: os campos enviados são mesclados com os já gravados, então dá para alterar só a série do RPS sem reenviar a senha.

Enviar null em um campo o remove da configuração.

certificate com pfx_base64 e password substitui o certificado e revalida a empresa emissora; o certificado anterior é apagado, a menos que outra configuração da conta use o mesmo arquivo.

Qualquer alteração revalida a empresa emissora. Se essa etapa falhar, nada é gravado.

Case de uso:

Como plataforma, quero trocar o certificado digital antes do vencimento, sem recriar a configuração.

PUT/v1/invoices/notas/config/:configId

Base URL Produção:https://api.validapay.com.br

Base URL Sandbox:https://sandbox.validapay.com.br

Authorizations

bearer

Authorization

string obrigatório

Cabeçalho de autenticação Bearer no formato Bearer {{token}} onde {{token}} é o seu token OAuth2.

Escopos requeridos

nota.fiscal/write

Path Parameters

configIdstringobrigatório

Configid

Body

application/json

Content-Type:application/json

JSON

{
  "config_name": "Matriz",
  "enabled": true,
  "invoiceTiming": "AFTER_CONFIRMATION",
  "daysAfterConfirmation": 3,
  "descricao_servico": "Consultoria em tecnologia da informação",
  "codigo_tributacao_nacional_iss": "010701",
  "tributacao_iss": 1,
  "tipo_retencao_iss": 1,
  "aliquota_iss": 2,
  "item_lista_servico": "07.02",
  "serie_dps": "1",
  "prefeitura": {
    "login": "usuario-do-portal",
    "senha": "chave-ou-senha-do-portal",
    "serie_rps": "1",
    "proximo_numero_rps": 145
  },
  "certificate": {
    "pfx_base64": "MIIQ…",
    "password": "senha-do-certificado"
  }
}

Schema

config_namestringopcional

enabledbooleanopcional

false desliga a emissão sem apagar a configuração

invoiceTimingstringopcional

Momento da emissão nas notas geradas por cobrança

Valores aceitos:IMMEDIATEAFTER_CONFIRMATIONDAYS_AFTER_CONFIRMATION

daysAfterConfirmationnumberopcional

Só com invoiceTiming DAYS_AFTER_CONFIRMATION

Regra:1

descricao_servicostringopcional

codigo_tributacao_nacional_issstringopcional

tributacao_issnumberopcional

tipo_retencao_issnumberopcional

aliquota_issnumberopcional

NFS-e municipal

item_lista_servicostringopcional

NFS-e municipal

serie_dpsstringopcional

NFS-en: série da DPS

prefeituraobjectopcional

Mesclado com o que já está gravado; envie só o que muda

certificateobjectopcional

Só para substituir o certificado

← Anterior

Criar Configuração Fiscal

Excluir Configuração Fiscal

const url = 'https://sandbox.validapay.com.br/v1/invoices/notas/config/{{configId}}';

const options = {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer {{token}}',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "config_name": "Matriz",
  "enabled": true,
  "invoiceTiming": "AFTER_CONFIRMATION",
  "daysAfterConfirmation": 3,
  "descricao_servico": "Consultoria em tecnologia da informação",
  "codigo_tributacao_nacional_iss": "010701",
  "tributacao_iss": 1,
  "tipo_retencao_iss": 1,
  "aliquota_iss": 2,
  "item_lista_servico": "07.02",
  "serie_dps": "1",
  "prefeitura": {
    "login": "usuario-do-portal",
    "senha": "chave-ou-senha-do-portal",
    "serie_rps": "1",
    "proximo_numero_rps": 145
  },
  "certificate": {
    "pfx_base64": "MIIQ…",
    "password": "senha-do-certificado"
  }
})
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

Response Examples

200200▾

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"
}

404404▾

JSON

{
    "error": {
        "message": "Configuração não encontrada",
        "code": "NOTA_CONFIG_NOT_FOUND",
        "details": null,
        "timestamp": "2026-07-14T21:39:36.322Z"
    }
}

← Anterior

Criar Configuração Fiscal

Excluir Configuração Fiscal