Pular para o conteúdo

Rotinas de emissão automática (NFS-e recorrente)

Uma rotina é uma nota de serviço que se repete: você cadastra uma vez o cliente, o serviço, o valor, a periodicidade e o dia, e a plataforma emite a NFS-e sozinha em cada data da agenda. É o mesmo módulo da tela do emissor (Outras > Rotinas): o que você cria pela API aparece na tela, e vice-versa.

Desde a versão 3.17.0.

A autenticação é a mesma de todas as rotas da v3 (Authorization: Token <chave> ou Authorization: Bearer <chave>). A empresa vem da chave, nunca do corpo. A chave precisa ter permissão fiscal: sem ela, toda rota de rotinas responde status: "400" com a descrição “A chave não tem permissão fiscal para rotinas.”

Endpoints

OperaçãoEndpointstatus de sucesso
Listar as rotinas da empresaGET /rotinas005
Modelos disponíveis e os campos de cada umGET /rotinas/modelos005
Buscar cliente para o campo de clienteGET /rotinas/clientes?busca=005
Serviços para o campo de serviçoGET /rotinas/servicos005
Conferir pendências sem gravarPOST /rotinas/validar005
Criar (ativa ou rascunho)POST /rotinas001
Detalhe, pendências, diagnóstico e históricoGET /rotinas/{id}005
AlterarPUT /rotinas/{id}001
ExcluirDELETE /rotinas/{id}001
Histórico de emissõesGET /rotinas/{id}/execucoes005
PausarPOST /rotinas/{id}/pausar001
RetomarPOST /rotinas/{id}/retomar001
Emitir uma competência agoraPOST /rotinas/{id}/emitir-agora001
Valores extras e meses disponíveisGET /rotinas/{id}/extras005
Lançar valor extra em um mêsPUT /rotinas/{id}/extras/{AAAA-MM}001
Remover valor extra de um mêsDELETE /rotinas/{id}/extras/{AAAA-MM}001

Todas respondem na mesma chamada, sem recibo. Quem gera recibo é a NFS-e que a rotina emite (veja Acompanhar a NFS-e gerada).

Nomes dos campos

As chaves da resposta seguem o padrão da v3 (kebab-case: id-rotina, proxima-emissao), inclusive na lista de campos de GET /rotinas/modelos (depende-de, depende-valor). A exceção é o mapa parametros e rotulos de uma rotina: ali as chaves são os nomes dos campos do modelo (id_clifor, vl_servico), exatamente como o nome de cada campo em GET /rotinas/modelos, tanto na entrada quanto na saída.

