Documentação da API de NFS-e

Visão geral

A emissão usa o emitente da chave. O prestador, o certificado e a escolha entre ambiente nacional e municipal ficam no cadastro, fora do JSON.

POST/nfseGrava a nota e, no nacional, envia ao ambiente nacional.

GET/nfse/{id}Consulta pelo id da nota ou pela identificação.

POST/nfse/{id}/cancelarCancela a nota deste emitente.

Testar

Cole a chave do emitente e envie a requisição nesta página. A chave fica neste navegador e segue somente para a API, no header Authorization.

—

Autenticação

Use a chave do emitente, a que começa com apse_. A chave geral da conta não autoriza estas rotas.

Authorization: Bearer apse_sua_chave_do_emitente
Content-Type: application/json
Accept: application/json

Sem chave, ou com chave inválida, a resposta é HTTP 401. Conta inativa ou emitente sem NFS-e habilitada responde HTTP 403.

Ambientes

A URL é a mesma. No cadastro do emitente ficam o sistema e o ambiente fiscal.

Cadastro	Valores	Efeito na emissão
Sistema	nacional ou municipal	Nacional envia a nota com o certificado A1. Municipal grava a nota como recebida.
Ambiente	2 homologação, 1 produção	Vale para o sistema escolhido. Sem essa escolha, o POST responde 422.

No nacional, a resposta 201 traz status autorizada, chave e numero_nfse. No municipal, o status fica recebida. Em São Paulo, a API envia o lote à prefeitura. Em homologação usa o método de teste, que valida e não gera NFS-e. Em produção, se a prefeitura aceitar, o status fica autorizada, com numero_nfse, codigo_verificacao, chave e link_impressao. O 201 e a consulta devolvem xml em base64 quando a nota tem XML gravado.

Emitir

POSThttps://api.apisimples.com/v1/nfse

HTTP 201 devolve a nota gravada. O número com a série, e a identificação, são únicos por emitente. Repetir um dos dois responde HTTP 409.

{
    "identificacao": "pedido-1042",
    "data_emissao": "2026-10-10T14:30:00-03:00",
    "numero": "15",
    "serie": "1",
    "tomador": {
        "cnpj": "19131243000197",
        "razao_social": "Cliente Exemplo Ltda",
        "email": "fiscal@cliente.exemplo",
        "endereco": {
            "logradouro": "Rua das Acácias",
            "numero": "120",
            "bairro": "Centro",
            "codigo_municipio": "3304557",
            "uf": "RJ",
            "cep": "20040020"
        }
    },
    "servico": {
        "codigo": "010101",
        "discriminacao": "Desenvolvimento de integração para emissão de NFS-e",
        "valor_servicos": 1500,
        "tributos_municipais": {
            "aliquota_iss": 2,
            "iss_retido": false
        }
    }
}

curl -X POST https://api.apisimples.com/v1/nfse \
  -H "Authorization: Bearer apse_sua_chave_do_emitente" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "identificacao": "pedido-1042",
    "data_emissao": "2026-10-10T14:30:00-03:00",
    "numero": "15",
    "serie": "1",
    "tomador": {
        "cnpj": "19131243000197",
        "razao_social": "Cliente Exemplo Ltda",
        "email": "fiscal@cliente.exemplo",
        "endereco": {
            "logradouro": "Rua das Acácias",
            "numero": "120",
            "bairro": "Centro",
            "codigo_municipio": "3304557",
            "uf": "RJ",
            "cep": "20040020"
        }
    },
    "servico": {
        "codigo": "010101",
        "discriminacao": "Desenvolvimento de integração para emissão de NFS-e",
        "valor_servicos": 1500,
        "tributos_municipais": {
            "aliquota_iss": 2,
            "iss_retido": false
        }
    }
}'

<?php

$payload = [
    'identificacao' => 'pedido-1042',
    'data_emissao' => '2026-10-10T14:30:00-03:00',
    'numero' => '15',
    'serie' => '1',
    'tomador' => [
        'cnpj' => '19131243000197',
        'razao_social' => 'Cliente Exemplo Ltda',
    ],
    'servico' => [
        'codigo' => '010101',
        'discriminacao' => 'Desenvolvimento de integração para emissão de NFS-e',
        'valor_servicos' => 1500,
    ],
];

$ch = curl_init('https://api.apisimples.com/v1/nfse');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer apse_sua_chave_do_emitente',
        'Content-Type: application/json',
        'Accept: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),
]);

$resposta = curl_exec($ch);
$nota = json_decode($resposta, true);

const resposta = await fetch("https://api.apisimples.com/v1/nfse", {
  method: "POST",
  headers: {
    Authorization: "Bearer apse_sua_chave_do_emitente",
    "Content-Type": "application/json",
    Accept: "application/json",
  },
  body: JSON.stringify({
    identificacao: "pedido-1042",
    data_emissao: "2026-10-10T14:30:00-03:00",
    numero: "15",
    serie: "1",
    tomador: {
      cnpj: "19131243000197",
      razao_social: "Cliente Exemplo Ltda",
    },
    servico: {
      codigo: "010101",
      discriminacao: "Desenvolvimento de integração para emissão de NFS-e",
      valor_servicos: 1500,
    },
  }),
});

