Emitir e consultar NFS-e

Emitir NFS-e

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

Envia a nota para a prefeitura. A resposta só confirma que recebemos a nota (201, situação recebida). A prefeitura responde depois — em segundos ou minutos — e você fica sabendo pelo webhook nfse.autorizada (ou nfse.rejeitada), ou consultando a nota.

Pode repetir a chamada sem medo de emitir duas vezes. Mande sempre o mesmo idIntegracao para a mesma venda (por exemplo, o número do pedido):

mesmo idIntegracao e mesmos dados: devolvemos a nota que já existe (200);
mesmo idIntegracao com dados diferentes: erro 409 idintegracao_reutilizado, com a nota que já existe no campo existente;
nota rejeitada + mesmo idIntegracao + dados corrigidos: é a correção — a nota vai de novo para a prefeitura com os dados novos (200);
duas chamadas iguais ao mesmo tempo: só uma nota é criada; a outra recebe 200 ou 409.

O idIntegracao vale para sempre dentro da empresa — não reaproveite números de pedido. Na comparação dos dados, a ordem dos campos e os espaços não fazem diferença.

Para testar sem certificado e sem enviar nada à prefeitura, use ambiente: simulacao. No período de teste grátis, producao não é aceito (403 ambiente_nao_liberado).

Exemplo de chamada

cURLcurl --request POST \
  --url "https://apifiscal.weesy.com.br/v1/nfse" \
  --header "Authorization: Bearer $WEESY_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "idIntegracao": "pedido-10432",
  "cnpjEmitente": "21664333000195",
  "ambiente": "producao",
  "servico": {
    "id": 42
  },
  "valorServico": 100,
  "discriminacao": "Suporte técnico — outubro/2026",
  "tomador": {
    "tipoPessoa": "J",
    "cpfCnpj": "11222333000181",
    "nome": "EMPRESA EXEMPLO LTDA",
    "email": "financeiro@agworks.com.br",
    "endereco": {
      "cep": "01001000",
      "logradouro": "Rua Exemplo",
      "numero": "100",
      "bairro": "Centro",
      "codigoIbge": "3550308"
    }
  }
}'

Node.jsconst resposta = await fetch("https://apifiscal.weesy.com.br/v1/nfse", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.WEESY_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "idIntegracao": "pedido-10432",
    "cnpjEmitente": "21664333000195",
    "ambiente": "producao",
    "servico": {
      "id": 42
    },
    "valorServico": 100,
    "discriminacao": "Suporte técnico — outubro/2026",
    "tomador": {
      "tipoPessoa": "J",
      "cpfCnpj": "11222333000181",
      "nome": "EMPRESA EXEMPLO LTDA",
      "email": "financeiro@agworks.com.br",
      "endereco": {
        "cep": "01001000",
        "logradouro": "Rua Exemplo",
        "numero": "100",
        "bairro": "Centro",
        "codigoIbge": "3550308"
      }
    }
  }),
});
console.log(resposta.status, await resposta.text());

Pythonimport os

import requests

resposta = requests.post(
    "https://apifiscal.weesy.com.br/v1/nfse",
    headers={"Authorization": f"Bearer {os.environ['WEESY_TOKEN']}"},
    json={
        "idIntegracao": "pedido-10432",
        "cnpjEmitente": "21664333000195",
        "ambiente": "producao",
        "servico": {
            "id": 42,
        },
        "valorServico": 100,
        "discriminacao": "Suporte técnico — outubro/2026",
        "tomador": {
            "tipoPessoa": "J",
            "cpfCnpj": "11222333000181",
            "nome": "EMPRESA EXEMPLO LTDA",
            "email": "financeiro@agworks.com.br",
            "endereco": {
                "cep": "01001000",
                "logradouro": "Rua Exemplo",
                "numero": "100",
                "bairro": "Centro",
                "codigoIbge": "3550308",
            },
        },
    },
    timeout=30,
)
print(resposta.status_code, resposta.text)

PHP<?php

