Introdução à API #

A API REST do Your AI Connector permite-lhe criar a sua própria integração sobre a sua conta. Pode criar e consultar contactos, gerir campanhas, FAQs, tarefas e marcações, enviar mensagens, registar webhooks, ler análises e ligar canais de mensagens — tudo o que o painel de controlo faz, orientado por código.

Esta é a página central da documentação da API. Se estiver a ligar o Your AI Connector a uma ferramenta que já possui uma integração integrada, poderá não precisar da API. A API destina-se a integrações personalizadas e automatização em escala.

URL Base #

Todos os pedidos são enviados para o mesmo endereço web base, e todos os caminhos nestes documentos são relativos a ele:

https://api.youraiconnector.com/v1

Portanto, o endpoint de campanhas é https://api.youraiconnector.com/v1/campaigns, o endpoint de contactos é https://api.youraiconnector.com/v1/contacts, e assim por diante.

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

Obter uma chave de API #

O acesso à API é uma funcionalidade paga. Se o seu plano não a incluir, cada pedido devolverá um 403 com este corpo:

{
  "success": false,
  "error_code": 403,
  "error": "This action requires the \"api_access\" feature, which is not enabled for this account."
}

Assim que o acesso à API estiver ativado no seu plano, gere uma chave a partir do painel de controlo. O passo a passo completo encontra-se em Acesso à API — resumidamente: vá a Definições → Integrações → Chave de API para gerar ou regenerar a sua chave. A Chave de API é uma secção própria em Integrações, separada dos Webhooks, e só aparece quando o acesso à API está ativo no seu plano. Trate a chave como uma palavra-passe: ela concede acesso total à sua conta.

Autenticação #

Pode enviar a sua chave de API de quatro formas. Todas funcionam em qualquer endpoint que aceite autenticação por chave de API.

Para produção, prefira uma das formas de cabeçalho para que a sua chave nunca fique registada num log de servidor ou histórico de navegador. A forma de parâmetro de consulta funciona sempre e é a mais simples para um teste pontual.

Consulte Autenticação para uma análise completa de cada método, com exemplos e orientações sobre quando utilizar cada um.

O seu primeiro pedido #

Aqui tem uma chamada completa e funcional que lista as campanhas na sua conta. Utiliza a sua chave de API e devolve as campanhas mais recentes primeiro.

cURL

curl "https://api.youraiconnector.com/v1/campaigns?apiKey=YOUR_API_KEY&limit=10"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/campaigns?limit=10", {
  headers: {
    "X-API-Key": "YOUR_API_KEY",
  },
});

const data = await res.json();
console.log(data.campaigns);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/campaigns",
    params={"limit": 10},
    headers={"X-API-Key": "YOUR_API_KEY"},
)

data = res.json()
print(data["campaigns"])

Uma resposta bem-sucedida tem este aspeto:

{
  "success": true,
  "campaigns": [
    {
      "id": "NBCXrhqGPSFsd6MV7pRo",
      "name": "Inbound WhatsApp Leads",
      "type": "Incoming from Unknown Contacts",
      "status": "Live",
      "enabled": true,
      "archived": false,
      "created_at": 1700000000000,
      "ai_mode": true,
      "language": "en",
      "enabled_channels": ["whatsapp", "instagram"]
    }
  ],
  "next_cursor": null
}

Respostas de sucesso e erro #

Todas as respostas JSON contêm um sinalizador success para que possa ramificar com base nele sem ter de analisar os códigos de estado.

Uma resposta bem-sucedida é success: true mais os dados para esse endpoint (o nome do campo varia — campaigns, contacts, data, e assim por diante):

{
  "success": true,
  "campaigns": []
}

Uma resposta falhada é success: false com uma mensagem error legível por humanos e um error_code numérico que corresponde ao estado HTTP:

{
  "success": false,
  "error": "Invalid cursor",
  "error_code": 400
}

Verifique sempre success (ou o estado HTTP) antes de ler os dados. Consulte Erros e Paginação para obter a tabela completa de códigos de estado e saber como paginar grandes conjuntos de resultados.

Limites de taxa #

Os pedidos autenticados estão limitados a 300 pedidos por minuto por chave de API. Existe também um limite mais abrangente de 1.200 pedidos por minuto por conta, contabilizando todos os pedidos autenticados efetuados para essa conta.

Se exceder qualquer um dos limites, receberá uma resposta 429:

{
  "success": false,
  "error_code": 429,
  "error": "Rate limit exceeded. Please try again later."
}

Aguarde e tente novamente após uma curta espera. Também pode verificar a sua utilização atual a qualquer momento com GET https://api.youraiconnector.com/v1/api-keys/usage, que devolve quantos pedidos utilizou na janela atual e quando esta é reiniciada — útil para criar limitação de débito no lado do cliente. Consulte Chaves de API.

Guias de recursos #

Os grupos de recursos abaixo têm cada um o seu próprio guia com os caminhos exatos, campos de pedido e formatos de resposta.

Agentes, Pontos de Entrada e Transmissões #

Os Agentes de IA, Pontos de Entrada e Broadcasts estão todos na especificação OpenAPI publicada, pelo que pode consultar os seus campos exatos e executar pedidos em tempo real no explorador de API. Cada um tem o seu próprio guia: Agentes de IA, Pontos de Entrada e Broadcasts.

Ler esta documentação em Markdown #

Todas as páginas desta documentação têm um equivalente em Markdown simples: basta pegar no endereço da página e adicionar /index.md ao final. Assim, esta página também está disponível em https://docs.youraiconnector.com/api/getting-started/index.md e é apresentada como texto simples em vez de uma página web — útil quando pretende colar uma página num assistente de IA ou integrá-la num script.

Para percorrer todo o conjunto, comece em https://docs.youraiconnector.com/sitemap.xml, que lista todas as páginas que publicamos. Tenha em atenção que a documentação é deliberadamente excluída dos motores de busca, pelo que aceder a estes endereços diretamente é a forma de a obter a partir de código.

Não existe um endpoint de documentação protegido por chave nem uma funcionalidade de transferência em massa — os equivalentes em Markdown e o mapa do site constituem toda a interface, e nenhum deles necessita de uma chave de API.

Próximos passos #

• Autenticação — escolha o método de autenticação correto para a sua integração.
• Erros e Paginação — lide com falhas e percorra os resultados por páginas.
• Acesso à API — gere a sua chave e veja exemplos práticos.