> ## Documentation Index > Fetch the complete documentation index at: https://docs.useintegra.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Criar campanha > Cria uma campanha de ligações automáticas. As ligações serão iniciadas no horário agendado. > **Onde encontrar os IDs?** > - `project_id`: No painel, clique no projeto e copie o ID no header (ícone de clipboard ao lado do nome) > - `agent_id`: No painel, cada card de agente mostra o ID no rodapé (ícone de clipboard) > - `phone_number_id`: Use o endpoint GET /api/v1/phone-numbers ou copie do painel em Telecom ## OpenAPI ````yaml POST /api/v1/campaigns openapi: 3.1.0 info: title: Integra BFI API version: 1.0.0 description: > Integra API pública da plataforma Integra para integrações externas. > [!tip] > **Copie a documentação completa para sua IA favorita:** > [Abrir página de cópia](/docs/markdown) ou baixe o [llm.txt](/llm.txt) --- ## Como começar ### 1. Gerar sua API Key Acesse o painel da Integra em **Settings > API Keys** e clique em **Nova API Key**. > [!important] > Copie a key gerada (`ik_live_...`) imediatamente — ela **só será exibida uma vez**. ### 2. Autenticar requests Envie o header `Authorization` em todas as chamadas: ``` Authorization: Bearer ik_live_sua_key_aqui ``` ### 3. Fazer sua primeira chamada ```bash curl -H "Authorization: Bearer ik_live_xxx" \ https://api.useintegra.com.br/api/v1/campaigns ``` > [!success] > Se a resposta for `200 OK` com JSON, sua integração está funcionando! --- ## Rate Limiting | Header | Descrição | |--------|-----------| | `X-RateLimit-Limit` | Limite total (60/min) | | `X-RateLimit-Remaining` | Requests restantes | | `X-RateLimit-Reset` | Timestamp de reset (epoch) | > [!warning] > Ao exceder **60 requests/minuto** por API Key, a API retorna status `429 Too Many Requests`. --- ## Erros comuns | Status | Erro | Causa | |--------|------|-------| | `401` | Invalid API key | Key inválida ou revogada | | `403` | Forbidden | Key sem permissão para o recurso | | `429` | Rate limit exceeded | Excedeu 60 req/min | | `500` | Internal server error | Erro interno — contate suporte | servers: - url: https://api.useintegra.com.br description: Production security: - ApiKey: [] tags: - name: Campaigns description: Gerenciamento de campanhas de ligações - name: Calls description: Histórico de chamadas - name: Webhooks description: Gerenciamento de webhooks para notificações em tempo real paths: /api/v1/campaigns: post: tags: - Campaigns summary: Criar nova campanha de ligações description: >- Cria uma campanha de ligações automáticas. As ligações serão iniciadas no horário agendado. > **Onde encontrar os IDs?** > - `project_id`: No painel, clique no projeto e copie o ID no header (ícone de clipboard ao lado do nome) > - `agent_id`: No painel, cada card de agente mostra o ID no rodapé (ícone de clipboard) > - `phone_number_id`: Use o endpoint GET /api/v1/phone-numbers ou copie do painel em Telecom requestBody: required: true content: application/json: schema: type: object properties: name: type: string minLength: 1 description: Nome da campanha example: Campanha Março 2026 project_id: type: string format: uuid description: ID do projeto (copie do Panel → header do projeto) example: b9c80a57-fad2-41a0-a304-727337ad1b1f agent_id: type: string format: uuid description: >- ID do agente que fará as ligações (copie do Panel → card do agente) example: 7e09d093-904a-48de-ac49-b0445906c38e phone_number_id: type: string format: uuid description: ID do número de telefone de origem example: d1082e49-1b2c-4337-81e2-8eb74810351d scheduled_at: type: string format: date-time description: Data/hora para iniciar as ligações (ISO 8601 com timezone) example: '2026-03-25T14:00:00Z' recipients: type: array description: Lista de destinatários (max 10.000) minItems: 1 maxItems: 10000 items: type: object properties: phone_number: type: string pattern: ^\+[1-9]\d{7,14}$ description: Número no formato E.164 example: '+5511999999999' recipient_name: type: string description: Nome do destinatário (opcional) example: João Silva dynamic_variables: type: object description: >- Variáveis dinâmicas para o prompt do agente (ex: {{leadName}}). Chave = nome da variável, valor = texto (max 1000 chars) additionalProperties: type: string maxLength: 1000 example: leadName: Joao companyName: Acme Corp required: - phone_number config: type: object description: Configurações opcionais da campanha properties: call_timeout: type: integer minimum: 15 maximum: 120 description: 'Timeout de ring em segundos (default: 45)' example: 45 machine_detection_timeout: type: integer minimum: 5 maximum: 60 description: >- Timeout de detecção de caixa postal em segundos (default: 30) example: 30 voicemail_mode: type: string enum: - hangup - tts description: >- Ação ao detectar caixa postal: hangup (desliga) ou tts (deixa recado) example: hangup voicemail_tts_message: type: string maxLength: 500 description: >- Mensagem TTS para caixa postal (usado quando voicemail_mode=tts) example: >- Oi {leadName}, tentei falar com você. Me retorne quando puder! outbound_auto_greet: type: boolean description: >- Agente cumprimenta imediatamente sem esperar o destinatário (default: true) example: true max_concurrent: type: integer minimum: 1 maximum: 10 description: 'Max ligações simultâneas nesta campanha (default: 2)' example: 2 required: - name - project_id - agent_id - phone_number_id - scheduled_at - recipients example: name: Campanha Março 2026 project_id: b9c80a57-fad2-41a0-a304-727337ad1b1f agent_id: 7e09d093-904a-48de-ac49-b0445906c38e phone_number_id: d1082e49-1b2c-4337-81e2-8eb74810351d scheduled_at: '2026-03-25T14:00:00Z' recipients: - phone_number: '+5511999999999' recipient_name: João Silva dynamic_variables: leadName: Joao companyName: Acme Corp - phone_number: '+5511888888888' recipient_name: Maria Santos dynamic_variables: leadName: Maria companyName: Beta Ltd config: call_timeout: 45 voicemail_mode: hangup outbound_auto_greet: true max_concurrent: 2 responses: '201': description: Campanha criada com sucesso content: application/json: schema: type: object properties: id: type: string format: uuid description: ID da campanha criada name: type: string status: type: string enum: - PENDING total_recipients: type: integer scheduled_at: type: string format: date-time created_at: type: string format: date-time '400': description: Bad Request — dados inválidos content: application/json: schema: type: object properties: error: type: string required: - error security: - ApiKey: [] components: securitySchemes: ApiKey: type: http scheme: bearer bearerFormat: API Key description: 'API Key da organização (Authorization: Bearer ik_live_xxx)' ````