Os campos de entrada são palavras únicas: modelo, nome, periodicidade, dia, inicio, fim, ativar, parametros, competencia, valor e motivo.

  1. Descobrir os modelos e os campos de cada um

    Terminal window
    curl $BASE/rotinas/modelos -H "Authorization: Token $TOKEN"
    {
    "status": "005",
    "descricao": "Modelos de rotina disponíveis para a empresa.",
    "data": {
    "modelos": [
    {
    "codigo": "NFSE_RECORRENTE",
    "nome": "Nota de serviço recorrente",
    "descricao": "Emite automaticamente a mesma nota de serviço para um cliente, na periodicidade que você escolher.",
    "efeito": "EMITE_DOCUMENTO",
    "unica-por-empresa": false,
    "parametros": [
    { "nome": "id_clifor", "rotulo": "Cliente", "tipo": "CLIENTE", "obrigatorio": true,
    "ajuda": "Para quem a nota é emitida todo período." },
    { "nome": "id_produto", "rotulo": "Serviço", "tipo": "PRODUTO_SERVICO", "obrigatorio": true,
    "ajuda": "O serviço prestado. O código fiscal vem do cadastro dele." },
    { "nome": "vl_servico", "rotulo": "Valor", "tipo": "VALOR", "obrigatorio": true,
    "ajuda": "Valor de cada nota." },
    { "nome": "st_reajuste", "rotulo": "Reajustar o valor", "tipo": "SIM_NAO", "obrigatorio": false,
    "ajuda": "Corrige o valor sozinho, no mês e pelo índice que você escolher." },
    { "nome": "cd_indice_reajuste", "rotulo": "Índice de reajuste", "tipo": "LISTA", "obrigatorio": false,
    "ajuda": "Usa o acumulado do período, até dois meses antes do reajuste. Acumulado negativo não reduz o valor.",
    "depende-de": "st_reajuste", "depende-valor": "S",
    "opcoes": [
    { "valor": "IPCA", "rotulo": "IPCA" },
    { "valor": "IGPM", "rotulo": "IGP-M" },
    { "valor": "INPC", "rotulo": "INPC" },
    { "valor": "IGPDI", "rotulo": "IGP-DI" },
    { "valor": "PERCENTUAL", "rotulo": "Percentual fixo" }
    ] },
    { "nome": "ds_discriminacao", "rotulo": "Descrição", "tipo": "TEXTO_LONGO", "obrigatorio": false,
    "ajuda": "Aceita {competencia}, {mes} e {ano} — trocados na hora da emissão." }
    ]
    }
    ]
    },
    "meta": { "request_id": "req_...", "timestamp": "...", "api_version": "3.17.0" }
    }

    Lista encurtada. Veja Modelos para todos os campos.

  2. Achar o cliente e o serviço

    Terminal window
    curl "$BASE/rotinas/clientes?busca=acme" -H "Authorization: Token $TOKEN"
    curl $BASE/rotinas/servicos -H "Authorization: Token $TOKEN"
    { "status": "005", "descricao": "Clientes encontrados.",
    "data": { "clientes": [ { "id": 1262804, "nome": "ACME SERVICOS LTDA", "documento": "12345678000199" } ] } }
    { "status": "005", "descricao": "Serviços da empresa.",
    "data": { "servicos": [ { "id": 88231, "nome": "SUPORTE TECNICO MENSAL", "referencia": "SRV-SUP" } ] } }

    O id de cada um é o valor de id_clifor e id_produto em parametros.

  3. Conferir antes de gravar (opcional, recomendado)

    Terminal window
    curl -X POST $BASE/rotinas/validar \
    -H "Authorization: Token $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
    "modelo": "NFSE_RECORRENTE",
    "nome": "Suporte mensal - ACME",
    "periodicidade": "mensal",
    "dia": 10,
    "inicio": "2026-11-01",
    "parametros": { "id_clifor": 1262804, "id_produto": 88231, "vl_servico": "3.500,50" }
    }'
    { "status": "005", "descricao": "Rotina conferida.",
    "data": { "pode-ativar": true, "pendencias": [] } }
  4. Criar e ativar

    Terminal window
    curl -X POST $BASE/rotinas \
    -H "Authorization: Token $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
    "modelo": "NFSE_RECORRENTE",
    "nome": "Suporte mensal - ACME",
    "periodicidade": "mensal",
    "dia": 10,
    "inicio": "2026-11-01",
    "parametros": {
    "id_clifor": 1262804,
    "id_produto": 88231,
    "vl_servico": "3.500,50",
    "ds_discriminacao": "Suporte técnico de {competencia}"
    }
    }'

    A resposta traz o detalhe da rotina, com status: "001" e a descrição “Rotina criada.”. Sem ativar, a rotina já sai ativa. Se o cadastro tiver pendência, nada é ativado e a resposta é 400 com a lista em data.pendencias.

  5. Acompanhar

    GET /rotinas/{id} mostra a próxima emissão, o diagnóstico de por que emitiu ou não e o histórico. O recibo de cada NFS-e emitida aparece em execucoes.

Campos da rotina (entrada)

Usados em POST /rotinas, PUT /rotinas/{id} e POST /rotinas/validar.

CampoObrigatórioRegra
modelosim (na criação)Código do modelo, de GET /rotinas/modelos (ex.: NFSE_RECORRENTE). Não muda depois de criada
nomepara ativarAté 100 caracteres. Sem nome, a rotina não ativa (pendência “Dê um nome para a rotina.”)
periodicidadenãomensal (padrão), bimestral, trimestral, semestral ou anual
diasimDia da emissão, de 1 a 31, número ou texto. 29 a 31 vira o último dia do mês quando o mês é mais curto
iniciosimA partir de quando a rotina vale, AAAA-MM-DD
fimnãoÚltima data da vigência, AAAA-MM-DD. Não pode ser antes do inicio. null ou vazio = sem fim
ativarnãotrue: confere, grava e ativa. false: grava como rascunho, que não emite. Padrão true, menos no PUT de rotina pausada (veja Alterar)
parametrosconforme o modeloObjeto { "nome_do_campo": valor } com os campos do modelo. Campo que o modelo não tem é recusado

