Como usar o usuário API para acessar as APIs Galgo

Este guia apresenta como utilizar as credenciais do usuário API para autenticar e consumir as APIs do Galgo.

Pré-requisitos

Antes de começar, certifique-se de que você possui:

• Username – Nome de usuário da conta API

• Password – Senha do usuário API

• URL Base – URL do ambiente Galgo fornecida pela RTM

Essas informações foram enviadas por e-mail após a criação do usuário API. Se você não possui essas credenciais, consulte o guia Como criar um usuário API.

---

Fluxo de Autenticação

O usuário API utiliza o mesmo fluxo de autenticação do Galgo. A diferença é que você utilizará as credenciais de API (username e password) ao invés de login interativo.

---

ETAPA 1 – Obter o Token de Acesso

1.1 – Endpoint de autenticação

Utilize o endpoint de autenticação do Galgo para obter o token de acesso:

Endpoint:

POST /v1/auth/token

1.2 – Parâmetros da requisição

Parâmetro	Tipo	Obrigatório	Descrição
usuario	string	Sim	Username recebido
senha	string	Sim	Senha recebida

1.3 – Exemplo com cURL

curl -X POST "{URL_BASE}/v1/auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "usuario": "SEU_USERNAME",
    "senha": "SUA_SENHA"
  }'

Substitua:

• {URL_BASE} pela URL do ambiente fornecida pela RTM
• SEU_USERNAME pelo username recebido por e-mail
• SUA_SENHA pela senha recebida por e-mail

1.4 – Resposta de sucesso

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 300,
  "token_type": "Bearer"
}

Campo	Descrição
access_token	Token de acesso para usar nas requisições
expires_in	Tempo em segundos até o token expirar
token_type	Tipo do token (sempre "Bearer")

⚠️ Importante: O access_token expira após o tempo indicado em expires_in. Quando expirar, realize uma nova autenticação para obter um novo token.

---

ETAPA 2 – Usar o Token nas APIs Galgo

2.1 – Header de autorização

Para todas as requisições às APIs Galgo, inclua o token no header Authorization:

Authorization: Bearer SEU_ACCESS_TOKEN

2.2 – Exemplo de requisição

Exemplo com cURL:

curl -X GET "{URL_BASE}/v1/fundos" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json"

Exemplo com JavaScript/Node.js:

const URL_BASE = process.env.GALGO_BASE_URL; // URL fornecida

const response = await fetch(`${URL_BASE}/v1/fundos`, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
console.log(data);

---

ETAPA 3 – Renovar o Token

3.1 – Quando renovar?

Renove o token antes que ele expire. Verifique o campo expires_in da resposta de autenticação para saber quando o token irá expirar.

3.2 – Exemplo de renovação

Para renovar o token, basta realizar uma nova autenticação com as credenciais:

curl -X POST "{URL_BASE}/v1/auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "usuario": "SEU_USERNAME",
    "senha": "SUA_SENHA"
  }'

3.3 – Resposta

A resposta terá o mesmo formato da autenticação inicial, com um novo access_token.

---

Códigos de Erro Comuns

Código	Erro	Descrição	Solução
401	Unauthorized	Token inválido ou expirado	Obtenha um novo token
401	Invalid credentials	Username ou senha incorretos	Verifique as credenciais
403	Forbidden	Sem permissão para o recurso	Verifique as permissões do usuário API
429	Too Many Requests	Limite de requisições excedido	Aguarde e tente novamente

---

Boas Práticas

✅ Recomendado

• Armazene as credenciais de forma segura – Use variáveis de ambiente ou serviços de secrets

• Renove o token antes de expirar – Evite erros de autenticação durante operações

• Trate erros de autenticação – Implemente retry com nova autenticação em caso de token expirado

• Use HTTPS – Todas as requisições devem usar conexão segura

❌ Evite

• Hardcode de credenciais no código fonte

• Compartilhar credenciais entre sistemas diferentes

• Ignorar erros de autenticação

---

Exemplo Completo em TypeScript

interface TokenResponse {
  access_token: string;
  expires_in: number;
  token_type: string;
}

class GalgoApiClient {
  private accessToken: string | null = null;
  private tokenExpiry: Date | null = null;

  constructor(
    private readonly baseUrl: string,
    private readonly usuario: string,
    private readonly senha: string
  ) {}

  async authenticate(): Promise<void> {
    const response = await fetch(`${this.baseUrl}/v1/auth/token`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        usuario: this.usuario,
        senha: this.senha,
      }),
    });

    if (!response.ok) {
      throw new Error(`Falha na autenticação: ${response.status}`);
    }

    const data: TokenResponse = await response.json();
    this.accessToken = data.access_token;
    this.tokenExpiry = new Date(Date.now() + (data.expires_in - 30) * 1000);
  }

  private async ensureValidToken(): Promise<void> {
    if (!this.accessToken || !this.tokenExpiry || new Date() >= this.tokenExpiry) {
      await this.authenticate();
    }
  }

  async request<T>(endpoint: string, options: RequestInit = {}): Promise<T> {
    await this.ensureValidToken();

    const response = await fetch(`${this.baseUrl}${endpoint}`, {
      ...options,
      headers: {
        ...options.headers,
        'Authorization': `Bearer ${this.accessToken}`,
        'Content-Type': 'application/json',
      },
    });

    if (!response.ok) {
      throw new Error(`Erro na requisição: ${response.status}`);
    }

    return response.json();
  }
}

// Uso
const client = new GalgoApiClient(
  process.env.GALGO_BASE_URL!,  // URL fornecida pela RTM
  process.env.GALGO_USERNAME!,
  process.env.GALGO_PASSWORD!
);

// Buscar fundos
const fundos = await client.request('/v1/fundos');
console.log(fundos);

---

Próximos Passos

Após configurar a autenticação, você pode:

1. Explorar as APIs disponíveis – Consulte a documentação das APIs Galgo
2. Gerenciar o usuário API – Editar configurações ou resetar senha

Consulte o guia Como gerenciar usuários API para saber como administrar os usuários.