SMS API — integracja krok po kroku (PHP, Python, JavaScript)

SMS API to najprostszy sposób na wysyłanie SMS-ów z własnej aplikacji. W tym przewodniku pokazujemy krok po kroku, jak zintegrować SMSIK API z Twoim projektem — z przykładami w PHP, Python i JavaScript.

Krok 1: Rejestracja i klucz API

Zacznij od rejestracji konta w SMSIK:

1. Wejdź na smsik.pl/auth/register
2. Podaj numer telefonu i hasło
3. Potwierdź numer kodem SMS
4. Przejdź do Ustawienia i kliknij "SMS API"
5. Wygeneruj nowy klucz API

Klucz API to długi ciąg znaków, np. sk_live_abc123.... Nigdy nie udostępniaj go publicznie i nie umieszczaj w kodzie na GitHubie.

Krok 2: Podstawowa wysyłka SMS

Endpoint

POST https://api.smsik.pl/v1/sms/send

Nagłówki

X-API-Key: TWOJ_KLUCZ_API
Content-Type: application/json

Body (JSON)

{
  "to": "+48512017029",
  "message": "Testowa wiadomość z SMSIK API",
  "sender": "TWOJAFIRMA"
}

Odpowiedź (200 OK)

{
  "status": "queued",
  "id": 81231,
  "to": "+48512017029",
  "parts": 1,
  "price_grosze": 1
}

Krok 3: Integracja w PHP

<?php
function sendSms($toNumber, $message) {
    $apiKey = getenv('SMSIK_API_KEY');
    $url = 'https://api.smsik.pl/v1/sms/send';

    $payload = [
        'to' => $toNumber,
        'message' => $message,
        'sender' => 'TWOJAFIRMA',
    ];

    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'X-API-Key: ' . $apiKey,
        'Content-Type: application/json',
    ]);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

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

    return json_decode($response, true);
}

// Użycie:
$result = sendSms('+48512017029', 'Testowa wiadomość');
echo 'Wysłano SMS o ID: ' . $result['id'];

Krok 4: Integracja w Python

import os
import httpx

def send_sms(to_number: str, message: str) -> dict:
    api_key = os.getenv("SMSIK_API_KEY")
    url = "https://api.smsik.pl/v1/sms/send"

    response = httpx.post(
        url,
        headers={
            "X-API-Key": api_key,
            "Content-Type": "application/json",
        },
        json={
            "to": to_number,
            "message": message,
            "sender": "TWOJAFIRMA",
        },
        timeout=30.0,
    )

    if response.status_code != 200:
        raise Exception(f"SMS API error: {response.text}")

    return response.json()

# Użycie:
result = send_sms("+48512017029", "Testowa wiadomość")
print(f"Wysłano SMS o ID: {result['id']}")

Krok 5: Integracja w JavaScript (Node.js)

async function sendSms(toNumber, message) {
    const apiKey = process.env.SMSIK_API_KEY;
    const url = 'https://api.smsik.pl/v1/sms/send';

    const response = await fetch(url, {
        method: 'POST',
        headers: {
            'X-API-Key': apiKey,
            'Content-Type': 'application/json',
        },
        body: JSON.stringify({
            to: toNumber,
            message: message,
            sender: 'TWOJAFIRMA',
        }),
    });

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

    return response.json();
}

// Użycie:
const result = await sendSms('+48512017029', 'Testowa wiadomość');
console.log(`Wysłano SMS o ID: ${result.id}`);

Krok 6: Obsługa błędów

SMSIK API zwraca standardowe kody HTTP:

Przykład retry w Python

import time
import httpx

