Pular para o conteúdo principal

Primeiros Passos

Bem-vindo à documentação da API XD Soba! Este guia vai ajudá-lo a começar com a nossa API, abordando autenticação, utilização básica e padrões comuns.

Autenticação​

Todos os pedidos à API requerem autenticação usando JWT (JSON Web Tokens). Para autenticar:

  1. Envie um pedido POST para /gateway/auth/login com as suas credenciais
  2. Use o token devolvido no cabeçalho Authorization para os pedidos subsequentes
# Exemplo de pedido de login
curl -X POST "https://api.xdsoba.com/gateway/auth/login" \
     -H "Content-Type: application/json" \
     -d '{"user": "seu_utilizador", "password": "sua_palavra_passe"}'

Inclua o token nos seus pedidos:

curl -X GET "https://api.xdsoba.com/gateway/your-endpoint" \
     -H "Authorization: Bearer seu_token_aqui"

URL Base​

Todos os endpoints da API são relativos ao URL base:

https://api.xdsoba.com

Cabeçalhos Comuns​

Inclua estes cabeçalhos nos seus pedidos:

  • Authorization: Bearer <token> - Obrigatório para endpoints autenticados
  • Content-Type: application/json - Obrigatório para pedidos POST/PUT
  • Accept: application/json - Recomendado para todos os pedidos

Rate Limiting​

Para garantir uma utilização justa e estabilidade do sistema, implementamos rate limiting:

  • 100 pedidos por minuto por chave de API
  • Os cabeçalhos de rate limit estão incluídos nas respostas:
    • X-RateLimit-Limit: Máximo de pedidos por janela
    • X-RateLimit-Remaining: Pedidos restantes na janela atual
    • X-RateLimit-Reset: Tempo até o rate limit ser reiniciado

Tratamento de Erros​

A API usa códigos de estado HTTP padrão e devolve detalhes do erro no corpo da resposta:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Mensagem de erro legível",
    "details": "Detalhes adicionais do erro se disponíveis"
  }
}

Códigos de estado comuns:

  • 200 OK: Pedido bem-sucedido
  • 400 Bad Request: Parâmetros de pedido inválidos
  • 401 Unauthorized: Autenticação inválida ou em falta
  • 403 Forbidden: Permissões insuficientes
  • 404 Not Found: Recurso não encontrado
  • 429 Too Many Requests: Rate limit excedido
  • 500 Internal Server Error: Erro do lado do servidor

Próximos Passos​

Agora que compreende o básico, pode:

Precisa de ajuda? Contacte a nossa equipa de suporte em support@xdsoba.com