Emitir e consultar NFS-e

Listar NFS-e

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

Lista as notas, com filtros por empresa, período e situação. Para manter o seu sistema em dia, use atualizadoDesde e atualize as notas pelo id.

Parâmetros

Nome	Onde	Tipo	Descrição
cnpjEmitente	query	string	CNPJ da empresa. Obrigatório para integradores, que têm várias empresas.
status	query	array de string
numero	query	string
tomador	query	string	CPF ou CNPJ do tomador.
competenciaDe	query	string (date)
competenciaAte	query	string (date)
ambiente	query	string	Valores: `simulacao`, `homologacao`, `producao`.
atualizadoDesde	query	string (date-time)	Traz só o que mudou a partir desta data e hora (inclusive). Para sincronizar: guarde a hora da última consulta e atualize os registros pelo `id` — pode vir algum repetido.
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/nfse" \
  --header "Authorization: Bearer $WEESY_TOKEN"

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

Respostas

200: Página de NFS-e, em ordem de atualizadoEm e id.
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)
429: Muitas chamadas em pouco tempo (limiteexcedido). Espere os segundos de Retry-After e tente de novo. (formato de erro)

Campos da resposta 200

Campo Tipo Descrição

dados
obrigatório array de object

dados[].id
obrigatório

string

Identificador da NFS-e na Weesy.

dados[].idIntegracao
obrigatório

string

Identificador informado pelo integrador na emissão.

dados[].status
obrigatório

string

Situação atual do processamento da NFS-e.

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[].ambiente
obrigatório

string

Ambiente em que a emissão foi solicitada.

Valor	Significado
`simulacao`	Teste sem certificado — a Weesy responde no lugar da prefeitura
`homologacao`	Teste no ambiente de testes da prefeitura — precisa de certificado
`producao`	A nota de verdade, com valor fiscal

dados[].empresa
obrigatório

object

A empresa que emitiu a nota.

dados[].empresa.cnpj
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[].empresa.razaoSocial
obrigatório string

dados[].empresa.inscricaoMunicipal string ou null

dados[].empresa.municipio
obrigatório

object

Identificação do município por código IBGE, nome e UF.

dados[].empresa.municipio.codigoIbge
obrigatório

string

Código IBGE do município.

dados[].empresa.municipio.nome

string

Nome do município.

dados[].empresa.municipio.uf

string

Sigla da unidade federativa.

dados[].tomador
obrigatório

object

Dados do tomador registrados na nota.

dados[].tomador.tipoPessoa
obrigatório

string

Tipo de pessoa do tomador.

Valores: F, J.

dados[].tomador.cpfCnpj
obrigatório

string

CPF ou CNPJ registrado para o tomador.

dados[].tomador.nome
obrigatório

string

Nome ou razão social do tomador.

dados[].tomador.inscricaoMunicipal

string ou null

Inscrição municipal informada para o tomador.

dados[].tomador.email

string ou null

E-mail registrado para o tomador.

dados[].tomador.telefone

string ou null

Telefone registrado para o tomador.

dados[].tomador.endereco

object

Endereço registrado para o tomador.

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

string

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

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

string

Tipo e nome do logradouro.

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

string

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

dados[].tomador.endereco.complemento

string

Complemento do endereço, quando aplicável.

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

string

Bairro do endereço.

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

string

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

dados[].tomador.endereco.cidade string

dados[].tomador.endereco.uf string

dados[].servico
obrigatório

object

Serviço congelado na nota.

dados[].servico.id integer

dados[].servico.descricao string

dados[].servico.itemListaServico string

dados[].servico.codigoTributacaoMunicipio string ou null

dados[].servico.codigoTributacaoNacional string ou null

dados[].servico.nbs string

dados[].servico.cIndOp string

dados[].servico.cClassTrib string

dados[].servico.cst string

dados[].discriminacao

string

Descrição da prestação registrada na nota.

dados[].competencia

string (date)

Data de competência da prestação.

dados[].valores
obrigatório

object

Valores calculados e registrados para a nota.

dados[].valores.servico

number

Valor do serviço prestado.

dados[].valores.deducoes

number

Valor das deduções consideradas.

dados[].valores.descontoIncondicionado

number

Valor do desconto incondicionado.

dados[].valores.descontoCondicionado

number

Valor do desconto condicionado.

dados[].valores.baseCalculo

number

Base de cálculo apurada para o ISS.

dados[].valores.aliquotaIss

number

Alíquota de ISS aplicada no cálculo, em percentual.

dados[].valores.iss

number

Valor de ISS apurado.

dados[].valores.issRetido

boolean

Indica a retenção do ISS.

dados[].valores.retencoesFederais

object

Valores de retenções federais.

dados[].valores.retencoesFederais.pis

number

Valor da retenção de PIS.

dados[].valores.retencoesFederais.cofins

number

Valor da retenção de COFINS.

dados[].valores.retencoesFederais.csll

number

Valor da retenção de CSLL.

dados[].valores.retencoesFederais.ir

number

Valor da retenção de Imposto de Renda.

dados[].valores.retencoesFederais.inss

number

Valor da retenção de INSS.

dados[].valores.liquido

number

Valor líquido da prestação.

dados[].ibsCbs

object

Ausente quando a nota não tem o grupo IBS/CBS.

dados[].ibsCbs.cIndOp string

dados[].ibsCbs.cClassTrib string

dados[].ibsCbs.cst string

dados[].ibsCbs.localidadeIncidencia

string

Código IBGE do município.

dados[].rps

object

Numeração e série do RPS da nota.

dados[].rps.numero string

dados[].rps.serie string

dados[].documento

object

Ausente até autorizar.

dados[].documento.numero string

dados[].documento.codigoVerificacao string

dados[].documento.chaveAcesso string ou null

dados[].documento.emitidoEm

string (date-time)

Data e hora no horário de Brasília (ex. 2026-10-26T09:27:34-03:00).

dados[].provedor

object

A última resposta da prefeitura (ou do sistema nacional).

dados[].provedor.padrao string

dados[].provedor.codigo string ou null

dados[].provedor.mensagem string ou null

dados[].provedor.protocolo string ou null

dados[].historico

array de object

Histórico das mudanças de situação da NFS-e.

dados[].historico[].status
obrigatório

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[].historico[].em
obrigatório

string (date-time)

Data e hora em UTC, terminada em Z (ex. 2026-10-26T12:27:34Z).

dados[].historico[].mensagens array de object

dados[].historico[].mensagens[].codigo string

dados[].historico[].mensagens[].mensagem string

dados[].cancelamento

object

Dados e situação da solicitação de cancelamento, quando houver.

dados[].cancelamento.motivo integer

dados[].cancelamento.justificativa string

dados[].cancelamento.solicitadoEm

string (date-time)

Data e hora em UTC, terminada em Z (ex. 2026-10-26T12:27:34Z).

dados[].cancelamento.concluidoEm string (date-time) ou null

dados[].links
obrigatório

object

Endereços relativos para consultar a nota e obter seus documentos, conforme disponibilidade.

dados[].links.self
obrigatório string

dados[].links.xml

string ou null

Nulo até autorizar.

dados[].links.pdf

string ou null

Nulo até autorizar.

dados[].criadoEm
obrigatório

string (date-time)

Instante de criação do registro na Weesy.

dados[].atualizadoEm
obrigatório

string (date-time)

Instante da última atualização do registro.

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