Esta API permite a integração com o sistema de Nota Fiscal de Serviços Eletrônica (NFSe) da Prefeitura de Belo Horizonte. Através dela, é possível realizar todas as operações relacionadas à emissão, consulta e cancelamento de notas fiscais.
Todas as requisições à API devem incluir um token de autenticação no header. Para obter o token:
Faça uma requisição POST para /api/authorization
Use o token retornado no header Authorization de todas as outras requisições
Authorization: Bearer <seu_token>
O sistema implementa um robusto mecanismo de segurança baseado em JWT (JSON Web Token) com as seguintes características:
O sistema possui três tipos de usuários com diferentes níveis de permissão:
Tem acesso completo ao sistema e pode gerenciar todos os prestadores e usuários.
Credenciais padrão: usuário: master, senha: master123
Tem acesso limitado ao prestador ao qual está vinculado e pode gerenciar usuários desse prestador.
Credenciais padrão: usuário: admin, senha: admin
Tem acesso limitado às funcionalidades básicas do sistema e está vinculado a um prestador específico.
Credenciais padrão: usuário: usuario, senha: usuario
As APIs implementam as seguintes restrições de acesso:
A API possui dois ambientes:
| Código | Ambiente | Descrição |
|--------|-------------|------------------------------------------------|
| 1 | Produção | Ambiente real, gera notas fiscais válidas |
| 2 | Homologação | Ambiente de testes, não gera notas fiscais reais |
Endpoint: /api/authorization
Método: POST
Request:
{
"authKey": "senha_de_acesso"
}
Response:
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresIn": 3600
}
Endpoint: /api/nfse/cancelar-nfse
Método: POST
Request:
{
"ambiente": 2,
"numeroNfse": "202500000000009",
"cnpj": "05065736000161",
"inscricaoMunicipal": "01733890014",
"codigoCancelamento": "2"
}
Códigos de Cancelamento:
1: Erro na emissão
2: Serviço não prestado
3: Duplicidade da nota
4: Outros
Response:
{
"success": true,
"message": "NFSe cancelada com sucesso",
"protocolo": "ABC123456789"
}
Endpoint: /api/nfse/consultar-lote-rps
Método: POST
Request:
{
"ambiente": 2,
"Prestador": {
"Cnpj": "05065736000161",
"InscricaoMunicipal": "01733890014"
},
"Protocolo": "Ak0126637325J138VqvXS2mc"
}
Response:
{
"success": true,
"situacao": 4,
"mensagem": "Lote processado com sucesso",
"notas": [
{
"numero": "202500000000009",
"codigoVerificacao": "ABC123",
"dataEmissao": "2025-05-21T14:30:00Z"
}
]
}
Endpoint: /api/nfse/consultar-nfse-por-rps
Método: POST
Request:
{
"ambiente": 2,
"ConsultarNfseRpsEnvio": {
"IdentificacaoRps": {
"Numero": "15",
"Serie": "HOMOL",
"Tipo": "1"
},
"Prestador": {
"CpfCnpj": {
"Cnpj": "05065736000161"
},
"InscricaoMunicipal": "01733890014"
}
}
}
Response:
{
"success": true,
"nfse": {
"numero": "202500000000009",
"codigoVerificacao": "ABC123",
"dataEmissao": "2025-05-21T14:30:00Z",
"status": "1",
"valorServicos": 1000.00
}
}
Endpoint: /api/nfse/consultar-nfse
Método: POST
Request:
{
"ambiente": 2,
"ConsultarNfseEnvio": {
"Prestador": {
"CpfCnpj": {
"Cnpj": "05065736000161"
},
"InscricaoMunicipal": "01733890014"
},
"NumeroNfse": "",
"Periodo": {
"DataInicial": "2025-01-01",
"DataFinal": "2025-12-31"
}
}
}
Response:
{
"success": true,
"notas": [
{
"numero": "202500000000009",
"dataEmissao": "2025-05-21T14:30:00Z",
"valorServicos": 1000.00,
"status": "1"
}
]
}
Endpoint: /api/nfse/consultar-situacao-lote-rps
Método: POST
Request:
{
"ambiente": 2,
"Prestador": {
"Cnpj": "05065736000161",
"InscricaoMunicipal": "01733890014"
},
"Protocolo": "Ak0126637325J138VqvXS2mc"
}
Response:
{
"success": true,
"situacao": 4,
"mensagem": "Lote processado com sucesso"
}
Códigos de Situação:
1: Não Recebido
2: Não Processado
3: Processado com Erro
4: Processado com Sucesso
Endpoint: /api/nfse/emitir-nfse-direct
Método: POST
Request:
{
"ambiente": 2,
"GerarNfseEnvio": {
"Rps": {
"InfRps": {
"IdentificacaoRps": {
"Numero": "123",
"Serie": "HOMOL",
"Tipo": "1"
},
"DataEmissao": "2025-05-21",
"NaturezaOperacao": "1",
"OptanteSimplesNacional": true,
"IncentivadorCultural": false,
"Status": "1",
"Servico": {
"Valores": {
"ValorServicos": 100.00,
"IssRetido": false,
"BaseCalculo": 100.00,
"Aliquota": 0.05,
"ValorLiquidoNfse": 100.00
},
"ItemListaServico": "1401",
"Discriminacao": "Serviço de desenvolvimento de software",
"CodigoMunicipio": "3106200"
},
"Prestador": {
"CpfCnpj": {
"Cnpj": "05065736000161"
},
"InscricaoMunicipal": "01733890014"
},
"Tomador": {
"IdentificacaoTomador": {
"CpfCnpj": {
"Cpf": "12345678900"
}
},
"RazaoSocial": "Nome do Cliente",
"Endereco": {
"Endereco": "Rua Exemplo",
"Numero": "123",
"Bairro": "Centro",
"CodigoMunicipio": "3106200",
"Uf": "MG",
"Cep": "30100000"
}
}
}
}
}
}
Response:
{
"success": true,
"numeroNfse": "202500000000010",
"codigoVerificacao": "XYZ789",
"dataEmissao": "2025-05-21T14:30:00Z",
"protocolo": "DEF987654321"
}
| Código | Descrição |
|--------|----------------------------------------------|
| 400 | Requisição inválida ou dados faltando |
| 401 | Não autorizado - Token inválido ou expirado |
| 404 | Recurso não encontrado |
| 500 | Erro interno do servidor |
Endpoint: /api/nfse/listar
Método: GET
Parâmetros de Consulta:
page: Número da página (padrão: 1)
pageSize: Quantidade de registros por página (padrão: 10)
filtro: Texto para filtrar por número, série ou razão social do tomador
status: Filtro por status da nota fiscal
dataInicio: Data inicial para filtro (formato: YYYY-MM-DD)
dataFim: Data final para filtro (formato: YYYY-MM-DD)
Response:
{
"data": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"numero": "202500000000010",
"serie": "HOMOL",
"dataEmissao": "2025-05-21T14:30:00Z",
"status": "1",
"valorServicos": 100.00,
"prestador": {
"razaoSocial": "Empresa Prestadora Ltda"
},
"tomador": {
"razaoSocial": "Cliente Exemplo"
}
}
],
"pagination": {
"total": 50,
"page": 1,
"pageSize": 10,
"totalPages": 5
}
}
Endpoint: /api/nfse/dados
Método: GET
Response:
{
"prestadores": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"razaoSocial": "Empresa Prestadora Ltda",
"cnpj": "05065736000161"
}
],
"tomadores": [
{
"id": "123e4567-e89b-12d3-a456-426614174001",
"razaoSocial": "Cliente Exemplo",
"cpfCnpj": "12345678900"
}
],
"servicos": [
{
"id": "123e4567-e89b-12d3-a456-426614174002",
"descricao": "Serviço de desenvolvimento de software",
"itemListaServico": "1401"
}
]
}
Endpoint: /api/prestadores/create
Método: POST
Request:
Enviar como FormData com os seguintes campos:
cnpj: CNPJ do prestador (sem formatação)
razaoSocial: Razão social do prestador
nomeFantasia: Nome fantasia (opcional)
inscricaoMunicipal: Inscrição municipal
email: Email de contato
telefone: Telefone de contato
endereco: Endereço
numero: Número do endereço
complemento: Complemento (opcional)
bairro: Bairro
codigoMunicipio: Código IBGE do município
uf: UF
cep: CEP (sem formatação)
serie: Série para emissão de notas (padrão: “1”)
ambiente: Ambiente (1: Produção, 2: Homologação)
optanteSimplesNacional: “true” ou “false”
incentivadorCultural: “true” ou “false”
Response:
Redirecionamento para /prestadores em caso de sucesso.
Endpoint: /api/prestadores/update
Método: POST
Request:
Enviar como FormData com os mesmos campos de criação, mais o campo id do prestador.
Response:
Redirecionamento para /prestadores em caso de sucesso.
Endpoint: /api/tomadores/create
Método: POST
Request:
Enviar como FormData com os seguintes campos:
cpfCnpj: CPF ou CNPJ do tomador (sem formatação)
tipo: Tipo de pessoa (“F” para física, “J” para jurídica)
razaoSocial: Nome ou Razão social do tomador
inscricaoMunicipal: Inscrição municipal (opcional)
email: Email de contato
telefone: Telefone de contato (opcional)
endereco: Endereço
numero: Número do endereço
complemento: Complemento (opcional)
bairro: Bairro
codigoMunicipio: Código IBGE do município
uf: UF
cep: CEP (sem formatação)
Response:
Redirecionamento para /tomadores em caso de sucesso.
Endpoint: /api/tomadores/update
Método: POST
Request:
Enviar como FormData com os mesmos campos de criação, mais o campo id do tomador.
Response:
Redirecionamento para /tomadores em caso de sucesso.
Endpoint: /api/servicos/create
Método: POST
Request:
Enviar como FormData com os seguintes campos:
codigoTributacao: Código de tributação
descricao: Descrição do serviço
itemListaServico: Item da lista de serviços
codigoCnae: Código CNAE (opcional)
codigoNbs: Código NBS (opcional)
unidade: Unidade de medida
valorUnitario: Valor unitário do serviço
codigoMunicipio: Código IBGE do município
exigibilidadeIss: Código de exigibilidade do ISS
aliquota: Alíquota em porcentagem
issRetido: “true” ou “false”
Response:
Redirecionamento para /servicos em caso de sucesso.
Endpoint: /api/servicos/update
Método: POST
Request:
Enviar como FormData com os mesmos campos de criação, mais o campo id do serviço.
Response:
Redirecionamento para /servicos em caso de sucesso.
O sistema oferece endpoints para geração de relatórios em formato PDF.
Endpoint: /api/relatorios/tomadores
Método: POST
Descrição: Gera um relatório em PDF de tomadores cadastrados no sistema.
Request:
{
"prestadorId": "e951a265-cdf8-4f7c-8b30-482a56e082a8",
"filtros": {
"nome": "Empresa XYZ",
"cpfCnpj": "12345678000199",
"codigoMunicipio": "3106200",
"dataInicio": "2025-01-01",
"dataFim": "2025-05-31"
}
}
Response:
Retorna um arquivo PDF com o relatório de tomadores.
Endpoint: /api/relatorios/servicos
Método: POST
Descrição: Gera um relatório em PDF de serviços cadastrados no sistema.
Request:
{
"prestadorId": "e951a265-cdf8-4f7c-8b30-482a56e082a8",
"filtros": {
"codigo": "1.01",
"descricao": "Desenvolvimento",
"dataInicio": "2025-01-01",
"dataFim": "2025-05-31"
}
}
Response:
Retorna um arquivo PDF com o relatório de serviços.
Endpoint: /api/relatorios/notasFiscais
Método: POST
Descrição: Gera um relatório em PDF de notas fiscais emitidas no sistema.
Request:
{
"prestadorId": "e951a265-cdf8-4f7c-8b30-482a56e082a8",
"filtros": {
"tomadorId": "f8a72b45-9d31-4c5e-b8a7-1e5f9a2c7d3e",
"numero": "202500000000009",
"status": "Emitida",
"dataInicio": "2025-01-01",
"dataFim": "2025-05-31"
}
}
Response:
Retorna um arquivo PDF com o relatório de notas fiscais.
Endpoint: /api/relatorios/logs
Método: POST
Descrição: Gera um relatório em PDF de logs do sistema para auditoria.
Request:
{
"prestadorId": "e951a265-cdf8-4f7c-8b30-482a56e082a8",
"filtros": {
"usuarioId": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
"entidade": "Prestador",
"acao": "Criar",
"tela": "Cadastro de Prestador",
"dataInicio": "2025-01-01",
"dataFim": "2025-05-31"
}
}
Response:
Retorna um arquivo PDF com o relatório de logs.
Endpoint: /api/relatorios/usuarios
Método: POST
Descrição: Gera um relatório em PDF de usuários cadastrados no sistema.
Request:
{
"prestadorId": "e951a265-cdf8-4f7c-8b30-482a56e082a8",
"filtros": {
"nome": "João",
"username": "joao.silva",
"role": "Administrador",
"dataInicio": "2025-01-01",
"dataFim": "2025-05-31"
}
}
Response:
Retorna um arquivo PDF com o relatório de usuários.
| Código | Descrição |
|--------|----------------------------------------------|
| 400 | Requisição inválida ou dados faltando |
| 401 | Não autorizado - Token inválido ou expirado |
| 404 | Recurso não encontrado |
| 500 | Erro interno do servidor |
Sempre teste primeiro no ambiente de homologação (ambiente=2)
Valide todos os cenários antes de usar em produção
Implemente tratamento para todos os códigos de erro
Mantenha logs das requisições e respostas
Nunca compartilhe ou exponha tokens de autenticação
Armazene dados sensíveis de forma segura
Implemente cache quando apropriado
Evite consultas desnecessárias
Valide todos os dados antes de enviar
Verifique formatos de datas e valores
Certifique-se que CNPJs e Inscrições Municipais estão sem formatação