Por que migramos para a versão 2.0
Comparação Direta
| Versão 1.0 (anterior) | Versão 2.0 (atual) | |
|---|---|---|
| Protocolo de comunicação | Socket IPC proprietário (Unix socket / named pipe), com um formato de mensagem JSON próprio — só funciona na mesma máquina e só quem implementa exatamente esse protocolo consegue conversar com o serviço |
HTTP/REST padrão de mercado — funciona local ou remoto, e qualquer ferramenta HTTP (navegador, curl, Postman, biblioteca HTTP nativa de qualquer linguagem) já conversa com ele |
| Precisa de outro programa rodando por trás | Sim — um serviço separado precisa estar de pé o tempo todo | Não — é um único programa autossuficiente |
| Conector diferente por linguagem | Sim — um pacote específico para cada linguagem (Node, PHP, Python, Ruby) | Não — qualquer linguagem se conecta diretamente, sem instalar nada extra |
|
Funciona em processadores ARM (comuns em equipamentos fiscais/embarcados) |
Não | Sim |
| Tamanho para instalar | Mais de 200 MB de dependências | Um único arquivo de ~15–30 MB |
| Como instalar | Vários passos: instalar runtime, dependências, compilar | Baixar, extrair, executar |
Equivalência de Métodos
Todos os métodos da versão 1.0 têm correspondente na versão 2.0. A versão 2.0 também adiciona operações que não existiam antes.
| Método v1.0 | Endpoint v2.0 | Descrição |
|---|---|---|
gerar |
POST /convtx2 |
Conversão TX2 → XML |
gerar_xml_json |
POST /jsontoxml |
Conversão JSON → XML |
assinar |
POST /assinar |
Assinar XML com certificado digital |
enviar_nota |
POST /enviar |
Enviar nota para a SEFAZ |
consultar_protocolo |
POST /consultar |
Consultar protocolo na SEFAZ |
status_servico |
POST /status |
Verificar status do serviço SEFAZ |
cancelar_nota |
POST /cancelar |
Cancelar uma NFC-e |
inutilizar_nota |
POST /inutilizar |
Inutilizar numeração |
imprimir_nota |
POST /printcupom |
Gerar DANFCE (PDF) |
calcular_chave |
sem equivalente direto | O cálculo da chave é feito internamente durante a conversão/processamento |
| — | POST /processar-nfce |
Novo: pipeline completo em uma só chamada (converte + assina + envia + gera PDF) |
| — | POST /escpos |
Novo: gera saída ESC/POS para impressoras térmicas |
| — | POST /gerarxmldestinatario |
Novo: gera XML do destinatário separado |
| — | GET /pdf/{chave} |
Novo: recupera o PDF de uma nota já emitida pela chave |
| — | GET /xml-destinatario/{chave} |
Novo: recupera o XML destinatário de uma nota pela chave |
| — | POST /setconfig · GET /getconfig · POST /loadconfig · POST /loadconfigjson |
Novo: gerenciamento de configuração via API (na v1.0 a config era passada em cada chamada IPC) |
| — | GET /health |
Novo: health check da API |
Limitações da Versão 1.0
1. Dependência de um serviço adicional
Antes de emitir qualquer NFC-e, é preciso ter um serviço separado rodando em segundo plano. Se esse serviço cair, a aplicação para de funcionar mesmo estando saudável — é um ponto extra de falha que não precisaria existir.
2. Protocolo de comunicação proprietário
A versão 1.0 conversa com as aplicações por um socket local (arquivo de socket no Linux, named pipe no Windows) usando um formato de mensagem JSON criado especificamente para esse projeto. Nenhuma ferramenta padrão de mercado consegue falar com ele diretamente — é por isso que cada linguagem precisa do seu próprio pacote de conexão (Node, PHP, Python, Ruby), e essa comunicação só funciona na mesma máquina. A versão 2.0 usa HTTP/REST, o protocolo padrão da web: qualquer linguagem, ferramenta ou dispositivo que já sabe fazer uma requisição HTTP consegue se conectar, local ou remotamente, sem instalar nenhum pacote adicional.
3. Sem suporte a processadores ARM
A versão 1.0 nunca teve build disponível para ARM, a arquitetura de processador usada na maioria dos equipamentos fiscais e dispositivos embarcados atuais. Isso limitava onde a solução podia ser instalada. A versão 2.0 já roda nativamente em ARM.
4. Peso para instalar e distribuir
Somando o runtime, os conectores por linguagem e o componente embarcado, a versão 1.0 facilmente ultrapassa 200 MB de dependências. A versão 2.0 é um único arquivo de ~15–30 MB, sem nenhuma dependência de sistema para instalar.
5. SDK específico por linguagem
A versão 1.0 exige a instalação de um pacote de conexão específico para cada linguagem de programação (Node.js, PHP, Python, Ruby). Qualquer linguagem que não tenha um conector disponível simplesmente não consegue usar o componente. A versão 2.0 usa HTTP/REST: qualquer linguagem que sabe fazer uma requisição HTTP — o que inclui praticamente todas as linguagens modernas — se conecta diretamente, sem instalar nenhum SDK ou pacote adicional.
O Que a Versão 2.0 Já Entrega
Conclusão
Documentação completa da API: spdNFCe API — Central de Atendimento Tecnospeed
Comentários
0 comentário
Artigo fechado para comentários.