Autenticação na API

Aprenda como obter e usar tokens de acesso para autenticar suas requisições na API AjnaPay.
Resumo Rápido

A API AjnaPay usa Bearer Tokens (Sanctum) para autenticação. O token é gerado dentro do painel administrativo e deve ser enviado no header Authorization de todas as requisições.

1. Obtendo seu Token

O token de acesso é gerado dentro da plataforma AjnaPay, não via API. Siga os passos:

  1. Acesse o Painel AjnaPay
  2. Faça login com suas credenciais
  3. Vá em Configurações → API Tokens
  4. Clique em "Gerar Novo Token"
  5. Dê um nome descritivo (ex: "Integração Sistema X")
  6. Selecione as permissões necessárias
  7. Copie o token gerado (ele só aparece uma vez!)

2. Usando o Token

Envie o token no header Authorization de todas as requisições:

Exemplo com cURL 
curl -X GET "https://ajnapay.com.br/api/v1/account/balance" \
  -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  -H "Accept: application/json"
Exemplo com PHP (Guzzle) 
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://ajnapay.com.br/api/',
    'headers' => [
        'Authorization' => 'Bearer ' . $token,
        'Accept' => 'application/json',
    ],
]);

$response = $client->get('v1/account/balance');
$data = json_decode($response->getBody(), true);
Exemplo com JavaScript (Fetch) 
const response = await fetch('https://ajnapay.com.br/api/v1/account/balance', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer ' + token,
        'Accept': 'application/json',
    }
});

const data = await response.json();

3. Códigos de Erro Comuns

Status Significado Causa
401 Unauthorized Token inválido, expirado ou ausente
403 Forbidden Token válido, mas sem permissão para este recurso
429 Too Many Requests Limite de requisições excedido

4. Tokens MCP (Agentes de IA)

A AjnaPay expõe um servidor MCP (Model Context Protocol) que permite que agentes de IA (GitHub Copilot, Claude Desktop, Cursor) criem cobranças, emitam PIX/boleto e consultem saldos diretamente pelo chat — sempre com confirmação do usuário antes de executar operações.

Passo 1: Criar o token com ability mcp:access
  1. Vá em Configurações → API Tokens
  2. Clique em "Gerar Novo Token"
  3. Dê um nome (ex: "MCP Access") e ative o switch "Acesso MCP (agentes de IA)"
  4. Copie o token gerado (ele só aparece uma vez!)
Passo 2: Configurar no seu agente de IA

Adicione o servidor MCP no arquivo de configuração do seu cliente:

Claude Desktop / Copilot / Cursor — mcpServers 
{
  "mcpServers": {
    "ajnapay": {
      "type": "http",
      "url": "https://api.ajnapay.com.br/mcp/api",
      "headers": {
        "Authorization": "Bearer SEU_TOKEN_MCP"
      }
    }
  }
}
Passo 3: Usar no chat

Exemplos de comandos que o agente entende:

  • "Quantas cobranças estão pendentes?" → lista as invoices
  • "Crie uma cobrança de R$ 150 para Maria" → pede confirmação e cria
  • "Quero um PIX de R$ 50 para cobrar o João" → pede confirmação e gera QR Code
  • "Qual meu saldo?" → consulta saldos da conta

5. Boas Práticas

  • Armazene o token com segurança: Use variáveis de ambiente, nunca hardcode no código
  • Use HTTPS sempre: Nunca envie tokens em conexões não seguras
  • Rotacione tokens periodicamente: Gere novos tokens a cada 90 dias
  • Revogue tokens não usados: Remova tokens de integrações descontinuadas
  • Use tokens específicos: Crie um token por integração/sistema
Voltar para Guides Próximo: Recebendo PIX