# API do LinkedIn e Assistentes de IA (MCP)

Tudo o que faz nas páginas do LinkedIn também pode ser feito a partir de um script ou de um assistente de IA: os seus leads, a fila de pedidos de ligação, as suas regras de ICP (incluindo que países aceita e qual o tamanho da rede que um lead deve ter), a sua caixa de entrada, os seus agentes de IA e as suas definições.

Não há nada de novo para configurar. Utiliza a **mesma chave de API que o resto do <span data-t="appName">DM Champ</span>**, por isso, se já chama a nossa API ou tem um assistente de IA ligado, está pronto.

## Onde encontrar a sua chave

Definições → Integrações → Chave de API. Se ainda não tiver uma, clique em **Gerar chave de API**. Os passos completos encontram-se em [Acesso à API](api-access.md).

Não existe uma chave do LinkedIn separada para criar, rodar ou revogar. A chave atua como se fosse o utilizador, com as mesmas permissões que tem na aplicação, por isso trate-a como uma palavra-passe. Revogá-la nas Definições corta instantaneamente o acesso a todos os scripts e assistentes ligados.

## Chamar a API diretamente

- **URL base:** `https://app.sdrpilot.ai/api/v1`
- **Cabeçalho:** `X-API-Key: YOUR_API_KEY`
- **Descrição legível por máquina:** `https://app.sdrpilot.ai/api/v1/docs/openapi.yaml`
  (também disponível como `.json`)

O documento OpenAPI é público e descreve todas as rotas, pelo que a maioria das ferramentas de API e geradores de código podem importá-lo diretamente sem uma chave.

`Authorization: Bearer YOUR_API_KEY` também funciona. O que não pode fazer é enviar uma chave errada e esperar que o sistema aceite outra coisa: uma vez apresentada uma chave, a resposta baseia-se nessa chave.

O que é devolvido quando algo corre mal:

| Resposta | O que significa |
|---|---|
| `401` | A chave está em falta, mal formatada ou não é aceite. |
| `403` | A chave é válida, mas essa conta não tem um espaço de trabalho do LinkedIn ou ainda não tem permissão. |
| `429` | Demasiadas tentativas rejeitadas num minuto para essa chave. Abrande. |
| `502` `dmchamp_unreachable` | Não foi possível verificar a sua chave nesse momento. Nunca é tratada como um acesso válido. Tente novamente. |

## Ligar um assistente de IA

As ferramentas do LinkedIn residem no mesmo endpoint MCP que as do <span data-t="appName">DM Champ</span>, com a mesma chave de API, pelo que um assistente que já tenha ligado as deteta automaticamente. Se ainda não ligou nenhum, siga [Ligar Assistentes de IA (MCP)](connect-ai-clients.md) e utilize o endpoint aí listado.

::: master-only
O endpoint é `https://mcp.youraiconnector.com/mcp`, autenticado com o cabeçalho `X-API-Key`, exatamente como descrito em Ligar Assistentes de IA (MCP).
:::

As ferramentas do LinkedIn têm todas o prefixo **`linkedin_`**, pelo que são fáceis de identificar na lista de ferramentas do seu assistente e fáceis de solicitar pelo nome ("usa as ferramentas do LinkedIn para me mostrar o que está na fila"). Não existem permissões por ferramenta: uma ferramenta pode fazer tudo o que você pode fazer na aplicação.

## Exemplo 1 — aceitar apenas leads de determinados países

O seu perfil ICP contém as regras que os leads têm de cumprir. Isto define uma lista de permissões para os Países Baixos e a Bélgica. Os códigos de país são de duas letras, em maiúsculas.

```bash
curl -X PUT https://app.sdrpilot.ai/api/v1/icp/YOUR_ICP_ID/filters \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"countries":{"mode":"allow","codes":["NL","BE"]}}'
```

Duas coisas a saber. O corpo é o conjunto **completo** de regras, não um patch: uma regra que deixe de fora é desativada. E a resposta inclui um bloco `impact_on_queue` que lhe indica quantos pedidos de ligação já em fila falhariam as novas regras, por exemplo `{"examined": 389, "would_withdraw": 155}`.
Guardar regras não retira nada por si só.

Num assistente, bastaria dizer: "Define o meu ICP para aceitar apenas os Países Baixos e a Bélgica, e diz-me o que isso faria à minha fila."

## Exemplo 2 — ver o que está na fila

Pedidos de ligação que foram aprovados, mas ainda não enviados:

```bash
curl -s "https://app.sdrpilot.ai/api/v1/connections/queue?status=queued&limit=100" \
  -H "X-API-Key: YOUR_API_KEY"
```

Cada linha contém o nome da pessoa, o título, a empresa, a localização, o país, o número de ligações e seguidores, e a pontuação. Pode restringir a lista com `country`, `min_score`, `max_score` e `source`, e navegar nela com `limit` e `cursor`. Apenas os pedidos em fila e a aguardar aprovação aparecem aqui. Os pedidos já enviados são histórico e não podem ser alterados.

## Exemplo 3 — retirar todos os que estão fora dos seus países

Após alterar as suas regras, volte a verificar a fila em relação às mesmas. Sem `apply=true`, isto é uma pré-visualização e não altera nada:

```bash
curl -X POST "https://app.sdrpilot.ai/api/v1/connections/queue/rescreen" \
  -H "X-API-Key: YOUR_API_KEY"
```

Recebe de volta quantos foram examinados, quantos seriam retirados e uma análise por regra, como `country` e `network_too_small` (a rede do lead era menor do que o seu mínimo). Satisfeito com o resultado? Execute novamente com `?apply=true` e esses pedidos serão retirados.

```bash
curl -X POST "https://app.sdrpilot.ai/api/v1/connections/queue/rescreen?apply=true" \
  -H "X-API-Key: YOUR_API_KEY"
```

Se preferir retirar um conjunto específico, envie os ids, ou um filtro como `{"filter":{"status":"queued","country":"NG"}}` para esvaziar tudo o que corresponda. Envie ids ou um filtro, não ambos.

## Resolução de Problemas

- **`401` em cada chamada** — a chave está em falta ou incorreta. Copie-a novamente a partir de Definições → Integrações → Chave de API.
- **`403` embora a chave funcione noutros locais** — essa conta não está ligada a um espaço de trabalho do LinkedIn, ou o LinkedIn ainda não está ativado para a mesma.
- **`502 dmchamp_unreachable`** — uma falha temporária ao verificar a sua chave. Nada foi processado; tente novamente.
- **Uma regra não corresponde a nada** — os códigos de país devem ser a forma de duas letras em maiúsculas (`NL`, não `Netherlands` ou `nl`), e os códigos de idioma devem estar em minúsculas.
- **O assistente não mostra ferramentas do LinkedIn** — volte a ligá-lo para que recarregue a lista de ferramentas e verifique se está a utilizar a mesma chave de API.

---

## Próximos Passos

- [Ligar Assistentes de IA (MCP)](connect-ai-clients.md) — configure o Claude, ChatGPT ou Cursor com a sua chave.
- [Acesso à API](api-access.md) — gere ou renove a chave que isto utiliza.