const nota = await resposta.json();

{
    "id": "8f3c2a10-6b4e-4d2a-9c11-2e5a7b9d0f31",
    "status": "recebida",
    "sistema": "municipal",
    "ambiente": "2",
    "identificacao": "pedido-1042",
    "numero": "15",
    "serie": "1",
    "data_emissao": "2026-10-10T14:30:00-03:00",
    "tomador": {
        "razao_social": "Cliente Exemplo Ltda"
    },
    "servico": {
        "codigo": "010101",
        "valor_servicos": 1500
    }
}

Se omitir, a API preenche data_competencia com a data de emissão, tipo_emitente com 1, regime_tributacao com 0 e o município da prestação com o IBGE do emitente.

Consultar

GEThttps://api.apisimples.com/v1/nfse/{id}

GEThttps://api.apisimples.com/v1/nfse/{identificacao}

O segundo caminho usa o valor de identificacao. HTTP 200 devolve o mesmo formato da emissão. HTTP 404 se a nota não for deste emitente.

Cancelar

POSThttps://api.apisimples.com/v1/nfse/{id}/cancelar

O caminho aceita o id da nota ou a identificação. HTTP 200 devolve a nota com status cancelada. Se ela já estiver cancelada, a resposta é HTTP 409.

{
    "motivo": "2",
    "justificativa": "Serviço contratado não foi prestado."
}

Campo	Tipo	Obrigatório	Descrição
motivo	string	Sim	1 erro na emissão, 2 serviço não prestado ou 9 outros.
justificativa	string	Sim	De 15 a 255 caracteres.

No nacional, a nota precisa estar autorizada. O cancelamento segue com o certificado A1 para o ambiente em que ela foi emitida. No municipal, a API registra o cancelamento da nota recebida. Em São Paulo, a nota autorizada pela prefeitura é cancelada no webservice, com o número da NFS-e e o certificado A1.

Nota

Campos da raiz do JSON. O prestador não entra aqui.

Campo	Tipo	Obrigatório	Descrição
identificacao	string	Não	Até 40 caracteres. Serve para consultar a nota depois.
data_emissao	string	Sim	Data e hora com fuso, no formato 2026-10-10T14:30:00-03:00.
data_competencia	string	Não	Dia AAAA-MM-DD. Sem o campo, usa o dia de data_emissao.
numero	string	Sim	De 1 a 9 dígitos.
serie	string	Sim	De 1 a 5 dígitos.
tipo_emitente	string	Não	1 prestador, 2 tomador ou 3 intermediário. O padrão é 1.
regime_apuracao	string	Não	1 federais e municipal pelo Simples, 2 federais pelo Simples e ISSQN por fora, 3 tributos por fora.
regime_tributacao	string	Não	0 nenhum até 9 outros. O padrão é 0.
informacoes_complementares	string	Não	Texto livre, até 2000 caracteres.

Com tipo_emitente 2 ou 3, envie emissao_tomador e informacoes.documento_ref.

Tomador

Campo	Tipo	Obrigatório	Descrição
cnpj ou cpf	string	Um dos dois	Só números, com dígitos verificadores. Também pode ser nif, com motivo_nif.
razao_social	string	Sim	Nome ou razão social, até 300 caracteres.
tipo_destinatario	string	Não	0 tomador, 1 adquirente ou 2 destinatário. O padrão é 0.
email	string	Não	Até 80 caracteres.
telefone	string	Não	Até 20 caracteres.
endereco	objeto	Sim	logradouro, numero, bairro, codigo_municipio, uf e cep.

Serviço

Campo	Tipo	Obrigatório	Descrição
codigo	string	Sim	No nacional, 6 dígitos. Em São Paulo, o código da prefeitura, de 4 ou 5 dígitos, como 06303.
codigo_tributacao_municipio	string	Não	Use quando servico.codigo for o código nacional de 6 dígitos e a prefeitura pedir outro código, de 4 ou 5 dígitos.
discriminacao	string	Sim	Descrição do serviço, até 2000 caracteres.
codigo_nbs	string	Sim no layout 2 de São Paulo	NBS com 9 dígitos. O Simples Nacional e o MEI usam o layout 1 e não enviam este campo.
valor_servicos	número	Sim	Valor do serviço, com até duas casas.
codigo_municipio_prestacao	string	Não	IBGE de 7 dígitos. Sem o campo, usa o município do emitente.
tributos_municipais	objeto	Não	aliquota_iss em percentual, por exemplo 2.00. iss_retido true ou false.
tributos_nacionais	objeto	Não	PIS, COFINS, INSS, IR e CSLL. tipo_retencao padrão 2 quando o grupo vai no JSON.
tributos_totais	objeto	Não	percentual_federal, percentual_estadual, percentual_municipal e percentual_simples_nacional.

