Recorrência de NFS-e

Editar o modelo

PUT https://apifiscal.weesy.com.br/v1/recorrencias/{id}/modelo

Troca o modelo das ocorrências programada (recorrência ativa ou pausada). As que tiveram o valor editado (valorEditado = true) mantêm o valor; as outras recebem o novo valorServico. As já emitidas não mudam. Mesmas validações e prévia da criação (a prévia usa a próxima data).

Parâmetros

Nome	Onde	Tipo	Descrição
id obrigatório	caminho	string

Exemplo de chamada

cURLcurl --request PUT \
  --url "https://apifiscal.weesy.com.br/v1/recorrencias/6ade6278e8340a492a46b564/modelo" \
  --header "Authorization: Bearer $WEESY_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "modelo": {
    "servico": "<servico>",
    "valorServico": {},
    "tomador": {
      "tipoPessoa": "F",
      "cpfCnpj": "<cpfCnpj>",
      "nome": "<nome>",
      "endereco": {
        "cep": "01001000",
        "logradouro": "<logradouro>",
        "numero": "<numero>",
        "bairro": "<bairro>",
        "codigoIbge": "3547809"
      }
    }
  }
}'

Node.jsconst resposta = await fetch("https://apifiscal.weesy.com.br/v1/recorrencias/6ade6278e8340a492a46b564/modelo", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.WEESY_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "modelo": {
      "servico": "<servico>",
      "valorServico": {},
      "tomador": {
        "tipoPessoa": "F",
        "cpfCnpj": "<cpfCnpj>",
        "nome": "<nome>",
        "endereco": {
          "cep": "01001000",
          "logradouro": "<logradouro>",
          "numero": "<numero>",
          "bairro": "<bairro>",
          "codigoIbge": "3547809"
        }
      }
    }
  }),
});
console.log(resposta.status, await resposta.text());

Pythonimport os

import requests

resposta = requests.put(
    "https://apifiscal.weesy.com.br/v1/recorrencias/6ade6278e8340a492a46b564/modelo",
    headers={"Authorization": f"Bearer {os.environ['WEESY_TOKEN']}"},
    json={
        "modelo": {
            "servico": "<servico>",
            "valorServico": {},
            "tomador": {
                "tipoPessoa": "F",
                "cpfCnpj": "<cpfCnpj>",
                "nome": "<nome>",
                "endereco": {
                    "cep": "01001000",
                    "logradouro": "<logradouro>",
                    "numero": "<numero>",
                    "bairro": "<bairro>",
                    "codigoIbge": "3547809",
                },
            },
        },
    },
    timeout=30,
)
print(resposta.status_code, resposta.text)

PHP<?php

$corpo = <<<'JSON'
{
  "modelo": {
    "servico": "<servico>",
    "valorServico": {},
    "tomador": {
      "tipoPessoa": "F",
      "cpfCnpj": "<cpfCnpj>",
      "nome": "<nome>",
      "endereco": {
        "cep": "01001000",
        "logradouro": "<logradouro>",
        "numero": "<numero>",
        "bairro": "<bairro>",
        "codigoIbge": "3547809"
      }
    }
  }
}
JSON;

$contexto = stream_context_create(["http" => [
    "method" => "PUT",
    "header" => implode("\r\n", ["Authorization: Bearer " . getenv("WEESY_TOKEN"), "Content-Type: application/json"]),
    "content" => $corpo,
    "ignore_errors" => true, // lê o corpo também nas respostas de erro
]]);
$resposta = file_get_contents("https://apifiscal.weesy.com.br/v1/recorrencias/6ade6278e8340a492a46b564/modelo", false, $contexto);
echo $http_response_header[0], PHP_EOL, $resposta, PHP_EOL;

C#using System.Net.Http.Headers;
using System.Text;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("WEESY_TOKEN"));

var corpo = """
    {
      "modelo": {
        "servico": "<servico>",
        "valorServico": {},
        "tomador": {
          "tipoPessoa": "F",
          "cpfCnpj": "<cpfCnpj>",
          "nome": "<nome>",
          "endereco": {
            "cep": "01001000",
            "logradouro": "<logradouro>",
            "numero": "<numero>",
            "bairro": "<bairro>",
            "codigoIbge": "3547809"
          }
        }
      }
    }
    """;

using var resposta = await http.PutAsync(
    "https://apifiscal.weesy.com.br/v1/recorrencias/6ade6278e8340a492a46b564/modelo",
    new StringContent(corpo, Encoding.UTF8, "application/json"));
Console.WriteLine($"{(int)resposta.StatusCode} {await resposta.Content.ReadAsStringAsync()}");

