# Acesso à API

Uma API (Application Programming Interface) é uma forma de diferentes sistemas de software comunicarem entre si. A API <span data-t="appName">Your AI Connector</span> permite-lhe (ou ao seu programador) criar contactos, enviar mensagens, gerir listas e receber mensagens de entrada de canais personalizados automaticamente — tudo isto sem utilizar o painel de controlo.


**Porquê utilizar a API?** Se pretende ligar a aplicação a uma ferramenta que não possui uma integração nativa, ou se precisa de automatizar tarefas repetitivas em grande escala, a API é a forma de o fazer.

::: note
**Nota:** Esta página tem uma natureza mais técnica. Se é proprietário de uma empresa e não um programador, poderá querer partilhar esta página com a sua equipa técnica ou com um programador freelancer.
:::


---

## Gerar a sua Chave de API

::: note
**Nota:** O acesso à API é uma funcionalidade paga disponível em planos elegíveis. Se o seu plano não a incluir, os pedidos à API serão rejeitados com uma resposta `403`. Verifique o seu plano ou contacte o suporte se não tiver a certeza se o acesso à API está ativado.
:::


1. Na barra lateral esquerda, clique em **Definições** (ícone de engrenagem).
2. Na barra lateral de Definições, sob o grupo **Integrações**, clique em **Chave de API**.


3. Se ainda não tiver uma chave, clique em **Generate API key**.
4. Se já tiver uma, esta é apresentada mascarada em **Your key**. Se a sua chave o permitir, clique em **Show** para a revelar e, em seguida, em **Copy** para a copiar — verá uma notificação de confirmação.
5. Guarde a chave num local seguro — irá precisar dela para todos os pedidos à API.


::: note
**Nota:** Algumas contas apresentam "Your key can't be displayed" em vez de um controlo Show/Copy — isto acontece com chaves criadas antes de a aplicação poder voltar a apresentá-las. A chave continua a funcionar normalmente; apenas precisa de **Regenerate** (abaixo do cartão da chave, na mesma secção) se precisar realmente de ver o texto simples novamente. A regeneração invalida a chave antiga imediatamente e interrompe todas as integrações que a utilizam até que cole a nova — atualize as suas integrações logo de seguida.
:::


::: warning
**Importante:** A sua chave de API é como uma palavra-passe — concede acesso total à sua conta. Não a partilhe publicamente nem a publique em locais onde outros a possam ver. Se acredita que a sua chave foi comprometida, regenere-a imediatamente.
:::


> **Membros da equipa:** a chave de API pertence ao proprietário da conta, por isso, se tiver sessão iniciada como membro convidado da equipa (incluindo um Administrador), a secção apresenta uma nota em vez da chave. Inicie sessão como proprietário da conta para a ver, copiar ou regenerar — isto aplica-se também às chaves com âmbito definido.

> **Onde a encontrar:** **Chave de API** é a sua própria secção em Definições → Integrações, separada de **Webhooks**. Se um guia ou um colega lhe disser para procurar a chave em "Webhooks", procure na secção ao lado.

---

## URL Base

Todos os pedidos à API utilizam o seguinte endereço web base:

```
https://api.youraiconnector.com/v1/
```

---

## Autenticação

Cada pedido deve incluir a sua chave de API para que a plataforma saiba que é o utilizador. A forma mais simples é adicioná-la ao final do endereço web:

```
https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY
```

Também pode enviar a chave como um cabeçalho de pedido em vez de a incluir no URL (recomendado para produção, para que a chave não apareça nos registos do servidor):

```
X-API-Key: YOUR_API_KEY
```
```
Authorization: Bearer YOUR_API_KEY
```

Todos os pedidos devem utilizar uma ligação segura (HTTPS). Pedidos inseguros (HTTP) são rejeitados.

> **Procura os guias completos para programadores?** Esta página é uma introdução rápida que abrange as operações mais comuns. Para guias completos, passo a passo — todos os recursos, com exemplos em cURL, JavaScript e Python — consulte [Introdução à API](../api/getting-started.md) e a [Referência da API](../api/reference.md).