A alíquota é o percentual informado pelo emitente: 2.00 significa 2%. Com ISS retido e sem responsavel_retencao, a API usa 2, tomador.

Opcionais

Envie o grupo só quando a nota precisar dele. Os nomes abaixo são os objetos do JSON.

Contingência e emissão pelo tomador

Campo	Tipo	Obrigatório	Descrição
contingencia.tipo	string	Sim no grupo	1 NFS-e rejeitada, 2 indisponibilidade municipal, 3 indisponibilidade nacional ou 4 SEFIN nacional.
contingencia.motivo	string	Sim no grupo	De 15 a 255 caracteres.
emissao_tomador.motivo	string	Sim no grupo	1 importação, 2 obrigação legal, 3 recusa do prestador ou 4 rejeição na emissão.
informacoes.documento_ref	string	Com tipo 2 ou 3	Chave ou identificação do documento de referência.

IBS, CBS, deduções e ressarcimento

Campo	Tipo	Obrigatório	Descrição
servico.ibs_cbs	objeto	Sim no layout 2 de São Paulo	consumidor_final, codigo_fornecimento com 6 dígitos e classificacao_tributaria com 6 dígitos. O Simples Nacional e o MEI usam o layout 1 e não enviam este grupo.
deducoes.itens	lista	Não	Cada item tem tipo, valor e um documento: nfse_nacional, nfse_municipal, nfe, outro ou sem_emissao_fiscal.
deducoes.percentual	número	Não	Use percentual ou valor, um por vez.

Intermediário, obra, evento, locação e exterior

Campo	Tipo	Obrigatório	Descrição
intermediario	objeto	Não	cnpj ou cpf, razao_social e endereco, no mesmo formato do tomador.
obra	objeto	Não	codigo_cib, inscricao_imobiliaria ou endereco. Informe um dos três.
evento	objeto	Não	nome, data_inicio, data_fim e identificacao.
locacao	objeto	Não	Dados do bem locado e do período.
exterior	objeto	Não	Modo de prestação, vínculo, moeda e valores no exterior.

Erros

Toda resposta de erro traz codigo e mensagem. O código é estável: use ele no sistema e a mensagem para mostrar ao usuário.

HTTP	Código	Quando
400	json_invalido	O corpo não é um objeto JSON.
401	autenticacao_ausente	O header Authorization não veio.
401	autenticacao_invalida	A chave do emitente não existe.
403	conta_inativa	A conta está inativa.
403	nfse_desabilitada	O emitente não tem NFS-e habilitada.
404	nfse_nao_encontrada	A nota não é deste emitente.
404	rota_nao_encontrada	A rota não existe.
409	nfse_duplicada	Número e série, ou identificação, já usados.
409	nfse_ja_cancelada	A nota já está cancelada.
422	validacao	Um ou mais campos foram recusados. A lista erros traz campo, código e mensagem.
422	ambiente_nacional	O ambiente nacional recusou. Cada item de erros traz o código devolvido por ele.
422	sistema_ausente	O emitente não tem nacional ou municipal definido.
422	cancelamento_invalido	O status da nota não permite cancelar.
500	gravacao	A nota não foi gravada.
422	prefeitura	A prefeitura de São Paulo recusou. Cada item de erros traz o código devolvido por ela.
502	ambiente_indisponivel	O ambiente nacional não concluiu a chamada.
502	prefeitura_indisponivel	Não foi possível falar com a prefeitura de São Paulo.

No 422 de validação, o código de cada campo é um destes: obrigatorio, texto_invalido, digitos_invalidos, tamanho_invalido, codigo_invalido, numero_invalido, valor_minimo, valor_maximo, data_hora_invalida, data_invalida, booleano_invalido, objeto_invalido, lista_invalida, email_invalido, uf_invalida, endereco_obrigatorio, cnpj_invalido, cpf_invalido, documento_obrigatorio, documento_unico ou motivo_invalido.

{
    "codigo": "validacao",
    "mensagem": "A requisição foi recusada.",
    "erros": [
        {
            "campo": "servico.valor_servicos",
            "codigo": "obrigatorio",
            "mensagem": "Campo obrigatório."
        }
    ]
}

{
    "codigo": "ambiente_nacional",
    "mensagem": "O ambiente nacional recusou a nota.",
    "erros": [
        {
            "codigo": "codigo_devolvido_pelo_ambiente",
            "mensagem": "Mensagem devolvida pelo ambiente nacional.",
            "complemento": "Detalhe complementar, quando o ambiente enviar."
        }
    ]
}

{
    "codigo": "autenticacao_invalida",
    "mensagem": "Chave do emitente inválida."
}