NF-e em produção. O ambiente publicado emite NF-e (modelo 55) com valor fiscal para as empresas que o Notaê liberou. A NFC-e em produção ainda depende do credenciamento do Notaê na SEF/SC. Confira official_issuance_enabled antes de emitir.
1. Consulte as capacidades
GET /api/v1/capabilities informa o modo configurado, a matriz de cobertura e o bloqueio global de emissão oficial. A consulta é somente leitura e não exige chave de API.
// Execute com Node.js 24. Esta consulta não cria documentos.
const base = process.env.FARO_APP_URL ?? 'http://127.0.0.1:3037';
const response = await fetch(base + '/api/v1/capabilities', {
signal: AbortSignal.timeout(15000)
});
const data = await response.json();
if (!response.ok) {
throw new Error(data.code + ': ' + data.message);
}
console.log('Ambiente:', data.mode);
console.log('Emissão oficial habilitada:', data.official_issuance_enabled);
console.log('Cobertura publicada:', data.data);
Trate official_issuance_enabled: false como bloqueio obrigatório. Uma linha de cobertura, isoladamente, não autoriza transmitir documentos.
2. Use credenciais restritas
Operações protegidas aceitam uma sessão pessoal ou uma chave de API com organização, ambiente, escopos e empresas autorizadas. Um administrador cria a chave em Integrações; o segredo aparece uma única vez e deve ficar apenas no servidor.
Envie a chave no header Authorization: Bearer …. Nunca inclua tokens em URLs, frontend público, logs ou mensagens de suporte. Criar e revogar chaves exige autorização atual, conferida de novo no banco.
3. Operações disponíveis
GET /api/v1/capabilitiesAmbiente, cobertura publicada e bloqueio de emissão oficial.GET /api/v1/meOrganização, ambiente, papel e escopos da credencial.GET /api/v1/issuersEmpresas autorizadas para a credencial.GET /api/v1/customers · /productsClientes e produtos cadastrados.POST /api/v1/documents/validateConfere a nota e calcula os impostos, sem reservar número.POST /api/v1/salesConector: manda a venda como o seu sistema conhece; o Notaê cadastra o que faltar e emite sozinho. Sem cliente, sai NFC-e; com cliente, NF-e.GET /api/v1/sales/{sale_id}A nota que a venda gerou, para reconciliar depois de queda de conexão.POST /api/v1/documentsAdmite a nota com Idempotency-Key (empresas liberadas para produção).GET /api/v1/documents/{id}Situação, protocolo e chave de acesso.GET /api/v1/documents/{id}/filesXML autorizado, DANFE e comprovantes.POST /api/v1/documents/{id}/reconcilePede nova consulta de um resultado desconhecido.POST /api/v1/documents/{id}/fiscal-eventsCancelamento e carta de correção.POST /api/v1/documents/{id}/emailEnvia XML e DANFE ao destinatário, quando há provedor configurado.GET /api/exportsBaixa em ZIP os arquivos de um período, com relação em CSV.GET · PUT /api/v1/issuers/{id}/sequencesConsulta e confirma a numeração por série. Use ?document_type=nfce para a NFC-e.GET · POST /api/v1/issuers/{id}/invalidationsInutilização de faixa de numeração.As rotas autenticadas dependem do acesso privado provisionado e do escopo correspondente na credencial.
4. Emissão, repetição e resultado
Validação, admissão idempotente, consulta, eventos e arquivos estão implementados. No acesso privado, a admissão funciona em produção para a NF-e das empresas liberadas; cada nota autorizada tem valor fiscal.
Repetições devem manter a mesma Idempotency-Key, referência comercial e conteúdo. Um timeout nunca autoriza criar outra nota: consulte e reconcilie a solicitação existente.
O que ainda falta
Connect com consentimento OAuth e sessões hospedadas ainda não estão disponíveis. Cancelamento, carta de correção e webhooks assinados estão implementados. A NFC-e em produção aguarda o credenciamento do Notaê na SEF/SC. O OpenAPI e os SDKs descrevem código em evolução.
Antes de desenvolver contra uma operação fiscal, confira a cobertura por cenário. A interface pública permanece versionada em /api/v1.