Acesso à API #

Uma API (Application Programming Interface) é uma forma de diferentes sistemas de software comunicarem entre si. A API Your AI Connector 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.

Gerar a sua Chave de API #

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.

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.

Chaves com âmbito: chaves adicionais para uma tarefa específica #

A sua chave principal pode fazer tudo, por isso não é a chave a fornecer a um relatório, a um dashboard de cliente ou a uma configuração separada de sandbox e desenvolvimento. Para isso, crie chaves com âmbito no cartão Chaves com âmbito, na mesma secção Chave API abaixo de A sua chave:

1. Clique em Nova chave.
2. Atribua-lhe um Nome que reconheça mais tarde, por exemplo “Sandbox” ou “Dashboard do cliente Acme”.
3. Em O que pode ver, selecione apenas as áreas necessárias.
4. Em O que pode fazer, mantenha Apenas leitura a menos que a ferramenta precise de efetuar alterações. Uma chave que pode efetuar alterações pode enviar mensagens e editar a sua configuração.
5. Opcionalmente, defina Pedidos por minuto (o seu próprio limite, para que nunca abrande as suas outras integrações) e uma data de Expira em.
6. Clique em Criar chave e copie-a imediatamente. As chaves com âmbito são apresentadas apenas uma vez; se perder uma, revogue-a e crie outra.

Pode criar tantas quantas precisar. Cada chave na lista mostra quando foi utilizada pela última vez, e Revogar chave impede o seu funcionamento imediato. Criar ou revogar uma chave com âmbito nunca afeta a sua chave principal. As opções completas, incluindo chaves limitadas a subcontas específicas, encontram-se na página de chaves API da referência da API.

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 e a Referência da API.

Operações Comuns da API #

Criar um Contacto #

Pedido:

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:

{
  "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”.

Adicionar um Contacto a uma Lista #

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 #

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. Detalhes completos na API de Contactos.

Enviar uma Mensagem (Canal Personalizado) #

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"
  }
}

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 Your AI Connector. Consulte Canais Personalizados para obter todos os detalhes.

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"
}

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

Limitação de Taxa (Rate Limiting) #

A API impõe limites de taxa para garantir a estabilidade da plataforma. Exceder o seu limite devolve 429 Too Many Requests — aguarde e tente novamente após o tempo indicado nos cabeçalhos da resposta. Para casos de utilização de elevado volume (importações em massa), utilize a funcionalidade de importação integrada ou envie um e-mail para hi@youraiconnector.com para obter orientação.

Melhores práticas #

• Guarde a sua chave de API de forma segura — utilize um gestor de palavras-passe ou uma configuração do lado do servidor, nunca 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 as duplicatas — um número de telefone duplicado devolve { "success": false, "error_code": 409 } em vez de um novo contacto, com o ID do contacto existente em contactId.
• Teste com um pequeno conjunto de dados antes de executar operações em massa.

Respostas de Erro #

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

Próximos Passos #

• Webhooks — receba notificações em tempo real da aplicação (uma secção separada da sua chave de API).
• Ligar Assistentes de IA (MCP) — utilize a mesma chave de API para permitir que o Claude controle a sua conta.
• Formulários de Leads do Facebook — utilize a API com plataformas de automatização para capturar leads.
• Integração GoHighLevel — um exemplo completo de integração de API bidirecional.