Recorrência de NFS-e

Consultar uma recorrência

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

A recorrência com as ocorrências. Em cada ocorrência emitida, nota traz o número e a situação atuais da nota.

Parâmetros

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

Exemplo de chamada

cURLcurl --request GET \
  --url "https://apifiscal.weesy.com.br/v1/recorrencias/6ade6278e8340a492a46b564" \
  --header "Authorization: Bearer $WEESY_TOKEN"

Node.jsconst resposta = await fetch("https://apifiscal.weesy.com.br/v1/recorrencias/6ade6278e8340a492a46b564", {
  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/6ade6278e8340a492a46b564",
    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/6ade6278e8340a492a46b564", 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/6ade6278e8340a492a46b564");
Console.WriteLine($"{(int)resposta.StatusCode} {await resposta.Content.ReadAsStringAsync()}");

Respostas

200: A recorrência.
401: Token ausente, errado ou revogado (credencialinvalida). Confira o cabeçalho Authorization. (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)

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