Docs Integracao — Noria NF-e

🔐 Autenticacao

Todas as requisicoes (exceto /api/nfe/status) exigem o header X-Api-Key com sua chave de API.

Sua API Key: SUA-API-KEY-AQUI

cURL

Python

JavaScript

PHP

C#

curl -X POST https://zapcorder.shop/api/nfe/assinar-transmitir \ -H "X-Api-Key: SUA-API-KEY-AQUI" \ -H "Content-Type: application/json" \ -d '{"xml": "...", "ambiente": "homologacao"}'

import requests resp = requests.post( "https://zapcorder.shop/api/nfe/assinar-transmitir", headers={"X-Api-Key": "SUA-API-KEY-AQUI", "Content-Type": "application/json"}, json={"xml": "...", "ambiente": "homologacao"} ) print(resp.json())

const resp = await fetch("https://zapcorder.shop/api/nfe/assinar-transmitir", { method: "POST", headers: { "X-Api-Key": "SUA-API-KEY-AQUI", "Content-Type": "application/json" }, body: JSON.stringify({ xml: "...", ambiente: "homologacao" }) }); console.log(await resp.json());

$ch = curl_init("https://zapcorder.shop/api/nfe/assinar-transmitir"); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ["X-Api-Key: SUA-API-KEY-AQUI", "Content-Type: application/json"], CURLOPT_POSTFIELDS => json_encode(["xml"=>"...","ambiente"=>"homologacao"]) ]); $resp = json_decode(curl_exec($ch), true);

using var http = new HttpClient(); http.DefaultRequestHeaders.Add("X-Api-Key", "SUA-API-KEY-AQUI"); var resp = await http.PostAsync( "https://zapcorder.shop/api/nfe/assinar-transmitir", new StringContent( JsonSerializer.Serialize(new { xml = "...", ambiente = "homologacao" }), Encoding.UTF8, "application/json" ) );

GET /api/nfe/status Publico

Verifica se a API esta online. Nao requer autenticacao.

GET https://zapcorder.shop/api/nfe/status

Resposta 200

{ "status": "online", "versao": "2.0.0", "biblioteca": "Zeus DFe.NET 2026.5.20.1650", "timestamp": "2026-05-27T17:00:00Z" }

POST /api/nfe/assinar-transmitir

Assina com o certificado A1 e transmite a NF-e para a SEFAZ. O CNPJ no XML e detectado automaticamente para selecionar o certificado correto.

POST https://zapcorder.shop/api/nfe/assinar-transmitir

Campo	Tipo	Descricao
xml	string *	XML da NF-e sem assinatura. Deve conter o CNPJ do emitente.
ambiente	string	"homologacao" (padrao) ou "producao"

cURL

Python

JavaScript

PHP

C#

curl -X POST https://zapcorder.shop/api/nfe/assinar-transmitir \ -H "X-Api-Key: SUA-API-KEY-AQUI" \ -H "Content-Type: application/json" \ -d '{"xml":"...","ambiente":"homologacao"}'

import requests resp = requests.post( "https://zapcorder.shop/api/nfe/assinar-transmitir", headers={"X-Api-Key": "SUA-API-KEY-AQUI"}, json={"xml": "...", "ambiente": "homologacao"} ) data = resp.json() print("Autorizado:", data["protocolo"]) if resp.ok else print("Erro:", data["erro"])

const resp = await fetch("https://zapcorder.shop/api/nfe/assinar-transmitir", { method: "POST", headers: { "X-Api-Key": "SUA-API-KEY-AQUI", "Content-Type": "application/json" }, body: JSON.stringify({ xml: "...", ambiente: "homologacao" }) }); const { protocolo, chave, status } = await resp.json();

$resp = json_decode(file_get_contents("https://zapcorder.shop/api/nfe/assinar-transmitir", false, stream_context_create(["http"=>[ "method"=>"POST", "header"=>"X-Api-Key: SUA-API-KEY-AQUI\r\nContent-Type: application/json\r\n", "content"=>json_encode(["xml"=>"...","ambiente"=>"homologacao"]) ]])), true);

