Pular para o conteúdo

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

  1. Acesse o Painel FazNota com suas credenciais.
  2. Navegue até Meus Dados → aba Integração.
  3. 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/json

Em 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

Terminal window
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

EndpointPropósito
GET /healthHealth check da plataforma. Use para uptime monitor.
GET /health/deepHealth check profundo (banco + pool de conexões).
GET /health/poolMétricas do pool de conexões.

Respostas de erro de autenticação

HTTPerror.statuserror.messageO que fazer
401401"Token não autorizado."Verifique se o header está correto e se o Token não foi revogado.
403403"Este contrato está inapto para realizar transações de API..."Contrato pendente. Entre em contato com o FazNota para regularizar.
429429"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

Terminal window
# .env (NUNCA commit este arquivo)
MYSE_API_TOKEN=abc123def456ghi789jkl012mno345pq
MYSE_API_BASE=https://api.mysebr.com.br/nfemyse-v3/rest
const 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:

  1. Deixe a troca preparada: o Token lido de variável de ambiente ou cofre de segredos, sem precisar de deploy de código.
  2. Gere o novo Token no painel.
  3. 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:

src/lib/myse-api.ts
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.