Integracja API SMS z CRM. Od zera do wysyłki w 30 minut

Zespół Przypominamy.com · 5 marca 2026 · 6 min czytania

Ręczne logowanie do panelu i wysyłanie SMS-ów z poziomu przeglądarki sprawdza się przy małych wolumenach. Ale gdy Twój CRM, system rezerwacji lub platforma e-commerce obsługuje tysiące kontaktów, potrzebujesz automatyzacji przez API. W tym artykule przeprowadzimy Cię przez pełną integrację z REST API Przypominamy.com. Od uzyskania klucza API, przez wysyłkę pierwszego SMS-a, konfigurację webhooków, aż po obsługę błędów i najlepsze praktyki produkcyjne.

Wymagania wstępne

Zanim zaczniesz, upewnij się, że masz:

• Konto na Przypominamy.com (rejestracja na app.przypominamy.com/register; konto testowe z kluczem pk_test_… i 25 SMS-ami działa od razu, produkcyjne po doładowaniu od 50 zł).
• Klucz API w postaci pk_live_…, który dostajesz po weryfikacji. Pokazywany jest raz, zapisz go w menedżerze sekretów.
• Środowisko deweloperskie, dowolny język programowania z obsługą HTTP. W przykładach użyjemy curl (linia poleceń) i Python 3.8+.
• Doładowane konto, API działa w modelu prepaid. Upewnij się, że masz wystarczające środki na koncie przed pierwszą wysyłką.

Krok 1: Autoryzacja. Nagłówek API Key

API Przypominamy.com używa autoryzacji przez nagłówek HTTP. Każde żądanie musi zawierać nagłówek Authorization z tokenem Bearer:

Authorization: Bearer TWOJ_KLUCZ_API

Klucz API zaczyna się od pk_live_. Traktuj go jak hasło. Nie commituj do repozytorium, nie przesyłaj w URL-ach i nie udostępniaj osobom trzecim. Zalecamy przechowywanie klucza w zmiennych środowiskowych:

# Bash. Eksport zmiennej środowiskowej
export PRZYPOMINAMY_API_KEY="pk_live_abc123def456..."

# Python. Odczyt ze zmiennej środowiskowej
import os
api_key = os.environ["PRZYPOMINAMY_API_KEY"]

Klucz można w każdej chwili odwołać i wydać nowy (napisz na [email protected]). Po odwołaniu stary klucz natychmiast przestaje działać. Możesz mieć kilka kluczy naraz, np. osobne dla produkcji i testów.

Krok 2: Wysyłka pojedynczego SMS-a

Endpoint do wysyłki SMS-a to POST /v1/messages. Ten sam endpoint obsługuje jednego odbiorcę i wysyłkę masową. Przykład w curl:

curl -X POST https://api.przypominamy.com/v1/messages \
  -H "Authorization: Bearer $PRZYPOMINAMY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: wizyta-4521-przypomnienie" \
  -d '{
    "to": "+48600123456",
    "from": "MojaFirma",
    "text": "Przypominamy o wizycie jutro o 10:00. Pozdrawiamy!",
    "reference": "wizyta-4521"
  }'

Ten sam request w Pythonie z biblioteką requests:

import os
import requests

API_URL = "https://api.przypominamy.com/v1/messages"
API_KEY = os.environ["PRZYPOMINAMY_API_KEY"]

response = requests.post(
    API_URL,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
        "Idempotency-Key": "wizyta-4521-przypomnienie",
    },
    json={
        "to": "+48600123456",
        "from": "MojaFirma",
        "text": "Przypominamy o wizycie jutro o 10:00. Pozdrawiamy!",
        "reference": "wizyta-4521",
    },
    timeout=10,
)

message = response.json()
print(f"Status HTTP: {response.status_code}")
print(f"Message ID: {message['id']}")
print(f"Koszt: {message['cost_grosze'] / 100:.2f} PLN")

Parametry żądania:

Nagłówek Idempotency-Key jest opcjonalny, ale warto go podawać: jeśli Twój kod ponowi żądanie po timeoucie, API zwróci pierwotną odpowiedź zamiast wysłać SMS drugi raz.

Odpowiedź (HTTP 201):

