Autenticação
A API do FazNota utiliza autenticação por Token único por empresa. O token é gerado
no Painel FazNota e enviado no header Authorization de cada requisição.
Como obter seu Token
- Acesse o Painel FazNota com suas credenciais.
- Navegue até Meus Dados → aba Integração.
- Gere ou copie o Token da empresa.
Só o administrador da conta vê, copia ou gera o Token. Gerar um Token novo desliga o anterior na hora: atualize todas as integrações juntas. O Token está incluso em todos os planos.
Se você é uma empresa administradora com acesso ao Painel de Gestão de Contas, pode gerar tokens individuais para cada empresa vinculada.
Cabeçalhos obrigatórios
Toda requisição autenticada deve incluir:
Authorization: Token <seu_token_aqui>Content-Type: application/jsonEm requisições com corpo (POST/PUT), o Content-Type é obrigatório.
Token é o formato canônico. O prefixo Bearer (Authorization: Bearer <token>) também é
aceito como alias tolerado, mas prefira Token.
Exemplo de chamada autenticada
curl https://api.mysebr.com.br/nfemyse-v3/rest/nfe \ -H "Authorization: Token abc123def456ghi789jkl012mno345pq" \ -H "Content-Type: application/json"Endpoints que NÃO exigem autenticação
| Endpoint | Propósito |
|---|---|
GET /health | Health check da plataforma. Use para uptime monitor. |
GET /health/deep | Health check profundo (banco + pool de conexões). |
GET /health/pool | Métricas do pool de conexões. |
Respostas de erro de autenticação
| HTTP | error.status | error.message | O que fazer |
|---|---|---|---|
401 | 401 | "Token não autorizado." | Verifique se o header está correto e se o Token não foi revogado. |
403 | 403 | "Este contrato está inapto para realizar transações de API..." | Contrato pendente. Entre em contato com o FazNota para regularizar. |
429 | 429 | "Você atingiu o limite de consumo de API..." | Aguarde a janela informada na mensagem ou no header X-RateLimit-Reset. |
Exemplo de resposta 401:
{ "error": { "status": 401, "message": "Token não autorizado." }}Boas práticas
Use variáveis de ambiente
# .env (NUNCA commit este arquivo)MYSE_API_TOKEN=abc123def456ghi789jkl012mno345pqMYSE_API_BASE=https://api.mysebr.com.br/nfemyse-v3/restconst token = process.env.MYSE_API_TOKEN;const base = process.env.MYSE_API_BASE;Rotação periódica
Considere trocar o Token periodicamente (a cada 6–12 meses). Como o Token é único por empresa, gerar um novo no painel faz o anterior deixar de valer. Para reduzir a janela de falha:
- Deixe a troca preparada: o Token lido de variável de ambiente ou cofre de segredos, sem precisar de deploy de código.
- Gere o novo Token no painel.
- Atualize imediatamente a variável em todas as instâncias da sua aplicação e confirme que as
chamadas voltaram a responder sem
401.
Centralize o cliente HTTP
Evite espalhar fetch/curl pelo código. Crie uma camada que injeta
automaticamente o header Authorization e trata erros comuns:
const BASE = process.env.MYSE_API_BASE!;const TOKEN = process.env.MYSE_API_TOKEN!;
export async function mApi<T = unknown>( method: string, path: string, body?: unknown): Promise<T> { const res = await fetch(`${BASE}${path}`, { method, headers: { Authorization: `Token ${TOKEN}`, 'Content-Type': 'application/json', }, body: body ? JSON.stringify(body) : undefined, }); return res.json();}Não compartilhe Token entre ambientes
O Token é único por empresa. O ambiente de transmissão (homologação ou produção) vem do cadastro da empresa no FazNota, não do Token nem da URL. Para isolar integrações distintas (ex.: ERP vs e-commerce), use tokens de empresas vinculadas, quando acessíveis pelo Painel de Gestão de Contas.