NFSe

Endpoints para emissão e cancelamento de Nota Fiscal de Serviço Eletrônica (NFSe) via acbrcmd. O payload segue o padrão aceito pelo ACBr (nacional, Ginfes, Betha, IssNet, etc.).

POST /api/v1/nfse/emitir

Emite NFSe. O corpo deve conter acao = "emitir", modeloDocumento = "nfse", certificadoDigital (hexadecimal), senhaCertificadoDigital, e os objetos prestador, tomador e servico conforme o provedor do município (padrão nacional, Ginfes, Betha, IssNet, etc.).

Campos obrigatórios na raiz

acao — use "emitir"
modeloDocumento — use "nfse"
certificadoDigital — conteúdo do certificado A1 em hexadecimal
senhaCertificadoDigital — senha do certificado
ambiente — "1" produção ou "2" homologação
prestador — dados do prestador do serviço (CNPJ, endereço, inscrição municipal, etc.)
tomador — dados do tomador (CPF/CNPJ, endereço, razão social)
servico — valores, item da lista de serviço, discriminação, código do município, exigibilidade ISS

Campos comuns (raiz) conforme provedor

numeroLote, numeroRps, serie — identificação do RPS
padraoNacional — "sim" para padrão nacional NFSe
simplesNacional — "1" Simples, "2" outro regime
regimeEspecialTributacao — código do regime (ex.: 1 a 9)
tipo, naturezaOperacao, incentivadorCultural, codigoObra, codigoArt, outrasInformacoes

Exemplos de código

# corpo (-d): {"acao":"emitir","modeloDocumento":"nfse","certificadoDigital":"hex","senhaCertificadoDigital":"...","ambiente":"2","prestador":{...},"tomador":{...},"servico":{...}}

curl -X POST "https://nfe.geranet.net/api/v1/nfse/emitir" \
  -H "Authorization: Bearer SUA_API_KEY" -H "Content-Type: application/json" \
  -d '{"acao":"emitir","modeloDocumento":"nfse","certificadoDigital":"...","senhaCertificadoDigital":"...","ambiente":"2","prestador":{...},"tomador":{...},"servico":{...}}'

$payload = [
    'acao' => 'emitir',
    'modeloDocumento' => 'nfse',
    'certificadoDigital' => $certHex,
    'senhaCertificadoDigital' => $senha,
    'ambiente' => '2',
    'prestador' => [...],
    'tomador' => [...],
    'servico' => [...],
];
$url = 'https://nfe.geranet.net/api/v1/nfse/emitir';
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiKey,
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_TIMEOUT, 120);
$response = curl_exec($ch);
$httpCode = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$dados = json_decode($response, true);

payload = {
    'acao': 'emitir',
    'modeloDocumento': 'nfse',
    'certificadoDigital': cert_hex,
    'senhaCertificadoDigital': senha,
    'ambiente': '2',
    'prestador': {...},
    'tomador': {...},
    'servico': {...}
}
response = requests.post('https://nfe.geranet.net/api/v1/nfse/emitir', headers={'Authorization': f'Bearer {api_key}', 'Content-Type': 'application/json'}, json=payload)
dados = response.json()