Corpo da requisição

Campo	Tipo	Descrição
modelo obrigatório	object	Os campos da emissão que se repetem em todas as notas, sem `competencia`, `idIntegracao` e `ambiente`. `valorServico` é o valor base das ocorrências. `servicoDescricao` é preenchido pela Weesy (o nome do serviço no cadastro), só para exibir.
modelo.cnpjEmitente	string	CNPJ da empresa responsável pela NFS-e. Precisa ser uma empresa da sua conta.
modelo.servico obrigatório	object	Um dos dois — `id` ou `codigo`.
modelo.servico.id	integer
modelo.servico.codigo	string	Código do integrador no cadastro, quando ele usa a própria codificação de serviços (ex.: `010902220`).
modelo.valorServico obrigatório	number	Valor bruto do serviço prestado.
modelo.discriminacao	string	Padrão = discriminação do serviço. Limite do padrão do município (1000 em Barueri e Nacional, 2000 nos outros) — acima disso é recusada, não truncada.
modelo.competencia	string (date)	Padrão = data da emissão.
modelo.municipioPrestacao	string	Município em que o serviço foi prestado, quando informado.
modelo.tomador obrigatório	object	Dados de identificação do tomador do serviço.
modelo.tomador.tipoPessoa obrigatório	string	Indica o tipo de pessoa do tomador. Valores: `F`, `J`.
modelo.tomador.cpfCnpj obrigatório	string	CPF ou CNPJ do tomador, sem pontuação.
modelo.tomador.nome obrigatório	string	Nome completo ou razão social do tomador.
modelo.tomador.inscricaoMunicipal	string	Inscrição municipal do tomador, quando aplicável.
modelo.tomador.email	string (email)	E-mail do tomador.
modelo.tomador.telefone	string	Telefone de contato do tomador.
modelo.tomador.endereco obrigatório	object	Endereço do tomador.
modelo.tomador.endereco.cep obrigatório	string	CEP do endereço, sem pontuação.
modelo.tomador.endereco.logradouro obrigatório	string	Tipo e nome do logradouro.
modelo.tomador.endereco.numero obrigatório	string	Número do endereço. Sem número? Mande `S/N`.
modelo.tomador.endereco.complemento	string	Complemento do endereço, quando aplicável.
modelo.tomador.endereco.bairro obrigatório	string	Bairro do endereço.
modelo.tomador.endereco.codigoIbge obrigatório	string	Código IBGE do município do endereço.
modelo.destinatario	object	Quando diferente do tomador (indDest = 1).
modelo.destinatario.tipoPessoa obrigatório	string	Indica o tipo de pessoa do tomador. Valores: `F`, `J`.
modelo.destinatario.cpfCnpj obrigatório	string	CPF ou CNPJ do tomador, sem pontuação.
modelo.destinatario.nome obrigatório	string	Nome completo ou razão social do tomador.
modelo.destinatario.inscricaoMunicipal	string	Inscrição municipal do tomador, quando aplicável.
modelo.destinatario.email	string (email)	E-mail do tomador.
modelo.destinatario.telefone	string	Telefone de contato do tomador.
modelo.destinatario.endereco obrigatório	object	Endereço do tomador.
modelo.destinatario.endereco.cep obrigatório	string	CEP do endereço, sem pontuação.
modelo.destinatario.endereco.logradouro obrigatório	string	Tipo e nome do logradouro.
modelo.destinatario.endereco.numero obrigatório	string	Número do endereço. Sem número? Mande `S/N`.
modelo.destinatario.endereco.complemento	string	Complemento do endereço, quando aplicável.
modelo.destinatario.endereco.bairro obrigatório	string	Bairro do endereço.
modelo.destinatario.endereco.codigoIbge obrigatório	string	Código IBGE do município do endereço.
modelo.imovel	object	Imóvel da operação — obrigatório com cIndOp `02xxxx` (operação com bem imóvel). Campos do grupo `imovel` do leiaute nacional.
modelo.imovel.cib obrigatório	string	Código do Cadastro Imobiliário Brasileiro (`cCIB`).
modelo.imovel.inscricaoImobiliaria	string ou null	Inscrição imobiliária fiscal no município (`inscImobFisc`), quando houver.
modelo.imovel.endereco obrigatório	object	Endereço para enviar. Não precisa mandar cidade nem UF — tiramos do código IBGE.
modelo.imovel.endereco.cep obrigatório	string	CEP do endereço, sem pontuação.
modelo.imovel.endereco.logradouro obrigatório	string	Tipo e nome do logradouro.
modelo.imovel.endereco.numero obrigatório	string	Número do endereço. Sem número? Mande `S/N`.
modelo.imovel.endereco.complemento	string	Complemento do endereço, quando aplicável.
modelo.imovel.endereco.bairro obrigatório	string	Bairro do endereço.
modelo.imovel.endereco.codigoIbge obrigatório	string	Código IBGE do município do endereço.
modelo.issRetido	boolean	Padrão = o do serviço.
modelo.aliquotaSimples	number	Obrigatória para Simples com retenção.
modelo.consumoPessoal	boolean	Padrão = o do serviço.
modelo.deducoes	number	Valor das deduções aplicado à prestação.
modelo.descontoIncondicionado	number	Desconto concedido sem condição.
modelo.descontoCondicionado	number	Desconto vinculado a condição.
modelo.outrasRetencoes	number	Valor de outras retenções informadas na prestação.
modelo.retencoesFederais	object	Valores de retenções federais informados na emissão.
modelo.retencoesFederais.pis	number	Valor da retenção de PIS.
modelo.retencoesFederais.cofins	number	Valor da retenção de COFINS.
modelo.retencoesFederais.csll	number	Valor da retenção de CSLL.
modelo.retencoesFederais.ir	number	Valor da retenção de Imposto de Renda.
modelo.retencoesFederais.inss	number	Valor da retenção de INSS.
modelo.enviarEmail	boolean	Quando verdadeiro, solicita o envio da nota por e-mail após o processamento previsto. O valor padrão do contrato é `true`.
modelo.servicoDescricao	string ou null

