> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.callix.dev.br/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.callix.dev.br/_mcp/server.

# Usando a API para bloquear números

Para bloquear números usando a API é preciso utilizar a interface do sistema para gerar um\
[token de acesso](/introducao/visao-geral#autenticação) da API.

Cumprindo esse requisito, siga os passos descritos abaixo:

## 1. Criar lista de bloqueio

> **Note**
>
> Caso já tenha criado uma lista de bloqueio pela interface ou até mesmo pela
> API e já tenha um ID de lista de bloqueio, siga para o próximo passo.

A lista de bloqueio agrupa números que não devem ser discados pela campanha. E pode ser criada tanto pela interface quanto pela API.

#### Exemplo de chamada:

```bash
curl -X POST "https://sua-conta.callix.com.br/api/v1/outbound_blacklists" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
  "data": {
    "type": "outbound_blacklists",
    "attributes": {
      "name": "Lista de bloqueios de discagem 1"
    }
  }
}'
```

#### Exemplo de resposta:

```json
{
  "data": {
    "id": 1,
    "type": "outbound_blacklists",
    "attributes": {
      "name": "Lista de bloqueios de discagem 1"
    }
  }
}
```

No exemplo acima, é criada uma lista de nome `Lista de bloqueios de discagem 1`. No retorno temos o **ID 1**, atribuído para a lista recém criada e que vamos
utilizar para adicionar números.

## 2. Adicionar números a lista de bloqueio

Essa chamada adiciona um ou mais números a uma lista de bloqueio específica. **O processamento dessa chamada é feito de forma assíncrona.**

#### Exemplo de chamada:

```bash
curl -X POST "https://sua-conta.callix.com.br/api/v1/outbound_blacklist_async" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
  "data": {
    "type": "outbound_blacklist_async",
    "attributes": {
      "import_data": [
        {
          "phone_number": "(15)98765-4321",
          "event": "bloqueado"
        }
      ]
    },
    "relationships": {
      "outbound_blacklist": {
        "data": {
          "type": "outbound_blacklists",
          "id": 1
        }
      }
    }
  }
}'
```

Na chamada, no atributo `import_data`, deve-se enviar os números a serem bloqueados juntamente do evento `'bloqueado'`.

#### Exemplo de resposta:

```json
{
  "data": {
    "id": 1,
    "type": "outbound_blacklist_async",
    "attributes": {
      "status": 1,
      "import_results": []
    }
  }
}
```

Como o processamento é feito de forma assíncrona, no retorno da chamada temos o status da importação e também um ID do
serviço de importação (job) que tratará a importação assíncrona:

Usando o ID (no exemplo, ID `1`), é possível consultar o progresso da importação.

> **Note**
>
> Solicitações de importação feitas pela API entram em uma fila de processamento
> e são feitas assim que possível dependendo da disponibilidade dos serviços de
> importação. Também é processado apenas uma solicitação por vez e por cliente.

## 3. Consultar progresso da importação de números bloqueados

Essa chamada retorna a situação da importação.
Para usá-la é necessário usar o ID do job de importação obtida no fim do passo 2 acima.

#### Exemplo de chamada:

```bash
curl -X GET "https://sua-conta.callix.com.br/api/v1/outbound_blacklist_async/:id" \
  -H "Authorization: Bearer SEU_TOKEN"
```

Como neste exemplo a lista de bloqueio consultada possui ID `1`, a rota chamada é a `https://sua-conta.callix.com.br/api/v1/outbound_blacklist_async/1`.

#### Exemplo de resposta:

```json
{
  "data": {
    "id": 1,
    "type": "outbound_blacklist_async",
    "attributes": {
      "status": 1,
      "import_results": []
    }
  }
}
```

O campo status pode assumir os seguintes valores:

| código | significado |
| ------ | ----------- |
| `1`    | Pendente    |
| `2`    | Executando  |
| `3`    | Completada  |
| `4`    | Falha       |