Documentação da API

Introdução

A API FiscalHub é uma REST API para emissão de documentos fiscais eletrônicos brasileiros. Todas as requisições são autenticadas por API Key e os retornos são sempre JSON.

Autenticação

Todas as requisições devem incluir o cabeçalho X-Api-Key com uma chave gerada no portal do cliente.

Erros

NF-e Nota Fiscal Eletrônica

POST /api/v1/nfe/emitir

{
  "empresaId": "uuid-da-empresa",
  "naturezaOperacao": "Venda de mercadoria",
  "tipoOperacao": 1,
  "itens": [
    {
      "numeroItem": 1,
      "codigoProduto": "PROD-001",
      "descricao": "Produto Exemplo",
      "ncm": "84713012",
      "cfop": "5102",
      "unidadeComercial": "UN",
      "quantidade": 2,
      "valorUnitario": 150.00,
      "valorTotal": 300.00
    }
  ],
  "pagamentos": [
    { "formaPagamento": "01", "valor": 300.00 }
  ]
}

{
  "documentoId": "uuid-do-documento",
  "status": "Autorizado",
  "chaveAcesso": "35240112345678000195
    55001000000001
    1abc123def456",
  "protocolo": "135240000000001",
  "dataAutorizacao": "2024-01-15T10:30:00Z",
  "motivoRejeicao": null
}

POST /api/v1/nfe/{chave}/manifestacao

Registra a manifestação do destinatário. O campo tipo aceita um dos quatro valores abaixo.

{
  "tipo": "ConfirmacaoDaOperacao",
  "cpfCnpj": "12345678000195",
  "sequenciaEvento": 1,
  "justificativa": null
}

// Valores aceitos para "tipo":
// "ConfirmacaoDaOperacao"
// "CienciaDaOperacao"
// "DesconhecimentoDaOperacao"
// "OperacaoNaoRealizada"
// (justificativa obrigatória nas 2 últimas)

{
  "eventoId": "uuid-do-evento",
  "status": "Registrado",
  "protocolo": "135240000000002",
  "dataEvento": "2024-01-15T11:00:00Z",
  "descricao": "Evento registrado e
    vinculado a NF-e"
}

POST /api/v1/nfe/{chave}/cancelar-substituicao

{
  "justificativa": "NF-e emitida com erro de destinatário, substituída pela chave abaixo",
  "chaveNFeSubstituta": "35240112345678000195550010000000021abc123de",
  "cpfCnpj": "12345678000195",
  "ufAutor": "SP",
  "sequenciaEvento": 1
}

NFC-e Nota Fiscal ao Consumidor

CT-e Conhecimento de Transporte

POST /api/v1/cte/{chave}/desacordo

Registrado pelo tomador/destinatário quando há discordância na prestação do serviço.

{
  "cpfCnpj": "12345678000195",
  "indicadorDesacordo": "1",
  "observacao": "Serviço não foi prestado na data acordada",
  "sequenciaEvento": 1
}

// indicadorDesacordo:
// "1" = Serviço não prestado
// "2" = Serviço prestado mas valor incorreto

POST /api/v1/cte/{chave}/carta-correcao

{
  "sequenciaEvento": 1,
  "correcoes": [
    {
      "grupoAlterado": "ide",
      "campoAlterado": "natOp",
      "valorAlterado": "Prestação de serviço de transporte rodoviário",
      "nroItemAlterado": null
    }
  ]
}

MDF-e Manifesto de Documentos Fiscais

POST /api/v1/mdfe/{chave}/incluir-condutor

{
  "nome": "João da Silva",
  "cpf": "12345678901",
  "sequenciaEvento": 1
}

POST /api/v1/mdfe/{chave}/incluir-dfe

{
  "codigoMunicipioCarregamento": "3550308",
  "nomeMunicipioCarregamento": "São Paulo",
  "sequenciaEvento": 1,
  "documentos": [
    {
      "codigoMunicipioDescarga": "3304557",
      "nomeMunicipioDescarga": "Rio de Janeiro",
      "chaveNFe": "35240112345678000195550010000000011abc1234"
    }
  ]
}

POST /api/v1/mdfe/{chave}/pagamento

{
  "qtdViagens": "1",
  "nroViagem": "001",
  "sequenciaEvento": 1,
  "pagamentos": [
    {
      "cnpj": "12345678000195",
      "xNome": "Transportadora Exemplo",
      "indPag": 0,
      "vContrato": 1500.00
    }
  ]
}

