Autenticação

​

Visão geral

​

Obtendo sua API Key

​

Passo 1: Acesse o Dashboard

1. Faça login no Dashboard Upay
2. Complete o processo de KYC (Know Your Customer) se ainda não tiver feito
3. Navegue até Configurações → Credenciais de API

​

Passo 2: Crie uma API Key

1. Clique em “Criar Nova API Key”
2. Dê um nome descritivo para sua API Key (ex: “Integração Produção”, “App Mobile”)
3. Selecione as permissões necessárias:
   • paymentLinks:read - Ler links de pagamento
   • paymentLinks:write - Criar/editar links de pagamento
   • products:read - Ler produtos
   • products:write - Criar/editar produtos
   • coupons:read - Ler cupons
   • coupons:write - Criar/editar cupons
   • transactions:read - Ler transações
   • transactions:write - Criar transações
   • webhooks:read - Ler webhooks
   • webhooks:write - Criar/editar webhooks
4. Clique em “Gerar API Key”
5. ⚠️ IMPORTANTE: Copie e guarde sua API Key imediatamente. Ela não será exibida novamente!

​

🔑 Usando sua API Key

​

Header de Autenticação

Authorization: Bearer SUA_API_KEY_AQUI

X-API-Key: SUA_API_KEY_AQUI

​

Exemplo com cURL

curl -X GET "https://upay-sistema-api.onrender.com/api/v1/payment-links" \
  -H "Authorization: Bearer sua_api_key_aqui" \
  -H "Content-Type: application/json"

{
  "data": [],
  "total": 0
}

​

Exemplo com JavaScript (Fetch)

const apiKey = 'sua_api_key_aqui';

const response = await fetch('https://upay-sistema-api.onrender.com/api/v1/payment-links', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  }
});

const data = await response.json();

​

Exemplo com Python (Requests)

import requests

api_key = 'sua_api_key_aqui'
headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://upay-sistema-api.onrender.com/api/v1/payment-links',
    headers=headers
)

data = response.json()

​

Exemplo com Node.js (Axios)

const axios = require('axios');

const apiKey = 'sua_api_key_aqui';

const response = await axios.get('https://upay-sistema-api.onrender.com/api/payment-links', {
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  }
});

console.log(response.data);

​

Segurança

​

Boas Práticas

1. Nunca commite API Keys no código
   • Use variáveis de ambiente
   • Use serviços de gerenciamento de secrets (AWS Secrets Manager, HashiCorp Vault, etc.)
2. Use diferentes API Keys para diferentes ambientes
   • Uma para desenvolvimento
   • Uma para produção
   • Facilita revogação se necessário
3. Revogue API Keys comprometidas imediatamente
   • Acesse o Dashboard → Configurações → Credenciais de API
   • Revogue a API Key comprometida
   • Gere uma nova API Key
4. Use apenas as permissões necessárias
   • Siga o princípio do menor privilégio
   • Não conceda permissões desnecessárias
5. Rotacione suas API Keys periodicamente
   • Recomendado a cada 90 dias
   • Facilita a detecção de uso não autorizado

​

Variáveis de Ambiente

​

.env (Node.js/Python)

UPAY_API_KEY=sua_api_key_aqui
UPAY_API_URL=https://upay-sistema-api.onrender.com

​

Uso no código

// Node.js
const apiKey = process.env.UPAY_API_KEY;

// Python
import os
api_key = os.getenv('UPAY_API_KEY')

​

Tratamento de erros

​

Códigos de status HTTP

​

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Token inválido ou expirado",
  "statusCode": 401
}

• API Key incorreta ou ausente
• Formato do header de autenticação incorreto
• API Key revogada ou expirada

• Verifique se a API Key está correta
• Verifique se está usando o formato Bearer {api_key}
• Verifique se a API Key não foi revogada no dashboard

​

403 Forbidden

{
  "error": "Forbidden",
  "message": "Você não tem permissão para acessar este recurso",
  "statusCode": 403
}

• API Key sem as permissões necessárias
• Tentativa de acessar recurso de outro usuário

• Verifique se sua API Key tem as permissões necessárias
• Entre em contato com o suporte para solicitar permissões adicionais

​

400 Bad Request

{
  "error": "Validation Error",
  "message": "Dados inválidos",
  "statusCode": 400,
  "details": [
    {
      "field": "amount",
      "message": "O valor deve ser maior que 0"
    },
    {
      "field": "currency",
      "message": "Moeda inválida. Use BRL"
    }
  ]
}

• Campos obrigatórios ausentes
• Valores fora do intervalo permitido
• Formato de dados incorreto

• Verifique a documentação do endpoint para campos obrigatórios
• Valide os tipos e formatos dos dados antes de enviar

​

429 Too Many Requests

{
  "error": "Rate Limit Exceeded",
  "message": "Você excedeu o limite de requisições",
  "statusCode": 429,
  "retryAfter": 60
}

• Endpoints públicos: 100 requisições por minuto por IP
• Endpoints autenticados: 1000 requisições por minuto por API Key

• Implemente exponential backoff nas suas requisições
• Use o header Retry-After para saber quando tentar novamente
• Considere fazer cache de dados que não mudam frequentemente

​

Próximos passos