> ## 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.

# Conversão de IDs

Converta nomes de usuário, IDs numéricos e URLs de perfis do X. São três endpoints, com uma requisição por conversão. As 100 requisições gratuitas, sem cartão, permitem começar imediatamente.

> Veja a explicação completa sobre identificadores no [guia do blog](https://api.sorsa.io/blog/twitter-id-converter).

> **Sem código:** o [Sorsa ID Converter](https://api.sorsa.io/playground/id-converter) gratuito converte nomes, IDs e URLs sem chave de API.

## Por que usar IDs

Nomes de usuário podem mudar e ser adotados por outra pessoa. O ID numérico é atribuído na criação e permanece estável.

* **Renomeações não quebram referências.** O ID continua apontando para a mesma conta.
* **Preserve a precisão.** Use strings em JSON e JavaScript. Em colunas inteiras de banco, confirme que o intervalo suporta o ID completo.
* **Una dados ao longo do tempo pelo ID.** É a chave estável entre coletas.
* **Alguns endpoints usam IDs.** `/info-batch` aceita `user_ids` ou `usernames`; listas e comunidades têm IDs próprios.

## Formato dos IDs

O X usa Snowflake de 64 bits, combinando timestamp, máquina e sequência. Publicações usam esse formato desde 2010.

IDs de usuários continuaram sequenciais por anos e migraram para Snowflake por volta de 2020. Por isso contas antigas têm IDs curtos, como `12`, e contas recentes podem ter 19 dígitos. Não é possível decodificar a criação de IDs antigos; consulte `created_at` no perfil.

## 1. Nome de usuário para ID

```http theme={null}
GET /v3/username-to-id/{user_handle}
```

Converte o nome sem @ em ID permanente.

```bash theme={null}
curl "https://api.sorsa.io/v3/username-to-id/elonmusk" \
  -H "ApiKey: YOUR_API_KEY"
```

```json theme={null}
{"id": "44196397"}
```

```python theme={null}
import requests

API_KEY = "YOUR_API_KEY"

def username_to_id(handle: str) -> str:
    resp = requests.get(
        f"https://api.sorsa.io/v3/username-to-id/{handle}",
        headers={"ApiKey": API_KEY},
    )
    resp.raise_for_status()
    return resp.json()["id"]

print(username_to_id("elonmusk"))  # "44196397"
```

```javascript theme={null}
async function usernameToId(handle) {
  const resp = await fetch(
    `https://api.sorsa.io/v3/username-to-id/${handle}`,
    { headers: { "ApiKey": "YOUR_API_KEY" } }
  );
  return (await resp.json()).id;
}
```

## 2. ID para nome de usuário

```http theme={null}
GET /v3/id-to-username/{user_id}
```

Resolve o nome atual, útil para exibir IDs salvos ou detectar renomeações.

```bash theme={null}
curl "https://api.sorsa.io/v3/id-to-username/44196397" \
  -H "ApiKey: YOUR_API_KEY"
```

```json theme={null}
{"handle": "elonmusk"}
```

```python theme={null}
def id_to_username(user_id: str) -> str:
    resp = requests.get(
        f"https://api.sorsa.io/v3/id-to-username/{user_id}",
        headers={"ApiKey": API_KEY},
    )
    resp.raise_for_status()
    return resp.json()["handle"]
```

## 3. Link de perfil para ID

```http theme={null}
GET /v3/link-to-id?link={profile_url}
```

Converte URLs de perfis, úteis ao normalizar links vindos de planilhas, favoritos ou páginas coletadas.

```bash theme={null}
curl "https://api.sorsa.io/v3/link-to-id?link=https://x.com/elonmusk" \
  -H "ApiKey: YOUR_API_KEY"
```

```json theme={null}
{"id": "44196397"}
```

```python theme={null}
def link_to_id(profile_url: str) -> str:
    resp = requests.get(
        "https://api.sorsa.io/v3/link-to-id",
        headers={"ApiKey": API_KEY},
        params={"link": profile_url},
    )
    resp.raise_for_status()
    return resp.json()["id"]
