> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gmproxys.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introdução

> Visão geral da API GmProxys, autenticação e URL base.

Bem-vindo à documentação oficial da **API GmProxys** — a interface programática para gerenciar proxies **datacenter** e **residenciais**, controlar saldo, consultar localizações e monitorar uso.

## URL Base

Todas as requisições devem ser feitas para a seguinte URL base:

```text theme={null}
https://api.gmproxys.com/v1
```

## Autenticação

A API do GmProxys utiliza **API Keys** para autenticar as requisições. Envie sua chave no header `X-API-Key` em todas as chamadas. Você pode obter sua chave no painel da GmProxys.

### Headers obrigatórios

| Header         | Valor              |
| -------------- | ------------------ |
| `X-API-Key`    | `gm_SUA_CHAVE`     |
| `Content-Type` | `application/json` |

### Exemplo

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.gmproxys.com/v1/proffile \
    -H "X-API-Key: gm_SUA_CHAVE" \
    -H "Content-Type: application/json"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.gmproxys.com/v1/proffile", {
    headers: {
      "X-API-Key": "gm_SUA_CHAVE",
      "Content-Type": "application/json",
    },
  });

  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.gmproxys.com/v1/proffile",
      headers={
          "X-API-Key": "gm_SUA_CHAVE",
          "Content-Type": "application/json",
      },
  )

  data = response.json()
  ```
</CodeGroup>

<Warning>
  Nunca compartilhe sua API Key publicamente. Trate-a como uma senha.
</Warning>

## Fluxo básico

O uso mais comum da API segue esta sequência:

<Steps>
  <Step title="Verifique seu saldo">
    Use [`GET /proffile`](/api-reference/user/get-profile) para consultar o saldo disponível na sua conta.
  </Step>

  <Step title="Escolha a localização">
    Consulte os [países](/api-reference/locations/countries), [estados](/api-reference/locations/states) e [cidades](/api-reference/locations/cities) disponíveis para o tipo de proxy desejado.
  </Step>

  <Step title="Crie um proxy">
    Use [`POST /proxy`](/api-reference/proxy/create-proxy) informando `type`, `balance`, `threads` e a localização.
  </Step>

  <Step title="Gerencie o proxy">
    [Liste](/api-reference/proxy/list-proxy), [obtenha](/api-reference/proxy/get-proxy), [edite](/api-reference/proxy/update-proxy) ou [delete](/api-reference/proxy/delete-proxy) seus proxies conforme necessário.
  </Step>

  <Step title="Acompanhe uso e saldo">
    Consulte o [histórico de uso](/api-reference/proxy/usage-proxy), o [saldo](/api-reference/saldo/get-saldo) e o [histórico de saldo](/api-reference/saldo/history-saldo) de cada proxy.
  </Step>
</Steps>

## Endpoints disponíveis

<CardGroup cols={2}>
  <Card title="Usuário" icon="user" href="/api-reference/user/get-profile">
    Consulte informações da conta autenticada e o saldo disponível.
  </Card>

  <Card title="Proxy" icon="globe" href="/api-reference/proxy/create-proxy">
    Crie, liste, edite, delete e monitore o uso dos seus proxies.
  </Card>

  <Card title="Saldo" icon="wallet" href="/api-reference/saldo/get-saldo">
    Consulte saldo, histórico e gerencie o saldo de cada proxy.
  </Card>

  <Card title="Locais" icon="map-pin" href="/api-reference/locations/countries">
    Descubra países, estados e cidades disponíveis para cada tipo de proxy.
  </Card>
</CardGroup>

## Tipos de proxy

<CardGroup cols={2}>
  <Card title="Residential" icon="house">
    IPs residenciais reais, ideais para casos que exigem alta reputação e menor taxa de bloqueio.
  </Card>

  <Card title="Datacenter" icon="server">
    IPs de datacenter, com maior velocidade e menor custo para operações de alto volume.
  </Card>
</CardGroup>

## Limites e regras

* **Threads:** ao criar um proxy, o valor de `threads` deve estar entre **1000** e **3000**.
* **Saldo:** informado em **bytes**. Ex.: `1000` = 10 GB.
* **Content-Type:** sempre `application/json`.
* **Localização:** ao editar (`POST /update`), envie apenas os campos que deseja alterar — todos exceto `user_id` são opcionais.

## Erros

A API retorna erros no formato padrão JSON com os campos `success` e `message`.

### 401 — Token inválido

Retornado quando a `X-API-Key` está ausente, incorreta ou expirada.

```json theme={null}
{
  "success": false,
  "message": "Invalid API token."
}
```

### 402 — Saldo insuficiente

Retornado ao tentar [criar um proxy](/api-reference/proxy/create-proxy) sem saldo suficiente na conta (consulte o campo `balance` em [`GET /proffile`](/api-reference/user/get-profile)).

```json theme={null}
{
  "success": false,
  "message": "Insufficient balance."
}
```

### 404 — Usuário da proxy inexistente

Retornado quando o `user_id` informado não existe ou foi digitado incorretamente. Aplica-se a: editar, histórico de uso, deletar, obter proxy, consultar saldo, histórico de saldo, adicionar saldo e remover saldo.

```json theme={null}
{
  "success": false,
  "message": "Proxy user not found."
}
```