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.
idExterno impede duplicidade em quedas de rede.
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*):
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
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
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:
"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
- Obtenha seu token de homologação no painel administrativo (formato
emk_...). - Monte um payload simples de NFC-e (Modelo 65) com apenas 1 item e pagamento à vista.
- Envie uma requisição HTTP POST para
https://api-hml.nexofisc.tech/v1/documentoscom o cabeçalhoX-Correlation-ID. - Receba o retorno HTTP 201 com o número da nota, protocolo de autorização e chave de 44 dígitos.
- Acesse os endpoints
/v1/documentos/{id}/xmle/v1/documentos/{id}/danfepara conferir o XML assinado e o PDF para impressão!
10. Glossário Técnico & Fiscal
Nota Fiscal Eletrônica mercantil para vendas no atacado, B2B ou mercadorias com entrega.
Cupom fiscal eletrônico emitido no caixa em vendas diretas ao consumidor final.
Novos tributos sobre o consumo criados pela Reforma Tributária em substituição ao ICMS, ISS, PIS e COFINS.
Identificador único que rastreia a transação da API até os logs do servidor e a SEFAZ.