Poradnik średni 30 min czytania

SMS API od zera dla developerów — kompletny przewodnik 2026

Tomasz Lewandowski — Lead Developer, SMSIK

Od rejestracji konta po pierwszą wdrożoną integrację. Klucz API, wysyłka, webhooks, idempotencja, obsługa błędów, bezpieczeństwo, testy. Wszystko, czego potrzebujesz, żeby zacząć.

1. Jak działa SMS API?

SMS API to interfejs programistyczny (REST), który pozwala wysyłać SMS-y z Twojej aplikacji bezpośrednio do bramki SMS. Zamiast klikać w panelu WWW, wysyłasz jedno żądanie HTTP — a bramka zajmuje się resztą.

Schemat działania

  1. Twoja aplikacja wysyła żądanie HTTP POST do SMSIK API
  2. SMSIK weryfikuje klucz API, sprawdza saldo i limity
  3. SMSIK przekazuje SMS do operatora (Orange, Play, Plus, T-Mobile)
  4. Operator dostarcza SMS do telefonu klienta
  5. SMSIK zwraca status dostarczenia (webhook lub polling)

Kiedy używać SMS API, a kiedy panelu WWW?

ScenariuszRekomendacja
Pojedyncze SMS-y, kilka dzienniePanel WWW
Kampanie masowe (100-5000 odbiorców)Panel WWW (kampanie)
Powiadomienia transakcyjne (zamówienia, wizyty)SMS API
Kody OTP (autoryzacja)SMS API
Integracja z CRM, ERP, sklepemSMS API
Automatyczne alerty (DevOps, monitoring)SMS API

Co będziesz potrzebować?

  • Konto SMSIK (rejestracja 2 minuty)
  • Klucz API (generowany w panelu)
  • Klient HTTP (curl, requests, axios, fetch — cokolwiek)
  • Środowisko testowe (5 groszy na start = 5 testowych SMS-ów)

2. Rejestracja i klucz API

Krok 1: Rejestracja

Wejdź na smsik.pl/auth/register i wypełnij formularz:

  • Numer telefonu (polski, 9 cyfr)
  • Hasło (min. 8 znaków)
  • Email (opcjonalny, ale zalecany)
  • Checkbox akceptacji regulaminu

Po rejestracji dostaniesz SMS z kodem weryfikacyjnym (8 znaków). Wpisz go na stronie weryfikacji.

Krok 2: Aktywacja funkcji deweloperskich

W panelu SMSIK przejdź do Developer (w menu). Jeśli funkcje deweloperskie są wyłączone, kliknij „Poproś o aktywację". Administrator aktywuje je w ciągu 24h.

Krok 3: Generowanie klucza API

Po aktywacji:

  1. Wejdź w Developer → Nowy klucz
  2. Wpisz nazwę (np. „produkcja", „testy")
  3. Opcjonalnie ustaw limity: dzienny (np. 1000 SMS) i miesięczny (np. 10000 SMS)
  4. Kliknij „Utwórz klucz"

Klucz zostanie wyświetlony tylko raz — skopiuj go od razu do bezpiecznego miejsca. Format:

sk_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789

Nowy klucz ma status „Oczekuje" — administrator musi go zaakceptować (do 24h). Do tego czasu żądania zwracają 401.

⚠️ Bezpieczeństwo: Nigdy nie umieszczaj klucza API w kodzie źródłowym ani w repozytorium Git. Używaj zmiennych środowiskowych: SMSIK_API_KEY=sk_live_...

3. Pierwsze żądanie — wysyłka SMS

Podstawowy endpoint to POST /api/v1/sms/send. Oto najprostszy przykład w cURL:

curl -X POST https://smsik.pl/api/v1/sms/send \
  -H "X-API-Key: sk_live_TWOJ_KLUCZ" \
  -H "Content-Type: application/json" \
  -d '{
    "to_number": "+48512017029",
    "message": "Test z SMSIK API"
  }'

