# Criar campanha
Source: https://docs.useintegra.com.br/api-reference/endpoint/create-campaign

POST /api/v1/campaigns
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



# Criar webhook
Source: https://docs.useintegra.com.br/api-reference/endpoint/create-webhook

POST /api/v1/webhooks
Cria um webhook para receber notificações de eventos. O secret retornado só é exibido uma vez — guarde-o para verificar assinaturas HMAC-SHA256. Máximo de 10 webhooks por organização.



# Excluir webhook
Source: https://docs.useintegra.com.br/api-reference/endpoint/delete-webhook

DELETE /api/v1/webhooks/{id}



# Detalhes da chamada
Source: https://docs.useintegra.com.br/api-reference/endpoint/get-call

GET /api/v1/calls/{id}



# Detalhes da campanha
Source: https://docs.useintegra.com.br/api-reference/endpoint/get-campaign

GET /api/v1/campaigns/{id}



# Detalhes do webhook
Source: https://docs.useintegra.com.br/api-reference/endpoint/get-webhook

GET /api/v1/webhooks/{id}



# Listar chamadas
Source: https://docs.useintegra.com.br/api-reference/endpoint/list-calls

GET /api/v1/calls



# Listar campanhas
Source: https://docs.useintegra.com.br/api-reference/endpoint/list-campaigns

GET /api/v1/campaigns



# Listar entregas
Source: https://docs.useintegra.com.br/api-reference/endpoint/list-webhook-deliveries

GET /api/v1/webhooks/{id}/deliveries



# Listar webhooks
Source: https://docs.useintegra.com.br/api-reference/endpoint/list-webhooks

GET /api/v1/webhooks



# Atualizar webhook
Source: https://docs.useintegra.com.br/api-reference/endpoint/update-webhook

PATCH /api/v1/webhooks/{id}



# Introdução
Source: https://docs.useintegra.com.br/api-reference/introduction

Visão geral da API BFI da Integra

## Base URL

```
https://api.useintegra.com.br
```

## Autenticação

Todos os endpoints requerem autenticação via API Key no header `Authorization`:

```bash theme={null}
Authorization: Bearer ik_live_sua_key_aqui
```

<Card title="Como obter uma API Key" icon="key" href="/authentication">
  Gere sua key no painel da Integra em Settings > API Keys.
</Card>

## Endpoints disponíveis

### Campanhas

| Método | Endpoint                 | Descrição                       |
| ------ | ------------------------ | ------------------------------- |
| `GET`  | `/api/v1/campaigns`      | Listar campanhas da organização |
| `GET`  | `/api/v1/campaigns/{id}` | Detalhes de uma campanha        |
| `POST` | `/api/v1/campaigns`      | Criar nova campanha de ligações |

### Chamadas

| Método | Endpoint             | Descrição                    |
| ------ | -------------------- | ---------------------------- |
| `GET`  | `/api/v1/calls`      | Listar histórico de chamadas |
| `GET`  | `/api/v1/calls/{id}` | Detalhes de uma chamada      |

## Rate Limiting

Limite de **60 requests por minuto** por API Key. Veja [Rate Limiting](/rate-limiting) para mais detalhes.

## Formato de erro

```json theme={null}
{
  "error": "Descrição do erro"
}
```

Veja [Erros](/errors) para a lista completa de códigos.


# Autenticação
Source: https://docs.useintegra.com.br/authentication

Como autenticar suas chamadas à API usando API Keys

Todas as rotas `/api/v1/*` requerem autenticação via API Key.

## Header de autenticação

```bash theme={null}
Authorization: Bearer ik_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

## Como obter uma API Key

<Steps>
  <Step title="Acesse o painel">
    Entre em [app.useintegra.com.br](https://app.useintegra.com.br) e vá em **Settings > API Keys**.
  </Step>

  <Step title="Crie uma nova key">
    Clique em **Nova API Key** e dê um nome descritivo (ex: "Integração CRM").
  </Step>

  <Step title="Copie a key">
    <Warning>
      A key só será exibida uma vez. Se perdê-la, revogue e crie uma nova.
    </Warning>
  </Step>
</Steps>

## Formato da key

As API Keys seguem o formato `ik_live_` seguido de 64 caracteres hexadecimais:

```
ik_live_a1b2c3d4e5f6789...
```

## Segurança

* A key é hasheada com **SHA-256** antes de ser armazenada
* Cada key pertence a uma **organização** e filtra dados automaticamente
* Keys podem ser **revogadas** a qualquer momento no painel
* O último uso de cada key é rastreado automaticamente

## Erros de autenticação

| Status | Mensagem                     | Causa                         |
| ------ | ---------------------------- | ----------------------------- |
| `401`  | Missing Authorization header | Header não enviado            |
| `401`  | Invalid API key format       | Key não começa com `ik_live_` |
| `401`  | Invalid or revoked API key   | Key inválida ou revogada      |


# Erros
Source: https://docs.useintegra.com.br/errors

Códigos de erro e formato de resposta

Todas as respostas de erro seguem o mesmo formato JSON.

## Formato

```json theme={null}
{
  "error": "Descrição do erro"
}
```

## Códigos de erro

| Status | Erro                  | Causa                                              |
| ------ | --------------------- | -------------------------------------------------- |
| `400`  | Bad Request           | Body ou parâmetros inválidos                       |
| `401`  | Unauthorized          | API Key ausente, inválida ou revogada              |
| `403`  | Forbidden             | Sem permissão para o recurso                       |
| `404`  | Not Found             | Recurso não encontrado                             |
| `429`  | Too Many Requests     | [Rate limit](/rate-limiting) excedido (60 req/min) |
| `500`  | Internal Server Error | Erro interno — contate suporte                     |

## Exemplos

### Key inválida (401)

```bash theme={null}
curl -H "Authorization: Bearer ik_live_invalida" \
  https://api.useintegra.com.br/api/v1/campaigns
