> ## 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.
# Listar campanhas
> Campanhas de voz e de WhatsApp da organização, com paginação
A lista traz os dois canais juntos. Use o campo `channel` de cada item para distinguir campanha de ligações (`voice`) de campanha de mensagens (`whatsapp`).
## Filtros
| Parâmetro | Valores | Padrão |
| - | - | - |
| `page` | Número da página | `1` |
| `limit` | Itens por página, máximo 100 | `20` |
| `status` | `PENDING`, `IN_PROGRESS`, `COMPLETED`, `FAILED`, `CANCELLED` | Todos |
| `project_id` | ID de um projeto da organização | Todos |
Um `status` fora da lista responde `400` em vez de devolver uma lista vazia — assim um erro de digitação não passa por "nenhuma campanha".
## Campos por canal
Campanhas de WhatsApp vêm com `agent`, `phone_number`, `config` e `started_at` nulos, e com `template_name` preenchido. Os detalhes de cada campo estão em [Detalhes da campanha](/api-reference/endpoint/get-campaign).
A lista **não** traz os destinatários, só os contadores (`total_recipients`, `dispatched_count`, `completed_count`, `failed_count`). Para ver contato a contato, e o motivo de cada falha, use o endpoint de detalhes.
## Exemplo
```bash Requisição theme={null}
curl "https://api.useintegra.com.br/api/v1/campaigns?status=COMPLETED&limit=2" \
-H "Authorization: Bearer ik_live_xxx"
```
```json Resposta 200 theme={null}
{
"campaigns": [
{
"id": "cmp_9f8e7d",
"name": "Retomada de matrículas",
"status": "COMPLETED",
"channel": "whatsapp",
"template_name": "retomada_matricula",
"scheduled_at": "2026-09-01T14:00:00.000Z",
"config": null,
"agent": null,
"phone_number": null,
"project": { "id": "proj_abc123", "name": "Comercial" },
"total_recipients": 2,
"dispatched_count": 2,
"completed_count": 1,
"failed_count": 1,
"started_at": null,
"ended_at": "2026-09-01T14:03:12.000Z",
"created_at": "2026-08-17T10:32:00.000Z"
},
{
"id": "cmp_1a2b3c",
"name": "Confirmação de consulta",
"status": "COMPLETED",
"channel": "voice",
"template_name": null,
"scheduled_at": "2026-08-30T13:00:00.000Z",
"config": { "call_timeout": 45, "max_concurrent": 2 },
"agent": { "id": "agt_xyz789", "name": "Bia" },
"phone_number": {
"id": "phn_456def",
"number": "+551130000000",
"friendly_name": "Comercial"
},
"project": { "id": "proj_abc123", "name": "Comercial" },
"total_recipients": 40,
"dispatched_count": 40,
"completed_count": 36,
"failed_count": 4,
"started_at": "2026-08-30T13:00:05.000Z",
"ended_at": "2026-08-30T13:41:22.000Z",
"created_at": "2026-08-29T18:10:00.000Z"
}
],
"pagination": { "page": 1, "limit": 2, "total": 12 }
}
```
## OpenAPI
````yaml GET /api/v1/campaigns
openapi: 3.1.0
info:
title: Integra BFI API
version: 1.0.0
description: >
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:
get:
tags:
- Campaigns
summary: Listar campanhas da organização
parameters:
- schema:
type: string
description: 'Página (default: 1)'
required: false
name: page
in: query
- schema:
type: string
description: 'Itens por página (default: 20, max: 100)'
required: false
name: limit
in: query
- schema:
type: string
description: >-
Filtrar por status (PENDING, IN_PROGRESS, COMPLETED, FAILED,
CANCELLED)
required: false
name: status
in: query
- schema:
type: string
description: Filtrar por projeto
required: false
name: project_id
in: query
responses:
'200':
description: Lista de campanhas
content:
application/json:
schema:
type: object
properties:
campaigns:
type: array
items:
type: object
properties:
id:
type: string
name:
type: string
status:
type: string
channel:
type: string
template_name:
type:
- string
- 'null'
scheduled_at:
type: string
agent:
type:
- object
- 'null'
properties:
id:
type: string
name:
type: string
required:
- id
- name
phone_number:
type:
- object
- 'null'
properties:
id:
type: string
number:
type: string
friendly_name:
type:
- string
- 'null'
required:
- id
- number
- friendly_name
project:
type: object
properties:
id:
type: string
name:
type: string
required:
- id
- name
config: {}
total_recipients:
type: number
dispatched_count:
type: number
completed_count:
type: number
failed_count:
type: number
started_at:
type:
- string
- 'null'
ended_at:
type:
- string
- 'null'
created_at:
type: string
required:
- id
- name
- status
- channel
- template_name
- scheduled_at
- agent
- phone_number
- project
- total_recipients
- dispatched_count
- completed_count
- failed_count
- started_at
- ended_at
- created_at
pagination:
type: object
properties:
page:
type: number
limit:
type: number
total:
type: number
required:
- page
- limit
- total
required:
- campaigns
- pagination
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
error:
type: string
required:
- error
'401':
description: Não autenticado
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)'
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.