Načíta záznamy z blacklistu — čísla, ktoré si odosielanie správ zakázali alebo boli do blacklistu vložené importom či cez API.

## API URL

Adresa URL používaná na odosielanie požiadaviek HTTP:

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

> [!NOTE]
> Ak sa požiadavka nedostane k cieľu, zopakujte ju na [záložnom serveri](https://www.bulkgate.com/sk/dokumentacia/api-administracia-a-tokeny/zalozny-server/) `backup1.bulkgate.com`.

## Podporované HTTP metódy

- `POST` - `application/json`

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

> [!NOTE]
> API má nastavenú kvótu `20` požiadaviek za deň.

## Tabuľka s parametrami

| NÁZOV PARAMETRA   | HODNOTA                                                                                                                                                                                 | POVINNÝ                    | PREDVOLENÁ HODNOTA |
|:------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------------------|:----------------|
| application_id    | [Aplikačný identifikátor](https://www.bulkgate.com/sk/dokumentacia/api-administracia-a-tokeny/administracia-api/)                                                                                                                                  | **Áno**                    | -               | 
| application_token | [Aplikačný overovací token](https://www.bulkgate.com/sk/dokumentacia/api-administracia-a-tokeny/api-tokeny/)	                                                                                                                                       | **Áno**                    | -               |
| from              | Vyberie záznamy **od** konkrétneho dátumu. Prijíma formát [unix timestamp](https://en.wikipedia.org/wiki/Unix_time) alebo [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).            | **Áno**                    | -               |
| to                | Vyberie záznamy **do** konkrétneho dátumu. Prijíma formát [unix timestamp](https://en.wikipedia.org/wiki/Unix_time) alebo [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).	          | Nie                        | `now`           |
| campaign_id       | Vyberie len záznamy konkrétnej kampane                                                                                                                                                  | Nie                        | -               |
| wallet            | Vyberie len záznamy konkrétnej peňaženky                                                                                                                                                | Nie                        | Predvolená peňaženka |

> [!NOTE]
> Maximálny rozsah medzi `from` a `to` je 30 dní.

## Príklad požiadavky

```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"
}
```

## Odpoveď

**V prípade úspechu:**

```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": "Nechcem dostávať obchodné oznámenia.",
            "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
        }
    ]
}
```

Kde:

- **key** a **id** sú identifikátor záznamu (zhodná hodnota)
- **phone_number** je číslo v medzinárodnom formáte
- **type** je `black-list`, alebo `opt-out`
- **created** a **modified** sú časy vytvorenia a poslednej zmeny záznamu v [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)
- **source** je spôsob, akým sa číslo do blacklistu dostalo — `web`, `import`, `api`, `manual`, alebo `auto`
- **source_key** je identifikátor skupiny, s ktorou bolo číslo vložené. Pri záznamoch so `source` = `import` obsahuje názov importovaného súboru.
- **reason** je dôvod uvedený pri zaradení čísla do blacklistu

**V prípade chyby:**

```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
}
```

Kde:

- **type** a **error** (popis chyby) nájdete v [tabuľke typov chýb](https://www.bulkgate.com/sk/dokumentacia/api-administracia-a-tokeny/typy-chyb-api/)
- **code** je HTTP kód chyby
- **detail** je doplňujúca informácia o chybe

### Typy chýb Blacklist API

Popri [všeobecných typoch](https://www.bulkgate.com/sk/dokumentacia/api-administracia-a-tokeny/typy-chyb-api/) vracia Blacklist API vlastné:

| TYP                               | KEDY NASTANE                                                     |
|:----------------------------------|:-----------------------------------------------------------------|
| `invalid_wallet`                  | Zadaná peňaženka neexistuje alebo k nej nemáte prístup.          |
| `invalid_input_parameters`        | Chýba `from`, má neplatný formát, alebo nie je starší ako `to`.  |
| `maximal_date_range_is_30_days`   | Rozsah medzi `from` a `to` je dlhší ako 30 dní.                  |
| `the_daily_quota_has_been_exceeded`| Vyčerpaná kvóta požiadaviek.                                    |