Autenticação

A API do OnnixPay utiliza API Keys para autenticação. Todas as requisições devem incluir sua API Key no header X-API-Key.

Como Funciona

┌─────────────┐         ┌──────────────┐         ┌─────────────┐
│   Cliente   │────────▶│  OnnixPay    │────────▶│  Resposta   │
│             │  API Key│              │  JSON   │             │
└─────────────┘         └──────────────┘         └─────────────┘

Cada requisição é:

1. Autenticada: Verificamos sua API Key
2. Autorizada: Checamos se você tem permissão (scopes)
3. Rate Limited: Controlamos o número de requisições
4. Logada: Registramos para auditoria

Obtendo sua API Key

1. Faça login em app.onnixpay.com
2. Navegue até Configurações > API Keys
3. Clique em Criar Nova Chave
4. Selecione os escopos necessários
5. Copie e guarde sua chave com segurança

Importante

A chave completa é exibida apenas uma vez. Se você perdê-la, precisará gerar uma nova.

Exemplo de Uso

curl -X GET https://api.onnixpay.com/sdk/status/health \
  -H "X-API-Key: opk_live_abc123def456ghi789"

const response = await fetch('https://api.onnixpay.com/sdk/status/health', {
  headers: {
    'X-API-Key': 'opk_live_abc123def456ghi789'
  }
});

Formato da API Key

As API Keys seguem um padrão específico:

opk_{environment}_{random_string}

• opk: Prefixo OnnixPay Key
• environment: test (sandbox) ou live (produção)
• random_string: String aleatória única

Exemplos

opk_test_abc123def456    → Ambiente de Sandbox
opk_live_xyz789uvw012    → Ambiente de Produção

Ambientes

Ambiente	Prefixo	URL Base
Sandbox	opk_test_	https://sandbox.onnixpay.com
Produção	opk_live_	https://api.onnixpay.com

Dica

Use chaves de Sandbox durante o desenvolvimento. Transações em sandbox não movimentam dinheiro real.

Segurança

✅ Boas Práticas

• Armazene suas chaves em variáveis de ambiente
• Nunca faça commit de chaves no Git
• Use chaves diferentes para cada ambiente
• Rotacione suas chaves periodicamente
• Revogue chaves comprometidas imediatamente

❌ Nunca Faça

// ❌ NUNCA exponha a chave no código client-side
const apiKey = 'opk_live_abc123';

// ❌ NUNCA faça commit no código
git add config.js  // contém apiKey = 'opk_live_...'

// ❌ NUNCA envie via URL
fetch('https://api.com?apikey=opk_live_abc123')

✅ Recomendado

// ✅ Use variáveis de ambiente
const apiKey = process.env.ONNIXPAY_API_KEY;

// ✅ Configure no servidor
// .env
ONNIXPAY_API_KEY=opk_live_abc123

// ✅ Adicione ao .gitignore
echo ".env" >> .gitignore

Testando Autenticação

Você pode testar se sua API Key está funcionando:

curl -X GET https://sandbox.onnixpay.com/sdk/status/health \
  -H "X-API-Key: sua_api_key_aqui" \
  -w "\nHTTP Status: %{http_code}\n"

Resposta com sucesso (200):

{
  "success": true,
  "data": {
    "status": "healthy",
    "timestamp": "2025-11-14T10:30:00Z",
    "version": "v1"
  }
}

Resposta com erro (401):

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API Key inválida ou ausente",
    "details": "Verifique se o header X-API-Key está presente e correto"
  }
}

Headers Requeridos

Além da API Key, algumas requisições podem exigir headers adicionais:

curl -X POST https://api.onnixpay.com/sdk/pix \
  -H "X-API-Key: sua_api_key_aqui" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: unique-request-id" \
  -d '{"amount": 100}'

Header	Obrigatório	Descrição
X-API-Key	✅ Sim	Sua chave de autenticação
Content-Type	✅ Para POST/PUT	Tipo do conteúdo (application/json)
X-Idempotency-Key	⚠️ Recomendado	Evita duplicação de transações
User-Agent	❌ Opcional	Identificação do cliente

Próximos Passos

• Gerenciar API Keys
• Entender Scopes
• Rate Limits