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 z planem Business lub Enterprise (API nie jest dostępne w planie Starter).
• Klucz API (API Key), wygenerujesz go w panelu klienta w sekcji Ustawienia → API → Wygeneruj klucz.
• Ś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 to ciąg 64 znaków alfanumerycznych. 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"]

W panelu klienta możesz w każdej chwili unieważnić istniejący klucz i wygenerować nowy. Po unieważnieniu stary klucz natychmiast przestaje działać.

Krok 2: Wysyłka pojedynczego SMS-a

Podstawowy endpoint do wysyłki SMS-a to POST /v1/sms. Oto przykład wywołania w curl:

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

Ten sam request w Pythonie z biblioteką requests:

import os
import requests

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

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

data = response.json()
message = data["data"]["messages"][0]
print(f"Status HTTP: {response.status_code}")
print(f"Message ID: {message['id']}")
print(f"Cost: {message['cost']} PLN")

Parametry żądania:

Odpowiedź (HTTP 200):

{
  "success": true,
  "data": {
    "count": 1,
    "messages": [
      {
        "id": "msg_7f3a2b1c9d4e",
        "to": "+48600123456",
        "status": "queued",
        "parts": 1,
        "cost": 0.15,
        "sent_at": "2026-03-20T10:00:00.000Z"
      }
    ]
  }
}

Krok 3: Wysyłka masowa (batch)

Aby wysłać tę samą wiadomość do wielu odbiorców lub spersonalizowane wiadomości w jednym żądaniu, użyj endpointu POST /v1/sms/bulk. Pierwszy wariant — ten sam tekst do wielu numerów:

curl -X POST https://api.przypominamy.com/v1/sms/bulk \
  -H "Authorization: Bearer $PRZYPOMINAMY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "MojaKlinika",
    "recipients": ["+48600111222", "+48600333444", "+48600555666"],
    "message": "Przypominamy o wizycie 20.03"
  }'

Drugi wariant — indywidualna treść per odbiorca (tablica messages):

curl -X POST https://api.przypominamy.com/v1/sms/bulk \
  -H "Authorization: Bearer $PRZYPOMINAMY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "MojaKlinika",
    "messages": [
      { "to": "+48600111222", "message": "Jan, wizyta 20.03 o 10:00." },
      { "to": "+48600333444", "message": "Anna, wizyta 20.03 o 11:30." },
      { "to": "+48600555666", "message": "Piotr, wizyta 20.03 o 14:00." }
    ]
  }'

Limity: do 10 000 odbiorców w wariancie z polem recipients i do 100 wiadomości w wariancie z tablicą messages. Dla większych wolumenów dziel wysyłkę na partie i wysyłaj sekwencyjnie z krótką przerwą między żądaniami.

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 w panelu klienta (Ustawienia → API → Callback URL). Po zapisaniu adresu wszystkie zdarzenia są kierowane na Twój endpoint bez żadnych dodatkowych wywołań API.

Przykładowy payload zdarzenia delivery_report wysyłany na skonfigurowany webhook:

{
  "event": "delivery_report",
  "message_id": "msg_7f3a2b1c9d4e",
  "to": "+48600123456",
  "status": "delivered",
  "sent_at": "2026-03-18T09:00:58.000Z",
  "done_at": "2026-03-18T09:01:23.000Z",
  "idx": "wizyta-4521"
}

Dla wiadomości przychodzących (odpowiedzi od odbiorców) wysyłany jest event incoming_sms z polami from, to i message. Dzięki temu możesz automatycznie przetwarzać odpowiedzi TAK/NIE i aktualizować status wizyty w CRM. Zalecamy, aby Twój endpoint odpowiadał kodem HTTP 200 w ciągu kilku sekund — 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, max_retries=3):
    """Wysyła SMS z automatycznym ponowieniem przy błędach serwera."""
    for attempt in range(max_retries):
        response = requests.post(
            "https://api.przypominamy.com/v1/sms",
            headers={
                "Authorization": f"Bearer {API_KEY}",
                "Content-Type": "application/json",
            },
            json=payload,
            timeout=10,
        )

        if response.status_code == 200:
            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) w zależności od planu:

• Business: 60 żądań/minutę, 10 000 wiadomości/dzień
• Enterprise: 300 żądań/minutę, 100 000 wiadomości/dzień

Oto praktyczne wskazówki dla stabilnej integracji produkcyjnej:

• Używaj endpointu bulk zamiast wysyłać wiadomości pojedynczo. Jedno żądanie /v1/sms/bulk z tysiącem odbiorców zużywa 1 request z limitu zamiast tysiąca.
• Przechowuj id wiadomości zwracane w data.messages[].id. Umożliwia to korelację ze statusami doręczenia otrzymywanymi przez webhooks i ułatwia debugowanie.
• Waliduj numery telefonów przed wysyłką. Użyj endpointu GET /v1/hlr?number=+48... do weryfikacji, czy numer jest aktywny (HLR lookup). Oszczędza to koszty wiadomości do nieistniejących numerów.
• Monitoruj saldo programowo. Endpoint GET /v1/balance zwraca aktualny stan konta. 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. Endpoint /v1/sms do pojedynczych wiadomości, /v1/sms/bulk do wysyłek masowych.
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 konta testowego do walidacji integracji, endpointu bulk do produkcji, 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.