## Čo na vašu adresu chodí

BulkGate hlási späť dve veci: ako dopadli vaše odoslané správy a čo vám ľudia
odpovedali. Oboje dorazí ako HTTP požiadavka na adresu, ktorú máte nastavenú.

| Čo dorazí | Ako to spoznáte |
|:--|:--|
| Potvrdenie o doručení | Parameter `status` s kódom stavu a `smsID` odoslanej správy |
| Prichádzajúca SMS alebo odpoveď | Parameter `status` s hodnotou `10`, odosielateľ v `from` a text v `message` |

Požiadavka chodí metódou HTTP **GET** — hodnoty teda nájdete v query stringu.

> [!TIP]
> Pri veľkých objemoch sa oplatí hromadná varianta: namiesto požiadavky na každú
> správu dorazí jedna požiadavka metódou POST s poľom záznamov vo formáte JSON.
> Popisuje ju [Hromadné potvrdenie o doručení](https://www.bulkgate.com/sk/dokumentacia/api-administracia-a-tokeny/api-hromadne-potvrdenie-o-doruceni-a-prichadzajucich-spravach/).

## Kde sa adresa nastavuje

Adresu si nastavíte sami v detaile svojej aplikácie — na karte `Nastavenie` v časti
`Web hooky` pri dlaždici `Potvrdenie o doručení`. Do poľa `URL pre doručenky`
v okne, ktoré sa otvorí, patrí adresa začínajúca `http://` alebo `https://`.

![Okno nastavenia potvrdenia o doručení s vypnutým hromadným zasielaním](docs:api-delivery-confirmations-and-incoming-sms/webhook-single_cs)

> [!IMPORTANT]
> Začiarkavacie políčko `Zasielať doručenky hromadne` nechajte vypnuté — s ním sa spôsob
> doručenia zmení na dávky metódou POST a platí
> [Hromadné potvrdenie o doručení](https://www.bulkgate.com/sk/dokumentacia/api-administracia-a-tokeny/api-hromadne-potvrdenie-o-doruceni-a-prichadzajucich-spravach/).

Celý postup vrátane ostatných volieb popisuje stránka
[Webhooky](https://www.bulkgate.com/sk/dokumentacia/api-administracia-a-tokeny/webhooky/).

## Parametre potvrdenia o doručení

| Parameter | Hodnota |
|:--|:--|
| `status` | Kód stavu správy — pozrite [stavy doručenia](#stavy-dorucenia) |
| `smsID` | Jednoznačné ID správy |
| `price` | Cena správy v kreditoch |
| `channel` | Kanál, ktorým správa išla (`sms`, `viber`, `whatsapp`, `rcs` a ďalšie) |
| `date` | Čas odoslania a doručenia oddelený bodkočiarkou v časovom pásme CET |

Hodnota `date` má tvar `RRMMDDHHMM;RRMMDDHHMM` — napríklad
`1812141317;1812141318` znamená odoslané 14. 12. 2018 o 13:17 a doručené
o minútu neskôr.

## Parametre prichádzajúcej správy

Keď má `status` hodnotu `10`, nejde o doručenku, ale o správu od príjemcu.
Dorazí s inou sadou parametrov:

| Parameter | Hodnota |
|:--|:--|
| `status` | Vždy `10` |
| `from` | Telefónne číslo odosielateľa |
| `to` | Telefónne číslo príjemcu, teda vaše číslo |
| `message` | Text správy v kódovaní UTF-8 |
| `channel` | Kanál, ktorým správa prišla |
| `smsdetails` | Podrobnosti vrátane použitého protokolu a času prijatia |

## Stavy doručenia

| Kód | Význam |
|:--|:--|
| `1` | Správa bola doručená |
| `2` | Správa čaká vo fronte na strane operátora — príjemca je momentálne nedostupný a doručenie sa skúsi znova |
| `3` | Správu sa nepodarilo doručiť — príjemca je neznámy alebo trvalo nedostupný |
| `10` | Prichádzajúca správa alebo odpoveď, nie doručenka |
| `13` | Správa bola prečítaná (len Viber) |

> [!NOTE]
> Stav `2` nie je konečný — na tú istú správu vám neskôr dorazí ďalšia požiadavka
> s výsledným stavom. Počítajte s tým, že `smsID` uvidíte viackrát.

## Ukážka spracovania

Skript rozlíši doručenku od prichádzajúcej správy podľa `status` a oboje zapíše do
vlastného logu:

```php
<?php declare(strict_types=1);

const STATUS = [
    1 => 'doručené',
    2 => 'čaká u operátora',
    3 => 'nedoručené',
    13 => 'prečítané',
];

$status = filter_input(INPUT_GET, 'status', FILTER_VALIDATE_INT);

function log_line(string $file, string $message): void
{
    file_put_contents(
        __DIR__ . "/$file.log",
        '[' . date('Y-m-d H:i:s') . '] ' . $message . PHP_EOL,
        FILE_APPEND
    );
}

if ($status === 10) // prichádzajúca správa
{
    $from = filter_input(INPUT_GET, 'from') ?? '';
    $message = filter_input(INPUT_GET, 'message') ?? '';

    log_line('inbox', sprintf('Od: [%s] Správa: [%s]', $from, $message));
}
else if (isset(STATUS[$status])) // potvrdenie o doručení
{
    $sms_id = filter_input(INPUT_GET, 'smsID') ?? '';
    $price = filter_input(INPUT_GET, 'price', FILTER_VALIDATE_FLOAT) ?: 0.0;

    log_line('delivery', sprintf('Správa [%s]: %s, cena %.4f', $sms_id, STATUS[$status], $price));
}
else
{
    http_response_code(400);
    exit;
}
```

> [!WARNING]
> Adresa musí odpovedať rýchlo a stavovým kódom `200`. Pomalé alebo chybujúce
> spracovanie zdržiava doručovanie ďalších hlásení — náročnú prácu preto odložte
> do fronty a požiadavku rovno potvrďte.