Valores dentro de parametros

Tipo do campo (tipo em /rotinas/modelos)Como enviar
CLIENTE, PRODUTO_SERVICOO id de GET /rotinas/clientes ou GET /rotinas/servicos (número ou texto)
VALOR, PERCENTUALNúmero JSON com ponto decimal (3500.5) ou texto no formato brasileiro ("3.500,50")
SIM_NAOtrue/false ou "S"/"N". Vazio vale "N"
DIASNúmero inteiro
LISTAUm dos valor de opcoes
DATAAAAA-MM-DD
TEXTO, TEXTO_LONGOTexto. TEXTO_LONGO aceita as variáveis indicadas na ajuda ({competencia}, {mes}, {ano}…)

Um campo com depende-de só vale quando o campo indicado tem o valor de depende-valor (por exemplo, os dias do boleto só valem com st_gerar_boleto em S).

Na resposta, os valores de parametros voltam como texto, do jeito que foram gravados. Um número com casas decimais é gravado com vírgula: 3500.5 volta "3500,5".

Modelos

Os modelos de hoje. O que vale para a sua empresa é sempre o que GET /rotinas/modelos devolve.

CódigoNomeObservação
NFSE_RECORRENTENota de serviço recorrenteO modelo genérico: mensalidade, consultoria, manutenção, assinatura
NFSE_ALUGUELAluguel de imóvelLocação tem caminho fiscal próprio. Enquanto a emissão de aluguel não estiver liberada na empresa, a rotina não ativa e a pendência explica o motivo
NFSE_CONDOMINIOTaxa de condomínioSó aparece para empresa marcada como condomínio edilício. O valor da nota é a soma das cobranças; não há campo de valor

Campos de cada modelo

CampoTipoRecorrenteAluguelCondomínio
id_cliforCLIENTEobrigatório (Cliente)obrigatório (Locatário)obrigatório (Condômino)
id_produtoPRODUTO_SERVICOobrigatório (Serviço)obrigatório (Item de locação)obrigatório (Serviço de condomínio, código 99.05.01)
vl_servicoVALORobrigatórioobrigatório (Valor do aluguel)—
st_reajusteSIM_NAOopcionalopcional—
cd_indice_reajusteLISTA (IPCA, IGPM, INPC, IGPDI, PERCENTUAL)com st_reajuste=Scom st_reajuste=S—
pe_reajustePERCENTUALcom cd_indice_reajuste=PERCENTUALcom cd_indice_reajuste=PERCENTUAL—
nr_meses_reajusteLISTA (12, 24, 6, 3)com st_reajuste=Scom st_reajuste=S—
dt_proximo_reajusteDATAcom st_reajuste=Scom st_reajuste=S—
ds_imovelTEXTO—opcional—
ds_unidadeTEXTO——opcional
nr_dia_vencimentoDIAS——obrigatório (1 a 31)
vl_taxa_ordinariaVALOR——obrigatório
vl_fundo_reservaVALOR——opcional
vl_outra_cobrancaVALOR——opcional
ds_outra_cobrancaTEXTO——obrigatória quando houver outra cobrança
vl_desconto_pontualidadeVALOR——opcional (desconto condicionado)
ds_discriminacaoTEXTO_LONGOopcionalopcional (aceita também {imovel})opcional (aceita também {unidade})
st_iss_retidoSIM_NAOopcional——
st_gerar_boletoSIM_NAOopcionalopcionalopcional
nr_dias_vencimento_boletoDIAScom st_gerar_boleto=Scom st_gerar_boleto=Scom st_gerar_boleto=S
vl_boletoVALORcom st_gerar_boleto=Scom st_gerar_boleto=Scom st_gerar_boleto=S

O código fiscal do serviço e a inscrição municipal vêm do cadastro do produto e da empresa. Quando falta algum dado de cadastro, ele aparece em pendencias.

