Szybki start: pierwsza pocztówka przez API

Utworzysz pocztówkę testową, sprawdzisz jej status, a potem przełączysz się na live. Pocztówki testowe są darmowe i nigdy nie są pisane ani wysyłane, więc każdy krok wykonasz bez ryzyka. Potrzebujesz: konta Paperjoy i terminala z curl.

Włącz tryb testowy

W panelu Paperjoy otwórz menu konta w prawym górnym rogu i włącz Tryb testowy.

Menu konta z przełącznikiem Tryb testowy.

Dopóki tryb testowy jest włączony, u góry każdej strony widać baner Tryb testowy.

Utwórz testowy klucz API

Otwórz Ustawienia → Klucze API, wpisz nazwę, np. szybki-start, i kliknij Utwórz klucz.

Strona Klucze API w trybie testowym z nowo utworzonym kluczem zaczynającym się od pj_test_.

Skopiuj klucz od razu. Paperjoy pokazuje go tylko raz. Sprawdź, czy zaczyna się od pj_test_, i zapisz go w terminalu:

export PAPERJOY_API_KEY="pj_test_..."

Utwórz pocztówkę testową

curl https://paperjoy.co/api/postcards \
  --header "Authorization: Bearer $PAPERJOY_API_KEY" \
  --header "Idempotency-Key: $(uuidgen)" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
    "recipient": {
      "first_name": "Anna",
      "last_name": "Kowalska"
    },
    "address": {
      "line_1": "ul. Marszałkowska 10",
      "line_2": "m. 4",
      "postal_code": "00-001",
      "city": "Warszawa",
      "country": "PL"
    },
    "content": "Droga Anno,\ndziękujemy za pierwsze zamówienie!",
    "signature": "Marta z Kwiaciarni Pod Lipą",
    "font_id": "font-1"
  }'

Paperjoy odpowiada 201 Created z nową pocztówką:

{
  "data": {
    "id": "pc_MXP7a4Ni0c",
    "test_mode": true,
    "status": "new",
    "content": "Droga Anno,\ndziękujemy za pierwsze zamówienie!",
    "font_id": "font-1",
    "sent_at": null,
    ...
  }
}

"test_mode": true potwierdza, że nie zużyto kredytu. Zapisz id, aby później sprawdzić pocztówkę.

Nagłówek Idempotency-Key sprawia, że ponowienia są bezpieczne. Jeśli połączenie zostanie zerwane i nie wiesz, czy żądanie dotarło, wyślij dokładnie to samo żądanie z tym samym kluczem. Paperjoy zwróci pierwotną pocztówkę zamiast tworzyć drugą. Zobacz Utwórz pocztówkę.

Sprawdź status

curl https://paperjoy.co/api/postcards/pc_MXP7a4Ni0c \
  --header "Authorization: Bearer $PAPERJOY_API_KEY" \
  --header "Accept: application/json"

Krótko po utworzeniu status zmienia się z new na queued. Pocztówka testowa zatrzymuje się na tym etapie i nigdy nie trafia do realizacji. Zobaczysz ją też na stronie Panel, dopóki tryb testowy jest włączony.

Przejdź na live

Gdy integracja działa:

Wyłącz tryb testowy w menu konta.
Kup kredyty, jeśli Twoje saldo jest puste.
Utwórz nowy klucz API. Zaczyna się od pj_live_.
Podmień klucz testowy w swojej integracji.

To samo żądanie składa teraz prawdziwe zamówienie i zużywa jeden kredyt.

Co dalej

Treść i wygląd kartki

Kroje pisma, podziały linii, podpisy i ile tekstu się zmieści.

Podgląd przed zamówieniem

Wygeneruj darmowy obraz PNG kartki.

Utwórz pocztówkę

Wszystkie pola, zasady walidacji i bezpieczne ponowienia.

Obsługa błędów

Kody statusów, limity i co warto ponawiać.

Pierwsze kroki

Sposoby wysyłki

Pocztówki

Konto

Dokumentacja API

Szybki start: pierwsza pocztówka przez API

Co dalej

Treść i wygląd kartki

Podgląd przed zamówieniem

Utwórz pocztówkę

Obsługa błędów

​Co dalej

Treść i wygląd kartki

Podgląd przed zamówieniem

Utwórz pocztówkę

Obsługa błędów

Co dalej