Utwórz pocztówkę

POST /api/postcards składa zamówienie. Aby przygotować kartkę bez zamawiania, wyślij "draft": true; zobacz Szkice. Z kluczem pj_live_ zużywa jeden kredyt, a kartka zostaje napisana i wysłana. Z kluczem pj_test_ jest darmowa i nigdy nie opuszcza piaskownicy.

curl https://paperjoy.co/api/postcards \
  --header "Authorization: Bearer $PAPERJOY_API_KEY" \
  --header "Idempotency-Key: 4f1c2a9e-6b0d-4d7e-9a51-3c8e2f7b1d20" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
    "recipient": {
      "prefix": "Pani",
      "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! Mamy nadzieję, że kwiaty sprawiły Ci dużo radości.",
    "signature": "Marta z Kwiaciarni Pod Lipą",
    "font_id": "font-1",
    "mistake": false
  }'

Pola

object

wymagane

Kto otrzyma kartkę. Podaj first_name, company_name albo oba. Opcjonalnie prefix (do 30 znaków) i last_name. Zobacz Adres i koperta.

object

wymagane

Polski adres: line_1, opcjonalnie line_2, postal_code (00-001), city i country (PL). Zobacz Adres dostawy.

string

wymagane

Wiadomość, do 300 znaków. Podziały linii są zachowywane. Musi zmieścić się na kartce. Zobacz Treść i wygląd kartki.

string

wymagane

font-1 (Standardowe) lub font-2 (Szybkie). Zobacz Pismo.

string

Podpis tekstowy, do 50 znaków, zapisany w jednej linii. Nie łącz z signature_id.

string

ID aktywnego własnego podpisu, np. sig_ZeXOkSQjTp. Nie łącz z signature.

boolean

domyślnie:"false"

Przekreśl jedno słowo i napisz je ponownie, aby kartka wyglądała naturalniej.

boolean

domyślnie:"false"

Zapisz pocztówkę jako darmowy szkic zamiast składać zamówienie. Pozostałe pola stają się opcjonalne, a sprawdzenie, czy treść mieści się na kartce i kopercie, odbywa się przy wysyłce.

Nigdy nie wysyłaj pola test_mode. O trybie decyduje klucz API.

Odpowiedź

201 Created z nową pocztówką. Zaczyna się od "status": "new" z uzupełnionym submitted_at albo, dla szkicu, od "status": "draft" i "submitted_at": null.

{
  "data": {
    "id": "pc_MXP7a4Ni0c",
    "test_mode": false,
    "address": {
      "line_1": "ul. Marszałkowska 10",
      "line_2": "m. 4",
      "postal_code": "00-001",
      "country": "PL",
      "city": "Warszawa"
    },
    "recipient": {
      "prefix": "Pani",
      "first_name": "Anna",
      "last_name": "Kowalska",
      "company_name": null
    },
    "content": "Droga Anno,\ndziękujemy za pierwsze zamówienie! Mamy nadzieję, że kwiaty sprawiły Ci dużo radości.",
    "signature": "Marta z Kwiaciarni Pod Lipą",
    "signature_id": null,
    "font_id": "font-1",
    "mistake": false,
    "status": "new",
    "submitted_at": "2026-10-17T14:31:48+00:00",
    "sent_at": null,
    "created_at": "2026-10-17T14:31:48+00:00",
    "updated_at": "2026-10-17T14:31:48+00:00"
  }
}

Zapisz id. Będzie potrzebne do śledzenia pocztówki.

Bezpieczne ponowienia

Sieć bywa zawodna. Nagłówek Idempotency-Key gwarantuje, że ponowienie nigdy nie wyśle tej samej kartki dwa razy.

Wygeneruj nowy klucz, np. UUID, dla każdej kartki, którą chcesz wysłać. Zapisz go w swoim rekordzie przed wywołaniem API.
Jeśli nie dostaniesz odpowiedzi (przekroczony czas, zerwane połączenie), ponów żądanie z tym samym kluczem i tym samym body. Jeśli pierwsze żądanie dotarło, Paperjoy zwróci pierwotną odpowiedź 201 z nagłówkiem Idempotency-Relayed. Nie powstanie druga kartka i nie zostanie zużyty drugi kredyt.
Jeśli zmienisz body pocztówki, która została już utworzona, użyj nowego klucza. Ponowne użycie klucza, który zakończył się sukcesem, z innym body zwraca 409 Conflict.

Paperjoy pamięta przez 7 dni tylko udane odpowiedzi. Błędy takie jak 402, 422 czy 429 nie są zapisywane, więc po usunięciu przyczyny możesz ponowić żądanie z tym samym kluczem, także z poprawionym body. Klucze są przypisane do Twojego konta i trybu. Nagłówek jest wymagany i może mieć do 255 znaków.

Twórz klucz z własnych danych, np. zamowienie-1042-podziekowanie-1. Ponowienie po awarii lub po poprawieniu błędu użyje wtedy automatycznie tego samego klucza.

Co jest sprawdzane

Paperjoy odrzuca żądanie błędem 422 i nie rusza Twoich kredytów, gdy:

Sprawdzenie	Klucz błędu
Brakuje wymaganego pola albo jest za długie	Nazwa pola, np. `content`
Kod pocztowy nie ma formatu `00-001` albo kraj to nie `PL`	`address.postal_code`, `address.country`
Nie podano ani `first_name`, ani `company_name`	`recipient.first_name`, `recipient.company_name`
Podano jednocześnie `signature` i `signature_id`	`signature`, `signature_id`
Wiadomość nie mieści się na kartce	`content`
Podpis nie mieści się w jednej linii	`signature`
Adres nie mieści się na kopercie	`address`
Własny podpis nie jest aktywny lub nie obejmuje go Twój plan	`signature_id`

Inne błędy: 402, gdy nie masz kredytów (tylko live), 400 bez Idempotency-Key i 429 po 100 pocztówkach w ciągu doby. Zobacz Błędy i limity.

Po utworzeniu

Paperjoy od razu uruchamia automatyczną weryfikację treści. Pocztówka przechodzi do queued albo do rejected ze zwrotem kredytu, jeśli wiadomość zostanie zakwestionowana. Śledź ją zgodnie z opisem w Śledzenie pocztówek.

Pierwsze kroki

Sposoby wysyłki

Pocztówki

Konto

Dokumentacja API

Utwórz pocztówkę

Pola

Odpowiedź

Bezpieczne ponowienia

Co jest sprawdzane

Po utworzeniu

​Pola

​Odpowiedź

​Bezpieczne ponowienia

​Co jest sprawdzane

​Po utworzeniu

Pola

Odpowiedź

Bezpieczne ponowienia

Co jest sprawdzane

Po utworzeniu