var payload = new { xml = nfeXml, ambiente = "homologacao" }; var resp = await http.PostAsync( "https://zapcorder.shop/api/nfe/assinar-transmitir", new StringContent(JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json") );

Resposta 200 — Autorizado

{ "status": "autorizado", "protocolo": "135240012345678", "chave": "35240612345678000195550010000000121234567890", "xmlAutorizado": "<?xml version=\"1.0\"?><nfeProc versao=\"4.00\"...>" }

Resposta 500 — Erro SEFAZ

{"status":"erro","erro":"539 - Certificado invalido ou revogado."}

POST /api/nfe/cancelar

Envia evento de cancelamento para a SEFAZ. Prazo maximo: 24h apos autorizacao em homologacao, ou conforme legislacao estadual em producao.

POST https://zapcorder.shop/api/nfe/cancelar

Campo	Tipo	Descricao
chave	string *	Chave de acesso da NF-e (44 digitos)
justificativa	string *	Motivo do cancelamento (minimo 15 caracteres)
protocoloAutorizacao	string *	Numero do protocolo de autorizacao
ambiente	string	"homologacao" ou "producao" (padrao)

curl -X POST https://zapcorder.shop/api/nfe/cancelar \ -H "X-Api-Key: SUA-API-KEY-AQUI" \ -H "Content-Type: application/json" \ -d '{ "chave": "35240612345678000195550010000000121234567890", "justificativa": "Nota emitida com erro no valor.", "protocoloAutorizacao": "135240012345678", "ambiente": "producao" }'

Resposta 200

{"status":"cancelado","protocolo":"135240099887766","chave":"35240612345678000195550010000000121234567890"}

GET /api/nfe/consultar/{chave}

Consulta a situacao atual de uma NF-e diretamente na SEFAZ.

GET https://zapcorder.shop/api/nfe/consultar/{chave}?ambiente=producao

Parametro	Tipo	Descricao
chave	path *	Chave de acesso (44 digitos) na URL
ambiente	query	"homologacao" ou "producao" (padrao)

curl "https://zapcorder.shop/api/nfe/consultar/35240612345678000195550010000000121234567890?ambiente=producao" \ -H "X-Api-Key: SUA-API-KEY-AQUI"

Resposta 200

{"chave":"35240612345678000195550010000000121234567890","situacao":"100 - Autorizado o uso da NF-e"}

GET /api/nfe/historico

Historico paginado de todas as operacoes realizadas pela sua conta.

GET https://zapcorder.shop/api/nfe/historico

Query	Tipo	Descricao
pagina	int	Pagina (padrao: 1)
por_pagina	int	Registros por pagina, max 100 (padrao: 20)
tipo	string	"emissao", "cancelamento" ou "consulta"
status	string	"autorizado", "cancelado", "erro" ou "ok"

curl "https://zapcorder.shop/api/nfe/historico?por_pagina=10&tipo=emissao&status=autorizado" \ -H "X-Api-Key: SUA-API-KEY-AQUI"

Resposta 200

{ "total": 142, "pagina": 1, "por_pagina": 10, "paginas": 15, "registros": [ { "id": 142, "tipo": "emissao", "status": "autorizado", "chaveNFe": "35240612345678000195550010000000121234567890", "dataHora": "2026-05-27T14:32:10Z" } ] }

PUT /api/nfe/webhook

Configura a URL e os eventos a receber. O campo eventos e opcional — omita para manter a configuracao atual. Envie url vazio para desativar.

PUT https://zapcorder.shop/api/nfe/webhook

Campo	Tipo	Descricao
url	string	URL HTTPS que receberá os POSTs. Vazio para desativar.
eventos	string[]	Quais eventos notificar. Opcoes: `nfe.autorizada`, `nfe.erro`, `nfe.cancelada`. Omita para manter atual.

curl -X PUT https://zapcorder.shop/api/nfe/webhook -H "X-Api-Key: SUA-API-KEY-AQUI" -H "Content-Type: application/json" -d '{ "url": "https://meusite.com.br/webhook/nfe", "eventos": ["nfe.autorizada", "nfe.cancelada"] }'

Resposta 200

{
  "webhook_url": "https://meusite.com.br/webhook/nfe",
  "webhook_secret": "seu-webhook-secret",
  "webhook_eventos": ["nfe.autorizada", "nfe.cancelada"],
  "eventos_disponiveis": ["nfe.autorizada", "nfe.erro", "nfe.cancelada"],
  "status": "configurado"
}

🔔 Webhooks — Como funciona

Quando um evento ocorre, a API faz um POST automatico para sua URL com os dados do evento e retenta ate 3 vezes em caso de falha (backoff exponencial).

1

Configure sua URL via PUT /api/nfe/webhook

2

Quando uma NF-e for processada, receba o POST automaticamente

3

Verifique o header X-Webhook-Signature com seu secret para garantir autenticidade

4

Retorne HTTP 2xx para confirmar. Sem resposta: retenta 3 vezes com intervalo crescente.

📡 Eventos disponíveis

nfe.autorizada

{ "evento": "nfe.autorizada", "clienteId": 1, "cnpj": "05110962000117", "timestamp": "2026-05-27T17:00:00Z", "dados": { "chave": "35240612345678000195550010000000121234567890", "protocolo": "135240012345678", "ambiente": "producao" } }

nfe.cancelada

{ "evento": "nfe.cancelada", "clienteId": 1, "cnpj": "05110962000117", "timestamp": "2026-05-27T17:05:00Z", "dados": { "chave": "35240612345678000195550010000000121234567890", "protocolo": "135240099887766", "justificativa": "Nota emitida com erro." } }

nfe.erro

{"evento":"nfe.erro","clienteId":1,"cnpj":"05110962000117","timestamp":"2026-05-27T17:10:00Z","dados":{"erro":"539 - Certificado invalido.","ambiente":"producao"}}

🛡️ Verificar assinatura HMAC

Cada webhook traz o header X-Webhook-Signature: sha256=.... Valide com seu secret para garantir que o POST veio da Noria NF-e.

Webhook Secret: seu-webhook-secret

Python

JavaScript

PHP

C#

import hmac, hashlib def verificar(body: bytes, signature: str, secret: str) -> bool: expected = "sha256=" + hmac.new(secret.encode(), body, hashlib.sha256).hexdigest() return hmac.compare_digest(expected, signature) # Flask/FastAPI: body = request.get_data() if not verificar(body, request.headers.get("X-Webhook-Signature",""), "seu-webhook-secret"): return {"erro": "Assinatura invalida"}, 401

$body = file_get_contents("php://input"); $sig = $_SERVER["HTTP_X_WEBHOOK_SIGNATURE"] ?? ""; $exp = "sha256=" . hash_hmac("sha256", $body, "seu-webhook-secret"); if (!hash_equals($exp, $sig)) { http_response_code(401); exit; } $evento = json_decode($body, true);

[HttpPost("/webhook/nfe")] public IActionResult Webhook() { var body = new StreamReader(Request.Body).ReadToEnd(); var sig = Request.Headers["X-Webhook-Signature"].ToString(); var hash = HMACSHA256.HashData(Encoding.UTF8.GetBytes("seu-webhook-secret"), Encoding.UTF8.GetBytes(body)); var exp = "sha256=" + Convert.ToHexString(hash).ToLower(); if (!CryptographicOperations.FixedTimeEquals(Encoding.UTF8.GetBytes(exp), Encoding.UTF8.GetBytes(sig))) return Unauthorized(); return Ok(); }

⚠️ Codigos de erro

HTTP	Mensagem	Descricao
401	X-Api-Key obrigatorio.	Header ausente na requisicao
401	API Key invalida.	Chave nao encontrada no sistema
403	Cliente bloqueado.	Conta suspensa pelo administrador
500	539 - Certificado invalido	Certificado A1 expirado ou senha incorreta
500	Nenhum certificado encontrado	CNPJ emitente sem certificado cadastrado
500	225 - Rejeicao SEFAZ	Erro de validacao no XML pela SEFAZ

🌐 Ambientes

Valor	Descricao
homologacao	Testes — notas sem valor fiscal. Use para desenvolvimento.
producao	Ambiente real — notas com valor fiscal e legal. Use apos homologar.

Atencao: Notas emitidas em producao tem valor fiscal e legal perante a Receita Federal. Sempre teste em homologacao primeiro.