Copy page

Autenticação

Autenticação via API Key e Token JWT

Autenticação via API Key e JWT

A API Nottou suporta dois métodos de autenticação: API Key de Workspace (recomendada para integrações server-to-server, ERPs, CRMs e rotinas de automação) e Token JWT (indicada para aplicações interativas com login de usuário).

Com uma API Key ativa, suas requisições podem emitir notas, consultar status e gerenciar clientes sem depender de sessões de login que expiram.

---

Formato e Obtenção da API Key

As chaves de API do Nottou possuem o prefixo ntk_ seguido por 64 caracteres hexadecimais:

Code
ntk_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2

Para gerar uma chave:

1. Acesse o painel da Nottou com uma conta de perfil Administrador.
2. Navegue até Configurações > Chaves de API.
3. Clique em "Criar nova chave", defina um nome descritivo (ex: ERP Faturamento Produção) e guarde o token com segurança.

---

Como Autenticar Requisições

Envie a chave no cabeçalho HTTP Authorization com o esquema Bearer:

Code
Authorization: Bearer ntk_<sua_chave_aqui>

Selecionando a Empresa no Workspace (empresa-id)

Como um único workspace no Nottou pode gerenciar múltiplas empresas prestadoras, você deve indicar qual empresa está operando na requisição através do cabeçalho empresa-id:

Code
Authorization: Bearer ntk_<sua_chave_aqui>
empresa-id: <uuid_da_empresa>

Atenção: Se o cabeçalho empresa-id for omitido, a API aplicará automaticamente as operações na empresa padrão configurada no seu workspace.

---

Exemplos Práticos de Requisição

1. Listar Tomadores de Serviço Cadastrados

Requisição de exemplo para buscar a lista de clientes vinculados à empresa:

Code
curl -X GET https://nfse.labds.com.br/api/v1/tomadores \
  -H "Authorization: Bearer ntk_a1b2c3d4e5f6..." \
  -H "empresa-id: 745b7faa-727d-4182-815b-359136407575" \
  -H "Accept: application/json"

2. Consultar Próximo Número Sequencial da Série

Antes de emitir uma nota fiscal por RPS, consulte a numeração ativa:

Code
curl -X GET https://nfse.labds.com.br/api/v1/series/proximo-numero \
  -H "Authorization: Bearer ntk_a1b2c3d4e5f6..." \
  -H "empresa-id: 745b7faa-727d-4182-815b-359136407575"

---

Códigos de Erro e Tratamento de Respostas

Ao integrar com a API, certifique-se de que sua aplicação trata adequadamente os seguintes status HTTP de autenticação:

Código HTTP	Mensagem de Retorno	Causa Provável	Ação Recomendada
401 Unauthorized	API Key inválida ou revogada	A chave foi digitada incorretamente ou revogada no painel.	Verifique o valor enviado no header Authorization.
403 Forbidden	Empresa não pertence ao workspace desta API Key	O UUID passado em empresa-id pertence a outro workspace.	Confira o identificador da empresa na rota /api/empresas.
403 Forbidden	Esta operação requer autenticação via token JWT	Tentativa de executar ações administrativas exclusivas de usuário.	Utilize login de usuário com JWT para gerenciamento de chaves.
404 Not Found	Nenhuma empresa vinculada a este workspace	O workspace atual ainda não possui empresas cadastradas.	Acesse Como cadastrar empresa ou use a rota /api/empresas.

---

Próximos Passos e Links Relacionados

• Referência de Endpoints de NFS-e — Guia de integração para envio e emissão de notas.
• Referência de Tomadores — Gerenciamento de clientes via API.
• Referência de Séries — Configuração de séries fiscais e ambientes.
• Tutorial de Emissão via Painel Web — Entenda os dados obrigatórios de cada nota fiscal.