Documentação da API NFS-eNFS-e API Documentation

QuickstartQuickstart

Fluxo completo para emitir sua primeira NFS-e de teste no Sandbox, do zero, em 4 passos. The complete flow to issue your first test invoice on the Sandbox, from scratch, in 4 steps.

1Visão geralOverview

A API opera em dois ambientes independentes, selecionados diretamente pelo caminho da rota.The API runs on two independent environments, selected directly through the route path.

2Segurança & boas práticasSecurity & best practices

Recomendações baseadas no comportamento real dos middlewares de autenticação.Recommendations based on the real behavior of the authentication middlewares.

3Ambientes e rotasEnvironments & routes

Cada operação possui uma rota equivalente em Sandbox e em Produção.Each operation has an equivalent route in Sandbox and Production.

4Headers e autenticaçãoHeaders & authentication

5Limites de requisiçõesRate limits

Todos os endpoints da API são limitados por IP de origem, com um limite adicional na geração de token. All API endpoints are rate-limited by source IP, with an additional limit on token generation.

{
  "message": "Too Many Attempts."
}

A resposta também inclui os headers Retry-After, X-RateLimit-Limit e X-RateLimit-Remaining. The response also includes the Retry-After, X-RateLimit-Limit and X-RateLimit-Remaining headers.

6GlossárioGlossary

Termos do domínio fiscal/NFS-e usados ao longo desta documentação. Tax/NFS-e domain terms used throughout this documentation.

7Gerar tokenGet token

Endpoint:Endpoint: POST /api/v1/{ambiente}/auth/token. Exemplos e teste ao vivo no painel à direita →Examples and live test in the right-hand panel →

{
  "codigo": 200,
  "descricao": "Autenticação realizada com sucesso.",
  "token": "aQ7f...(80 caracteres)",
  "token_type": "Bearer",
  "expires_in": 43200,
  "expira_em": "2026-09-29 04:10:51"
}

{
  "codigo": 401,
  "descricao": "CNPJ, e-mail ou senha inválidos."
}

8Cadastro de tomadorCustomer registration

Endpoint:Endpoint: POST /api/v1/{ambiente}/tomadores. RequerRequires Authorization: Bearer {token}

{
  "codigo": 200,
  "descricao": "Tomador cadastrado com sucesso.",
  "tomador": {
    "razao_social": "Empresa Exemplo LTDA",
    "cpf_cnpj": "12345678000190",
    "pais": "Brasil",
    "cidade": "Salvador",
    "endereco": "Av. Exemplo"
    "...": "demais campos do cadastro"
  }
}

9Consulta de tomadoresCustomer lookup

Endpoint:Endpoint: GET /api/v1/{ambiente}/tomadores

{
  "codigo": 200,
  "mensagem": "Tomadores encontrados.",
  "total": 1,
  "tomadores": [
    { "razao_social": "Empresa Exemplo LTDA", "...": "demais campos" }
  ]
}

10Emissão / cadastro de NFS-eInvoice issuance

Endpoint:Endpoint: POST /api/v1/{ambiente}/nfse

Identificação e serviçoIdentification & service

LocalizaçãoLocation

Tributação e valoresTaxation & amounts

Benefício municipal e RPSMunicipal benefit & RPS

Dados adicionais da prestaçãoAdditional service data

Obra, evento e endereço da prestaçãoConstruction site, event & service address

Informações adicionais e deduçõesAdditional info & deductions

{
  "codigo": 200,
  "mensagem": "NFS-e processada com sucesso.",
  "nfse": {
    "numero": "000123",
    "chave": "...",
    "codigo_verificacao": "...",
    "competencia": "2026-09",
    "emissao": "2026-09-28 17:05:00",
    "status": 1,
    "dps_numero": "...",
    "dps_chave": "..."
  }
}

Campo status: 1 = Emitida, 2 = Cancelada.status field: 1 = Issued, 2 = Cancelled.

11Cancelamento de NFS-eInvoice cancellation

O cancelamento é realizado pela chave da NFS-e e exige autenticação Bearer.Cancellation is performed using the invoice key and requires Bearer authentication.

RotasRoutes

{chave} deve ser substituído pela chave da NFS-e que será cancelada.must be replaced with the key of the invoice to be cancelled.

Campos enviados no corpoBody fields

Regras de cancelamentoCancellation rules

{
  "codigo": 200,
  "mensagem": "NFS-e cancelada com sucesso.",
  "nfse": {
    "numero": "000123",
    "chave": "...",
    "status": 2
  }
}

12Códigos de retornoResponse codes

Todas as respostas trazem um campo codigo no corpo, além do HTTP status. Estes dois valores nem sempre coincidem.Every response carries a codigo field in the body, besides the HTTP status. These two values don't always match.

Status da APIAPI Status

Verificação rápida de disponibilidade do ambiente Sandbox, feita diretamente do seu navegador. Quick availability check for the Sandbox environment, performed directly from your browser.