NFe-Fácil logo
API docs by Redocly

NFe-Fácil API (1.0.0)

Download OpenAPI specification:

  API para extração de dados de Notas Fiscais Eletrônicas de Serviço (NFSe).
  Permite o processamento, consulta e gerenciamento de lotes de NFSe,
  incluindo operações síncronas e assíncronas.
  
  A NFSe é o documento fiscal eletrônico que comprova a prestação de serviços,
  sendo obrigatório para empresas e profissionais autônomos.
  
  Principais funcionalidades:
   - Extração de dados de NFSe de arquivos PDF e ZIP síncrona e assíncrona
   - Webhooks para notificação de status de processamento

Autenticação

Utilize API Key and Secret gerados no Dashboard da NFe-Fácil para autenticação no formato Basic. As requisições devem ser feitas no formato: Authorization: Basic {base64(API_KEY:SECRET)}

NFSe

Módulo para processamento de Notas Fiscais de Serviço Eletrônicas (NFSe). Oferece funcionalidades completas para criação, gerenciamento e processamento de lotes de NFSe, tanto de forma síncrona quanto assíncrona. Este módulo faz parte da API de Documentos Fiscais Eletrônicos, que será expandida com novos módulos para outros tipos de documentos no futuro.

Processar um único arquivo de NFSe de forma síncrona

Realiza a extração de dados de um único arquivo de NFSe de forma síncrona. Este endpoint aceita apenas um arquivo PDF e retorna os dados extraídos em formato camelCase. O processamento é realizado de forma imediata e a resposta contém os dados estruturados da NFSe.

Authorizations:
basic
Request Body schema: multipart/form-data
required
file
required
string <binary>

Arquivo PDF contendo a NFSe a ser processada

Responses

Response samples

Content type
application/json
{
  • "dataEmissao": "2023-07-15T14:30:00",
  • "prestadorCnpjCpf": "12345678901234",
  • "prestadorInscricaoMunicipal": "123456789",
  • "prestadorTelefone": "11912345678",
  • "prestadorNomeEmpresarial": "Empresa XYZ Ltda",
  • "prestadorEmail": "[email protected]",
  • "prestadorEndereco": "Rua Exemplo, 123, Sala 45",
  • "prestadorMunicipio": "São Paulo",
  • "prestadorCep": "01234-567",
  • "tomadorCnpjCpf": "98765432109876",
  • "tomadorInscricaoMunicipal": "987654321",
  • "tomadorTelefone": "11987654321",
  • "tomadorNomeEmpresarial": "Cliente ABC S/A",
  • "tomadorEmail": "[email protected]",
  • "tomadorEndereco": "Avenida Cliente, 456, Andar 10",
  • "tomadorMunicipio": "Rio de Janeiro",
  • "tomadorCep": "20000-000",
  • "servicoPrestadoCodigo": "01.01",
  • "servicoPrestadoDescricaoServico": "Desenvolvimento de software sob encomenda",
  • "valorTotalNfseValorLiquidoNfse": "950.00",
  • "totaisAproximadosTributosFederais": "142.50",
  • "totaisAproximadosTributosEstaduais": "47.50",
  • "totaisAproximadosTributosMunicipais": "95.00"
}

Criar um novo lote de processamento de NFSe

Cria um novo lote para extração assíncrona de dados de arquivos de NFSe. Este endpoint permite iniciar um lote vazio ou com arquivos iniciais. É a primeira etapa do fluxo assíncrono, ideal para processamento em lote de grandes volumes de arquivos. Consulte o diagrama em /diagrams/nfse-flow-diagram.png para melhor entendimento.

Authorizations:
basic
Request Body schema: multipart/form-data
required
files
Array of strings <binary> [ items <binary > ]

Lista opcional de arquivos a serem processados. Aceita PDFs e ZIPs contendo PDFs.

outputFormats
Array of strings
Items Enum: "json" "csv" "xlsx"

Formatos de saída desejados (json, csv, xlsx)

Responses

Response samples

Content type
application/json
{
  • "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  • "status": "PROCESSING",
  • "template": "d7e8f9a0-b1c2-3456-d7e8-f9a0b1c23456",
  • "user": "12345678-90ab-cdef-1234-567890abcdef",
  • "totalFiles": 10,
  • "processedFiles": 5,
  • "requestedFormats": [
    ],
  • "jsonResults": "{\"results\": [...]}",
  • "csvResults": "id,nome,valor\n1,item1,100.00\n2,item2,200.00",
  • "excelResults": "base64-encoded-excel-content"
}

Obter informações de um lote extração de NFSe