{
  "id": "msg_7f3a2b1c9d4e",
  "status": "queued",
  "to": "+48600123456",
  "from": "MojaFirma",
  "text": "Przypominamy o wizycie jutro o 10:00. Pozdrawiamy!",
  "parts": 1,
  "cost_grosze": 15,
  "reference": "wizyta-4521",
  "send_at": null,
  "delivered_at": null,
  "error": null,
  "created_at": "2026-09-07T08:00:00.000Z",
  "updated_at": "2026-09-07T08:00:00.000Z"
}

Krok 3: Wysyłka masowa (batch)

Aby wysłać tę samą wiadomość do wielu odbiorców w jednym żądaniu, podaj w polu to tablicę numerów (do 500, duplikaty są usuwane):

curl -X POST https://api.przypominamy.com/v1/messages \
  -H "Authorization: Bearer $PRZYPOMINAMY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "MojaKlinika",
    "to": ["+48600111222", "+48600333444", "+48600555666"],
    "text": "Przypominamy o wizycie 20.09",
    "reference": "kampania-2026-09-20"
  }'

Odpowiedź zbiorcza zawiera koszt łączny i osobny rekord dla każdego odbiorcy:

{
  "count": 3,
  "accepted": 3,
  "total_cost_grosze": 45,
  "messages": [
    { "id": "msg_a1…", "status": "queued", "to": "+48600111222", "cost_grosze": 15, ... },
    { "id": "msg_b2…", "status": "queued", "to": "+48600333444", "cost_grosze": 15, ... },
    { "id": "msg_c3…", "status": "queued", "to": "+48600555666", "cost_grosze": 15, ... }
  ]
}

Spersonalizowane treści (imię, godzina wizyty) wysyłasz jako osobne żądania. Limit 120 żądań na minutę wystarcza na kilka tysięcy przypomnień na godzinę; dla większych wolumenów użyj kolejki i wysyłaj z respektowaniem nagłówka Retry-After.

Krok 4: Webhooks. Odbieranie statusów doręczenia

Webhooks pozwalają Twojemu systemowi CRM otrzymywać powiadomienia o zdarzeniach w czasie rzeczywistym - doręczeniu wiadomości, błędzie dostarczenia, odpowiedzi odbiorcy. Konfigurację wykonujesz raz, jednym wywołaniem:

curl -X PUT https://api.przypominamy.com/v1/account/webhook \
  -H "Authorization: Bearer $PRZYPOMINAMY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://twoj-crm.pl/webhooks/sms"}'

{ "webhook_url": "https://twoj-crm.pl/webhooks/sms",
  "webhook_secret": "whsec_…",
  "signature_header": "X-Przypominamy-Signature" }

Zapisz webhook_secret. Każde wywołanie webhooka jest podpisane nagłówkiem X-Przypominamy-Signature: t=<unix>,v1=<hex>, gdzie v1 = HMAC-SHA256(webhook_secret, "<t>.<body>"). Weryfikuj podpis i odrzucaj wywołania starsze niż 5 minut.

Przykładowy payload zdarzenia message.delivered wysyłany na skonfigurowany webhook:

{
  "id": "evt_8sK2mQ…",
  "type": "message.delivered",
  "created_at": "2026-09-18T09:01:25.000Z",
  "data": {
    "message": {
      "id": "msg_7f3a2b1c9d4e",
      "status": "delivered",
      "to": "+48600123456",
      "reference": "wizyta-4521",
      "delivered_at": "2026-09-18T09:01:23.000Z",
      ...
    }
  }
}

Typy zdarzeń: message.sent, message.delivered, message.undelivered, message.failed, message.expired. Pole data.message.reference to wartość, którą podałeś przy wysyłce - po niej odnajdziesz wizytę w CRM. Zalecamy, aby Twój endpoint odpowiadał kodem HTTP 2xx w ciągu kilku sekund; przy innym kodzie platforma ponawia dostarczenie (łącznie 3 próby). Dłuższe przetwarzanie wykonuj asynchronicznie.

Krok 5: Obsługa błędów i retry

API zwraca standardowe kody HTTP. Oto najważniejsze scenariusze błędów i sposoby ich obsługi:

Implementacja strategii retry w Pythonie z wykładniczym cofaniem (exponential backoff):

import time
import requests