Como a agenda funciona

  • O agendador roda a cada 15 minutos e emite as rotinas ativas cuja data chegou. A emissão sai às 08:00 do dia da agenda.
  • Dia 29 a 31 vira o último dia do mês nos meses mais curtos.
  • A primeira emissão é sempre no futuro. A rotina não emite sozinha mês que já passou nem o mês da criação quando o dia já tinha passado. Para emitir o mês atual, use emitir-agora.
  • Falha (cadastro incompleto, recusa da emissão) é tentada de novo no dia seguinte. Na 3ª falha seguida, a rotina é pausada (situacao: "pausada_por_falha"), com a causa em ultima-falha.
  • Competência já emitida não se repete, nem pelo agendador nem pelo emitir-agora.
  • Ao chegar à data fim, a rotina fica encerrada.

Situações

situacaoSignificado
ativaEmite sozinha nas datas da agenda
rascunhoGravada sem ativar. Não emite
pausadaPausada pelo usuário. Não emite até ser retomada
pausada_por_falhaPausada sozinha após 3 falhas seguidas. Corrija a causa e retome
encerradaCumpriu a vigência. Não pode ser alterada: crie outra rotina

Detalhe da rotina

GET /rotinas/{id} (e as respostas de criar, alterar, pausar e retomar) traz:

{
"status": "005",
"descricao": "Rotina consultada.",
"data": {
"rotina": {
"id-rotina": 418,
"nome": "Suporte mensal - ACME",
"modelo": "NFSE_RECORRENTE",
"situacao": "ativa",
"situacao-descricao": "ativa",
"periodicidade": "mensal",
"dia": 10,
"inicio": "2026-11-01",
"fim": null,
"proxima-emissao": "2026-12-10 08:00:00",
"ultima-emissao": null,
"emitidas": 0,
"falhas-seguidas": 0,
"ultima-falha": null,
"parametros": {
"id_clifor": "1262804",
"id_produto": "88231",
"vl_servico": "3.500,50",
"ds_discriminacao": "Suporte técnico de {competencia}"
},
"rotulos": { "id_clifor": "ACME SERVICOS LTDA — 12345678000199" },
"pendencias": [],
"diagnostico": "ATIVA e sem erro: a próxima emissão está agendada para 2026-12-10 08:00:00 (sempre às 08:00; dia 29–31 vira o último dia do mês). Ela NÃO emite mês que já passou nem o mês da criação quando o dia já tinha passado: para emitir o mês atual agora, use POST /rotinas/418/emitir-agora. Ainda não houve nenhuma emissão.",
"execucoes": []
}
},
"meta": { "request_id": "req_...", "timestamp": "...", "api_version": "3.17.0" }
}
CampoSignificado
situacao-descricaoA situação em texto (ativa, pausada por falha…)
proxima-emissao / ultima-emissaoData e hora (AAAA-MM-DD HH:MM:SS), ou null
emitidasQuantas competências já foram emitidas
falhas-seguidasFalhas consecutivas (na 3ª a rotina pausa)
ultima-falhaO motivo da última falha, ou null
parametrosOs campos do modelo, como foram gravados (texto)
rotulosO nome por trás dos ids, para exibir (hoje: o cliente, com o documento). Só vem quando há
pendenciasO que impede ativar, retomar ou emitir. Lista vazia = cadastro ok
diagnosticoTexto de por que a rotina emitiu ou não, e o que fazer, citando as rotas da API com o id da rotina (ex.: POST /rotinas/418/retomar). Feito para mostrar ao usuário
execucoesO histórico (veja abaixo)

GET /rotinas lista as rotinas com um resumo: id-rotina, nome, modelo, nome-modelo, situacao, situacao-descricao, periodicidade, periodicidade-descricao (ex.: “Todo mês, dia 10”), proxima-emissao, emitidas, ultima-falha e aceita-valor-extra.

Histórico (execucoes)

GET /rotinas/{id}/execucoes devolve as últimas 24 competências, da mais recente para a mais antiga (o mesmo que vem no detalhe):

{
"status": "005",
"descricao": "Histórico de emissões da rotina.",
"data": {
"execucoes": [
{
"competencia": "2026-12",
"prevista": "2026-12-10 08:00:00",
"executada": "2026-12-10 08:04:12",
"situacao": "E",
"situacao-descricao": "Enviada para emissão",
"valor": 3500.50,
"recibo": "a1b2c3d4e5f6...",
"retorno": "Nota enfileirada para emissão."
}
]
}
}
situacaosituacao-descricao
EEnviada para emissão (ou Já processada, quando a nota já existia)
FNão emitida. O motivo está em retorno
PAguardando (em processamento)
CCancelada

