# Introdução à API A API REST do Your AI Connector permite que você crie sua própria integração com sua conta. Você pode criar e pesquisar contatos, gerenciar campanhas, FAQs, tarefas e agendamentos, enviar mensagens, registrar webhooks, ler análises e conectar canais de mensagens — tudo o que o painel faz, controlado por código. Esta é a página central da documentação da API. Se você estiver conectando o Your AI Connector a uma ferramenta que já possui uma integração integrada, talvez você nem precise da API. A API é destinada a integrações personalizadas e automação em escala. ::: note **Nota:** Estas páginas foram escritas para desenvolvedores. Se você não é um desenvolvedor, compartilhe esta seção com sua equipe técnica. ::: --- ## URL Base Todas as solicitações vão 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 contatos é `https://api.youraiconnector.com/v1/contacts`, e assim por diante. Todas as solicitações devem usar uma conexão segura (HTTPS). Solicitações HTTP simples são rejeitadas. --- ## Obtendo uma chave de API O acesso à API é um **recurso pago**. Se o seu plano não o incluir, cada solicitação retornará 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 habilitado em seu plano, gere uma chave a partir do painel. O passo a passo completo está em [Acesso à API](../integrations/api-access.md) — em resumo: vá para **Configurações → Integrações → Chave de API** para gerar ou regenerar sua chave. A Chave de API é uma seção própria em Integrações, separada de Webhooks, e ela só aparece quando o acesso à API está habilitado em seu plano. Trate a chave como uma senha: ela concede acesso total à sua conta. --- ## Autenticação Você pode enviar sua chave de API de quatro maneiras. Todas funcionam em todos os endpoints que aceitam 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 de produção | | Cabeçalho Bearer | `Authorization: Bearer YOUR_API_KEY` | Integrações de produção | | Token de ID do Firebase | `Authorization: Bearer ` | Apenas sessões de aplicativos de primeira parte | Para produção, prefira uma das formas de cabeçalho para que sua chave nunca apareça em um log de servidor ou histórico do navegador. A forma de parâmetro de consulta sempre funciona e é a mais simples para um teste rápido. Consulte [Autenticação](authentication.md) para uma análise completa de cada método, com exemplos e orientações sobre quando usar cada um. --- ## Sua primeira solicitação Aqui está uma chamada completa e funcional que lista as campanhas em sua conta. Ela usa sua chave de API e retorna 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 esta aparência: ```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 Toda resposta JSON contém uma flag `success` para que você possa ramificar a lógica sem precisar analisar códigos de status. Uma resposta bem-sucedida é `success: true` mais os dados para aquele endpoint (o nome do campo varia — `campaigns`, `contacts`, `data`, e assim por diante): ```json { "success": true, "campaigns": [] } ``` Uma resposta com falha é `success: false` com uma mensagem `error` legível por humanos e um `error_code` numérico que corresponde ao status HTTP: ```json { "success": false, "error": "Invalid cursor", "error_code": 400 } ``` Sempre verifique `success` (ou o status HTTP) antes de ler os dados. Consulte [Erros e Paginação](errors-and-pagination.md) para ver a tabela completa de códigos de status e como paginar grandes conjuntos de resultados. --- ## Limites de taxa Requisições autenticadas são limitadas a **300 requisições por minuto** por chave de API. Há também um limite mais amplo de **1.200 requisições por minuto por conta**, contando cada requisição autenticada feita para essa conta. Se você 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 um curto intervalo. Você também pode verificar seu uso atual a qualquer momento com `GET https://api.youraiconnector.com/v1/api-keys/usage`, que retorna quantas requisições você usou na janela atual e quando ela será redefinida — útil para criar limitação de taxa (throttling) no lado do cliente. Consulte [Chaves de API](api-keys.md). --- ## Guias de recursos Os grupos de recursos abaixo possuem cada um seu próprio guia com os caminhos exatos, campos de solicitação e formatos de resposta. | Recurso | O que cobre | |---|---| | [Agentes de IA](agents.md) | Crie e configure Agentes de IA: configurações, horário de funcionamento, conhecimento, regras de marcação, ferramentas, mídia e rascunhos | | [Pontos de Entrada](entry-points.md) | Decida qual Agente de IA responde a uma nova conversa: padrões de canal, um Agente por número de WhatsApp, regras de palavra-chave, comentário e seguidor | | [Transmissões](broadcasts.md) | Crie, precifique, inicie, pause e duplique envios únicos para uma lista de contatos | | [Campanhas](campaigns.md) | Crie, atualize, duplique, habilite, arquive e inspecione campanhas e suas configurações de bot | | [Contatos](contacts.md) | Crie, pesquise, liste, atualize, importe, marque e exclua contatos | | [FAQs](faqs.md) | Gerencie as entradas de perguntas e respostas que seu assistente de IA usa e vincule-as a campanhas | | [Base de Conhecimento](knowledge-base.md) | Importe sites e documentos para o conhecimento da sua IA e agrupe FAQs em conjuntos | | [Tarefas](tasks.md) | Crie e gerencie tarefas de CRM, estágios de quadro e tipos de tarefa | | [Mensagens](messages.md) | Envie mensagens de saída e leia o histórico de conversas | | [Agendamentos](appointments.md) | Agende, remarque, cancele e exclua agendamentos | | [Canais](channels.md) | Conecte e desconecte canais de mensagens, compre números e defina qual Agente de IA responde a novas conversas em cada canal | | [Modelos](templates.md) | Crie, envie e verifique o status de aprovação de modelos de mensagem do WhatsApp | | [Análise](analytics.md) | Leia estatísticas diárias de eventos de mensagens, uso de créditos e resumos de custos de IA | | [Webhooks](webhooks.md) | Registre endpoints para receber notificações de eventos em tempo real | | [Equipe](team.md) | Gerencie membros da equipe, convites, funções, permissões e departamentos | | [Chaves de API](api-keys.md) | Inspecione, rotacione e revogue sua chave de API, verifique o uso do limite de taxa e crie chaves extras com acesso limitado | ### Agentes, Pontos de Entrada e Transmissões Agentes de IA, Pontos de Entrada e Transmissões estão todos na especificação OpenAPI publicada, para que você possa navegar pelos seus campos exatos e executar solicitações ao vivo no [explorador de API](reference.md). Cada um tem seu próprio guia: [Agentes de IA](agents.md), [Pontos de Entrada](entry-points.md) e [Transmissões](broadcasts.md). --- ## Lendo esta documentação como Markdown Cada página nesta documentação possui um equivalente em Markdown simples: pegue o endereço da página e adicione `/index.md` ao final. Portanto, esta página também está disponível em `https://docs.youraiconnector.com/api/getting-started/index.md`, e ela é retornada como texto simples em vez de uma página da web — útil quando você deseja colar uma página em um assistente de IA ou importá-la para um script. Para percorrer todo o conjunto, comece em `https://docs.youraiconnector.com/sitemap.xml`, que lista todas as páginas que publicamos. Observe que a documentação é mantida deliberadamente fora dos mecanismos de busca, portanto, buscar esses endereços diretamente é a maneira de acessá-la via código. Não há um endpoint de documentação protegido por chave nem download em massa disponível ainda — os equivalentes em Markdown e o mapa do site são toda a interface, e nenhum deles requer uma chave de API. --- ## Próximos passos - [Autenticação](authentication.md) — escolha o método de autenticação correto para sua integração. - [Erros e Paginação](errors-and-pagination.md) — lide com falhas e pagine através dos resultados. - [Acesso à API](../integrations/api-access.md) — gere sua chave e veja exemplos práticos.