# 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. ::: note **Nota:** Estas páginas foram escritas para programadores. Se não for um programador, partilhe esta secção com a sua equipa técnica. ::: --- ## 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: ```json { "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](../integrations/api-access.md) — 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. | Método | Como | Ideal para | |---|---|---| | Parâmetro de consulta | `?apiKey=YOUR_API_KEY` | Testes rápidos, URLs de navegador, configurações legadas | | Cabeçalho | `X-API-Key: YOUR_API_KEY` | Integrações em produção | | Cabeçalho Bearer | `Authorization: Bearer YOUR_API_KEY` | Integrações em produção | | Token de ID Firebase | `Authorization: Bearer ` | Apenas sessões de aplicações próprias | 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](authentication.md) 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** ```bash curl "https://api.youraiconnector.com/v1/campaigns?apiKey=YOUR_API_KEY&limit=10" ``` **JavaScript** ```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** ```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: ```json { "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): ```json { "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: ```json { "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](errors-and-pagination.md) 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`: ```json { "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](api-keys.md). --- ## 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. | Recurso | O que abrange | |---|---| | [Agentes de IA](agents.md) | Criar e configurar Agentes de IA: definições, horas de atividade, conhecimentos, regras de etiquetagem, ferramentas, multimédia e rascunhos | | [Pontos de Entrada](entry-points.md) | Decidir que Agente de IA responde a uma nova conversação: predefinições de canal, um Agente por número de WhatsApp, regras de palavras-chave, comentários e seguidores | | [Broadcasts](broadcasts.md) | Criar, definir preços, lançar, pausar e duplicar envios únicos para uma lista de contactos | | [Campanhas](campaigns.md) | Criar, atualizar, duplicar, ativar, arquivar e inspecionar campanhas e a sua configuração de bot | | [Contactos](contacts.md) | Criar, procurar, listar, atualizar, importar, etiquetar e eliminar contactos | | [FAQs](faqs.md) | Gerir as entradas de perguntas e respostas que o seu assistente de IA utiliza e associá-las a campanhas | | [Base de Conhecimento](knowledge-base.md) | Importar websites e documentos para o conhecimento da sua IA e agrupar FAQs em conjuntos | | [Tarefas](tasks.md) | Criar e gerir tarefas de CRM, etapas de quadros e tipos de tarefas | | [Mensagens](messages.md) | Enviar mensagens de saída e ler o histórico de conversações | | [Marcações](appointments.md) | Marcar, reagendar, cancelar e eliminar marcações | | [Canais](channels.md) | Ligar e desligar canais de mensagens, comprar números e definir que Agente de IA responde a novas conversações em cada canal | | [Modelos](templates.md) | Criar, submeter e verificar o estado de aprovação de modelos de mensagens de WhatsApp | | [Análise](analytics.md) | Ler estatísticas diárias de eventos de mensagens, utilização de créditos e resumos de custos de IA | | [Webhooks](webhooks.md) | Registar endpoints para receber notificações de eventos em tempo real | | [Equipa](team.md) | Gerir membros da equipa, convites, funções, permissões e departamentos | | [Chaves de API](api-keys.md) | Inspecionar, rodar e revogar a sua chave de API, verificar a utilização do limite de taxa e criar chaves adicionais com acesso limitado | ### 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](reference.md). Cada um tem o seu próprio guia: [Agentes de IA](agents.md), [Pontos de Entrada](entry-points.md) e [Broadcasts](broadcasts.md). --- ## 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](authentication.md) — escolha o método de autenticação correto para a sua integração. - [Erros e Paginação](errors-and-pagination.md) — lide com falhas e percorra os resultados por páginas. - [Acesso à API](../integrations/api-access.md) — gere a sua chave e veja exemplos práticos.