```

> Se precisar do ID e do perfil completo, use [`/info`](https://docs.sorsa.io/pt-br/api-reference/usu%C3%A1rios/perfil-do-usu%C3%A1rio) com `username`, evitando a conversão separada. Veja [otimização](https://docs.sorsa.io/pt-BR/optimizing-api-usage).

## Padrões comuns

### Conversão de várias contas

Para listas de CRM, concorrentes ou planilhas:

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

API_KEY = "YOUR_API_KEY"
BASE = "https://api.sorsa.io/v3"
HEADERS = {"ApiKey": API_KEY}


def batch_username_to_id(handles, pause=0.05):
    """
    Resolve a list of handles to user IDs.
    Returns: dict mapping handle -> id (or None if lookup failed).
    """
    results = {}
    for handle in handles:
        handle = handle.strip().lstrip("@")
        try:
            resp = requests.get(f"{BASE}/username-to-id/{handle}", headers=HEADERS, timeout=10)
            if resp.status_code == 200:
                results[handle] = resp.json()["id"]
            elif resp.status_code == 404:
                results[handle] = None  # Account does not exist or is suspended
            elif resp.status_code == 429:
                time.sleep(1)
                retry = requests.get(f"{BASE}/username-to-id/{handle}", headers=HEADERS, timeout=10)
                results[handle] = retry.json()["id"] if retry.status_code == 200 else None
            else:
                results[handle] = None
        except requests.RequestException:
            results[handle] = None
        time.sleep(pause)
    return results


handles = ["NASA", "SpaceX", "Tesla", "OpenAI", "stripe"]
id_map = batch_username_to_id(handles)

for handle, uid in id_map.items():
    print(f"@{handle} -> {uid or '(not found)'}")
```

No sentido inverso, use `/id-to-username/{user_id}` e leia `handle`. Isso ajuda a atualizar nomes antigos na base.

### Normalizar entradas mistas

Aceite nomes, URLs ou IDs e normalize para ID. Se já for um ID, evite a chamada:

```python theme={null}
def normalize_to_id(value: str) -> str:
    """
    Accepts a handle, an @handle, a profile URL, or a numeric ID.
    Returns the numeric user ID.
    """
    value = value.strip().lstrip("@")

    if value.isdigit():
        return value

    if "x.com/" in value or "twitter.com/" in value:
        return link_to_id(value)

    return username_to_id(value)


# All four return the same ID
for source in ["elonmusk", "@elonmusk", "https://x.com/elonmusk", "44196397"]:
    print(normalize_to_id(source))
```

Use como primeira etapa do pipeline para que as etapas seguintes trabalhem com identificadores estáveis.

### Detectar renomeações

Com ID e nome salvos, consulte novamente para detectar mudanças:

```python theme={null}
def detect_renames(records):
    """
    records: list of {"user_id": str, "stored_handle": str}
    Returns: list of accounts that have renamed.
    """
    changes = []
    for record in records:
        try:
            current = id_to_username(record["user_id"])
        except requests.HTTPError:
            continue  # Deleted, suspended, or transient error

        if current and current.lower() != record["stored_handle"].lower():
            changes.append({
                "user_id": record["user_id"],
                "old_handle": record["stored_handle"],
                "new_handle": current,
            })
        time.sleep(0.05)
    return changes
```

Para uma auditoria mais detalhada, [`/about`](https://docs.sorsa.io/pt-br/api-reference/usu%C3%A1rios/informa%C3%A7%C3%B5es-da-conta) retorna `username_change_count` e `last_username_change_at`, com quantidade e data da última mudança.

## Próximos passos

* [Seguidores](https://docs.sorsa.io/pt-BR/followers-and-following): extração com identificadores estáveis.
* [Localização](https://docs.sorsa.io/pt-BR/Audience-Geography): país e histórico pelo ID.
* [Otimização](https://docs.sorsa.io/pt-BR/optimizing-api-usage): evite conversões desnecessárias.
* [Referência da API](https://docs.sorsa.io/pt-BR/api-reference-guide): especificações de `/username-to-id`, `/id-to-username` e `/link-to-id`.