Ambiente Ativo:

Referência da API NexoFisc

A API REST do NexoFisc fornece emissão síncrona e inteligente de documentos fiscais eletrônicos diretamente para as SEFAZ estaduais e prefeituras municipais, com validação tributária prévia, garantia de idempotência e observabilidade ponta a ponta.

Emissão Síncrona Retorno com chave de 44 dígitos e protocolo SEFAZ na mesma requisição.
Idempotência Absoluta O idExterno impede duplicidade em quedas de rede.
Reforma Tributária Grupos nativos de IBS e CBS prontos para a transição fiscal.

2. Ambientes e URLs Oficiais

Serviço Produção Homologação Local (Dev)
API Fiscal https://api.nexofisc.tech/v1 https://api-hml.nexofisc.tech/v1 http://localhost:8080/v1
Documentação https://api.nexofisc.tech/docs https://api-hml.nexofisc.tech/docs http://localhost:8080/docs
OpenAPI / Swagger https://api.nexofisc.tech/api https://api-hml.nexofisc.tech/api http://localhost:8080/api
Painel do Cliente https://conta.nexofisc.tech - http://localhost:8081

3. Autenticação e Chaves de Integração

Todas as requisições à API fiscal exigem um token portador no cabeçalho Authorization. O token possui o prefixo fixo emk_ (*Emissor Key*):

Cabeçalho HTTP Obrigatório
Authorization: Bearer emk_seu_token_de_integracao_aqui

Por segurança, as chaves nunca são salvas em texto puro no servidor (apenas o hash SHA-256 é armazenado). Guarde a chave em um cofre seguro ao criá-la.

4. Cabeçalhos HTTP Padronizados

Estrutura Padronizada de Headers
POST /v1/documentos HTTP/1.1
Host: https://api.nexofisc.tech
Authorization: Bearer emk_seu_token_aqui
Content-Type: application/json
Accept: application/json
X-Correlation-ID: 8f91a4d2-1234-4567-9876-123456789abc
Idempotency-Key: opcional
X-Client-Version: ERP-Versao-2.4.0
  • X-Correlation-ID: Identificador exclusivo da operação (UUID ou alfanumérico até 64 caracteres). Propagado automaticamente para todos os logs (MDC) e devolvido no cabeçalho de resposta para auditoria.
  • Idempotency-Key: Cabeçalho opcional para garantia extra contra reprocessamento.
  • X-Client-Version: Identifica a versão do seu sistema cliente comercial.

5. Emissão de Documentos Fiscais

POST /v1/documentos JSON UTF-8 • Content-Type: application/json

          

6. Reforma Tributária (IBS e CBS)

O NexoFisc é totalmente compatível com as regras de transição da EC 132/2023. Para empresas do Regime Normal (CRT 3) em estados que já exigem a validação (como São Paulo - Rejeição SEFAZ 1115), adicione o grupo ibsCbs no item:

Estrutura do Grupo IBS/CBS no Item
"ibsCbs": {
  "cst": "000",         // CST oficial da Receita Federal (ex.: 000 tributação integral)
  "cClassTrib": "000001", // Código de Classificação Tributária da operação
  "pIbsUf": 0.1,        // Alíquota de IBS Estadual de teste (%)
  "pIbsMun": 0.0,       // Alíquota de IBS Municipal (%)
  "pCbs": 0.9           // Alíquota de CBS Federal de teste (%)
}

7. Exemplos de Código em 5 Linguagens


          

8. Catálogo de Erros e Rejeições SEFAZ

Status / cStat Mensagem Causa Provável Ação Corretiva
HTTP 401 Chave de API ausente ou inválida Header Authorization sem o prefixo Bearer emk_. Conferir o token configurado no arquivo de ambiente do ERP.
HTTP 422 Regra fiscal ou campo inválido NCM incorreto, CPF ausente em venda > R$ 500 ou alíquota incompatível. Corrigir o campo informado no atributo campo do JSON.
cStat 232 IE do destinatário não informada Cliente PJ possui Inscrição Estadual ativa na SEFAZ, mas foi enviado com indIeDest: 9. Alterar para indIeDest: 1 e preencher a Inscrição Estadual.
cStat 1115 Grupo IBSCBS não informado Empresa do Regime Normal (CRT 3) em SP sem informar o grupo ibsCbs. Informar cst, cClassTrib e alíquotas de IBS/CBS.

9. Tutorial — Minha Primeira Emissão

  1. Obtenha seu token de homologação no painel administrativo (formato emk_...).
  2. Monte um payload simples de NFC-e (Modelo 65) com apenas 1 item e pagamento à vista.
  3. Envie uma requisição HTTP POST para https://api-hml.nexofisc.tech/v1/documentos com o cabeçalho X-Correlation-ID.
  4. Receba o retorno HTTP 201 com o número da nota, protocolo de autorização e chave de 44 dígitos.
  5. Acesse os endpoints /v1/documentos/{id}/xml e /v1/documentos/{id}/danfe para conferir o XML assinado e o PDF para impressão!

10. Glossário Técnico & Fiscal

NF-e (Modelo 55)

Nota Fiscal Eletrônica mercantil para vendas no atacado, B2B ou mercadorias com entrega.

NFC-e (Modelo 65)

Cupom fiscal eletrônico emitido no caixa em vendas diretas ao consumidor final.

IBS & CBS

Novos tributos sobre o consumo criados pela Reforma Tributária em substituição ao ICMS, ISS, PIS e COFINS.

X-Correlation-ID

Identificador único que rastreia a transação da API até os logs do servidor e a SEFAZ.