---

## Operações Comuns da API

### Criar um Contacto

**Pedido:**

```http
POST https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "firstName": "Jane",
  "lastName": "Smith",
  "phoneNumber": "+15551234567",
  "email": "jane@example.com"
}
```

**Campos obrigatórios:** um `phoneNumber` (com código de país) é sempre necessário para criar um contacto. Um endereço de e-mail por si só não é suficiente — um pedido sem um número de telefone válido será rejeitado. O e-mail é opcional.

**Resposta:**

```json
{
  "success": true,
  "data": {
    "message": "Successfully created new contact",
    "contactId": "abc123xyz",
    "listsAdded": []
  }
}
```

Guarde o `data.contactId` — irá precisar dele para a chamada "Adicionar um Contacto a uma Lista".

::: note
**Nota:** se um contacto com o mesmo número de telefone já existir, a API **não** cria nem devolve esse contacto — devolve `{ "success": false, "error_code": 409 }`. Procure primeiro o contacto existente com `GET https://api.youraiconnector.com/v1/contacts?phoneNumber=...`.
:::


---

### Adicionar um Contacto a uma Lista

```http
POST https://api.youraiconnector.com/v1/contacts/lists?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "contactId": "abc123xyz",
  "listId": "YOUR_LIST_ID"
}
```

Encontre o ID de uma lista na aplicação em **Contactos → Listas**, a partir do menu da linha da lista (**Copiar ID da lista**).

---

### Atualizar um Contacto

```http
PUT https://api.youraiconnector.com/v1/contacts/YOUR_CONTACT_ID?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customFields": { "company": "Acme Inc" }
}
```