var payload = new {
    acao = "emitir",
    modeloDocumento = "nfse",
    certificadoDigital = certHex,
    senhaCertificadoDigital = senha,
    ambiente = "2",
    prestador = ...,
    tomador = ...,
    servico = ...
};
var content = new StringContent(JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://nfe.geranet.net/api/v1/nfse/emitir", content);
var dados = await response.Content.ReadFromJsonAsync<JsonElement>();

Exemplo de payload completo

Estrutura completa aceita para emissão, incluindo os campos de tributação explícitos (valorAliquota, valorPis, valorCofins, valorRetencaoCP/IRRF/CSLL, totaisTributos) e o bloco IBS/CBS (Reforma Tributária). O certificado deve ser enviado em certificadoDigital em hexadecimal.

{
    "acao": "emitir",
    "modeloDocumento": "nfse",
    "ambiente": "2",
    "padraoNacional": "sim",
    "numeroLote": "1",
    "numeroRps": "1",
    "serie": "1",
    "simplesNacional": "1",
    "regimeEspecialTributacao": "1",
    "incentivadorCultural": "2",
    "tipo": "1",
    "naturezaOperacao": "1",
    "certificadoDigital": "(conteúdo do certificado A1 em hexadecimal)",
    "senhaCertificadoDigital": "sua_senha",
    "codigoObra": "",
    "codigoArt": "",
    "outrasInformacoes": "",
    "servico": {
        "valor": "100.00",
        "deducoes": "0.00",
        "aliquotaPis": "0.00",
        "aliquotaCofins": "0.00",
        "inss": "0.00",
        "ir": "0.00",
        "csll": "0.00",
        "issRetido": "2",
        "valorIssRetido": "0.00",
        "outrasRetencoes": "0.00",
        "descontoIncondicionado": "0.00",
        "descontoCondicionado": "0.00",
        "aliquota": "2.00",
        "responsavelRetencao": "4",
        "itemListaServico": "01.07",
        "codigoTributacaoMunicipio": "0107",
        "codigoLcServ": "0107",
        "codigoCnae": "6209100",
        "codigoNBS": "125060000",
        "codigoClassificacaoTributaria": "000001",
        "discriminacao": "Descrição completa do serviço prestado conforme item da lista de serviços do município.",
        "codigoMunicipio": "1702109",
        "municipioIncidencia": "1702109",
        "descricaoLocalidadeIncidencia": "",
        "exigibilidadeISS": "1",
        "tributacao": {
            "percentualTributosSimplesNacional": "2.00",
            "tributacaoMunicipal": {
                "tipoImunidade": "0",
                "valorAliquota": "2.00"
            },
            "tributacaoFederal": {
                "CST": "49",
                "tipoRetencaoPisCofins": "2",
                "aliquotaPis": "0.00",
                "aliquotaCofins": "0.00",
                "valorPis": "0.00",
                "valorCofins": "0.00",
                "baseCalculoPisCofins": "100.00",
                "valorRetencaoCP": "0.00",
                "valorRetencaoIRRF": "0.00",
                "valorRetencaoCSLL": "0.00"
            },
            "totaisTributos": {
                "percentualTributosFederais": "0.00",
                "valorTributosFederais": "0.00",
                "percentualTributosEstaduais": "0.00",
                "valorTributosEstaduais": "0.00",
                "percentualTributosMunicipais": "2.00",
                "valorTributosMunicipais": "2.00"
            },
            "ibscbs": {
                "cst": "000",
                "cIndOp": "030101",
                "ibsEstadual": {
                    "percentualIbs": "0.10",
                    "percentualReducaoAliquota": "0.00"
                },
                "ibsMunicipal": {
                    "percentualIbs": "0.00",
                    "percentualReducaoAliquota": "0.00"
                },
                "cbsFederal": {
                    "percentualCbs": "0.90",
                    "percentualReducaoAliquota": "0.00"
                }
            }
        }
    },
    "prestador": {
        "logomarca": "",
        "cnpj": "00000000000191",
        "inscricaoMunicipal": "12345",
        "endereco": "Rua Exemplo",
        "numero": "100",
        "complemento": "Sala 1",
        "bairro": "Centro",
        "municipio": "1702109",
        "nomeMunicipio": "ARAGUAINA",
        "uf": "TO",
        "cep": "77800000",
        "razaoSocial": "PRESTADOR EXEMPLO LTDA",
        "nomeFantasia": "Exemplo Prestador",
        "telefone": "63900000000",
        "email": "contato@exemplo.com.br",
        "usuario": "",
        "senha": "",
        "fraseSecreta": "",
        "chaveAcesso": "",
        "chaveAutorizacao": "",
        "codigoUf": "17"
    },
    "tomador": {
        "cpfCnpj": "00000000000",
        "inscricaoMunicipal": "",
        "endereco": "Rua do Tomador",
        "numero": "50",
        "complemento": "",
        "bairro": "Centro",
        "municipio": "1702109",
        "nomeMunicipio": "ARAGUAINA",
        "uf": "TO",
        "codigoPais": "1058",
        "pais": "Brasil",
        "cep": "77800000",
        "razaoSocial": "Tomador Exemplo",
        "telefone": "63999999999",
        "email": "tomador@exemplo.com"
    }
}

Respostas

A API retorna JSON com a estrutura abaixo. Em emissão pode vir também numero.

Sucesso (HTTP 200)

{
  "situacao": "sucesso",
  "mensagem": "NFSe emitida com sucesso.",
  "xml": "(conteúdo do XML em hexadecimal)",
  "pdf": "(conteúdo do PDF em hexadecimal)",
  "numero": "000001"
}

Erro (HTTP 422)

{
  "situacao": "erro",
  "mensagem": "Erro ao comunicar com o provedor do município. Verifique prestador e serviço.",
  "xml": "",
  "pdf": ""
}

Emissão Nacional da NFSe

Alguns municípios estão aderindo à emissão nacional da NFSe. Abaixo você encontra como verificar se o seu município já utiliza o padrão nacional e como emitir pela nossa API usando o portal nacional.

Como saber se o município usa emissão nacional?

Para verificar se o município está usando 100% da emissão nacional da NFSe, consulte o painel oficial no link abaixo. Use o filtro de município para localizar a cidade desejada.

Se no card «Adesão ao Emissor Nacional da NFS-e» aparecer SIM, o município já está aderido e você pode emitir usando o portal nacional com nossa API.

Abrir painel de adesão (Power BI)

Emitir pelo portal nacional com nossa API

Quando o município estiver aderido ao emissor nacional, basta:

Incluir no payload a variável padraoNacional = "sim".
Preencher os dados comuns, como item da lista de serviços, código NBS e demais campos exigidos pelo padrão nacional.

O endpoint continua sendo POST /api/v1/nfse/emitir. A estrutura do payload segue a aba Emitir acima, com o acréscimo de padraoNacional: "sim" na raiz.

Exemplo (trecho do payload)

{
  "acao": "emitir",
  "modeloDocumento": "nfse",
  "padraoNacional": "sim",
  "certificadoDigital": "...",
  "senhaCertificadoDigital": "...",
  "prestador": { ... },
  "tomador": { ... },
  "servico": {
    "itemListaServico": "01.01",
    "codigoNbs": "...",
    ...
  }
}

Dúvidas?

Entre em contato com nosso suporte por WhatsApp:

(63) 3412-4546 – Falar no WhatsApp

POST /api/v1/nfse/cancelar

Cancela uma NFSe. Envie acao = "cancelar", modeloDocumento = "nfse", certificadoDigital, senhaCertificadoDigital, prestador. No padrão nacional: inclua xml (NFSe em hexadecimal), codigoCancelamento e motivoCancelamento. O formato pode variar conforme o provedor do município.

Exemplos de código

# corpo (-d): {"acao":"cancelar","modeloDocumento":"nfse","certificadoDigital":"...","senhaCertificadoDigital":"...","ambiente":"1","padraoNacional":"sim","xml":"hex NFSe","codigoCancelamento":"2","motivoCancelamento":"...","prestador":{...}}

curl -X POST "https://nfe.geranet.net/api/v1/nfse/cancelar" \
  -H "Authorization: Bearer SUA_API_KEY" -H "Content-Type: application/json" \
  -d '{"acao":"cancelar","modeloDocumento":"nfse","certificadoDigital":"...","senhaCertificadoDigital":"...","ambiente":"1","padraoNacional":"sim","prestador":{...}}'

$payload = ['acao' => 'cancelar', 'modeloDocumento' => 'nfse', 'certificadoDigital' => $certHex, 'senhaCertificadoDigital' => $senha, 'ambiente' => '1', 'padraoNacional' => 'sim', 'prestador' => [...], 'xml' => $xmlHex, 'codigoCancelamento' => '2', 'motivoCancelamento' => $motivo];
$ch = curl_init('https://nfe.geranet.net/api/v1/nfse/cancelar');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer ' . $apiKey, 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
$response = curl_exec($ch);
curl_close($ch);
$dados = json_decode($response, true);

payload = {'acao': 'cancelar', 'modeloDocumento': 'nfse', 'certificadoDigital': cert_hex, 'senhaCertificadoDigital': senha, 'ambiente': '1', 'padraoNacional': 'sim', 'prestador': {...}, 'xml': xml_hex, 'codigoCancelamento': '2', 'motivoCancelamento': motivo}
response = requests.post('https://nfe.geranet.net/api/v1/nfse/cancelar', headers={'Authorization': f'Bearer {api_key}', 'Content-Type': 'application/json'}, json=payload)
dados = response.json()

var payload = new { acao = "cancelar", modeloDocumento = "nfse", certificadoDigital = certHex, senhaCertificadoDigital = senha, ambiente = "1", padraoNacional = "sim", prestador = ..., xml = xmlHex, codigoCancelamento = "2", motivoCancelamento = motivo };
var content = new StringContent(JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://nfe.geranet.net/api/v1/nfse/cancelar", content);
var dados = await response.Content.ReadFromJsonAsync<JsonElement>();

Exemplo de payload (padrão nacional)

{
  "acao": "cancelar",
  "modeloDocumento": "nfse",
  "certificadoDigital": "(conteúdo do certificado A1 em hexadecimal)",
  "senhaCertificadoDigital": "sua_senha",
  "ambiente": "1",
  "padraoNacional": "sim",
  "xml": "(conteúdo do XML da NFSe em hexadecimal)",
  "codigoCancelamento": "2",
  "motivoCancelamento": "Erro nos valores informados na nota.",
  "prestador": {
    "cnpj": "00000000000191",
    "inscricaoMunicipal": "12345",
    "endereco": "Rua Exemplo",
    "numero": "100",
    "complemento": "",
    "bairro": "Centro",
    "municipio": "1702109",
    "nomeMunicipio": "ARAGUAINA",
    "uf": "TO",
    "cep": "77800000",
    "razaoSocial": "PRESTADOR EXEMPLO LTDA",
    "nomeFantasia": "Exemplo",
    "telefone": "63900000000",
    "email": "contato@exemplo.com.br",
    "usuario": "",
    "senha": "",
    "fraseSecreta": "",
    "chaveAcesso": "",
    "chaveAutorizacao": "",
    "codigoUf": "17"
  }
}

Estrutura da resposta:

Sucesso (200)

{
  "situacao": "sucesso",
  "mensagem": "NFSe cancelada com sucesso.",
  "xml": "...",
  "pdf": "..."
}

Erro (422)

{
  "situacao": "erro",
  "mensagem": "XML inválido ou código de cancelamento não permitido.",
  "xml": "",
  "pdf": ""
}

← NFe / NFCe · Introdução →