Recupera informações detalhadas sobre um lote específico de NFSe, incluindo seu status atual, quantidade de arquivos e resultados de processamento (se concluído).

Authorizations:
basic
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  • "status": "PROCESSING",
  • "template": "d7e8f9a0-b1c2-3456-d7e8-f9a0b1c23456",
  • "user": "12345678-90ab-cdef-1234-567890abcdef",
  • "totalFiles": 10,
  • "processedFiles": 5,
  • "requestedFormats": [
    ],
  • "jsonResults": "{\"results\": [...]}",
  • "csvResults": "id,nome,valor\n1,item1,100.00\n2,item2,200.00",
  • "excelResults": "base64-encoded-excel-content"
}

Cancelar processamento de lote de NFSe

Cancela o processamento de um lote existente. Se o lote já estiver em processamento, tenta interromper as operações em andamento. Lotes já processados não podem ser cancelados.

Authorizations:
basic
path Parameters
id
required
string

Responses

Adicionar arquivos a um lote existente

Permite adicionar novos arquivos a um lote de processamento já existente. Útil para agregar mais NFSe a um lote antes de iniciar seu processamento assíncrono. Os arquivos são validados antes de serem adicionados ao lote.

Authorizations:
basic
path Parameters
id
required
string
Request Body schema: multipart/form-data
required
files
required
Array of strings <binary> [ items <binary > ]

Lista de arquivos a serem processados. Aceita PDFs e ZIPs contendo PDFs.

Responses

Processar lote de NFSe de forma assíncrona

Inicia o processamento assíncrono de um lote de NFSe. Este endpoint retorna imediatamente após iniciar o processamento em segundo plano, permitindo o processamento eficiente de grandes volumes de arquivos. O progresso pode ser acompanhado consultando o status do lote, e notificações via webhook podem ser configuradas para informar sobre a conclusão. Para entender o fluxo completo, consulte o diagrama em /diagrams/nfse-flow-diagram.png

Authorizations:
basic
path Parameters
id
required
string

Responses

Webhooks

Criar um novo webhook para NFSe

Cria um novo endpoint de webhook para receber notificações relacionadas ao processamento de NFSe. Os eventos disponíveis são:

• DOCUMENT_PROCESSED: Enviado quando uma NFSe é processada com sucesso. O payload contém os dados extraídos da NFSe, ID do documento, status, nome do arquivo e data de processamento.

• DOCUMENT_FAILED: Enviado quando ocorre uma falha no processamento de uma NFSe. O payload contém o ID do documento, a mensagem de erro, nome do arquivo e data da falha.

• BATCH_FINISHED: Enviado quando um lote completo de NFSe é finalizado. O payload contém o ID do lote processado.

Authorizations:
basic
Request Body schema: application/json
required

Dados para criação do webhook

name
required
string

Nome do webhook

url
required
string

URL de destino para as notificações do webhook

events
required
Array of strings
Items Enum: "DOCUMENT_PROCESSED" "DOCUMENT_FAILED" "BATCH_FINISHED"

Lista de eventos para se inscrever

authType
required
string
Enum: "NONE" "BASIC" "OAUTH2"

Tipo de autenticação para o webhook

BasicAuthConfigInputPt (object) or OAuth2ConfigInputPt (object)

Configuração de autenticação (se necessário)

headers
object

Cabeçalhos personalizados para a requisição do webhook

maxRetries
number
Default: 5

Número máximo de tentativas para o webhook

timeout
number
Default: 5000

Tempo limite para a requisição do webhook (em milissegundos)

Responses

Request samples

Content type
application/json
{
  • "name": "Webhook de Processamento de Notas Fiscais",
  • "url": "https://api.exemplo.com.br/webhooks",
  • "events": [
    ],
  • "authType": "NONE",
  • "authConfig": {
    },
  • "headers": {
    },
  • "maxRetries": 3,
  • "timeout": 5000
}

Response samples

Content type
application/json
{
  • "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  • "name": "Webhook de Processamento de Notas Fiscais",
  • "url": "https://api.exemplo.com.br/webhooks",
  • "events": [
    ],
  • "authType": "NONE",
  • "authConfig": {
    },
  • "headers": {
    },
  • "maxRetries": 3,
  • "timeout": 5000,
  • "active": true,
  • "userId": "12345678-90ab-cdef-1234-567890abcdef",
  • "createdAt": "2023-09-15T14:30:15.123Z",
  • "updatedAt": "2023-09-15T14:30:15.123Z"
}

Listar todos os webhooks de NFSe

