Documentacao da API NFSe

API REST profissional para operacoes de NFSe (Nota Fiscal de Servicos Eletronica) no Brasil.

REST API Autenticacao Segura JSON
Base URL
https://eznotas.com/api/v1
Content-Type
application/json
Autenticacao Operacoes NFSe Codigos de Erro Exemplos

Autenticacao

A API suporta multiplos metodos de autenticacao.

Recomendado

Bearer Token

Authorization: Bearer {your_api_token}

Basic Auth

Authorization: Basic {base64(email:password)}
POST /api/v1/auth/token

Gera um token de API usando email e senha.

Request

{
  "email": "user@example.com",
  "password": "your_password",
  "device_name": "My App"
}

Response

{
  "success": true,
  "data": {
    "token": "abc123...",
    "token_type": "Bearer"
  }
}

Operacoes NFSe

Endpoints para gerenciar Notas Fiscais de Servico Eletronicas.

GET /api/v1/nfse/cities Publico

Lista todas as cidades suportadas para emissao de NFSe.

GET /api/v1/nfse Autenticacao Necessaria

Lista NFSes com filtros e paginacao.

Parametros de Consulta

Parametro Tipo Descricao
search string Busca por numero, nome ou documento
status string authorized, pending, cancelled
date_from date YYYY-MM-DD
date_to date YYYY-MM-DD
per_page integer Itens por pagina (padrao: 15, max: 100)
POST /api/v1/nfse Autenticacao Necessaria

Emite uma nova NFSe.

Request Body

{
  "title": "NFSe - Client Name",
  "company_id": 1,
  "city_code": "3550308",
  "rps_number": 1,
  "rps_series": "RPS",
  "service_value": 1000.00,
  "service_description": "Professional services",
  "service_code": "01.01",
  "iss_retido": false,
  "aliquota_iss": 5.0,
  "tomador": {
    "nome": "Client Name",
    "documento": "12345678901",
    "endereco": "Av. Paulista",
    "numero": "1000",
    "bairro": "Bela Vista",
    "cep": "01310100",
    "cidade": "Sao Paulo",
    "uf": "SP",
    "email": "client@example.com"
  }
}
GET /api/v1/nfse/{id}

Retorna detalhes de uma NFSe especifica.

GET /api/v1/nfse/{id}/pdf

Retorna o link do PDF da NFSe.

POST /api/v1/nfse/{id}/consult

Consulta o status da NFSe no webservice municipal.

{ "certificate_id": 1 }
POST /api/v1/nfse/{id}/cancel

Cancela uma NFSe emitida.

{
  "certificate_id": 1,
  "cancel_reason": "Service not provided as agreed."
}
POST /api/v1/nfse/sync

Sincroniza NFSes do webservice municipal por periodo.

{
  "start_date": "2026-01-01",
  "end_date": "2026-01-31",
  "city_code": "3550308",
  "certificate_id": 1,
  "environment": "production"
}

Codigos de Erro

Todos os erros seguem um formato padronizado para facilitar o tratamento.

Formato da Resposta de Erro

{
  "success": false,
  "error": {
    "code": "NFSE_4400_CERTIFICATE_INVALID",
    "numeric_code": 4400,
    "category": "certificate",
    "message": "Certificado digital inválido.",
    "timestamp": "2026-01-09T12:00:00+00:00",
    "request_id": "req_abc123xyz",
    "retryable": false
  }
}

Categorias de Erro

Faixa de Codigo Categoria HTTP Status
4000-4099 Validacao 400/422
4100-4199 Autenticacao 401
4200-4299 Autorizacao 403
4300-4399 Nao Encontrado 404
4400-4499 Certificado 422
4500-4599 Cidade/Servico 422
4600-4699 Logica de Negocio 409/422
4700-4799 Limite de Requisicoes 429
5000-5099 Servidor 500
5100-5199 Webservice 502/503/504
5200-5299 SEFAZ 422

Exemplos de Codigo

Exemplos praticos em diferentes linguagens de programacao.

Gerar Token

curl -X POST https://eznotas.com/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"your_password"}'

Listar NFSes

curl https://eznotas.com/api/v1/nfse \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Emitir NFSe

curl -X POST https://eznotas.com/api/v1/nfse \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "NFSe Test",
    "company_id": 1,
    "city_code": "3550308",
    "rps_number": 1,
    "rps_series": "RPS",
    "service_value": 1000.00,
    "service_description": "Services rendered",
    "service_code": "01.01",
    "tomador": {
      "nome": "Client",
      "documento": "12345678901",
      "endereco": "Street",
      "numero": "100",
      "bairro": "District",
      "cep": "01310100",
      "cidade": "Sao Paulo",
      "uf": "SP"
    }
  }'

Limite de Requisicoes

A API possui limites de requisicoes para garantir estabilidade:

  • 60 requisicoes por minuto por usuario
  • 1000 requisicoes por dia por usuario

Pronto para comecar?

Integre seu sistema com nossa API e automatize a emissao de NFSe.

Comecar Agora Falar com Suporte