Integre a NFS-e com contexto, previsibilidade e segurança.

Visão geral

O modelo mental da integração

A configuração fiscal vive em recursos reutilizáveis. Cada emissão referencia um emitente e um perfil de serviço, entra em uma fila assíncrona e evolui até um estado final.

1. 1
   Configure

   Emitente, perfil de serviço e certificado A1 válido.

2. 2
   Valide e envie

   Valide o payload e crie a emissão com uma chave de idempotência.

3. 3
   Acompanhe

   Consulte o estado ou processe os webhooks assinados.

4. 4
   Concilie

   Relacione o resultado ao seu billing e obtenha o XML autorizado.

Autenticação

Uma credencial por integração, com o menor escopo possível

Todas as rotas /v1 exigem o header Authorization: Bearer <API_KEY>. A chave identifica a organização automaticamente.

Primeira chamada

Confirme a URL e a disponibilidade do serviço

Defina as variáveis no seu shell. O healthcheck é público e não acessa dados da organização.

export INVIO_API_URL="https://SUA_URL_DA_API"
export INVIO_API_KEY="sua_chave_de_api"

curl --fail-with-body "$INVIO_API_URL/health"

Chamadas autenticadas atualizam apenas o campo operacional last_used_at da chave.

Referência principal

Emissões

curl --fail-with-body   "$INVIO_API_URL/v1/emissions?status=authorized&limit=20&offset=0"   -H "Authorization: Bearer $INVIO_API_KEY"

{
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "emitter_id": "00000000-0000-0000-0000-000000000000",
      "status": "authorized",
      "ambiente": "restrita",
      "chave_acesso": "00000000000000000000000000000000000000000000000000",
      "created_at": "2026-08-06T12:00:00.000Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

Paginação

Navegue com limit e offset

A resposta de listagem sempre inclui data, total, limit e offset. Para a próxima página, some o limit atual ao offset.

Ciclo de vida

Estados de uma emissão

Integração nacional

SEFIN: protocolo, ambientes e regras de transporte

A API Invio encapsula a comunicação com o Sistema Nacional NFS-e. A unidade enviada é uma DPS no layout 1.01; a NFS-e é o documento autorizado devolvido pelo ambiente nacional.

Ambientes nacionais

Operações do protocolo nacional

Essas são operações entre a infraestrutura Invio e a SEFIN, não endpoints para consumo direto do cliente. O transporte usa timeout de 60 segundos e valida a cadeia TLS do servidor.

Regras que evitam rejeições recorrentes

Diagnóstico rápido

SDK TypeScript

@useinvio/nfse-sdk: a camada protocolar da NFS-e Nacional

O pacote público atende Node.js 20 ou superior, usa ESM e não depende de banco, tenant ou estado da aplicação. Ele transforma dados declarativos em DPS, valida, assina, compacta e transporta — sem decidir o tratamento fiscal pelo integrador.

Pontos de entrada públicos

Exemplo seguro: gerar a DPS sem transmitir

Este exemplo apenas valida o objeto e produz o XML localmente. Use dados fictícios em desenvolvimento e valide escolhas fiscais com a contabilidade.

import { buildDpsFromJson, type DpsJsonRequest } from "@useinvio/nfse-sdk";

const nota: DpsJsonRequest = {
  ambiente: "restrita",
  prestador: {
    cnpj: "12345678000195",
    cLocEmi: "4106902",
    serie: "1601",
    opSimpNac: "1",
    regEspTrib: "0"
  },
  servico: {
    cTribNac: "010201",
    xDescServ: "Desenvolvimento de software — exemplo",
    cLocPrestacao: "4106902"
  },
  emissao: {
    nDPS: "1",
    dhEmi: "2026-08-06T10:00:00-03:00",
    dCompet: "2026-08-01",
    valores: { vServ: "1000.00" },
    tributacaoMunicipal: { tribISSQN: "3", cPaisResult: "BR", tpRetISSQN: "1" },
    tributacaoFederal: { piscofins: { CST: "07" } },
    totTrib: { pTotTribFed: "0.00", pTotTribEst: "0.00", pTotTribMun: "5.00" }
  }
};

const { id, xml } = buildDpsFromJson(nota);
console.log(id, xml); // apenas gera XML local; não transmite

Validações e invariantes

• Layout: DPS_SCHEMA_VERSION = 1.01.
• Sem defaults fiscais silenciosos: blocos obrigatórios, como tributação municipal e total de tributos, precisam ser explícitos.
• totTrib: segue um xs:choice; informe exatamente uma modalidade de totalização.
• Certificado: aceita PFX em arquivo, Buffer ou base64; a chave privada e o certificado PEM são usados no handshake mTLS.
• XML: a DPS é validada no XSD antes de ser assinada; a assinatura é verificada antes da transmissão.
• Limite atual: o bloco RTC IBSCBS do layout nacional ainda não está implementado na SDK.

Pipeline de emissão da SDK

Tratamento de falhas

Leia o status HTTP e preserve o corpo da resposta

A API ainda possui formatos de erro específicos por rota. Sempre trate o status e o campo error; respostas de validação também podem incluir issues, warnings ou um relatório fiscal.

{
  "error": "Muitas requisições",
  "message": "Limite de emissões atingido. Tente novamente em 30s.",
  "retryAfter": 30
}

Eventos assíncronos

Webhooks assinados com HMAC-SHA256

A Invio envia JSON por POST para uma URL HTTPS pública. O header X-Invio-Signature contém sha256=<hex>, calculado sobre os bytes exatos do corpo.

{
  "event": "emission.authorized",
  "emission_id": "00000000-0000-0000-0000-000000000000",
  "chave_acesso": "00000000000000000000000000000000000000000000000000",
  "timestamp": "2026-08-06T12:00:00.000Z"
}

Validação da assinatura em Node.js

Valide o corpo bruto antes de fazer o parse do JSON e compare os hashes em tempo constante.

import { createHmac, timingSafeEqual } from "node:crypto";

export function isValidInvioSignature(rawBody, signature, secret) {
  const received = signature.replace(/^sha256=/, "");
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(received, "hex");
  const b = Buffer.from(expected, "hex");
  return a.length === b.length && timingSafeEqual(a, b);
}

Mapa de recursos

Superfície da API v1

Operações com efeito

Entenda o impacto antes de executar

Estas rotas são parte da API, mas não recebem comandos copiáveis nesta documentação pública.