Recorrência de NFS-e

Listar as recorrências

GET https://apifiscal.weesy.com.br/v1/recorrencias

Mais recente primeiro. Cada item vem completo, com as ocorrências.

Parâmetros

Nome	Onde	Tipo	Descrição
cnpjEmitente obrigatório	query	string
situacao	query	string	Valores: `ativa`, `pausada`, `concluida`, `cancelada`.
data	query	string (date)	Só as que têm uma ocorrência com essa data prevista.
limite	query	integer
cursor	query	string	Para pegar a próxima página, repasse o `paginacao.proximoCursor` da resposta anterior.

Exemplo de chamada

cURLcurl --request GET \
  --url "https://apifiscal.weesy.com.br/v1/recorrencias?cnpjEmitente=21664333000195" \
  --header "Authorization: Bearer $WEESY_TOKEN"

Node.jsconst resposta = await fetch("https://apifiscal.weesy.com.br/v1/recorrencias?cnpjEmitente=21664333000195", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.WEESY_TOKEN}`,
  },
});
console.log(resposta.status, await resposta.text());

Pythonimport os

import requests

resposta = requests.get(
    "https://apifiscal.weesy.com.br/v1/recorrencias?cnpjEmitente=21664333000195",
    headers={"Authorization": f"Bearer {os.environ['WEESY_TOKEN']}"},
    timeout=30,
)
print(resposta.status_code, resposta.text)

PHP<?php

$contexto = stream_context_create(["http" => [
    "method" => "GET",
    "header" => implode("\r\n", ["Authorization: Bearer " . getenv("WEESY_TOKEN")]),
    "ignore_errors" => true, // lê o corpo também nas respostas de erro
]]);
$resposta = file_get_contents("https://apifiscal.weesy.com.br/v1/recorrencias?cnpjEmitente=21664333000195", false, $contexto);
echo $http_response_header[0], PHP_EOL, $resposta, PHP_EOL;

C#using System.Net.Http.Headers;

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

using var resposta = await http.GetAsync("https://apifiscal.weesy.com.br/v1/recorrencias?cnpjEmitente=21664333000195");
Console.WriteLine($"{(int)resposta.StatusCode} {await resposta.Content.ReadAsStringAsync()}");

Respostas

200: Página de recorrências.
400: Algum dado está errado ou faltando. A lista erros diz qual campo e o que corrigir (code = validacao). (formato de erro)
401: Token ausente, errado ou revogado (credencialinvalida). Confira o cabeçalho Authorization. (formato de erro)

Campos da resposta 200

Campo Tipo Descrição

dados
obrigatório array de object

dados[].id
obrigatório

string

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

dados[].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.

dados[].situacao
obrigatório

string

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

Valores: ativa, pausada, concluida, cancelada.

dados[].periodicidade
obrigatório

string

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

dados[].quantidade
obrigatório integer

dados[].primeiraData
obrigatório string (date)

dados[].proximaData

string (date) ou null

A menor data prevista entre as programadas.

dados[].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.

dados[].modelo.cnpjEmitente

string

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

dados[].modelo.servico
obrigatório

object

Um dos dois — id ou codigo.

dados[].modelo.servico.id integer

dados[].modelo.servico.codigo

string

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

dados[].modelo.valorServico
obrigatório

number

Valor bruto do serviço prestado.

dados[].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.

dados[].modelo.competencia

string (date)

Padrão = data da emissão.

dados[].modelo.municipioPrestacao

string

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

dados[].modelo.tomador
obrigatório

object

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

dados[].modelo.tomador.tipoPessoa
obrigatório

string

Indica o tipo de pessoa do tomador.

Valores: F, J.

dados[].modelo.tomador.cpfCnpj
obrigatório

string

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

dados[].modelo.tomador.nome
obrigatório

string

Nome completo ou razão social do tomador.

dados[].modelo.tomador.inscricaoMunicipal

string

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

dados[].modelo.tomador.email

string (email)

E-mail do tomador.

dados[].modelo.tomador.telefone

string

Telefone de contato do tomador.

dados[].modelo.tomador.endereco
obrigatório

object

Endereço do tomador.

dados[].modelo.tomador.endereco.cep
obrigatório

string

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

dados[].modelo.tomador.endereco.logradouro
obrigatório

string

Tipo e nome do logradouro.

dados[].modelo.tomador.endereco.numero
obrigatório

string

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

dados[].modelo.tomador.endereco.complemento

string

Complemento do endereço, quando aplicável.

dados[].modelo.tomador.endereco.bairro
obrigatório

string

Bairro do endereço.

dados[].modelo.tomador.endereco.codigoIbge
obrigatório

string

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

dados[].modelo.destinatario

object

Quando diferente do tomador (indDest = 1).

dados[].modelo.destinatario.tipoPessoa
obrigatório

string

Indica o tipo de pessoa do tomador.

Valores: F, J.

dados[].modelo.destinatario.cpfCnpj
obrigatório

string

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

dados[].modelo.destinatario.nome
obrigatório

string

Nome completo ou razão social do tomador.

dados[].modelo.destinatario.inscricaoMunicipal

string

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

dados[].modelo.destinatario.email

string (email)

E-mail do tomador.

dados[].modelo.destinatario.telefone

string

Telefone de contato do tomador.

dados[].modelo.destinatario.endereco
obrigatório

object

Endereço do tomador.

dados[].modelo.destinatario.endereco.cep
obrigatório

string

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

dados[].modelo.destinatario.endereco.logradouro
obrigatório

string

Tipo e nome do logradouro.

dados[].modelo.destinatario.endereco.numero
obrigatório

string

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

dados[].modelo.destinatario.endereco.complemento

string

Complemento do endereço, quando aplicável.

dados[].modelo.destinatario.endereco.bairro
obrigatório

string

Bairro do endereço.

dados[].modelo.destinatario.endereco.codigoIbge
obrigatório

string

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

dados[].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.

dados[].modelo.imovel.cib
obrigatório

string

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

dados[].modelo.imovel.inscricaoImobiliaria

string ou null

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

dados[].modelo.imovel.endereco
obrigatório

object

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

dados[].modelo.imovel.endereco.cep
obrigatório

string

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

dados[].modelo.imovel.endereco.logradouro
obrigatório

string

Tipo e nome do logradouro.

dados[].modelo.imovel.endereco.numero
obrigatório

string

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

dados[].modelo.imovel.endereco.complemento

string

Complemento do endereço, quando aplicável.

dados[].modelo.imovel.endereco.bairro
obrigatório

string

Bairro do endereço.

dados[].modelo.imovel.endereco.codigoIbge
obrigatório

string

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

dados[].modelo.issRetido

boolean

Padrão = o do serviço.

dados[].modelo.aliquotaSimples

number

Obrigatória para Simples com retenção.

dados[].modelo.consumoPessoal

boolean

Padrão = o do serviço.

dados[].modelo.deducoes

number

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

dados[].modelo.descontoIncondicionado

number

Desconto concedido sem condição.

dados[].modelo.descontoCondicionado

number

Desconto vinculado a condição.

dados[].modelo.outrasRetencoes

number

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

dados[].modelo.retencoesFederais

object

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

dados[].modelo.retencoesFederais.pis

number

Valor da retenção de PIS.

dados[].modelo.retencoesFederais.cofins

number

Valor da retenção de COFINS.

dados[].modelo.retencoesFederais.csll

number

Valor da retenção de CSLL.

dados[].modelo.retencoesFederais.ir

number

Valor da retenção de Imposto de Renda.

dados[].modelo.retencoesFederais.inss

number

Valor da retenção de INSS.

dados[].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.

dados[].modelo.servicoDescricao string ou null

dados[].ocorrencias
obrigatório array de object

dados[].ocorrencias[].numero
obrigatório integer

dados[].ocorrencias[].dataPrevista
obrigatório

string (date)

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

dados[].ocorrencias[].valor
obrigatório

number

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

dados[].ocorrencias[].valorEditado
obrigatório

boolean

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

dados[].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.

dados[].ocorrencias[].emitirAgora
obrigatório

boolean

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

dados[].ocorrencias[].idIntegracao

string ou null

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

dados[].ocorrencias[].avisadaEm

string (date-time) ou null

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

dados[].ocorrencias[].motivoImpedimento

object ou null

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

dados[].ocorrencias[].motivoImpedimento.code string

dados[].ocorrencias[].motivoImpedimento.mensagem string

dados[].ocorrencias[].nota

object ou null

A nota emitida, lida na hora.

dados[].ocorrencias[].nota.id

string

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

dados[].ocorrencias[].nota.numero

string ou null

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

dados[].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

dados[].ocorrencias[].falha

object ou null

Por que não saiu.

dados[].ocorrencias[].falha.code string

dados[].ocorrencias[].falha.mensagem string

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

dados[].ocorrencias[].avisoVespera

string

Só na resposta de Editar data ou valor.

Valores: com_aviso, sem_aviso.

dados[].ocorrencias[].mensagem

string

Só na resposta de Emitir agora.

dados[].criadaEm
obrigatório string (date-time)

dados[].alteradaEm
obrigatório string (date-time)

dados[].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).

dados[].alertas[].code
obrigatório string

dados[].alertas[].mensagem
obrigatório string

dados[].alertas[].bloqueante
obrigatório boolean

paginacao
obrigatório

object

Como pegar a próxima página. Enquanto temMais for true, chame a mesma rota passando cursor=<proximoCursor>. A lista vem da atualização mais recente para a mais antiga, e o cursor vale por 24 horas. Registros criados enquanto você pagina não bagunçam as páginas: eles aparecem numa nova consulta.

paginacao.limite
obrigatório

integer

Quantos registros vêm por página (padrão 50, máximo 100).

paginacao.proximoCursor

string ou null

Código da próxima página. Repasse como veio, sem alterar — ele já leva os filtros. null quando acabou.

paginacao.temMais
obrigatório

boolean

true se ainda há mais páginas.

← Voltar ao início