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.

Se você é uma empresa administradora com acesso ao Painel de Gestão de Contas, pode gerar tokens individuais para cada empresa vinculada.

Cuidado com seu Token

O Token concede acesso total aos endpoints da empresa. Trate-o como uma senha:

• Nunca commit o Token em repositórios públicos ou privados.
• Use variáveis de ambiente ou cofres de segredos (AWS Secrets Manager, GCP Secret Manager, Vault, etc.).
• Não exponha o Token em frontends que rodam no browser do usuário final.
• Em caso de vazamento, gere um novo Token imediatamente e revogue o anterior.

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.

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.

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

Dica

Não faça const TOKEN = "abc123..." no código.

# .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 rotacionar o Token periodicamente (a cada 6–12 meses). Para rotação sem indisponibilidade:

1. Gere um novo Token no painel (sem revogar o atual).
2. Atualize a variável de ambiente nas instâncias da sua aplicação.
3. Quando confirmar que tudo continua funcionando, revogue o Token antigo no painel.

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

Tenha tokens separados para homologação e produção (quando aplicável) e não use o mesmo Token em diferentes integrações — isso facilita revogar uma sem afetar as demais.