def send_sms_with_retry(payload, idempotency_key, max_retries=3):
    """Wysyła SMS z automatycznym ponowieniem przy błędach serwera.
    Ten sam Idempotency-Key przy każdej próbie = brak podwójnej wysyłki."""
    for attempt in range(max_retries):
        response = requests.post(
            "https://api.przypominamy.com/v1/messages",
            headers={
                "Authorization": f"Bearer {API_KEY}",
                "Content-Type": "application/json",
                "Idempotency-Key": idempotency_key,
            },
            json=payload,
            timeout=10,
        )

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

        if response.status_code == 429:
            wait = int(response.headers.get("Retry-After", 5))
            time.sleep(wait)
            continue

        if response.status_code >= 500:
            wait = 2 ** attempt  # 1s, 2s, 4s
            time.sleep(wait)
            continue

        # Błędy 4xx (oprócz 429). Nie ponawiaj
        response.raise_for_status()

    raise Exception("Nie udało się wysłać SMS po 3 próbach")

Rate limits i najlepsze praktyki

API Przypominamy.com stosuje limity żądań (rate limits):

• Każde konto: 120 żądań/minutę; jedno żądanie może zawierać do 500 odbiorców
• Wyższe limity: na życzenie, ustalane indywidualnie (Enterprise)

Oto praktyczne wskazówki dla stabilnej integracji produkcyjnej:

• Używaj tablicy odbiorców zamiast wysyłać tę samą treść pojedynczo. Jedno żądanie z 500 numerami w polu to zużywa 1 request z limitu zamiast 500.
• Przechowuj id wiadomości (msg_…) i podawaj własne reference. Umożliwia to korelację ze statusami z webhooków i wyszukiwanie w GET /v1/messages?reference=….
• Waliduj numery telefonów po swojej stronie przed wysyłką (9 cyfr dla Polski, prefiks kraju dla zagranicy). API odrzuca numery o złym formacie z kodem 400 i polem error.param = "to".
• Monitoruj saldo programowo. Endpoint GET /v1/account zwraca balance_grosze. Skonfiguruj alert, gdy saldo spadnie poniżej progu (np. 100 zł), aby uniknąć przerwania wysyłek.
• Loguj wszystkie żądania i odpowiedzi po stronie swojego systemu. W razie problemów z doręczeniem logi umożliwią szybką diagnozę - czy problem leży po stronie Twojego kodu, API, czy operatora.
• Testuj z osobnym kontem roboczym przed wdrożeniem produkcyjnym. Utwórz konto testowe z własnym kluczem API i wysyłaj na własny numer, zanim podłączysz produkcję.

Integracja z popularnymi CRM-ami

Jeśli korzystasz z gotowego systemu CRM, integracja może być jeszcze prostsza dzięki natywnym wtyczkom i connectorom:

• Salesforce, pakiet na AppExchange, konfiguracja w 10 minut.
• HubSpot, integracja przez Workflows z natywnym action „Wyślij SMS".
• Pipedrive, webhook trigger przy zmianie etapu dealu + automatyczna wysyłka SMS.
• Zapier / Make (Integromat), gotowe moduły Przypominamy.com umożliwiające integrację z ponad 5 000 aplikacji bez pisania kodu.
• WooCommerce / PrestaShop / Magento, wtyczki do automatycznych powiadomień transakcyjnych i kampanii marketingowych.

Szczegółowe instrukcje instalacji dla każdego CRM znajdziesz w dokumentacji API.

Podsumowanie

Integracja API SMS z CRM to inwestycja jednego dnia pracy developera, która automatyzuje komunikację z klientami na lata. Kluczowe wnioski:

1. Autoryzacja przez Bearer token: prosty i bezpieczny mechanizm.
2. Jeden endpoint POST /v1/messages do pojedynczych wiadomości i wysyłek masowych (tablica to).
3. Webhooks dają Ci informacje o doręczeniu i odpowiedziach w czasie rzeczywistym.
4. Implementuj retry z exponential backoff dla błędów 429 i 5xx.
5. Używaj osobnego klucza do testów, nagłówka Idempotency-Key przy retry i monitoruj saldo programowo.

Cała dokumentacja API z interaktywnym exploratorem jest dostępna pod adresem przypominamy.com/api/docs. Jeśli potrzebujesz wsparcia przy integracji, napisz na [email protected], nasz zespół techniczny odpowiada w ciągu 2 godzin w dni robocze.