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

# Início rápido com a Sorsa API

> Obtenha sua chave de API e faça a primeira requisição à API do X (Twitter) em minutos.

Este guia leva você até a primeira resposta: crie uma conta, configure a autenticação e execute requisições GET e POST. Cada etapa inclui exemplos em cURL, Python e JavaScript.

## Etapa 1: obtenha sua chave de API

1. Abra o [painel da Sorsa](https://api.sorsa.io/overview), clique em **Sign in** e cadastre-se com uma das opções disponíveis. A Sorsa não pede nada além do que seu provedor de autenticação compartilha.
2. Sua conta começa com **100 requisições gratuitas**, sem cartão de crédito. Elas funcionam em todos os endpoints disponíveis e não expiram.
3. Quando precisar de mais volume, escolha um plano (10 mil, 100 mil ou 500 mil requisições por mês), o ciclo de cobrança mensal ou anual e pague com cartão ou cripto.

Após o login, o painel mostra sua **chave de API** e a **cota restante**.

> **Mantenha sua chave em sigilo.** Não a exponha em código de frontend, repositórios públicos ou JavaScript executado no cliente. Trate-a como uma senha.

## Etapa 2: entenda o básico

**URL base**

```text theme={null}
https://api.sorsa.io/v3
```

**Autenticação**

Toda requisição deve incluir sua chave no cabeçalho `ApiKey`:

```text theme={null}
ApiKey: YOUR_API_KEY
```

**Formato de resposta**

Todos os endpoints retornam JSON. Requisições bem-sucedidas retornam HTTP `200`.

**Limite de requisições**

Todos os planos têm limite de 20 requisições por segundo. Consulte [limites de requisições](https://docs.sorsa.io/pt-BR/rate-limits) para controlar o ritmo e as novas tentativas.

## Etapa 3: envie sua primeira requisição GET

**Antes de executar os exemplos:** instale o pacote Python `requests` com `python -m pip install requests`. Execute o JavaScript no backend com Node.js 18+ e `fetch`; salve os exemplos como `.mjs` para usar `await` no nível superior. Substitua `YOUR_API_KEY` pela sua chave. As respostas de perfis e publicações abaixo são ilustrativas.

Para confirmar a configuração, consulte um perfil público com `/info`.

**cURL**

```bash theme={null}
curl --request GET \
  --url 'https://api.sorsa.io/v3/info?username=elonmusk' \
  --header 'ApiKey: YOUR_API_KEY'
```

**Python**

```python theme={null}
import requests

response = requests.get(
    "https://api.sorsa.io/v3/info",
    params={"username": "elonmusk"},
    headers={"ApiKey": "YOUR_API_KEY"},
    timeout=30,
)

response.raise_for_status()
data = response.json()
print(data["display_name"])      # Elon Musk
print(data["followers_count"])   # 236021252
```

**JavaScript**

```javascript theme={null}
const response = await fetch(
  "https://api.sorsa.io/v3/info?username=elonmusk",
  { headers: { ApiKey: "YOUR_API_KEY" } }
);

if (!response.ok) throw new Error(`HTTP ${response.status}`);
const data = await response.json();
console.log(data.display_name);      // Elon Musk
console.log(data.followers_count);   // 236021252
```

**Exemplo de resposta**

```json theme={null}
{
  "id": "44196397",
  "username": "elonmusk",
  "display_name": "Elon Musk",
  "description": "",
  "location": "",
  "profile_image_url": "https://pbs.twimg.com/profile_images/1234567890/avatar.jpg",
  "profile_background_image_url": "https://pbs.twimg.com/profile_banners/44196397/1700000000",
  "followers_count": 236021252,
  "followings_count": 1292,
  "tweets_count": 98479,
  "favourites_count": 214650,
  "media_count": 4374,
  "verified": true,
  "protected": false,
  "can_dm": false,
  "possibly_sensitive": false,
  "created_at": "2009-06-02T20:12:29Z",
  "bio_urls": [],
  "pinned_tweet_ids": ["2028500984977330453"]
}
```

Se você receber JSON com os dados do usuário, a chave está funcionando.

## Etapa 4: envie sua primeira requisição POST

Vários endpoints de publicações e busca usam `POST` com corpo JSON. Veja uma busca com `/search-tweets`:

**cURL**

```bash theme={null}
curl --request POST \
  --url 'https://api.sorsa.io/v3/search-tweets' \
  --header 'ApiKey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{ "query": "bitcoin" }'
```

**Python**

```python theme={null}
import requests

response = requests.post(
    "https://api.sorsa.io/v3/search-tweets",
    headers={"ApiKey": "YOUR_API_KEY"},
    json={"query": "bitcoin"},
    timeout=30,
)

response.raise_for_status()
data = response.json()
for tweet in data.get("tweets", []):
    print(tweet["full_text"])
```

**JavaScript**

```javascript theme={null}
const response = await fetch("https://api.sorsa.io/v3/search-tweets", {
  method: "POST",
  headers: {
    ApiKey: "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "bitcoin" }),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
const data = await response.json();
data.tweets?.forEach((tweet) => console.log(tweet.full_text));
```

**Exemplo de resposta (abreviado)**

```json theme={null}
{
  "tweets": [
    {
      "id": "1782368585664626774",
      "full_text": "Bitcoin just crossed another milestone.",
      "created_at": "2024-01-15T10:30:00Z",
      "lang": "en",
      "likes_count": 200,
      "retweet_count": 50,
      "reply_count": 10,
      "view_count": 10000,
      "user": {
        "id": "44196397",
        "username": "elonmusk",
        "display_name": "Elon Musk",
        "followers_count": 236021252,
        "verified": true
      }
    }
  ],
  "next_cursor": "DAABCgABF7d..."
}
```

Para obter mais resultados, envie o `next_cursor` retornado na próxima requisição. Veja o fluxo completo em [paginação](https://docs.sorsa.io/pt-BR/pagination).

## Etapa 5: consulte o consumo da API

Use `/key-usage-info` para consultar as requisições restantes:

```bash theme={null}
curl --request GET \
  --url 'https://api.sorsa.io/v3/key-usage-info' \
  --header 'ApiKey: YOUR_API_KEY'
```

**Exemplo de resposta**

```json theme={null}
{
  "key_requests": 100000,
  "remaining_requests": 94231,
  "total_requests": 5769,
  "valid_until": "2026-08-01T00:00:00Z"
}
```

Faça essa consulta antes de trabalhos em lote grandes. O histórico completo também está no [painel](https://api.sorsa.io/overview/usage).

## Códigos de erro comuns

| Código | Significado            | O que fazer                                                 |
| :----- | :--------------------- | :---------------------------------------------------------- |
| 200    | OK                     | Requisição concluída                                        |
| 400    | Requisição inválida    | Confira os parâmetros e o corpo da requisição               |
| 401    | Não autorizado         | Chave ausente ou inválida; confira o cabeçalho `ApiKey`     |
| 403    | Acesso proibido        | O acesso ao recurso foi negado                              |
| 404    | Não encontrado         | Confira a URL do endpoint ou o ID do recurso                |
| 429    | Excesso de requisições | Aguarde e tente novamente                                   |
| 500    | Erro no servidor       | Tente após uma breve espera; procure o suporte se persistir |

Veja detalhes e estratégias na [referência de códigos de erro](https://docs.sorsa.io/pt-BR/error-codes).

## Teste sem código

Explore os endpoints pela [referência da API](https://docs.sorsa.io/pt-BR/api-reference-guide) ou pelo [API Playground](https://api.sorsa.io/playground). Ambos permitem enviar requisições reais e inspecionar respostas antes de escrever código.

## Próximos passos

* [Autenticação](https://docs.sorsa.io/pt-BR/authentication): segurança e configuração de cabeçalhos.
* [Paginação](https://docs.sorsa.io/pt-BR/pagination): cursores e respostas paginadas.
* [Limites de requisições](https://docs.sorsa.io/pt-BR/rate-limits): ritmo e novas tentativas.
* [Referência da API](https://docs.sorsa.io/pt-BR/api-reference-guide): endpoints e esquemas.
* [Casos de uso](https://docs.sorsa.io/pt-BR/use-cases-overview): padrões de implementação.