$corpo = <<<'JSON'
{
  "idIntegracao": "pedido-10432",
  "cnpjEmitente": "21664333000195",
  "ambiente": "producao",
  "servico": {
    "id": 42
  },
  "valorServico": 100,
  "discriminacao": "Suporte técnico — outubro/2026",
  "tomador": {
    "tipoPessoa": "J",
    "cpfCnpj": "11222333000181",
    "nome": "EMPRESA EXEMPLO LTDA",
    "email": "financeiro@agworks.com.br",
    "endereco": {
      "cep": "01001000",
      "logradouro": "Rua Exemplo",
      "numero": "100",
      "bairro": "Centro",
      "codigoIbge": "3550308"
    }
  }
}
JSON;

$contexto = stream_context_create(["http" => [
    "method" => "POST",
    "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/nfse", 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 = """
    {
      "idIntegracao": "pedido-10432",
      "cnpjEmitente": "21664333000195",
      "ambiente": "producao",
      "servico": {
        "id": 42
      },
      "valorServico": 100,
      "discriminacao": "Suporte técnico — outubro/2026",
      "tomador": {
        "tipoPessoa": "J",
        "cpfCnpj": "11222333000181",
        "nome": "EMPRESA EXEMPLO LTDA",
        "email": "financeiro@agworks.com.br",
        "endereco": {
          "cep": "01001000",
          "logradouro": "Rua Exemplo",
          "numero": "100",
          "bairro": "Centro",
          "codigoIbge": "3550308"
        }
      }
    }
    """;

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

Corpo da requisição

Campo Tipo Descrição

cnpjEmitente
obrigatório

string

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

servico
obrigatório

object

Um dos dois — id ou codigo.

servico.id integer

servico.codigo

string

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

valorServico
obrigatório

number

Valor bruto do serviço prestado.

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.

competencia

string (date)

Padrão = data da emissão.

municipioPrestacao

string

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

tomador
obrigatório

object

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

tomador.tipoPessoa
obrigatório

string

Indica o tipo de pessoa do tomador.

Valores: F, J.

tomador.cpfCnpj
obrigatório

string

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

tomador.nome
obrigatório

string

Nome completo ou razão social do tomador.

tomador.inscricaoMunicipal

string

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

tomador.email

string (email)

E-mail do tomador.

tomador.telefone

string

Telefone de contato do tomador.

tomador.endereco
obrigatório

object

Endereço do tomador.

tomador.endereco.cep
obrigatório

string

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

tomador.endereco.logradouro
obrigatório

string

Tipo e nome do logradouro.

tomador.endereco.numero
obrigatório

string

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

tomador.endereco.complemento

string

Complemento do endereço, quando aplicável.

tomador.endereco.bairro
obrigatório

string

Bairro do endereço.

tomador.endereco.codigoIbge
obrigatório

string

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

destinatario

object

Quando diferente do tomador (indDest = 1).

destinatario.tipoPessoa
obrigatório

string

Indica o tipo de pessoa do tomador.

Valores: F, J.

destinatario.cpfCnpj
obrigatório

string

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

destinatario.nome
obrigatório

string

Nome completo ou razão social do tomador.

destinatario.inscricaoMunicipal

string

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

destinatario.email

string (email)

E-mail do tomador.

destinatario.telefone

string

Telefone de contato do tomador.

destinatario.endereco
obrigatório

object

Endereço do tomador.

destinatario.endereco.cep
obrigatório

string

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

destinatario.endereco.logradouro
obrigatório

string

Tipo e nome do logradouro.

destinatario.endereco.numero
obrigatório

string

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

destinatario.endereco.complemento

string

Complemento do endereço, quando aplicável.

destinatario.endereco.bairro
obrigatório

string

Bairro do endereço.

destinatario.endereco.codigoIbge
obrigatório

string

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

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.

imovel.cib
obrigatório

string

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

imovel.inscricaoImobiliaria

string ou null

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

imovel.endereco
obrigatório

object

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

imovel.endereco.cep
obrigatório

string

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

imovel.endereco.logradouro
obrigatório

string

Tipo e nome do logradouro.

imovel.endereco.numero
obrigatório

string

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

imovel.endereco.complemento

string

Complemento do endereço, quando aplicável.

imovel.endereco.bairro
obrigatório

string

Bairro do endereço.

imovel.endereco.codigoIbge
obrigatório

string

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

issRetido

boolean

Padrão = o do serviço.

aliquotaSimples

number

Obrigatória para Simples com retenção.

consumoPessoal

boolean

Padrão = o do serviço.

deducoes

number

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

descontoIncondicionado

number

Desconto concedido sem condição.

descontoCondicionado

number

Desconto vinculado a condição.

outrasRetencoes

number

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

retencoesFederais

object

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

retencoesFederais.pis

number

Valor da retenção de PIS.

retencoesFederais.cofins

number

Valor da retenção de COFINS.

retencoesFederais.csll

number

Valor da retenção de CSLL.

retencoesFederais.ir

number

Valor da retenção de Imposto de Renda.

retencoesFederais.inss

number

Valor da retenção de INSS.

enviarEmail

boolean

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

idIntegracao
obrigatório

string

Um código seu, único por venda (ex.: o número do pedido). Repetir a chamada com o mesmo código não emite outra nota.

ambiente
obrigatório

string

Onde a nota vai ser emitida. O endereço da API é o mesmo para os três — quem decide é este campo, em cada nota.

Valor	Para quê	Precisa de certificado?
`simulacao`	Desenvolver e testar. Nada sai da Weesy: nós respondemos no lugar da prefeitura	Não
`homologacao`	Testar no ambiente de testes da própria prefeitura. Nem toda prefeitura tem — veja Verificar se a cidade é atendida	Sim
`producao`	A nota de verdade, com valor fiscal	Sim

Como a simulação se comporta

A nota passa por recebida → em_processamento → autorizada em poucos segundos, e os webhooks são enviados como em produção.
O número e o código de verificação são fictícios. O PDF e o XML existem e vêm marcados "SEM VALOR FISCAL — SIMULAÇÃO".
Para testar uma rejeição, comece a discriminacao com SIMULAR_REJEICAO: a nota termina como rejeitada, com uma mensagem de exemplo.
O cancelamento também é simulado (cancelada).
Os dados são validados como em produção — o que passa aqui, passa lá.
Notas em simulação e homologação não contam no seu uso.

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

Exemplo

JSON

{
  "idIntegracao": "pedido-10432",
  "cnpjEmitente": "21664333000195",
  "ambiente": "producao",
  "servico": {
    "id": 42
  },
  "valorServico": 100,
  "discriminacao": "Suporte técnico — outubro/2026",
  "tomador": {
    "tipoPessoa": "J",
    "cpfCnpj": "11222333000181",
    "nome": "EMPRESA EXEMPLO LTDA",
    "email": "financeiro@agworks.com.br",
    "endereco": {
      "cep": "01001000",
      "logradouro": "Rua Exemplo",
      "numero": "100",
      "bairro": "Centro",
      "codigoIbge": "3550308"
    }
  }
}

Respostas

200: Repetição idêntica — devolve a nota já recebida.
201: Recebida (não autorizada — o resultado é assíncrono).
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)
403: ambientenaoliberado — no período de teste grátis só dá para emitir em homologacao ou simulacao. (formato de erro)
404: empresanaoencontrada ou serviconaoencontrado — confira o CNPJ e o serviço. (formato de erro)
409: A nota não pode ser emitida como está. O code diz o motivo: - idintegracaoreutilizado — esse idIntegracao já foi usado com outros dados (a nota que existe vem em existente); - servicoinativo — o serviço foi desativado; - empresasemcertificado ou certificadovencido — envie um certificado válido (em simulacao não precisa); - municipionaoatendido — ainda não emitimos na cidade da empresa. (formato de erro)
429: Muitas chamadas em pouco tempo (limiteexcedido). Espere os segundos de Retry-After e tente de novo. (formato de erro)
500: Erro do nosso lado (errointerno). Tente de novo; se continuar, mande o traceId para o suporte. (formato de erro)

Campos da resposta 200

Campo Tipo Descrição

id
obrigatório

string

Identificador da NFS-e na Weesy.

idIntegracao
obrigatório

string

Identificador informado pelo integrador na emissão.

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

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

empresa
obrigatório

object

A empresa que emitiu a nota.

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.

empresa.razaoSocial
obrigatório string

empresa.inscricaoMunicipal string ou null

empresa.municipio
obrigatório

object

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

empresa.municipio.codigoIbge
obrigatório

string

Código IBGE do município.

empresa.municipio.nome

string

Nome do município.

empresa.municipio.uf

string

Sigla da unidade federativa.

tomador
obrigatório

object

Dados do tomador registrados na nota.

tomador.tipoPessoa
obrigatório

string

Tipo de pessoa do tomador.

Valores: F, J.

tomador.cpfCnpj
obrigatório

string

CPF ou CNPJ registrado para o tomador.

tomador.nome
obrigatório

string

Nome ou razão social do tomador.

tomador.inscricaoMunicipal

string ou null

Inscrição municipal informada para o tomador.

tomador.email

string ou null

E-mail registrado para o tomador.

tomador.telefone

string ou null

Telefone registrado para o tomador.

tomador.endereco

object

Endereço registrado para o tomador.

tomador.endereco.cep
obrigatório

string

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

tomador.endereco.logradouro
obrigatório

string

Tipo e nome do logradouro.

tomador.endereco.numero
obrigatório

string

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

tomador.endereco.complemento

string

Complemento do endereço, quando aplicável.

tomador.endereco.bairro
obrigatório

string

Bairro do endereço.

tomador.endereco.codigoIbge
obrigatório

string

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

tomador.endereco.cidade string

tomador.endereco.uf string

servico
obrigatório

object

Serviço congelado na nota.

servico.id integer

servico.descricao string

servico.itemListaServico string

servico.codigoTributacaoMunicipio string ou null

servico.codigoTributacaoNacional string ou null

servico.nbs string

servico.cIndOp string

servico.cClassTrib string

servico.cst string

discriminacao

string

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

competencia

string (date)

Data de competência da prestação.

valores
obrigatório

object

Valores calculados e registrados para a nota.

valores.servico

number

Valor do serviço prestado.

valores.deducoes

number

Valor das deduções consideradas.

valores.descontoIncondicionado

number

Valor do desconto incondicionado.

valores.descontoCondicionado

number

Valor do desconto condicionado.

valores.baseCalculo

number

Base de cálculo apurada para o ISS.

valores.aliquotaIss

number

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

valores.iss

number

Valor de ISS apurado.

valores.issRetido

boolean

Indica a retenção do ISS.

valores.retencoesFederais

object

Valores de retenções federais.

valores.retencoesFederais.pis

number

Valor da retenção de PIS.

valores.retencoesFederais.cofins

number

Valor da retenção de COFINS.

valores.retencoesFederais.csll

number

Valor da retenção de CSLL.

valores.retencoesFederais.ir

number

Valor da retenção de Imposto de Renda.

valores.retencoesFederais.inss

number

Valor da retenção de INSS.

valores.liquido

number

Valor líquido da prestação.

ibsCbs

object

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

ibsCbs.cIndOp string

ibsCbs.cClassTrib string

ibsCbs.cst string

ibsCbs.localidadeIncidencia

string

Código IBGE do município.

rps

object

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

rps.numero string

rps.serie string

documento

object

Ausente até autorizar.

documento.numero string

documento.codigoVerificacao string

documento.chaveAcesso string ou null

documento.emitidoEm

string (date-time)

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

provedor

object

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

provedor.padrao string

provedor.codigo string ou null

provedor.mensagem string ou null

provedor.protocolo string ou null

historico

array de object

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

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

historico[].em
obrigatório

string (date-time)

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

historico[].mensagens array de object

historico[].mensagens[].codigo string

historico[].mensagens[].mensagem string

cancelamento

object

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

cancelamento.motivo integer

cancelamento.justificativa string

cancelamento.solicitadoEm

string (date-time)

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

cancelamento.concluidoEm string (date-time) ou null

links
obrigatório

object

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

links.self
obrigatório string

links.xml

string ou null

Nulo até autorizar.

links.pdf

string ou null

Nulo até autorizar.

criadoEm
obrigatório

string (date-time)

Instante de criação do registro na Weesy.

atualizadoEm
obrigatório

string (date-time)

Instante da última atualização do registro.

← Voltar ao início