Oficiální PHP knihovna pro TopSMS: composer require topsms/topsms-php

Od dneška má TopSMS oficiální PHP knihovnu. Žádné ruční skládání cURL requestů — instalace přes Composer a odesíláte na tři řádky.

Instalace

composer require topsms/topsms-php

Zdrojáky a issues: github.com/topsms-ghb/topsms-php · MIT licence · žádné závislosti (jen ext-curl a ext-json) · PHP ≥ 7.4.

Odeslání SMS

use TopSms\TopSmsClient;
use TopSms\TopSmsException;

$client = new TopSmsClient('VAS_CLIENT_ID', 'VAS_SECRET');

try {
    $result = $client->send('+420601234567', 'Vase objednavka #1024 je na ceste.', 'MojeFirma');
    echo "Odesláno, ID: {$result['id']}, cena: {$result['price']} Kč";
} catch (TopSmsException $e) {
    echo "Chyba ({$e->getHttpCode()}): {$e->getMessage()}";
}

Client ID a Secret vygenerujete v dashboardu v sekci API přístup. Výjimka nese HTTP kód (402 = nedostatečný kredit, 400 = neplatné číslo…) i surovou odpověď serveru.

Stav doručení a kredit

$status = $client->status($result['id']);
echo $status['status']; // sent | delivered | failed | expired

$credit = $client->credit();
echo "Zůstatek: {$credit['credit']} Kč";

Endpoint credit() se hodí pro automatické hlídání — např. upozornění ve vašem systému, když zůstatek klesne pod týdenní spotřebu.

Webhooky bez práce navíc

K webhookům pro doručenky (HTTP POST na vaši URL při doručení či selhání) má knihovna vestavěné ověření podpisu:

$raw = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_TOPSMS_SIGNATURE'] ?? '';

if (!TopSmsClient::verifyWebhookSignature($raw, $signature, 'VAS_WEBHOOK_SECRET')) {
    http_response_code(401);
    exit;
}

$event = json_decode($raw, true);
// $event['status'] => delivered | failed | expired

Webhook secret najdete v dashboardu u API klíče (tlačítko „⎘ secret").

Nepíšete v PHP?

REST API je jednoduché v jakémkoli jazyce — dokumentace obsahuje funkční příklady v curl, Pythonu a Node.js a k dispozici je i OpenAPI specifikace pro import do Postman/Insomnia nebo vygenerování klienta. Ozvěte se, který jazyk by vám pomohl příště.

Ještě nemáte účet? Registrace je zdarma, účet je aktivní okamžitě a 10 SMS na testování dostanete v ceně — první $client->send() můžete mít funkční do pěti minut.