```

```json Response theme={null}
{
  "error": "Invalid or revoked API key"
}
```

### Recurso não encontrado (404)

```bash theme={null}
curl -H "Authorization: Bearer ik_live_xxx" \
  https://api.useintegra.com.br/api/v1/campaigns/id-inexistente
```

```json Response theme={null}
{
  "error": "Campaign not found"
}
```

### Rate limit excedido (429)

```json Response theme={null}
{
  "error": "Rate limit exceeded. Try again later."
}
```

<Tip>
  Sempre verifique o campo `error` na resposta para entender o que aconteceu. Os erros são descritivos em inglês para facilitar o debugging.
</Tip>


# Introdução
Source: https://docs.useintegra.com.br/index

API pública da plataforma Integra para integrações externas

## Bem-vindo à Integra API

A **Integra BFI** (Backend for Integrations) é a API pública da plataforma Integra. Com ela, você pode integrar campanhas de ligações e histórico de chamadas diretamente no seu sistema.

<Card title="Quickstart" icon="rocket" href="/quickstart">
  Configure sua primeira integração em 3 minutos.
</Card>

## O que você pode fazer

<Columns>
  <Card title="Campanhas" icon="phone-volume" href="/api-reference/endpoint/list-campaigns">
    Crie e gerencie campanhas de ligações automatizadas.
  </Card>

  <Card title="Chamadas" icon="clock-rotate-left" href="/api-reference/endpoint/list-calls">
    Consulte o histórico completo de chamadas com transcrições.
  </Card>

  <Card title="Autenticação" icon="key" href="/authentication">
    Gere API Keys no painel e autentique suas chamadas.
  </Card>

  <Card title="API Reference" icon="terminal" href="/api-reference/introduction">
    Documentação completa de todos os endpoints.
  </Card>
</Columns>

## Base URL

```
https://api.useintegra.com.br
```

Todos os endpoints da API estão sob o prefixo `/api/v1/`.


# Quickstart
Source: https://docs.useintegra.com.br/quickstart

Configure sua primeira integração em 3 minutos

<Steps>
  <Step title="Gerar sua API Key">
    Acesse o painel da Integra em **Settings > API Keys** e clique em **Nova API Key**.

    <Warning>
      Copie a key gerada (`ik_live_...`) imediatamente — ela **só será exibida uma vez**.
    </Warning>
  </Step>

  <Step title="Autenticar requests">
    Envie o header `Authorization` em todas as chamadas:

    ```bash theme={null}
    Authorization: Bearer ik_live_sua_key_aqui
    ```
  </Step>

  <Step title="Fazer sua primeira chamada">
    ```bash theme={null}
    curl -H "Authorization: Bearer ik_live_xxx" \
      https://api.useintegra.com.br/api/v1/campaigns
    ```

    <Check>
      Se a resposta for `200 OK` com JSON, sua integração está funcionando!
    </Check>
  </Step>
</Steps>

## Próximos passos

<CardGroup>
  <Card title="Autenticação" icon="key" href="/authentication">
    Entenda o fluxo completo de autenticação via API Key.
  </Card>

  <Card title="Rate Limiting" icon="gauge" href="/rate-limiting">
    Conheça os limites de requisições por minuto.
  </Card>

  <Card title="Erros" icon="triangle-exclamation" href="/errors">
    Veja os códigos de erro e como tratá-los.
  </Card>

  <Card title="API Reference" icon="terminal" href="/api-reference/introduction">
    Explore todos os endpoints disponíveis.
  </Card>
</CardGroup>


# Rate Limiting
Source: https://docs.useintegra.com.br/rate-limiting

Limites de requisições por minuto e como monitorá-los

A API limita a **60 requests por minuto** por API Key.

## Headers de resposta

Toda resposta inclui headers de rate limiting:

| Header                  | Descrição                          |
| ----------------------- | ---------------------------------- |
| `X-RateLimit-Limit`     | Limite total (60/min)              |
| `X-RateLimit-Remaining` | Requests restantes na janela       |
| `X-RateLimit-Reset`     | Timestamp de reset (epoch seconds) |

## Exemplo

```bash theme={null}
< X-RateLimit-Limit: 60
< X-RateLimit-Remaining: 42
< X-RateLimit-Reset: 1709913600
```

## Excedendo o limite

Ao exceder o limite, a API retorna `429 Too Many Requests`:

```json theme={null}
{
  "error": "Rate limit exceeded. Try again later."
}
```

## Boas práticas

<CardGroup>
  <Card title="Monitore os headers" icon="chart-line">
    Verifique `X-RateLimit-Remaining` para evitar atingir o limite.
  </Card>

  <Card title="Retry com backoff" icon="rotate">
    Implemente retry com backoff exponencial ao receber `429`.
  </Card>

  <Card title="Respeite o reset" icon="clock">
    Aguarde `X-RateLimit-Reset` antes de tentar novamente.
  </Card>

  <Card title="Cache respostas" icon="database">
    Cache respostas quando possível para reduzir chamadas.
  </Card>
</CardGroup>