Carrega registos da blacklist — números que cancelaram a subscrição de mensagens (opt-out) ou que foram adicionados à blacklist por importação ou através da API.

## URL da API

O URL utilizado para enviar os pedidos HTTP:

```url
https://portal.bulkgate.com/api/1.0/black-list/load
```

> [!NOTE]
> Se o pedido não chegar ao destino, repita-o no [servidor de reserva](https://www.bulkgate.com/pt/documentacao/administracao-da-api/servidor-de-reserva/) `backup1.bulkgate.com`.

## Métodos HTTP suportados

- `POST` - `application/json`

```http
POST /api/1.0/black-list/load HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
```

> [!NOTE]
> A API tem uma quota de `20` pedidos por dia.

## Tabela de parâmetros

| NOME DO PARÂMETRO | VALOR | OBRIGATÓRIO | VALOR PREDEFINIDO |
|:------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------|:------------------------|:---------------|
| application_id    | [ID da aplicação](https://www.bulkgate.com/pt/documentacao/administracao-da-api/administracao-de-apis/) | **Sim** | - |
| application_token | [Token de autenticação da aplicação](https://www.bulkgate.com/pt/documentacao/administracao-da-api/tokens-de-api/) | **Sim** | - |
| from              | Seleciona registos **a partir de** uma data específica. Aceita o formato [unix timestamp](https://en.wikipedia.org/wiki/Unix_time) ou [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). | **Sim** | - |
| to                | Seleciona registos **até** uma data específica. Aceita o formato [unix timestamp](https://en.wikipedia.org/wiki/Unix_time) ou [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). | Não | `now` |
| campaign_id       | Seleciona apenas os registos de uma campanha específica | Não | - |
| wallet            | Seleciona apenas os registos de uma carteira específica | Não | Carteira predefinida |

> [!NOTE]
> O intervalo máximo entre `from` e `to` é de 30 dias.

## Exemplo de pedido

```http-json
POST /api/1.0/black-list/load HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json

{
  "application_id": 451,
  "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj",
  "campaign_id": "id-bulkgate-000001",
  "wallet": "bg1905014138000023",
  "from": "2018-05-14T18:30:00-01:00",
  "to": "2018-05-15T18:30:00-01:00"
}
```

## Resposta

**Em caso de sucesso:**

```json
{
    "data": [
        {
            "key": "198668",
            "id": "198668",
            "wallet": "bg1905014138000023",
            "phone_number": "420777777777",
            "country": "cz",
            "type": "black-list",
            "created": "2018-11-21T15:30:31+01:00",
            "modified": null,
            "source": "web",
            "source_key": null,
            "reason": "Não quero receber comunicações comerciais.",
            "campaign_id": "id-bulkgate-000001",
            "application_id": 451,
            "channel": null,
            "tag": null,
            "contact": null
        },
        {
            "key": "198667",
            "id": "198667",
            "wallet": "bg1905014138000023",
            "phone_number": "420777777778",
            "country": "cz",
            "type": "black-list",
            "created": "2018-11-21T15:30:35+01:00",
            "modified": null,
            "source": "import",
            "source_key": "import.csv",
            "reason": null,
            "campaign_id": null,
            "application_id": 451,
            "channel": null,
            "tag": null,
            "contact": null
        }
    ]
}
```

Em que:

- **key** e **id** são o identificador do registo (o mesmo valor)
- **phone_number** é o número em formato internacional
- **type** é `black-list` ou `opt-out`
- **created** e **modified** são as datas em que o registo foi criado e alterado pela última vez, em [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)
- **source** indica como o número entrou na blacklist — `web`, `import`, `api`, `manual` ou `auto`
- **source_key** é o identificador do grupo com o qual o número foi adicionado. Nos registos com `source` = `import`, contém o nome do ficheiro importado.
- **reason** é o motivo indicado quando o número foi colocado na blacklist

**Em caso de erro:**

```json
{
    "type": "invalid_wallet",
    "code": 400,
    "error": "Invalid wallet",
    "detail": null
}
```

```json
{
    "type": "invalid_input_parameters",
    "code": 400,
    "error": "Invalid input parameters",
    "detail": null
}
```

```json
{
    "type": "maximal_date_range_is_30_days",
    "code": 400,
    "error": "Maximal date range is 30 days",
    "detail": null
}
```

```json
{
    "type": "the_daily_quota_has_been_exceeded",
    "code": 400,
    "error": "The daily quota has been exceeded",
    "detail": null
}
```

Em que:

- **type** e **error** (descrição do erro) encontram-se na [tabela de tipos de erro](https://www.bulkgate.com/pt/documentacao/administracao-da-api/tipos-de-erro-api/)
- **code** é o código de erro HTTP
- **detail** contém informações adicionais sobre o erro

### Tipos de erro da Blacklist API

Para além dos [tipos gerais](https://www.bulkgate.com/pt/documentacao/administracao-da-api/tipos-de-erro-api/), a Blacklist API devolve os seus próprios:

| TIPO | QUANDO OCORRE |
|:----------------------------------|:-----------------------------------------------------------------|
| `invalid_wallet`                  | A carteira indicada não existe ou não tem acesso a ela. |
| `invalid_input_parameters`        | `from` está em falta, tem um formato inválido ou não é anterior a `to`. |
| `maximal_date_range_is_30_days`   | O intervalo entre `from` e `to` é superior a 30 dias. |
| `the_daily_quota_has_been_exceeded`| A quota de pedidos está esgotada. |