> ## 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.
# Detalhes da campanha
> Campanha com a lista completa de destinatários e o motivo de cada falha
## Campos por canal
O campo `channel` diz se a campanha é de voz ou de WhatsApp, e alguns campos só fazem sentido em um dos dois.
| Campo | `voice` | `whatsapp` |
| - | - | - |
| `agent` | O agente que liga | `null` |
| `phone_number` | O número de origem | `null` |
| `config` | Parâmetros de discagem | `null` |
| `template_name` | `null` | Nome do template aprovado na Meta |
| `started_at` | Quando a campanha começou | `null` |
`started_at` vem `null` no canal `whatsapp` de propósito. Internamente aquele carimbo é o batimento do processo de disparo, recarimbado a cada destinatário, e não o horário em que a campanha começou. Publicá-lo mentiria. Use `created_at` e `scheduled_at`.
## Status dos destinatários
Cada item de `recipients` tem um `status` próprio. O canal de WhatsApp usa a escala de entrega da Meta:
| Status | Significado |
| - | - |
| `PENDING` | Ainda não disparado |
| `SENT` | Template entregue à Meta |
| `DELIVERED` | Chegou ao aparelho |
| `READ` | O contato abriu a mensagem |
| `REPLIED` | O contato respondeu |
| `FAILED` | A Meta recusou o envio. O motivo está em `error_message` |
| `CANCELLED` | A campanha foi cancelada antes de disparar este contato |
Os status nunca regridem: um recibo de entrega atrasado não rebaixa quem já respondeu.
`error_message` traz o erro **cru da Meta**, com código e tudo (por exemplo `(#132000) Number of parameters does not match the expected number of params`). É o único lugar da API que diz por que um envio específico falhou — a lista de campanhas só sabe contar falhas.
## Exemplo
```bash Requisição theme={null}
curl https://api.useintegra.com.br/api/v1/campaigns/cmp_9f8e7d \
-H "Authorization: Bearer ik_live_xxx"
```
```json Resposta 200 theme={null}
{
"id": "cmp_9f8e7d",
"name": "Retomada de matrículas",
"status": "COMPLETED",
"channel": "whatsapp",
"template_name": "retomada_matricula",
"scheduled_at": "2026-09-01T14:00:00.000Z",
"agent": null,
"phone_number": null,
"config": 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",
"recipients": [
{
"id": "rcp_111",
"phone_number": "+5511999999999",
"recipient_name": "Ana",
"status": "REPLIED",
"error_message": null,
"dynamic_variables": { "1": "Ana", "2": "quinta às 14h" }
},
{
"id": "rcp_222",
"phone_number": "+5521988887777",
"recipient_name": "Bruno",
"status": "FAILED",
"error_message": "(#132000) Number of parameters does not match the expected number of params",
"dynamic_variables": { "1": "Bruno" }
}
]
}
```
## OpenAPI
````yaml GET /api/v1/campaigns/{id}
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/{id}:
get:
tags:
- Campaigns
summary: Detalhes de uma campanha
parameters:
- schema:
type: string
description: ID da campanha
required: true
name: id
in: path
responses:
'200':
description: Detalhes da campanha com recipients
content:
application/json:
schema:
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
recipients:
type: array
items:
type: object
properties:
id:
type: string
phone_number:
type: string
recipient_name:
type:
- string
- 'null'
status:
type: string
error_message:
type:
- string
- 'null'
dynamic_variables: {}
conversation_id:
type:
- string
- 'null'
duration_ms:
type:
- number
- 'null'
cost_usd:
type:
- number
- 'null'
started_at:
type:
- string
- 'null'
ended_at:
type:
- string
- 'null'
required:
- id
- phone_number
- recipient_name
- status
- error_message
- conversation_id
- duration_ms
- cost_usd
- started_at
- ended_at
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
- recipients
'404':
description: Não encontrada
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.