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
- Twoja aplikacja wysyła żądanie HTTP POST do SMSIK API
- SMSIK weryfikuje klucz API, sprawdza saldo i limity
- SMSIK przekazuje SMS do operatora (Orange, Play, Plus, T-Mobile)
- Operator dostarcza SMS do telefonu klienta
- SMSIK zwraca status dostarczenia (webhook lub polling)
Kiedy używać SMS API, a kiedy panelu WWW?
| Scenariusz | Rekomendacja |
|---|---|
| Pojedyncze SMS-y, kilka dziennie | Panel 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, sklepem | SMS 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:
- Wejdź w Developer → Nowy klucz
- Wpisz nazwę (np. „produkcja", „testy")
- Opcjonalnie ustaw limity: dzienny (np. 1000 SMS) i miesięczny (np. 10000 SMS)
- 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.
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,failedprice_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):
| Pole | Typ | Wymagane | Opis |
|---|---|---|---|
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:
| Kodowanie | 1 część | Kolejne części |
|---|---|---|
| GSM-7 (bez polskich znaków) | 160 znaków | 153 znaki |
| UCS-2 (polskie znaki, emoji) | 70 znaków | 67 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:
+48XXXXXXXXXlubXXXXXXXXX(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?
- Wysyłasz żądanie z
idempotency_key: "order-1234-confirmation" - SMSIK sprawdza, czy istnieje SMS z tym kluczem
- Jeśli nie istnieje — tworzy nowy SMS, zapisuje klucz
- 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:
| Status | Kiedy | Co robić |
|---|---|---|
queued | SMS przekazany do bramki | Czekaj na dalsze statusy |
sent | Bramka przekazała SMS do operatora | Czekaj na DLR |
delivered | Operator potwierdził dostarczenie | Sukces — SMS dotarł |
failed | Błąd (brak zasięgu, filtr antyspamowy) | Sprawdź error_message |
scheduled | SMS 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)
| Event | Kiedy |
|---|---|
sms.sent | SMS wysłany przez urządzenie |
sms.delivered | SMS dostarczony do odbiorcy |
sms.failed | SMS nieudany |
sms.scheduled | SMS zaplanowany |
sms.received | Klient odpowiedział SMS-em (inbound) |
campaign.finished | Kampania zakończona |
balance.low | Saldo 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
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(wymagabodyParser.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óba | Opóźnienie |
|---|---|
| 1 (natychmiast) | 0s |
| 2 | 30 sekund |
| 3 | 2 minuty |
| 4 | 10 minut |
| 5 | 1 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
| HTTP | Znaczenie | Retry? | Co robić |
|---|---|---|---|
400 | Błąd walidacji | ❌ | Sprawdź detail — zły numer, treść, data |
401 | Brak/nieprawidłowy klucz API | ❌ | Sprawdź klucz w panelu |
402 | Za mało środków na koncie | ❌ | Doładuj konto |
403 | Konto nieaktywne lub usunięte | ❌ | Skontaktuj się z supportem |
404 | Zasób nie istnieje | ❌ | Sprawdź URL |
422 | Nieprawidłowe parametry (Pydantic) | ❌ | Sprawdź typy pól |
429 | Przekroczony limit (rate limit lub limit klucza) | ✅ | Poczekaj Retry-After lub backoff |
500 | Błąd serwera SMSIK | ✅ | Retry z backoffem (3 próby, 1s, 2s, 4s) |
502 | Bramka SMS niedostępna | ✅ | Retry z backoffem (3 próby, 5s, 15s, 45s) |
503 | Serwis 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
.envdo.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:
- Utwórz nowy klucz w panelu
- Wdróż nowy klucz w aplikacji
- Poczekaj, aż stary klucz przestanie być używany (monitoruj
last_used_at) - 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ę:
- Wyślij SMS na swój numer — sprawdź, czy dociera
- Sprawdź status dostarczenia — czy DLR działa
- Przetestuj obsługę błędów — nieprawidłowy numer, brak klucza
- Przetestuj idempotencję — wyślij to samo żądanie dwa razy, sprawdź, czy jest jeden SMS
- 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ąć:
- Zarejestruj się na smsik.pl
- Aktywuj developer i wygeneruj klucz API
- Wyślij pierwszy SMS przez cURL / Python / PHP / Node
- Dodaj idempotencję (jeśli wysyłasz transakcyjne)
- Skonfiguruj webhooks (dla statusów w czasie rzeczywistym)
- Obsłuż błędy (retry z backoffem)
- Zabezpiecz klucz (zmienne środowiskowe, rotacja)
- Przetestuj (testy jednostkowe + testy na małą skalę)
- 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.