Acompanhar a NFS-e gerada

A rotina emite pelo mesmo caminho do POST /nfse/emissao: cada competência entra na fila da NFS-e e ganha um recibo. Enviada para emissão não quer dizer autorizada: o desfecho (autorizada ou rejeitada pela prefeitura) vem depois.

  • O recibo de cada competência está em execucoes[].recibo. Consulte o desfecho em GET /nfse/nota/{recibo}, como em qualquer NFS-e.
  • Cada competência usa o numero-origem ROT-<id>-<AAAA-MM> (ex.: ROT-418-2026-12). É essa chave que garante que a mesma competência nunca vira duas notas (veja Idempotência). Use-a para casar a nota com a rotina no seu sistema.

Conferir sem gravar

POST /rotinas/validar recebe o mesmo corpo da criação e devolve, sem gravar nada, pode-ativar e as pendencias que impediriam ativar:

{
"status": "005",
"descricao": "Rotina conferida.",
"data": {
"pode-ativar": false,
"pendencias": [
"Preencha \"Cliente\".",
"Informe um valor maior que zero."
]
}
}

Erro de formato (modelo desconhecido, dia fora de 1 a 31, data fora de AAAA-MM-DD, parâmetro que o modelo não tem) volta como 400 com data.campo, igual à criação.

Alterar

PUT /rotinas/{id} recebe os mesmos campos da criação, todos opcionais:

  • Parcial nos parâmetros: os campos de parametros que você não enviar continuam como estavam.
  • O modelo não muda. Enviar outro modelo é recusado (data.campo: "modelo"); crie outra rotina.
  • O padrão de ativar depende da situação da rotina:
    • rotina rascunho ou ativa: true. A alteração confere, grava e ativa, como na criação. Com pendência, nada é gravado;
    • rotina pausada: false. Alterar uma rotina pausada não a religa. Para religar, envie "ativar": true ou use retomar.
  • "ativar": false numa rotina ativa é recusado (400, data.campo: "ativar", “Rotina ativa não volta a rascunho. Para parar de emitir, use pausar.”). Para parar uma rotina ativa, use pausar.
  • Rotina encerrada não pode ser alterada.
Terminal window
curl -X PUT $BASE/rotinas/418 \
-H "Authorization: Token $TOKEN" \
-H "Content-Type: application/json" \
-d '{ "dia": 5, "parametros": { "vl_servico": 3800 } }'

A resposta é o detalhe atualizado, com status: "001".

DELETE /rotinas/{id} exclui a rotina (status: "001", “Rotina excluída.”, data.id-rotina com o id, número). Depois disso ela não aparece mais e as rotas por id respondem 500.

Pausar e retomar

  • POST /rotinas/{id}/pausar: só para rotina ativa. Ela para de emitir até ser retomada.
  • POST /rotinas/{id}/retomar: só para rotina pausada ou pausada_por_falha. Confere o cadastro antes (com pendência, não retoma e devolve 400 com data.pendencias) e recalcula a agenda para a próxima data: os meses que ficaram para trás não são emitidos. Para o mês atual, use emitir-agora depois de retomar.

Os dois devolvem o detalhe com status: "001".

Emitir agora

POST /rotinas/{id}/emitir-agora emite uma competência na hora, pelo mesmo caminho do agendador. Serve para emitir o mês atual (que a agenda não emite sozinha) e para tentar de novo uma competência que falhou. Só vale para rotina ativa.

Terminal window
curl -X POST $BASE/rotinas/418/emitir-agora \
-H "Authorization: Token $TOKEN" \
-H "Content-Type: application/json" \
-d '{ "competencia": "2026-11" }'

competencia no formato AAAA-MM. Corpo vazio (ou sem competencia) = o mês atual.

{
"status": "001",
"descricao": "Emissão enviada para a fila da NFS-e. Acompanhe pelo histórico da rotina.",
"data": {
"id-rotina": 418,
"competencia": "2026-11",
"numero-origem": "ROT-418-2026-11",
"mensagem": "Nota enfileirada para emissão."
}
}

