Tokens de API
Crie chaves para o seu ERP ou script emitir e consultar notas pela API, com escopos, clientes, IPs, limite e validade, e troque-as sem parar a integração.
Para que serve
Um token de API é uma chave secreta que deixa outro sistema (ERP, planilha automatizada, script) usar a API do emissor sem o login de uma pessoa. Na tela Tokens de API (menu Configurações → Tokens de API) você cria, edita, troca e revoga essas chaves.
Cada token tem:
- escopos: o que ele pode fazer (escopo), por exemplo emitir notas ou só consultar;
- clientes: todos ou só alguns (restrição por cliente);
- IPs permitidos, limite por minuto e validade.
Quem vê: Dono e Administrador. Só pessoas da equipe, logadas no painel, gerenciam tokens: um token nunca cria nem renova outro token. Você só consegue dar a um token permissões que você mesmo tem.
O botão Documentação da API, no alto da tela, abre a documentação da API em nova aba, com os endereços, exemplos e como autenticar.
Passo a passo
Criar um token
- Clique em + Novo token.
- Preencha Nome (único entre os tokens ativos) e, se quiser, Descrição de uso (para que serve, onde está instalado).
- Em Escopos, marque o que o token pode fazer. Os Atalhos marcam conjuntos prontos (veja abaixo). Escopos que você não tem aparecem bloqueados.
- Em Clientes, escolha Todos os clientes (atuais e futuros) ou Somente os clientes selecionados.
- Escolha a Validade (30, 90, 180 ou 365 dias; padrão 90).
- Se quiser, ajuste o Limite por minuto e os IPs permitidos.
- Clique em Gerar token.
- Na janela Token "…" gerado, clique em Copiar e guarde o token num cofre de senhas. Ele não será mostrado de novo. A janela também traz um exemplo de emissão e os links como autenticar e Documentação da API.
- Clique em Já copiei, fechar.
Editar um token
Clique em Editar na linha do token. Você pode mudar nome, descrição, clientes, IPs e limite. Os escopos só podem ser reduzidos: para ampliar, crie outro token. A validade não muda na edição (use Gerar substituto).
Trocar um token sem parar a integração (Gerar substituto)
- Clique em Gerar substituto na linha do token.
- Escolha por quanto tempo o token atual continua valendo (24 horas a 7 dias; padrão 24 horas).
- Clique em Gerar substituto e copie o token novo, que tem a mesma configuração.
- Troque o token na sua integração dentro do prazo. Depois, o antigo expira sozinho.
Na lista, os dois aparecem ligados ("Substituído por…" e "Substitui…").
Revogar um token
Clique em Revogar e confirme. As integrações que usam o token passam a receber erro de acesso imediatamente.
Consultar tokens
Use as abas Ativos, Expirados e Revogados. A coluna Último uso mostra a data e o IP da última chamada (atualizada no máximo uma vez por minuto). Validade destaca tokens vencidos ou que vencem em até 7 dias.
Evitar nota em dobro (Idempotency-Key)
Nas chamadas que gravam algo (por exemplo, emitir), envie o cabeçalho Idempotency-Key com um código único por operação (sugestão: um UUID). Se a sua integração repetir a chamada com a mesma chave e o mesmo conteúdo, a API devolve a mesma resposta sem emitir de novo; a mesma chave com outro conteúdo é recusada (Idempotency-Key reutilizada).
Campos
| Campo | O que significa |
|---|---|
| Nome | Identificação do token. Único entre os ativos da conta. |
| Descrição de uso | Texto livre para lembrar onde o token está instalado. |
| Escopos | Permissões do token (tabela abaixo). Pelo menos um. |
| Clientes | Todos os clientes ou só os selecionados. Quem tem acesso restrito só cria tokens restritos. |
| Validade | 30, 90 (padrão), 180 ou 365 dias, ou Sem validade (não recomendado: se vazar, continua funcionando até ser revogado). |
| Limite por minuto | De 1 a 600 requisições por minuto (padrão 600). |
| IPs permitidos | Um por linha: IPv4, IPv6 ou faixa CIDR (até 50). Vazio = qualquer IP. |
| Prefixo | Começo do token, para você reconhecê-lo. O token completo nunca aparece de novo. |
Escopos disponíveis
| Escopo | Nome na tela | O que permite |
|---|---|---|
nfse:write | Emitir e registrar eventos | Emitir NFS-e (uma a uma ou em lote), cancelar, substituir e inutilizar. |
nfse:read | Consultar notas | Listar e consultar NFS-e emitidas, XML/DANFSe, situação e relatórios. |
dfe:read | Ler notas recebidas | Ler as NFS-e recebidas (DF-e) e a situação da busca. |
webhooks:read | Ver webhooks | Listar os webhooks e o histórico de entregas. |
webhooks:write | Gerenciar webhooks | Criar, alterar, testar e remover webhooks. |
empresas:read | Ver clientes e cadastros | Ler clientes, tomadores, serviços e configurações fiscais. |
empresas:write | Alterar clientes e cadastros | Criar e alterar clientes, tomadores, serviços e configurações fiscais. |
cadastros:read | Ver tomadores e serviços | Ler tomadores, serviços e regras serviço × tomador; com nfse:write, emitir a partir dos cadastros. |
cadastros:write | Alterar tomadores e serviços | Criar, alterar e desativar tomadores, serviços e regras serviço × tomador. |
fiscal:read | Ver perfil fiscal | Ler o perfil fiscal do cliente, as vigências de regime tributário e a situação do IBPT (nunca o token do IBPT). |
fiscal:write | Alterar perfil fiscal | Criar e alterar vigências de regime; cadastrar, testar e remover o token do IBPT. |
cert:read | Ver certificados | Ler validade e titular dos certificados digitais. |
cert:write | Enviar certificados | Enviar e substituir certificados A1 dos clientes. |
cobrancas:read | Ver cobranças | Ler as contas a receber. |
cobrancas:write | Gerenciar cobranças | Gerar, cancelar e estornar cobranças dos tomadores. |
audit:read | Ler auditoria | Ler a trilha de auditoria da conta. |
Atalhos
| Atalho | Escopos marcados |
|---|---|
| Emissão completa | nfse:write, nfse:read, empresas:read, cadastros:read, fiscal:read |
| Integração de cadastros | cadastros:read, cadastros:write, fiscal:read, fiscal:write |
| Somente leitura | Todos os escopos de leitura (:read) |
| Webhooks | webhooks:read, webhooks:write |
Pessoas, convites, outros tokens e plano não podem ser liberados para um token.
Erros comuns e como resolver
| Mensagem ou situação | O que fazer |
|---|---|
| Nome em uso | Já existe um token ativo com esse nome. Escolha outro. Veja Nome em uso. |
| "Escopos só podem ser reduzidos" | Na edição não dá para acrescentar escopos. Crie outro token. Veja Escopo ampliado. |
| Escopo além do seu acesso | Você não tem essa permissão, então não pode passá-la ao token. Veja Escopo excedente. |
| IP ou faixa inválida | Confira o formato (ex.: 203.0.113.10 ou 203.0.113.0/24). Veja IP inválido. |
| A integração recebe "IP não autorizado" | O IP de saída do sistema não está na lista do token. Inclua-o. Veja IP não autorizado. |
| A integração recebe "Token expirado" | Gere um token novo (ou um substituto antes do vencimento). Veja Token expirado. |
| "Token já substituído" | Esse token já tem um substituto. Use o substituto existente. Veja Token já substituído. |
| Perdi o token | Ele não pode ser mostrado de novo. Use Gerar substituto e troque na integração. |
| Não aparece o botão + Novo token | Você pode ver, mas não criar tokens. Peça ao Dono ou a um Administrador. |
Você recebe um e-mail 7 dias e 1 dia antes de um token seu vencer (categoria "Token de API vencendo" em Notificações).
Veja também
Termos usados
- Token de API
- Chave secreta que permite a outro sistema emitir e consultar notas pela API, sem login de pessoa.
- Escopo
- Permissão específica de um token ou papel (ex.: nfse:write para emitir notas).
- Restrição por cliente
- Limita o acesso de uma pessoa, contador ou token de API a alguns clientes da conta, em vez de todos.
- DF-e
- Documentos fiscais eletrônicos distribuídos pelo ADN — aqui, as notas em que o cliente é tomador.
- Webhook
- Aviso automático que o sistema envia para um endereço seu quando algo acontece (ex.: nota autorizada).
Mais em Integrações
- WebhooksReceba avisos automáticos no seu sistema quando uma nota é autorizada, rejeitada ou cancelada, quando chega uma nota recebida e mais.