// indPag: 0 = À Vista, 1 = A Prazo

NFS-e Nota Fiscal de Serviços

Motor Tributário

POST /api/v1/tributario/simular-nfe

{
  "empresaId": "uuid-da-empresa",
  "ufDestino": "RJ",
  "naturezaOperacao": "Venda",
  "valorFrete": 50.00,
  "valorSeguro": 0.00,
  "desconto": 0.00,
  "itens": [
    {
      "ncm": "84713012",
      "cfop": "6102",
      "valorUnitario": 1250.00,
      "quantidade": 2,
      "cst": "00"
    }
  ]
}

{
  "valorProdutos": 2500.00,
  "valorFrete":      50.00,
  "valorSeguro":      0.00,
  "desconto":         0.00,
  "valorIcms":      300.00,
  "valorIpi":         0.00,
  "valorIcmsSt":      0.00,
  "valorPis":        41.25,
  "valorCofins":    190.00,
  "valorDifal":     112.50,
  "valorTotalNota": 2843.75
}

IBS/CBS — Reforma Tributária

A partir de 2026, a NF-e passa a exigir o preenchimento dos tributos da Reforma Tributária: IBS (Imposto sobre Bens e Serviços — substitui ICMS e ISS) e CBS (Contribuição sobre Bens e Serviços — substitui PIS e COFINS), conforme EC 132/2023 e LC 214/2025.

Informar IBS/CBS em um item da NF-e

Inclua o objeto ibsCbs dentro de impostos em cada item:

"itens": [
  {
    "numeroItem": 1,
    "descricao": "Produto Exemplo",
    "ncm": "84713012",
    "quantidade": 1,
    "valorUnitario": 2500.00,
    "valorTotal": 2500.00,
    "impostos": {
      "ibsCbs": {
        "cst": "000",
        "baseCalculo": 2500.00,
        "aliquotaIbsUf":  0.05,
        "valorIbsUf":     1.25,
        "aliquotaIbsMun": 0.05,
        "valorIbsMun":    1.25,
        "aliquotaCbs":    0.90,
        "valorCbs":      22.50
      }
    }
  }
]

{
  "totais": {
    "valorIcms":    300.00,
    "valorPis":      41.25,
    "valorCofins":  190.00,
    "valorIbsUf":     1.25,
    "valorIbsMun":    1.25,
    "valorCbs":      22.50
  }
}

Consultar XML de NF-e

Consulta o XML autorizado (nfe-proc = NF-e + protocolo) diretamente na SEFAZ. Útil para reobter o XML caso ele não tenha sido armazenado localmente.

GET /api/v1/nfe/{chave}/xml

{
  "chaveAcesso": "35250112345678...",
  "codigoStatus": 100,
  "motivo": "Autorizado o uso da NF-e",
  "protocolo": "135250000000001",
  "xmlNfeProc": "<?xml version=\"1.0\"?>
    <nfeProc versao=\"4.00\">...</nfeProc>"
}

Distribuição DFe — Importação de XML

Busca as NF-es e eventos emitidos contra o CNPJ de uma empresa, diretamente da SEFAZ. Retorna os documentos em ordem de NSU (Número Sequencial Único), permitindo varredura incremental. Use para implementar importação automática de notas recebidas no seu ERP ou sistema.

GET /api/v1/nfe/distribuicao

{
  "codigoStatus": 138,
  "motivo": "Documento localizado",
  "ultNsu": 1523,
  "maxNsu": 9999,
  "documentos": [
    {
      "nsu": 1501,
      "schema": "resNFe",
      "chaveAcesso": "35250112345678...",
      "cnpjEmitente": "12345678000195",
      "nomeEmitente": "Fornecedor Ltda",
      "valorNf": 1500.00,
      "dataEmissao": "2025-04-01T10:00:00Z",
      "xmlBase64": "PD94bWwgdmVyc2..."
    }
  ]
}

Consulta NCM

GET /api/v1/ncm/84713012

{
  "codigo": "84713012",
  "descricao": "Máquinas automáticas para processamento de dados, portáteis",
  "aliquotaIpi": 0.00,
  "cest": null,
  "unidadeMedida": "UN",
  "atualizadoEm": "2024-01-10T00:00:00Z"
}