Pirátská SMS brána

Kdo by to byl tušil, že si Piráti budou navzájem účtovat SMSky.

Instalace

Ne všechny závislosti jsou na Hackage, takže prozatím je potřeba vytvořit cabal.project:

packages: .

source-repository-package
    type: git
    location: https://github.com/mordae/hs-praha
    tag: master
    subdir: praha

source-repository-package
    type: git
    location: https://github.com/mordae/hs-praha
    tag: master
    subdir: praha-logger

source-repository-package
    type: git
    location: https://github.com/mordae/hs-praha
    tag: master
    subdir: praha-config

source-repository-package
    type: git
    location: https://github.com/mordae/hs-praha
    tag: master
    subdir: praha-migrate

source-repository-package
    type: git
    location: https://github.com/mordae/hs-aweg
    tag: master

source-repository-package
    type: git
    location: https://github.com/mordae/hikaru
    tag: master

Následně je možné projekt standardně sestavit:

cabal build

Pro sestavení a spuštění z lokálního adresáře:

cabal run pelican -- --help

V souboru pelican.env jsou přednastavené některé povinné proměnné prostředí. Je však zapotřebí dodefinovat ještě SMS_LOGIN a SMS_PASSWORD. Například skrze další konfigurační soubor:

cabal run pelican -- -C pelican.env -C prod.env

Případně přímo v prostředí:

export SMS_LOGIN='john'
export SMS_PASSWORD='wayne'
cabal run pelican -- -C pelican.env

Při lokálním testování s ostrým účtem od brány doporučuji zakázat potvrzování zpráv nastavením proměnné NOACK=1, jinak vaše lokální instance potvrdí příjem doručenek z produkce, což je nežádoucí.

Balíček je také možné nainstalovat:

cabal install

Technické detaily

SMS brána v tuto chvíli vystavuje následující služby:

API

Odeslání SMS zprávy na číslo

POST /v1/send/to-number HTTP/1.1
Content-Type: application/json

{
    "application": "přidělené <appid>",
    "token": "přidělený přístupový <token>",
    "number": "+420123456789",
    "payload": "Váš PIN je $$. Piráti",
    "interpolate": ["1234"],
    "receipt": "volitelné <uuid> pro kontrolu doručení",
    "centre": "volitelný <název> nákladového střediska"
}

HTTP/1.1 202 Accepted
Content-Type: text/plain; charset=utf8

V případě zaslání pole interpolate dojde k nahrazení skupin $$ v poli payload odpovídajícími prvky z pole interpolate. Hodnoty z pole interpolate se po odeslání zprávy neuchovávají. Tato funkce slouží k předávání citlivých údajů.

V historii zpráv tak v příkladu výše zůstane pouze text "Váš PIN je $$. Piráti".

• V případě úspěchu je kód odpovědi 202 a tělo je prázdné.
• V případě chyby je kód odpovědi z řad 400 nebo 500 a tělo obsahuje vysvětlení. U chyb na straně klienta (400) je tělo zpravidla typu text/plain a obsahuje krátký popis problému.

Odeslání SMS zprávy kontaktu

POST /v1/send/to-contact HTTP/1.1
Content-Type: application/json

{
    "application": "přidělené <appid>",
    "token": "přidělený přístupový <token>",
    "contact": "<název> kontaktu",
    "payload": "Váš PIN je $$. Piráti",
    "interpolate": ["1234"],
    "receipt": "volitelné <uuid> pro kontrolu doručení",
    "centre": "volitelný <název> nákladového střediska",
    "billing": "bill-sender|bill-recipient"
}

HTTP/1.1 202 Accepted
Content-Type: text/plain; charset=utf8

Funguje obdobně jako /v1/send/to-number s následujícími rozdíly:

• Namísto číslo příjemce se použije název kontaktu. Například uid:jan.hamal.dvorak, forum:410 nebo sso:b503b712-9f7c-4479-a1dd-e7b6447dc2cb. Záleží jaké kontakty jsou v DB definovány.
• Je nutné uvést pole billing; hodnota bill-sender účtuje zprávu na vrub nákladového střediska uvedeného v poli centre (které je možné vynechat pro výchozí účtování na vrub aplikace); naopak bill-recipient účtuje zprávu na vrub nákladového střediska příjemce.

Kontrola doručenky

GET /v1/receipt/<uuid> HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "pending|accepted|rejected|delivered|failed",
    "reason": "zdůvodnění nebo null",
    "ts": "2021-05-17T00:03:48.799695Z",
    "updated": "2021-05-17T00:03:00Z"
}

Pole ts obsahuje čas zanesení zprávy do systému na naší straně. Pole updated pak obsahuje čas poslední informace o zprávě od SMS brány.

Význam stavů:

• pending -- zatím nebyla předána SMS bráně
• accepted -- přijata bránou
• rejected -- odmítnuta bránou
• delivered -- úspěšně doručena
• failed -- nepodařilo se doručit nebo problém na straně brány

Stav vždy začíná jako pending a končí jako rejected, delivered nebo failed. Vy výjimečných případech může dojít k tomu, že se stav z accepted změní na rejected a nelze vyloučit ani změnu ze stavu delivered na jiný.

Hromadná kontrola doručenek

GET /v1/receipts?since=2021-05-17T00:00:00Z HTTP/1.1
Authorization: Basic <base64(<appid>:<token>)>

HTTP/1.1 200 OK
Content-Type: application/json

[
    {...},
    {...},
    {...}
]

Pro hromadnou kontrolu doručenek je potřeba zadat přihlašovací údaje formou Basic Authentication. Výsledkem je pole doručenek. Jejich výpis je možné omezit pomocí parametru since v URL, který musí být platným ISO 8601 časem (včetně časového pásma nebo koncovky Z pro UTC).

Doporučený způsob využití je ptát se pravidelně s parametrem since nastaveným na čas poslední odeslané zprávy, která je na vaší straně ještě ve stavu pending nebo accepted.