Recorrência & Mensalidades (NFS-e)

Criar Contrato Recorrente

Cadastra um contrato para emissão 100% autônoma de NFS-e Nacional. Todo mês, no dia estipulado, o robô inteligente da NFER resolve as variáveis dinâmicas de competência ({{mes_ano}}, {{mes_atual}}), monta a DPS, assina com seu certificado A1, transmite ao ADN/SEFIN e despacha o DANFSE e XML por e-mail.

POST
https://api.nfer.me
/v1/recurring-contracts

Authorizations

X-API-Key
string
header
required

Chave de API emitida no painel NFER enviada no header da requisição.

Content-Type
string
header
required

application/json

Body

application/json
customerName
string
required

Nome Completo ou Razão Social do tomador.

Exemplo:Poliana Lima
customerDocument
string
required

CPF (11 dígitos) ou CNPJ (14 dígitos) do tomador.

Exemplo:04022170123
customerEmail
string
opcional

E-mail para despacho automático do PDF e XML da nota emitida.

Exemplo:poliana@exemplo.com.br
customerPhone
string
opcional

Telefone com DDD para contato ou alertas.

Exemplo:11999998888
customerId
string<uuid>
opcional

UUID do tomador caso já cadastrado em /v1/customers.

Exemplo:c1f7b882-990a-41d9-95e2-6320a0ee1234
description
string
required

Discriminação do serviço no corpo da NFS-e. Aceita variáveis dinâmicas: {{mes_ano}} (ex: 11/2026), {{competencia}}, {{mes_atual}} (ex: Novembro), {{mes_anterior}}.

Exemplo:Serviços de consultoria em TI e manutenção - Ref. {{mes_ano}}
amount
number
required

Valor financeiro do serviço (R$) faturado a cada ciclo.

Exemplo:1250.00
serviceCode
string
opcional

Código de Tributação Nacional com 6 dígitos (cTribNac).

Exemplo:010701
cTribMun
string
opcional

Subitem complementar municipal caso exigido pela prefeitura.

cNbs
string
opcional

Código da Nomenclatura Brasileira de Serviços (NBS).

cLocPrestacao
string
opcional

Código IBGE de 7 dígitos do município da prestação (se diferente da sede).

issRetained
boolean
opcional
default:false

Indica se o ISSQN é retido na fonte pelo tomador (padrão: false).

dayOfMonth
integer (1 a 31)
required

Dia do mês programado para a emissão da NFS-e (ex: dia 10 de cada mês).

Exemplo:10
firstIssueDate
string<date>
opcional

Data da primeira emissão (YYYY-MM-DD). Se omitida, calculada automaticamente a partir do dayOfMonth.

Exemplo:2026-11-10
durationType
"indefinite" | "fixed_installments" | "end_date"
opcional
default:indefinite

Regime de vigência: "indefinite" (indeterminado até pausar), "fixed_installments" (quantidade de parcelas/meses) ou "end_date" (data limite).

maxInstallments
integer
opcional

Quantidade total de parcelas quando durationType = "fixed_installments".

Exemplo:12
endDate
string<date>
opcional

Data de encerramento da recorrência (YYYY-MM-DD).

sendEmail
boolean
opcional
default:true

Se true, dispara e-mail com PDF/XML para o tomador assim que autorizada.

Response

application/json

Contrato recorrente cadastrado com sucesso e data de emissão agendada.

id
string<uuid>
opcional

Identificador único do recurso.

Exemplo:a819c940-bf72-46a2-9659-192518e11a91
customer_name
string
opcional

Exemplo retornado: "Poliana Lima"

Exemplo:Poliana Lima
customer_document
string
opcional

Exemplo retornado: "04022170123"

Exemplo:04022170123
customer_email
string
opcional

Exemplo retornado: "poliana@exemplo.com.br"

Exemplo:poliana@exemplo.com.br
description
string
opcional
Exemplo:Mensalidade do Plano Enterprise - Ref. {{mes_ano}}
amount
integer
opcional
Exemplo:1500
service_code
string
opcional

Exemplo retornado: "010701"

Exemplo:010701
day_of_month
integer
opcional
Exemplo:10
next_issue_date
string
opcional

Exemplo retornado: "2026-11-10"

Exemplo:2026-11-10
active
boolean
opcional
Exemplo:true
duration_type
string
opcional

Exemplo retornado: "indefinite"

Exemplo:indefinite
send_email
boolean
opcional
Exemplo:true
created_at
string<date-time>
opcional

Data e hora de criação do registro.

Exemplo:2026-10-14T23:00:00.000Z
Criar Contrato Recorrente
curl --request POST \
  --url https://api.nfer.me/v1/recurring-contracts \
  --header 'X-API-Key: <sua_chave_api>' \
  --header 'Content-Type: application/json' \
  --data '{
  "customerName": "Poliana Lima",
  "customerDocument": "04022170123",
  "customerEmail": "poliana@exemplo.com.br",
  "description": "Mensalidade do Plano Enterprise - Ref. {{mes_ano}}",
  "amount": 1500,
  "serviceCode": "010701",
  "dayOfMonth": 10,
  "durationType": "indefinite",
  "sendEmail": true
}'
{
  "id": "a819c940-bf72-46a2-9659-192518e11a91",
  "customer_name": "Poliana Lima",
  "customer_document": "04022170123",
  "customer_email": "poliana@exemplo.com.br",
  "description": "Mensalidade do Plano Enterprise - Ref. {{mes_ano}}",
  "amount": 1500,
  "service_code": "010701",
  "day_of_month": 10,
  "next_issue_date": "2026-11-10",
  "active": true,
  "duration_type": "indefinite",
  "send_email": true,
  "created_at": "2026-10-14T23:00:00.000Z"
}