Apenas os campos que incluir são alterados. Esta é também a forma de carregar em massa valores de campos personalizados após uma importação — consulte [Campos Personalizados, Perfil de Contacto e Notas](../get-started/custom-contact-fields.md#bulk-loading-custom-fields). Detalhes completos na [API de Contactos](../api/contacts.md).

---

### Enviar uma Mensagem (Canal Personalizado)

```http
POST https://api.youraiconnector.com/v1/send_custom_channel_message?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customData": {
    "fromId": "external-contact-id",
    "customChannel": "my-channel",
    "body": "Hello Jane! Your order has been shipped.",
    "campaignId": "optional-campaign-id",
    "firstName": "Jane",
    "lastName": "Smith"
  }
}
```

| Campo | Obrigatório | Descrição |
|---|---|---|
| `customData.fromId` | Sim | O ID do contacto na sua plataforma |
| `customData.customChannel` | Sim | O nome do seu canal personalizado |
| `customData.body` | Sim | O texto da mensagem a enviar |
| `customData.campaignId` | Não | Encaminhar a mensagem para uma campanha específica |
| `customData.firstName` | Não | Nome próprio do contacto (utilizado ao criar um novo contacto) |
| `customData.lastName` | Não | Apelido do contacto |
| `customData.email` | Não | Endereço de e-mail do contacto |

::: note
**Nota:** este endpoint destina-se a mensagens de canais personalizados. Para WhatsApp, SMS, Instagram e Messenger, as mensagens são enviadas através de Transmissões, Campanhas e Agentes de IA.
:::


---

### Receber Mensagens Recebidas (Canal Personalizado)

Aceite mensagens de sistemas externos como um canal personalizado. É assim que integrações como o GoHighLevel enviam mensagens para o <span data-t="appName">Your AI Connector</span>. Consulte [Canais Personalizados](../messaging-channels/custom-channels.md) para obter todos os detalhes.

```http
POST https://api.youraiconnector.com/v1/incoming_custom_channel_message?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customData": {
    "messageSid": "unique-message-id",
    "fromId": "external-contact-id",
    "toId": "your-user-id",
    "body": "Customer's message here",
    "channel": "custom",
    "status": "received"
  },
  "messageType": "text"
}
```

| Campo | Obrigatório | Descrição |
|---|---|---|
| `customData.messageSid` | Sim | Um ID único para esta mensagem (evita duplicados). Também pode usar `customData.id`. |
| `customData.fromId` | Sim | O ID do remetente no seu sistema externo. |
| `customData.toId` | Sim | O seu identificador de empresa. |
| `customData.body` | Sim | O texto da mensagem. |
| `customData.channel` | Não | Uma etiqueta para a origem (por exemplo, `"email"`, `"livechat"`, `"custom"`). |
| `customData.status` | Não | Estado da mensagem. O padrão é `"received"`. |
| `messageType` | Não | `"text"` para mensagens de texto, `"reaction"` para reações com emoji. |

---

## Visão Geral das Operações Disponíveis

| Ação | Método | Endereço | Descrição |
|---|---|---|---|
| Criar um contacto | `POST` | `/contacts` | Adicionar um novo contacto à sua conta |
| Obter detalhes do contacto | `GET` | `/contacts?phoneNumber=X` ou `/contacts?email=X` | Procurar um contacto por número de telefone ou e-mail |
| Atualizar um contacto | `PUT` | `/contacts/{contactId}` | Atualizar qualquer campo num contacto existente |
| Adicionar contacto a uma lista | `POST` | `/contacts/lists` | Adicionar um contacto existente a uma lista específica |
| Enviar uma mensagem | `POST` | `/send_custom_channel_message` | Enviar uma mensagem através de um canal personalizado |
| Receber uma mensagem | `POST` | `/incoming_custom_channel_message` | Aceitar uma mensagem de um sistema externo |

---

## Limitação de Taxa (Rate Limiting)

The API enforces rate limits to ensure platform stability. Exceeding your limit returns `429 Too Many Requests` — back off and retry after the time indicated in the response headers. For high-volume use cases (bulk imports), use the built-in [import feature](../get-started/importing-contacts.md) or email [<span data-t="supportEmail">hi@youraiconnector.com</span>](mailto:hi@youraiconnector.com) for guidance.

---

## Melhores práticas

- **Guarde a sua chave de API de forma segura** — num gestor de palavras-passe ou configuração do lado do servidor, nunca em código do lado do cliente que um visitante do navegador possa ler.
- **Inclua sempre o código do país** nos números de telefone (`+1` para os EUA, `+44` para o Reino Unido, `+31` para os Países Baixos).
- **Trate os erros de forma elegante** — verifique os códigos de estado e leia quaisquer mensagens de erro devolvidas.
- **Trate os duplicados** — um número de telefone duplicado devolve `{ "success": false, "error_code": 409 }` em vez de um novo contacto. Procure primeiro o contacto se precisar de trabalhar com ele.
- **Teste com um pequeno conjunto de dados** antes de executar operações em massa.

---

## Respostas de Erro

```json
{
  "error": {
    "code": "INVALID_PHONE",
    "message": "Phone number must include a valid country code."
  }
}
```

| Status Code | Meaning |
|---|---|
| `200` | Success |
| `201` | Resource created |
| `400` | Bad request — check your parameters |
| `401` | Unauthorized — invalid or missing API key |
| `403` | Forbidden — your plan doesn't include API access, or you lack permission |
| `404` | Resource not found |
| `429` | Rate limit exceeded |
| `500` | Server error — email [<span data-t="supportEmail">hi@youraiconnector.com</span>](mailto:hi@youraiconnector.com) if this persists |

---

## Próximos Passos

- [Webhooks](webhooks.md) — receba notificações em tempo real da aplicação (uma secção separada da sua chave de API).
- [Ligar Assistentes de IA (MCP)](connect-ai-clients.md) — utilize a mesma chave de API para permitir que o Claude controle a sua conta.
- [Formulários de Leads do Facebook](facebook-lead-forms.md) — utilize a API com plataformas de automatização para capturar leads.
- [Integração GoHighLevel](ghl-integration.md) — um exemplo completo de integração de API bidirecional.