Retorna uma lista paginada de todos os webhooks configurados para o processamento de NFSe.

Authorizations:
basic
query Parameters
sortDirection
string
Default: "ASC"
Enum: "ASC" "DESC"
sortField
string
Default: "id"

The field to sort by

page
number >= 1
Default: 1
pageSize
number [ 1 .. 100 ]
Default: 10

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 100,
  • "page": 1,
  • "pageSize": 10,
  • "totalPages": 10
}

Obter webhook por ID

Recupera informações detalhadas de um webhook específico configurado para NFSe pelo seu ID.

Authorizations:
basic
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  • "name": "Webhook de Processamento de Notas Fiscais",
  • "url": "https://api.exemplo.com.br/webhooks",
  • "events": [
    ],
  • "authType": "NONE",
  • "authConfig": {
    },
  • "headers": {
    },
  • "maxRetries": 3,
  • "timeout": 5000,
  • "active": true,
  • "userId": "12345678-90ab-cdef-1234-567890abcdef",
  • "createdAt": "2023-09-15T14:30:15.123Z",
  • "updatedAt": "2023-09-15T14:30:15.123Z"
}

Atualizar webhook

Atualiza as configurações de um webhook existente para o processamento de NFSe.

Authorizations:
basic
path Parameters
id
required
string
Request Body schema: application/json
required

Dados de atualização do webhook

name
string

Nome do webhook

url
string

URL de destino para as notificações do webhook

events
Array of strings
Items Enum: "DOCUMENT_PROCESSED" "DOCUMENT_FAILED" "BATCH_FINISHED"

Lista de eventos para se inscrever

authType
string
Enum: "NONE" "BASIC" "OAUTH2"

Tipo de autenticação para o webhook

authConfig
object

Configuração de autenticação (se necessário)

headers
object

Cabeçalhos personalizados para a requisição do webhook

active
boolean

Indica se o webhook está ativo

Responses

Request samples

Content type
application/json
{
  • "name": "Webhook de Processamento de Notas Fiscais",
  • "url": "https://api.exemplo.com.br/webhooks",
  • "events": [
    ],
  • "authType": "NONE",
  • "authConfig": {
    },
  • "headers": {
    },
  • "active": true
}

Response samples

Content type
application/json
{
  • "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  • "name": "Webhook de Processamento de Notas Fiscais",
  • "url": "https://api.exemplo.com.br/webhooks",
  • "events": [
    ],
  • "authType": "NONE",
  • "authConfig": {
    },
  • "headers": {
    },
  • "maxRetries": 3,
  • "timeout": 5000,
  • "active": true,
  • "userId": "12345678-90ab-cdef-1234-567890abcdef",
  • "createdAt": "2023-09-15T14:30:15.123Z",
  • "updatedAt": "2023-09-15T14:30:15.123Z"
}

Excluir webhook

Remove um webhook configurado para o processamento de NFSe.

Authorizations:
basic
path Parameters
id
required
string

Responses

Acionar notificações de webhook

Dispara manualmente notificações para webhooks registrados no contexto de processamento de NFSe (Utilizado para testes).

Estruturas de Payload por Evento:

• DOCUMENT_PROCESSED: 

{
  "documentId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "PROCESSED",
  "fileName": "nfse_12345.pdf",
  "processedAt": "2023-09-15T14:30:15.123Z",
  "batchId": "123e4567-e89b-12d3-a456-426614174001",
  "result": { /* Dados extraídos da NFSe */ }
}

• DOCUMENT_FAILED: 

{
  "documentId": "123e4567-e89b-12d3-a456-426614174000",
  "error": "Não foi possível extrair os dados do documento: formato inválido",
  "fileName": "nfse_12345.pdf",
  "failedAt": "2023-09-15T14:30:15.123Z",
  "batchId": "123e4567-e89b-12d3-a456-426614174001"
}

• BATCH_FINISHED: 

{
  "batchId": "123e4567-e89b-12d3-a456-426614174001"
}
Authorizations:
basic
Request Body schema: application/json
required

Payload de notificação de webhook baseado no tipo de evento

Any of
documentId
required
string

Identificador único do documento processado

status
required
string

Status do processamento do documento

fileName
required
string

Nome do arquivo processado

processedAt
required
string

Data e hora do processamento

batchId
required
string

Identificador do lote ao qual o documento pertence

result
required
object

Resultado do processamento com os dados extraídos

Responses

Request samples

Content type
application/json
Example
{
  • "event": "DOCUMENT_PROCESSED",
  • "timestamp": "2023-09-15T14:30:15.123Z",
  • "payload": {
    }
}