Respostas

200: A recorrência, com alertas.
400: Algum dado está errado ou faltando. A lista erros diz qual campo e o que corrigir (code = validacao). (formato de erro)
404: Não encontrado. Pode ser que não exista ou que pertença a outra empresa — por segurança, os dois casos respondem igual. (formato de erro)
409: A ação não vale na situação atual. O code diz o motivo: - recorrenciasituacaoinvalida — a recorrência está cancelada, concluída ou na situação errada para a ação; - recorrenciapausada — Emitir agora com a recorrência pausada (retome antes); - ocorrenciasituacaoinvalida — a ocorrência não está numa situação que aceita a ação; - prazoencerrado — o pulo só pode ser desfeito até 07:59 do dia da data prevista; - ocorrenciadataemconflito — outra ocorrência programada ocupa a data. (formato de erro)

Campos da resposta 200

Campo Tipo Descrição

id
obrigatório

string

O id que a Weesy dá ao documento. Guarde como texto e não tente interpretar.

cnpjEmitente
obrigatório

string

CNPJ sem pontos, barra ou traço (14 posições). Já aceita o CNPJ com letras, que começa a valer em 2026.

situacao
obrigatório

string

ativa (inicial); pausada (não emite); concluida (nenhuma ocorrência programada sobrou); cancelada (final).

Valores: ativa, pausada, concluida, cancelada.

periodicidade
obrigatório

string

Valores: semanal, quinzenal, mensal, bimestral, trimestral, semestral, anual.

quantidade
obrigatório integer

primeiraData
obrigatório string (date)

proximaData

string (date) ou null

A menor data prevista entre as programadas.

modelo
obrigatório

object

Os campos da emissão que se repetem em todas as notas, sem competencia, idIntegracao e ambiente. valorServico é o valor base das ocorrências. servicoDescricao é preenchido pela Weesy (o nome do serviço no cadastro), só para exibir.

modelo.cnpjEmitente

string

CNPJ da empresa responsável pela NFS-e. Precisa ser uma empresa da sua conta.

modelo.servico
obrigatório

object

Um dos dois — id ou codigo.

modelo.servico.id integer

modelo.servico.codigo

string

Código do integrador no cadastro, quando ele usa a própria codificação de serviços (ex.: 010902220).

modelo.valorServico
obrigatório

number

Valor bruto do serviço prestado.

modelo.discriminacao

string

Padrão = discriminação do serviço. Limite do padrão do município (1000 em Barueri e Nacional, 2000 nos outros) — acima disso é recusada, não truncada.

modelo.competencia

string (date)

Padrão = data da emissão.

modelo.municipioPrestacao

string

Município em que o serviço foi prestado, quando informado.

modelo.tomador
obrigatório

object

Dados de identificação do tomador do serviço.

modelo.tomador.tipoPessoa
obrigatório

string

Indica o tipo de pessoa do tomador.

Valores: F, J.

modelo.tomador.cpfCnpj
obrigatório

string