Odpowiedź 200 OK:

{
  "id": 81231,
  "status": "queued",
  "to_number": "+48512017029",
  "price_grosze": 1,
  "scheduled_at": null,
  "expires_at": null
}

Co oznaczają pola:

  • id — unikalny identyfikator SMS-a w SMSIK (przydatny do śledzenia)
  • status — queued (wysłany do bramki), scheduled (zaplanowany), sent, delivered, failed
  • price_grosze — koszt SMS-a w groszach (1 gr = 1 część SMS)

Przykład w Pythonie

import os
import requests

def send_sms(to: str, message: str) -> dict:
    response = requests.post(
        "https://smsik.pl/api/v1/sms/send",
        headers={
            "X-API-Key": os.environ["SMSIK_API_KEY"],
            "Content-Type": "application/json",
        },
        json={"to_number": to, "message": message},
        timeout=30,
    )
    response.raise_for_status()
    return response.json()

result = send_sms("+48512017029", "Test z SMSIK API")
print(f"SMS ID: {result['id']}, status: {result['status']}")

Przykład w Node.js (natywny fetch)

const response = await fetch('https://smsik.pl/api/v1/sms/send', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.SMSIK_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    to_number: '+48512017029',
    message: 'Test z SMSIK API',
  }),
});

if (!response.ok) {
  throw new Error(`SMS API error: ${await response.text()}`);
}

const data = await response.json();
console.log(`SMS ID: ${data.id}, status: ${data.status}`);

Przykład w PHP (cURL)

<?php
$ch = curl_init('https://smsik.pl/api/v1/sms/send');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . getenv('SMSIK_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'to_number' => '+48512017029',
        'message' => 'Test z SMSIK API',
    ]),
    CURLOPT_TIMEOUT => 30,
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode !== 200) {
    throw new Exception('SMS API error: ' . $response);
}

$data = json_decode($response, true);
echo 'SMS ID: ' . $data['id'];

4. Parametry żądania

Endpoint POST /api/v1/sms/send przyjmuje następujące parametry (JSON body):

PoleTypWymaganeOpis
to_number string ✅ Numer w formacie E.164 (np. +48512017029). Tylko polskie numery komórkowe (9 cyfr, prefiksy 5-8).
message string ✅ Treść 1-1600 znaków. Max 3 części SMS.
scheduled_at ISO 8601 — Planowany czas wysyłki. Puste = natychmiast.
expires_at ISO 8601 — Data wygaśnięcia SMS-a. Po tym czasie bramka przestanie próbować wysyłać.
idempotency_key string (max 64) — Klucz idempotencji. Retry z tym samym kluczem zwraca istniejącego SMS-a.

Liczba części SMS

SMS jest dzielony na części zgodnie ze standardem GSM 03.40:

Kodowanie1 częśćKolejne części
GSM-7 (bez polskich znaków)160 znaków153 znaki
UCS-2 (polskie znaki, emoji)70 znaków67 znaków

Znaki rozszerzone GSM-7 (^ { } [ ] ~ \ | €) liczą się jako 2 znaki. Maksymalnie 3 części na wiadomość.

Walidacja numeru telefonu

SMSIK akceptuje tylko polskie standardowe numery komórkowe:

  • 9 cyfr
  • Prefiks 5, 6, 7 lub 8 (pierwsza cyfra)
  • Format: +48XXXXXXXXX lub XXXXXXXXX (bez +48)

Odrzucane:

  • Numery Premium SMS (krótkie kody 4-6 cyfr)
  • Numery specjalne (800, 801, 804, 806, 808, 700)
  • Numery zagraniczne (+49, +44 itd.)
  • Numery stacjonarne (prefiks 1-4)

5. Idempotencja

