Como funciona
A API roda no próprio computador em http://127.0.0.1:8099. Qualquer linguagem que faça uma requisição HTTP com JSON consegue emitir notas.
Seu sistema envia JSON
Dados da empresa, certificado, cliente, produtos e pagamento em uma única chamada POST /emitir.
A API processa
Monta o XML, assina com o certificado digital e transmite à SEFAZ.
Você recebe o resultado
status: aprovado, chave, protocolo e o DANFE em PDF pela rota /danfe.
Instalação em 6 passos
Funciona no Windows 7, 8, 10 e 11. Não precisa de Apache, XAMPP nem banco de dados.
Extrair o pacote
Crie C:\nfe-api e extraia o nfe-api.zip. Evite “Arquivos de Programas”.
Visual C++
Instale o Redistributable 2015-2019 da Microsoft (x64 ou x86).
PHP 7.4
Baixe o zip VC15 Non Thread Safe em windows.php.net (Archives) e extraia em C:\nfe-api\php.
Certificado A1
Copie o .pfx para gerador\certificados. Guarde nome e senha.
Iniciar
Dê dois cliques em iniciar-servidor.bat e deixe a janela aberta.
Testar
Abra http://127.0.0.1:8099/ping. Deve responder "status":"ok".
tpAmb = 2). Só mude para produção (tpAmb = 1) depois de tudo aprovado. Mantenha o relógio do Windows correto.Rotas da API
Todas recebem e devolvem JSON (UTF-8). Se definir um token em settings.php, envie o cabeçalho X-API-KEY.
| Método | Rota | Função |
|---|---|---|
| GET | /ping | Verifica PHP, extensões, pastas e certificados |
| POST | /validar-certificado | Confere senha, validade, razão social e CNPJ |
| POST | /emitir | Emite NFC-e (modelo 65) ou NF-e (modelo 55). Com "teste":"ok" só assina, sem transmitir |
| GET | /danfe?chave=… | PDF do DANFE/DANFCE da nota |
| POST | /cancelar * | Cancela nota autorizada (chave + motivo) |
| POST | /carta-correcao * | Carta de correção da NF-e (chave, motivo, sequencia) |
| POST | /exportar-xml * | ZIP mensal para o contador (cnpj, codigoUF, mes, ano, modelo) |
* Nomes das rotas conforme os arquivos CancelarNota.php, CCNota.php e ExportarXML.php. Confirme o caminho exato no LEIA-ME.md do seu pacote.
Emitir uma NFC-e
Primeiro o JSON de exemplo. Depois, o mesmo envio em cada linguagem.
{"status":"aprovado","chave":"3526…","protocolo":"…"}. Para imprimir, baixe /danfe?chave=…. Se vier error, a mensagem explica o motivo. Em falha de comunicação a resposta traz a chave: consulte a situação antes de emitir de novo, para não duplicar.Cancelar uma nota
Informe a chave de 44 dígitos e o motivo (mín. 15 caracteres). A nota precisa estar em gerador\xml\autorizadas.
{"status":"cancelado","chave":"…","cstat":"135"}. O XML com o evento é salvo em gerador\xml\canceladas.Solução de problemas
Se precisar de ajuda, reúna a resposta da API, o gerador\logs\php-error.log, o /ping e o XML de gerador\xml\entradas. Nunca envie o certificado ou a senha.
| Sintoma | O que fazer |
|---|---|
| Falha ao conectar / sem resposta | Servidor desligado ou porta diferente. Abra /ping no navegador e confira a URL |
| VCRUNTIME140.dll não encontrado | Instale o Visual C++ Redistributable 2015-2019 |
| Failed to listen on 127.0.0.1:8099 | Porta em uso. Troque no iniciar-servidor.bat e na sua URL |
| Certificado ou Senha invalida | Confira a senha. Se o detalhe for unsupported ou 0308010C, use PHP 7.4 |
| Dados incompletos: … | A mensagem lista os campos faltantes (tpAmb, CNPJ, CSC, produtos…) |
| Rejeicao: … (cStat) | A SEFAZ recusou. O texto e o código explicam; veja storage\cstat.json |
| Rejeição por data/hora | Acerte data, hora e fuso do Windows |
| Acentos trocados no DANFE | Envie o JSON em UTF-8 (ou escape \uXXXX no VB6) |
127.0.0.1. Nunca troque para 0.0.0.0 nem exponha a porta na rede. Faça backup de gerador\xml\autorizadas e canceladas: a lei exige guarda por 5 anos.Boas práticas de segurança
A API manipula certificado digital e documentos fiscais. Siga estes cuidados na integração.
Ative o token
Defina 'token' em settings.php e envie X-API-KEY em toda chamada. Sem token, qualquer site aberto no navegador do PC pode tentar chamar 127.0.0.1:8099.
Proteja segredos
Nunca grave a senha do certificado no código, em repositório Git ou em logs. Leia de um cofre, variável de ambiente ou digitação do usuário.
Valide as entradas
Antes de montar o JSON ou a URL, aceite só dígitos na chave (44) e use um serializador JSON em vez de concatenar texto.
Só localhost
Mantenha 127.0.0.1. Não exponha a porta na rede, na internet nem em túnel.
Evite a linha de comando
No cURL, a senha fica no histórico do terminal. Prefira --data-binary @arquivo.json e apague o arquivo depois.
Arquivos e backup
Restrinja o acesso a gerador\certificados, mantenha antivírus ativo e faça backup criptografado dos XMLs.