CPF ou CNPJ do tomador, sem pontuação.

modelo.tomador.nome
obrigatório

string

Nome completo ou razão social do tomador.

modelo.tomador.inscricaoMunicipal

string

Inscrição municipal do tomador, quando aplicável.

modelo.tomador.email

string (email)

E-mail do tomador.

modelo.tomador.telefone

string

Telefone de contato do tomador.

modelo.tomador.endereco
obrigatório

object

Endereço do tomador.

modelo.tomador.endereco.cep
obrigatório

string

CEP do endereço, sem pontuação.

modelo.tomador.endereco.logradouro
obrigatório

string

Tipo e nome do logradouro.

modelo.tomador.endereco.numero
obrigatório

string

Número do endereço. Sem número? Mande S/N.

modelo.tomador.endereco.complemento

string

Complemento do endereço, quando aplicável.

modelo.tomador.endereco.bairro
obrigatório

string

Bairro do endereço.

modelo.tomador.endereco.codigoIbge
obrigatório

string

Código IBGE do município do endereço.

modelo.destinatario

object

Quando diferente do tomador (indDest = 1).

modelo.destinatario.tipoPessoa
obrigatório

string

Indica o tipo de pessoa do tomador.

Valores: F, J.

modelo.destinatario.cpfCnpj
obrigatório

string

CPF ou CNPJ do tomador, sem pontuação.

modelo.destinatario.nome
obrigatório

string

Nome completo ou razão social do tomador.

modelo.destinatario.inscricaoMunicipal

string

Inscrição municipal do tomador, quando aplicável.

modelo.destinatario.email

string (email)

E-mail do tomador.

modelo.destinatario.telefone

string

Telefone de contato do tomador.

modelo.destinatario.endereco
obrigatório

object

Endereço do tomador.

modelo.destinatario.endereco.cep
obrigatório

string

CEP do endereço, sem pontuação.

modelo.destinatario.endereco.logradouro
obrigatório

string

Tipo e nome do logradouro.

modelo.destinatario.endereco.numero
obrigatório

string

Número do endereço. Sem número? Mande S/N.

modelo.destinatario.endereco.complemento

string

Complemento do endereço, quando aplicável.

modelo.destinatario.endereco.bairro
obrigatório

string

Bairro do endereço.

modelo.destinatario.endereco.codigoIbge
obrigatório

string

Código IBGE do município do endereço.

modelo.imovel

object

Imóvel da operação — obrigatório com cIndOp 02xxxx (operação com bem imóvel). Campos do grupo imovel do leiaute nacional.

modelo.imovel.cib
obrigatório

string

Código do Cadastro Imobiliário Brasileiro (cCIB).

modelo.imovel.inscricaoImobiliaria

string ou null

Inscrição imobiliária fiscal no município (inscImobFisc), quando houver.

modelo.imovel.endereco
obrigatório

object

Endereço para enviar. Não precisa mandar cidade nem UF — tiramos do código IBGE.

modelo.imovel.endereco.cep
obrigatório

string

CEP do endereço, sem pontuação.

modelo.imovel.endereco.logradouro
obrigatório

string

Tipo e nome do logradouro.

modelo.imovel.endereco.numero
obrigatório

string

Número do endereço. Sem número? Mande S/N.

modelo.imovel.endereco.complemento

string

Complemento do endereço, quando aplicável.

modelo.imovel.endereco.bairro
obrigatório

string

Bairro do endereço.

modelo.imovel.endereco.codigoIbge
obrigatório

string

Código IBGE do município do endereço.

modelo.issRetido

boolean

Padrão = o do serviço.

modelo.aliquotaSimples

number

Obrigatória para Simples com retenção.

modelo.consumoPessoal

boolean

Padrão = o do serviço.

modelo.deducoes

number

Valor das deduções aplicado à prestação.

modelo.descontoIncondicionado

number

Desconto concedido sem condição.

modelo.descontoCondicionado

number

Desconto vinculado a condição.

modelo.outrasRetencoes

number

Valor de outras retenções informadas na prestação.

modelo.retencoesFederais

object

Valores de retenções federais informados na emissão.

modelo.retencoesFederais.pis

number

Valor da retenção de PIS.

modelo.retencoesFederais.cofins

number

Valor da retenção de COFINS.

modelo.retencoesFederais.csll

number

Valor da retenção de CSLL.

modelo.retencoesFederais.ir

number

Valor da retenção de Imposto de Renda.

modelo.retencoesFederais.inss

number

Valor da retenção de INSS.

modelo.enviarEmail

boolean