Idempotencja to mechanizm, który zapobiega wysłaniu dwóch SMS-ów w przypadku retry po timeout. Jeśli nie masz pewności, czy żądanie dotarło do serwera (np. timeout), wysyłasz je ponownie z tym samym idempotency_key — SMSIK nie utworzy duplikatu, zwróci istniejącego SMS-a.

Kiedy używać idempotencji?

  • Zawsze przy wysyłce transakcyjnej (zamówienia, płatności, OTP)
  • Przy każdym retry — jeśli ponawiasz żądanie, użyj tego samego klucza
  • Przy webhookach — SMSIK może wysłać webhook dwa razy, użyj klucza do deduplikacji

Jak działa?

  1. Wysyłasz żądanie z idempotency_key: "order-1234-confirmation"
  2. SMSIK sprawdza, czy istnieje SMS z tym kluczem
  3. Jeśli nie istnieje — tworzy nowy SMS, zapisuje klucz
  4. Jeśli istnieje — zwraca istniejącego SMS-a (nie tworzy duplikatu)

Przykład

curl -X POST https://smsik.pl/api/v1/sms/send \
  -H "X-API-Key: sk_live_TWOJ_KLUCZ" \
  -H "Content-Type: application/json" \
  -d '{
    "to_number": "+48512017029",
    "message": "Zamowienie #1234 przyjete",
    "idempotency_key": "order-1234-confirmation"
  }'

Retry z tym samym idempotency_key zwróci ten sam SMS (z tym samym id).

Dobre praktyki

  • Unikalny klucz per operacja — np. order-{id}-confirmation, payment-{id}-paid
  • Nie zmieniaj klucza przy retry — jeśli ponawiasz, użyj tego samego
  • Klucz max 64 znaki — krótkie, czytelne identyfikatory
  • Nie używaj tego samego klucza do różnych SMS-ów — każdy SMS musi mieć unikalny klucz

6. Statusy dostarczenia

Po wysłaniu SMS-a, SMSIK zwraca status queued (wysłany do bramki). Ale to nie koniec — SMS przechodzi przez kolejne statusy:

StatusKiedyCo robić
queuedSMS przekazany do bramkiCzekaj na dalsze statusy
sentBramka przekazała SMS do operatoraCzekaj na DLR
deliveredOperator potwierdził dostarczenieSukces — SMS dotarł
failedBłąd (brak zasięgu, filtr antyspamowy)Sprawdź error_message
scheduledSMS zaplanowany na przyszłośćPoczekaj na scheduled_at

Jak śledzić statusy?

Masz dwie opcje:

Opcja 1: Polling (prostsze, ale mniej efektywne)

Co jakiś czas odpytujesz endpoint GET /api/v1/sms/status:

curl "https://smsik.pl/api/v1/sms/status?page=1&page_size=20" \
  -H "X-API-Key: sk_live_TWOJ_KLUCZ"

Odpowiedź:

