# Acesso à API

Uma API (Interface de Programação de Aplicações) é uma maneira de diferentes sistemas de software se comunicarem. A API <span data-t="appName">Your AI Connector</span> permite que você (ou seu desenvolvedor) crie contatos automaticamente, envie mensagens, gerencie listas e receba mensagens de entrada de canais personalizados — tudo sem usar o painel de controle.


**Por que usar a API?** Se você deseja conectar o aplicativo a uma ferramenta que não possui uma integração nativa, ou se precisa automatizar tarefas repetitivas em escala, a API é o caminho a seguir.

::: note
**Nota:** Esta página tem uma natureza mais técnica. Se você é proprietário de uma empresa e não um desenvolvedor, talvez queira compartilhar esta página com sua equipe técnica ou com um desenvolvedor freelancer.
:::


---

## Gerando sua Chave de API

::: note
**Nota:** O acesso à API é um recurso pago disponível em planos qualificados. Se o seu plano não o incluir, as solicitações de API serão rejeitadas com uma resposta `403`. Verifique seu plano ou entre em contato com o suporte se não tiver certeza se o acesso à API está habilitado.
:::


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


3. Se você ainda não possui uma chave, clique em **Generate API key**.
4. Se você já possui uma, ela será exibida mascarada em **Your key**. Se sua chave permitir, clique em **Show** para revelá-la e, em seguida, em **Copy** para copiá-la — você verá uma notificação de confirmação.
5. Armazene a chave em um local seguro — você precisará dela para cada solicitação de API.


::: note
**Nota:** Algumas contas exibem "Your key can't be displayed" em vez de um controle Show/Copy — isso acontece com chaves criadas antes que o aplicativo pudesse exibi-las novamente. A chave continua funcionando normalmente; você só precisa de **Regenerate** (abaixo do cartão da chave, na mesma seção) se realmente precisar ver o texto simples novamente. Regenerar invalida a chave antiga imediatamente e interrompe todas as integrações que a utilizam até que você cole a nova — atualize suas integrações logo em seguida.
:::


::: warning
**Importante:** Sua chave de API é como uma senha — ela concede acesso total à sua conta. Não a compartilhe publicamente nem a publique em qualquer lugar onde outros possam vê-la. Se você acredita que sua chave foi comprometida, regenere-a imediatamente.
:::


> **Membros da equipe:** a chave de API pertence ao proprietário da conta, portanto, se você estiver conectado como um membro convidado da equipe (incluindo um Administrador), a seção exibirá uma nota em vez da chave. Entre como proprietário da conta para visualizar, copiar ou regenerar a chave — isso também se aplica a chaves com escopo definido.

> **Onde encontrá-la:** **Chave de API** é uma seção própria em Configurações → Integrações, separada de **Webhooks**. Se um guia ou um colega disser para você procurar a chave em "Webhooks", procure na seção ao lado.

---

## URL Base

Todas as solicitações de API usam o seguinte endereço web base:

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

---

## Autenticação

Cada solicitação deve incluir sua chave de API para que a plataforma saiba que é você. A maneira mais simples é adicioná-la ao final do endereço web:

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

Você também pode enviar a chave como um cabeçalho de solicitação em vez de na URL (recomendado para produção, para que a chave não acabe nos logs do servidor):

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

Todas as solicitações devem usar uma conexão segura (HTTPS). Solicitações inseguras (HTTP) são rejeitadas.

> **Procurando pelos guias completos para desenvolvedores?** Esta página é uma introdução rápida que cobre as operações mais comuns. Para guias completos e passo a passo — com todos os recursos, incluindo 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 de API

### Criar um Contato

**Solicitação:**

```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 do país) é sempre necessário para criar um contato. Apenas um endereço de e-mail não é suficiente — uma solicitação sem um número de telefone válido será rejeitada. O e-mail é opcional.

**Resposta:**

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

Salve o `data.contactId` — você precisará dele para a chamada "Adicionar um Contato a uma Lista".

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


---

### Adicionar um Contato 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 no aplicativo em **Contatos → Listas**, no menu da linha da lista (**Copiar ID da lista**).

---

### Atualizar um contato

```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 você incluir serão alterados. Esta também é a maneira de carregar em massa valores de campos personalizados após uma importação — consulte [Campos Personalizados, Perfil do Lead e Notas](../get-started/custom-contact-fields.md#bulk-loading-custom-fields). Detalhes completos na [API de Contatos](../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 contato na sua plataforma |
| `customData.customChannel` | Sim | O nome do seu canal personalizado |
| `customData.body` | Sim | O texto da mensagem a ser enviada |
| `customData.campaignId` | Não | Direcionar a mensagem para uma campanha específica |
| `customData.firstName` | Não | Primeiro nome do contato (usado ao criar um novo contato) |
| `customData.lastName` | Não | Sobrenome do contato |
| `customData.email` | Não | Endereço de e-mail do contato |

::: note
**Nota:** este endpoint é para mensagens de canal personalizado. Para WhatsApp, SMS, Instagram e Messenger, as mensagens são enviadas através de Transmissões, Campanhas e Agentes de IA.
:::


---

### Receber Mensagens de Entrada (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>. Veja [Canais Personalizados](../messaging-channels/custom-channels.md) para detalhes completos.

```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 exclusivo para esta mensagem (evita duplicatas). Você também pode usar `customData.id`. |
| `customData.fromId` | Sim | O ID do remetente no seu sistema externo. |
| `customData.toId` | Sim | Seu identificador de negócio. |
| `customData.body` | Sim | O texto da mensagem. |
| `customData.channel` | Não | Um rótulo para a origem (por exemplo, `"email"`, `"livechat"`, `"custom"`). |
| `customData.status` | Não | Status 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 contato | `POST` | `/contacts` | Adicionar um novo contato à sua conta |
| Obter detalhes do contato | `GET` | `/contacts?phoneNumber=X` ou `/contacts?email=X` | Pesquisar um contato por número de telefone ou e-mail |
| Atualizar um contato | `PUT` | `/contacts/{contactId}` | Atualizar qualquer campo em um contato existente |
| Adicionar contato à lista | `POST` | `/contacts/lists` | Adicionar um contato 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

- **Armazene sua chave de API com segurança** — use um gerenciador de senhas ou configuração do lado do servidor, nunca código do lado do cliente que um visitante do navegador possa ler.
- **Sempre inclua o código do país** nos números de telefone (`+1` para EUA, `+44` para Reino Unido, `+31` para Holanda).
- **Trate erros de forma elegante** — verifique os códigos de status e leia quaisquer mensagens de erro retornadas.
- **Trate duplicatas** — um número de telefone duplicado retorna `{ "success": false, "error_code": 409 }` em vez de um novo contato. Procure o contato primeiro se precisar 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 do aplicativo (uma seção separada da sua chave de API).
- [Conectar assistentes de IA (MCP)](connect-ai-clients.md) — use a mesma chave de API para permitir que o Claude gerencie sua conta.
- [Formulários de lead do Facebook](facebook-lead-forms.md) — use a API com plataformas de automação para capturar leads.
- [Integração com GoHighLevel](ghl-integration.md) — um exemplo completo de integração de API bidirecional.