Quando verdadeiro, solicita o envio da nota por e-mail após o processamento previsto. O valor padrão do contrato é true.

modelo.servicoDescricao string ou null

ocorrencias
obrigatório array de object

ocorrencias[].numero
obrigatório integer

ocorrencias[].dataPrevista
obrigatório

string (date)

O dia (Brasília) em que a nota sai, às 08:00; vira a competencia da nota.

ocorrencias[].valor
obrigatório

number

Valor em reais, como número com 2 casas decimais (ex. 100.00). Não mande como texto.

ocorrencias[].valorEditado
obrigatório

boolean

O valor foi mudado à mão e não acompanha o valor do modelo.

ocorrencias[].situacao
obrigatório

string

programada — vai ser emitida às 08:00 da data prevista;
emitida — a nota foi criada (acompanhe a nota em nota); final;
falhou — a emissão foi recusada (motivo em falha); não tentamos de novo sozinhos — corrija e use Emitir agora;
pulada — não será emitida (dá para desfazer até 07:59 do dia);
perdida — passou de 3 dias da data prevista sem emitir; use Emitir agora se ainda quiser a nota;
cancelada — a recorrência foi cancelada; final.

Valores: programada, emitida, falhou, pulada, perdida, cancelada.

ocorrencias[].emitirAgora
obrigatório

boolean

Marcada por Emitir agora; sai na próxima execução (até 5 min).

ocorrencias[].idIntegracao

string ou null

O da nota desta ocorrência: rec-{id}-{numero} ou rec-{id}-{numero}-m{k}.

ocorrencias[].avisadaEm

string (date-time) ou null

Quando entrou no aviso da véspera (só empresas do ERP Weesy).

ocorrencias[].motivoImpedimento

object ou null

O que impediria a emissão, visto na véspera.

ocorrencias[].motivoImpedimento.code string

ocorrencias[].motivoImpedimento.mensagem string

ocorrencias[].nota

object ou null

A nota emitida, lida na hora.

ocorrencias[].nota.id

string

O id que a Weesy dá ao documento. Guarde como texto e não tente interpretar.

ocorrencias[].nota.numero

string ou null

Número da NFS-e; nulo até autorizar.

ocorrencias[].nota.status

string

Em que pé está a nota. Novos valores podem aparecer: trate valor desconhecido sem quebrar.

Valor	O que quer dizer	O que fazer
`recebida`	Recebemos a nota e vamos enviar à prefeitura	Aguardar
`em_processamento`	Enviada à prefeitura, aguardando a resposta	Aguardar
`autorizada`	A prefeitura autorizou — a nota tem número e código de verificação	Pronto: baixe o PDF e o XML
`rejeitada`	A prefeitura recusou por algum dado errado	Leia o motivo em `mensagens`, corrija e emita de novo com o mesmo `idIntegracao`
`erro`	Não conseguimos falar com a prefeitura (fora do ar, demora)	Tentar emitir de novo
`cancelamento_solicitado`	Pedimos o cancelamento, aguardando a prefeitura	Aguardar
`cancelada`	A prefeitura cancelou a nota	—
`cancelamento_rejeitado`	A prefeitura recusou o cancelamento — a nota continua valendo	Leia o motivo; às vezes é preciso cancelar no site da prefeitura

Valor	Significado
`recebida`	Recebemos a nota e vamos enviar à prefeitura
`em_processamento`	Enviada à prefeitura, aguardando a resposta
`autorizada`	Autorizada pela prefeitura
`rejeitada`	Recusada pela prefeitura — corrija e emita de novo
`erro`	Não conseguimos falar com a prefeitura — tente de novo
`cancelamento_solicitado`	Cancelamento pedido, aguardando a prefeitura
`cancelada`	Cancelada pela prefeitura
`cancelamento_rejeitado`	A prefeitura recusou o cancelamento

ocorrencias[].falha

object ou null

Por que não saiu.

ocorrencias[].falha.code string

ocorrencias[].falha.mensagem string

ocorrencias[].falha.em string (date-time)

ocorrencias[].avisoVespera

string

Só na resposta de Editar data ou valor.

Valores: com_aviso, sem_aviso.

ocorrencias[].mensagem

string

Só na resposta de Emitir agora.

criadaEm
obrigatório string (date-time)

alteradaEm
obrigatório string (date-time)

alertas

array de object

Só na criação e na edição do modelo — os avisos da prévia (bloqueante não impediu gravar, mas impede emitir).

alertas[].code
obrigatório string

alertas[].mensagem
obrigatório string

alertas[].bloqueante
obrigatório boolean

← Voltar ao início