{
  "items": [
    {
      "id": 81231,
      "to_number": "+48512017029",
      "status": "delivered",
      "price_grosze": 1,
      "created_at": "2026-11-04T09:15:00+00:00"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 20
}

Zalety: prostota, działa bez webhooks.
Wady: opóźnienie (trzeba czekać na kolejny polling), obciążenie API.

Opcja 2: Webhooks (rekomendowane)

SMSIK wysyła żądanie HTTP do Twojego serwera, gdy tylko zmieni się status SMS-a. Bez pollowania, w czasie rzeczywistym.

Zalety: natychmiastowość, mniejsze obciążenie API.
Wady: wymaga publicznego endpointu HTTP.

7. Webhooks

Webhooks to powiadomienia HTTP wysyłane do Twojego serwera, gdy w SMSIK wydarzy się coś istotnego. Zamiast pollować API, Ty czekasz na żądanie.

Dostępne eventy (7)

EventKiedy
sms.sentSMS wysłany przez urządzenie
sms.deliveredSMS dostarczony do odbiorcy
sms.failedSMS nieudany
sms.scheduledSMS zaplanowany
sms.receivedKlient odpowiedział SMS-em (inbound)
campaign.finishedKampania zakończona
balance.lowSaldo poniżej progu

Format żądania webhooka

POST https://twoj-serwer.pl/webhook/sms
Content-Type: application/json
X-Webhook-Signature: sha256=2328b52e5832fab0ca0da19e3ef8206fcc605e8bfade67dd29071e377110f8db
X-Webhook-Event: sms.delivered

{
  "event": "sms.delivered",
  "timestamp": "2026-11-04T09:15:32.123456+00:00",
  "data": {
    "sms_id": 81231,
    "to_number": "+48512017029",
    "status": "delivered",
    "price_grosze": 1,
    "delivered_at": "2026-11-04T09:15:31+00:00"
  }
}

Weryfikacja HMAC — KRYTYCZNE

⚠️ Weryfikuj HMAC na SUROWYM body żądania, nie na sparsowanym JSON!

Wiele frameworków (Django, Flask, FastAPI, Laravel) domyślnie parsuje JSON i daje Ci już sparsowany słownik. Jeśli zrobisz hmac(secret, json.dumps(request.json)) — hash się NIE zgodzi, bo json.dumps doda spacje i może zmienić kolejność kluczy.

Prawidłowo — czytaj raw body:

  • Python FastAPI: await request.body()
  • Django: request.body
  • Flask: request.get_data()
  • PHP: file_get_contents('php://input')
  • Node Express: req.rawBody (wymaga bodyParser.json({ verify: ... }))

Przykład w Pythonie (FastAPI):

import hmac
import hashlib
import json
from fastapi import FastAPI, Request, HTTPException

app = FastAPI()
SECRET = "twoj_webhook_secret"

@app.post("/webhook/sms")
async def webhook(request: Request):
    raw = await request.body()
    signature = request.headers.get("X-Webhook-Signature", "")
    expected = "sha256=" + hmac.new(
        SECRET.encode(), raw, hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(expected, signature):
        raise HTTPException(401, "Invalid signature")

    data = json.loads(raw)
    print(f"Event: {data['event']}")
    return {"ok": True}

Przykład w PHP:

<?php
$raw = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $raw, getenv('SMSIK_WEBHOOK_SECRET'));

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit;
}

$data = json_decode($raw, true);

Retry i circuit breaker

Jeśli Twój serwer zwróci błąd (5xx, timeout, brak połączenia), SMSIK ponawia próbę z wykładniczym backoffem:

PróbaOpóźnienie
1 (natychmiast)0s
230 sekund
32 minuty
410 minut
51 godzina
6 (ostatnia)6 godzin

Po 10 nieudanych próbach pod rząd webhook zostaje automatycznie dezaktywowany (circuit breaker). Możesz go włączyć ręcznie w panelu po naprawie błędu.

8. Obsługa błędów

API zwraca standardowe kody HTTP. Ciało błędu to JSON z polem detail:

{
  "detail": "Nieprawidłowy numer telefonu"
}

Kody błędów

HTTPZnaczenieRetry?Co robić
400Błąd walidacji❌Sprawdź detail — zły numer, treść, data
401Brak/nieprawidłowy klucz API❌Sprawdź klucz w panelu
402Za mało środków na koncie❌Doładuj konto
403Konto nieaktywne lub usunięte❌Skontaktuj się z supportem
404Zasób nie istnieje❌Sprawdź URL
422Nieprawidłowe parametry (Pydantic)❌Sprawdź typy pól
429Przekroczony limit (rate limit lub limit klucza)✅Poczekaj Retry-After lub backoff
500Błąd serwera SMSIK✅Retry z backoffem (3 próby, 1s, 2s, 4s)
502Bramka SMS niedostępna✅Retry z backoffem (3 próby, 5s, 15s, 45s)
503Serwis tymczasowo niedostępny✅Retry z backoffem

Strategia retry (exponential backoff)

Dla błędów 429, 500, 502, 503 zalecamy ponawianie z wykładniczym backoffem i jitterem (losowe odchylenie, żeby uniknąć thundering herd):

import random
import time
import requests

def send_with_retry(url, headers, payload, max_attempts=4):
    for attempt in range(max_attempts):
        try:
            r = requests.post(url, headers=headers, json=payload, timeout=30)
            if r.status_code == 200:
                return r.json()
            if r.status_code in (429, 500, 502, 503):
                delay = (2 ** attempt) + random.uniform(0, 1)
                time.sleep(delay)
                continue
            raise Exception(f"API error: {r.text}")
        except requests.RequestException:
            if attempt == max_attempts - 1:
                raise
            time.sleep((2 ** attempt) + random.uniform(0, 1))
    raise Exception("Max retries exceeded")

Idempotencja przy retry — obowiązkowa

Jeśli ponawiasz żądanie POST /v1/sms/send, zawsze używaj tego samego idempotency_key. Dzięki temu nawet jeśli pierwsze żądanie dotarło do serwera (a Ty dostałeś timeout), retry nie utworzy duplikatu.

{
  "to_number": "+48512017029",
  "message": "Test",
  "idempotency_key": "order-1234-confirmation"
}

9. Bezpieczeństwo

Klucz API — najważniejsza rzecz

Klucz API to Twoje hasło do SMSIK. Jeśli wycieknie, ktoś może wysyłać SMS-y na Twój koszt. Zasady:

  • Nigdy nie umieszczaj klucza w kodzie źródłowym — używaj zmiennych środowiskowych
  • Nigdy nie commituj klucza do Git — dodaj .env do .gitignore
  • Nie loguj klucza — nawet w debug
  • Nie wysyłaj klucza w URL — tylko w nagłówku X-API-Key
  • Rotuj klucz co 90 dni — lub gdy podejrzewasz wyciek
  • Używaj różnych kluczy dla różnych środowisk — test, produkcja

Zmienne środowiskowe

W .env:

SMSIK_API_KEY=sk_live_TWOJ_KLUCZ

W kodzie:

import os
API_KEY = os.environ["SMSIK_API_KEY"]

Dodaj .env do .gitignore:

.env
.env.local
*.env

Rate limiting — po Twojej stronie

SMSIK ma rate limiting (limity techniczne na konto), ale Ty też powinieneś ograniczać wysyłkę:

  • Max 3 kody OTP na numer w 15 minut — ochrona przed botami
  • Max 100 SMS-ów na godzinę z jednego IP — jeśli masz formularz publiczny
  • Blokuj podejrzane IP — jeśli widzisz nietypowe wzorce
  • Monitoruj nietypowe wzorce wysyłki — nagłe skoki wolumenu

HTTPS — obowiązkowe

Wszystkie żądania do SMSIK API muszą iść przez HTTPS. SMSIK nie akceptuje HTTP. Upewnij się, że Twój klient HTTP weryfikuje certyfikat SSL (nie ustawiaj verify=False!).

Rotacja kluczy

Klucze można rotować bez przestoju:

  1. Utwórz nowy klucz w panelu
  2. Wdróż nowy klucz w aplikacji
  3. Poczekaj, aż stary klucz przestanie być używany (monitoruj last_used_at)
  4. Usuń stary klucz

SMSIK nie ogranicza liczby kluczy na konto, więc trzymanie dwóch równolegle jest bezpieczne.

Webhooks — weryfikacja HMAC

Zawsze weryfikuj podpis HMAC webhooka (patrz rozdział 7). Bez tego ktoś może wysłać fałszywe żądanie do Twojego endpointu.

SSRF — jeśli tworzysz webhooki przez API

Jeśli Twoja aplikacja pozwala użytkownikom tworzyć webhooki (np. w SaaS), musisz chronić przed atakami SSRF (Server-Side Request Forgery). SMSIK robi to automatycznie (blokuje prywatne IP, loopback, metadata cloud), ale jeśli tworzysz własne webhooki — też powinieneś.

10. Testy i wdrożenie

Krok 1: Test na małą skalę

Zanim wdrożysz integrację na produkcję, przetestuj ją na małą skalę:

  1. Wyślij SMS na swój numer — sprawdź, czy dociera
  2. Sprawdź status dostarczenia — czy DLR działa
  3. Przetestuj obsługę błędów — nieprawidłowy numer, brak klucza
  4. Przetestuj idempotencję — wyślij to samo żądanie dwa razy, sprawdź, czy jest jeden SMS
  5. Przetestuj rate limiting — wyślij serię żądań, sprawdź 429

Krok 2: Testy jednostkowe

W testach jednostkowych nie wysyłaj prawdziwych SMS-ów — mockuj HTTP. Przykład w Pythonie (pytest + responses):

import pytest
import responses
from myapp.sms import send_sms

@responses.activate
def test_send_sms_success():
    responses.add(
        responses.POST,
        "https://smsik.pl/api/v1/sms/send",
        json={"id": 123, "status": "queued", "to_number": "+48512017029", "price_grosze": 1},
        status=200,
    )

    result = send_sms("+48512017029", "Test")
    assert result["id"] == 123
    assert result["status"] == "queued"

@responses.activate
def test_send_sms_insufficient_balance():
    responses.add(
        responses.POST,
        "https://smsik.pl/api/v1/sms/send",
        json={"detail": "Za mało środków"},
        status=402,
    )

    with pytest.raises(Exception, match="402"):
        send_sms("+48512017029", "Test")

Krok 3: Monitoring

Po wdrożeniu monitoruj:

  • Delivery rate — procent SMS-ów dostarczonych (cel: > 95%)
  • Error rate — procent błędów (cel: < 1%)
  • Latency — czas odpowiedzi API (cel: < 1s)
  • Webhook delivery rate — procent dostarczonych webhooków (cel: > 99%)
  • Balance — saldo konta (alert, gdy < 10 zł)

Krok 4: Alerty

Ustaw alerty:

  • Email — gdy delivery rate spadnie poniżej 90%
  • Slack / Teams — gdy error rate przekroczy 5%
  • SMS do admina — gdy saldo spadnie poniżej 10 zł
  • PagerDuty / Opsgenie — gdy API nie odpowiada przez 5 minut

Krok 5: Dokumentacja

Udokumentuj integrację dla swojego zespołu:

  • Kto zarządza kluczem API — i jak go rotować
  • Jak debugować — gdzie są logi, jak sprawdzić status
  • Jakie są limity — ile SMS-ów dziennie, jaki rate limit
  • Co robić w razie awarii — plan działania

Podsumowanie

Masz wszystko, czego potrzebujesz, żeby zacząć:

  1. Zarejestruj się na smsik.pl
  2. Aktywuj developer i wygeneruj klucz API
  3. Wyślij pierwszy SMS przez cURL / Python / PHP / Node
  4. Dodaj idempotencję (jeśli wysyłasz transakcyjne)
  5. Skonfiguruj webhooks (dla statusów w czasie rzeczywistym)
  6. Obsłuż błędy (retry z backoffem)
  7. Zabezpiecz klucz (zmienne środowiskowe, rotacja)
  8. Przetestuj (testy jednostkowe + testy na małą skalę)
  9. Wdróż i monitoruj (delivery rate, error rate, saldo)

Zarejestruj się bezpłatnie — dostajesz 5 groszy na start (5 testowych SMS-ów). To wystarczy, żeby przetestować pierwszą integrację.

Masz pytania? Napisz na info@smsik.pl — pomożemy w integracji.

Wypróbuj SMSIK bezpłatnie

Rejestracja trwa 2 minuty. Otrzymasz 5 groszy na start (5 testowych SMS-ów). Bez karty kredytowej.