def send_sms_with_retry(to_number: str, message: str, max_retries: int = 3):
    for attempt in range(max_retries):
        try:
            response = httpx.post(
                "https://api.smsik.pl/v1/sms/send",
                headers={"X-API-Key": os.getenv("SMSIK_API_KEY")},
                json={"to": to_number, "message": message},
                timeout=30.0,
            )

            if response.status_code == 200:
                return response.json()

            if response.status_code == 429:
                # Exponential backoff
                wait = 2 ** attempt
                time.sleep(wait)
                continue

            if response.status_code >= 500:
                wait = 2 ** attempt
                time.sleep(wait)
                continue

            # 400, 401 — nie ma sensu retry
            raise Exception(f"SMS API error: {response.text}")

        except httpx.RequestError as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)

    raise Exception("Max retries exceeded")

Krok 7: Idempotencja (bezpieczne retry)

Jeśli nie wiesz, czy żądanie dotarło do serwera (np. timeout), użyj idempotency_key:

{
  "to": "+48512017029",
  "message": "Test",
  "idempotency_key": "order-12345-confirmation"
}

Retry z tym samym kluczem zwróci istniejący SMS (nie utworzy duplikatu).

Krok 8: Statusy dostarczenia

Aby śledzić statusy SMS-ów, używaj endpointu /v1/sms/status:

GET /v1/sms/status?updated_since=2026-10-05T00:00:00Z&limit=100

Zwracane statusy:

• queued — SMS przekazany do bramki
• sent — SMS wysłany z bramki
• delivered — SMS dostarczony do klienta
• failed — błąd wysyłki

Polling vs Webhooks

Obecnie SMSIK oferuje polling. Webhooks są w planach.

Przykład pollingu w Python:

import httpx
from datetime import datetime, timedelta, timezone

def fetch_statuses(last_sync: str = None):
    if last_sync is None:
        # Pierwszy sync — ostatnie 24h
        since = (datetime.now(timezone.utc) - timedelta(hours=24)).isoformat()
    else:
        since = last_sync

    response = httpx.get(
        "https://api.smsik.pl/v1/sms/status",
        headers={"X-API-Key": os.getenv("SMSIK_API_KEY")},
        params={"updated_since": since, "limit": 1000},
        timeout=30.0,
    )

    data = response.json()
    return data["items"], data.get("server_time")

Krok 9: Bezpieczeństwo kluczy API

Nie umieszczaj klucza w kodzie

Zamiast:

API_KEY = "sk_live_abc123..."  # NIE!

Użyj zmiennych środowiskowych:

import os
API_KEY = os.getenv("SMSIK_API_KEY")

Użyj .env dla developmentu

# .env
SMSIK_API_KEY=sk_live_abc123...

I dodaj .env do .gitignore.

Rotacja kluczy

Zmieniaj klucze API co 90 dni lub gdy podejrzewasz wyciek. W SMSIK możesz mieć wiele kluczy jednocześnie (np. osobny dla produkcji i testów).

Krok 10: Testy

Zawsze testuj integrację przed produkcją:

1. Wyślij SMS na swój numer
2. Sprawdź status dostarczenia
3. Przetestuj obsługę błędów (nieprawidłowy numer, brak klucza)
4. Przetestuj rate limiting
5. Przetestuj idempotencję

Dobre praktyki

• Timeout — ustaw timeout 30 sekund
• Retry z backoff — nie bombarduj API przy błędach
• Idempotencja — używaj kluczy idempotencji
• Logi — loguj wszystkie wysyłki (ID SMS-a, timestamp)
• Monitoring — śledź delivery rate, error rate
• Rate limiting — nie przekraczaj limitów (1000/h, 10000/dzień)
• Bezpieczeństwo — nigdy nie loguj kluczy API

Podsumowanie

Integracja SMS API jest prosta:

1. Zarejestruj się i wygeneruj klucz API
2. Wyślij POST na /v1/sms/send
3. Obsłuż odpowiedź (200 = OK, inne = błąd)
4. Śledź statusy przez /v1/sms/status
5. Dodaj retry z backoff, idempotencję, monitoring

W SMSIK oferujemy REST API z pełną dokumentacją i wsparciem technicznym. Zobacz pełną dokumentację lub skontaktuj się z nami, aby omówić integrację.