A nota foi enfileirada, não autorizada. O recibo aparece em execucoes da rotina; acompanhe como em Acompanhar a NFS-e gerada. Competência já processada é recusada (400, “A competência 2026-11 já foi processada.”).

Valor extra em um mês

Um valor a mais na cobrança de um mês (ex.: uma visita técnica avulsa): entra na nota e no boleto daquela competência. O valor normal da rotina não muda, e o mês seguinte volta sozinho ao normal. Vale para os modelos em que o valor vem de um campo (recorrente e aluguel); a listagem indica isso em aceita-valor-extra.

Terminal window
curl -X PUT $BASE/rotinas/418/extras/2026-12 \
-H "Authorization: Token $TOKEN" \
-H "Content-Type: application/json" \
-d '{ "valor": 250, "motivo": "Visita técnica extra em 02/12" }'
CampoRegra
valorObrigatório. Maior que zero, até duas casas decimais. Número JSON (250.5) ou texto brasileiro ("250,50")
motivoDe 3 a 100 caracteres. Aparece na descrição da nota

Em rotina de um tipo que não aceita extra (como a de condomínio), a resposta é 400 “Este tipo de rotina não aceita valor extra.”

Regras: só em rotina ativa; só nos próximos meses de emissão da agenda (a lista está em competencias-disponiveis); e não dá para lançar, trocar ou remover o extra de um mês cuja nota já foi emitida ou está em emissão.

GET /rotinas/{id}/extras (e as respostas do PUT e do DELETE):

{
"status": "005",
"descricao": "Valores extras da rotina.",
"data": {
"extras": [
{
"competencia": "2026-12",
"valor": 250.00,
"motivo": "Visita técnica extra em 02/12",
"situacao": "Programado",
"pode-alterar": true
}
],
"competencias-disponiveis": ["2026-12", "2027-01", "2027-02"]
}
}

situacao do extra: Programado, Em emissão, Aplicado, Aguardando nova tentativa ou Não aplicado. DELETE /rotinas/{id}/extras/{AAAA-MM} remove o extra do mês.

Erros

Todas as respostas são HTTP 200, com o resultado em status, como no resto da v3. A exceção são as falhas de autenticação (401/403) e o limite de consumo (429).

statusQuandoO que fazer
005Leitura (GET) e POST /rotinas/validarLeia data
001Gravação ou ação concluída (criar, alterar, excluir, pausar, retomar, emitir agora, extras)Leia data
400Campo fora do formato (data.campo), regra do módulo (ex.: pausar rotina que não está ativa), pendências que impedem ativar ou retomar (data.pendencias), chave sem permissão fiscal ou JSON inválidoCorrija o que a descricao e o data indicam. Repetir igual não resolve
500Rotina não encontrada nesta empresa (ou excluída)Confira o id em GET /rotinas
999Falha interna ao falar com o módulo de rotinasTente de novo em instantes. Cite o meta.request_id no suporte se persistir

data.campo traz o campo da entrada (dia, inicio, fim, modelo, periodicidade, ativar, competencia, valor, busca). Para um parâmetro do modelo, vem parametros.<nome>, com o nome como o modelo declara (ex.: parametros.id_clifor).

Exemplos:

{
"status": "400",
"descricao": "A rotina não foi ativada: corrija as pendências.",
"data": { "pendencias": ["Preencha \"Cliente\".", "Dê um nome para a rotina."] }
}
{
"status": "400",
"descricao": "Campo inválido: parametros.vl_aluguel (Este modelo não tem esse parâmetro. Veja GET /rotinas/modelos.).",
"data": { "campo": "parametros.vl_aluguel" }
}
{
"status": "500",
"descricao": "Rotina não encontrada nesta empresa."
}

Limites

ItemLimite
nome100 caracteres
busca (clientes)2 a 60 caracteres; até 50 clientes ativos por busca, por nome ou documento
GET /rotinas/servicosAté 300 serviços ativos
HistóricoÚltimas 24 competências
Valor extraMaior que zero, até R$ 9.999.999,99; motivo de 3 a 100 caracteres

As chamadas contam no mesmo limite de consumo das demais rotas da v3.