Szkice pocztówek: przygotuj, sprawdź i wyślij później

Szkic to pocztówka, która nie została jeszcze zamówiona. Jest darmowa, nigdy nie zostanie napisana ani wysłana i możesz ją zmieniać dowolnie często. Gdy będzie gotowa, wyślij ją: Paperjoy ją sprawdzi, pobierze jeden kredyt, a pocztówka trafi do realizacji jak zwykłe zamówienie.

Utwórz szkic

Wyślij "draft": true do POST /api/postcards. Wszystkie pola są opcjonalne, więc szkic zapiszesz, zanim poznasz adres albo ostateczną treść.

curl https://paperjoy.co/api/postcards \
  --header "Authorization: Bearer $PAPERJOY_API_KEY" \
  --header "Idempotency-Key: draft-order-1042" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
    "draft": true,
    "recipient": { "first_name": "Anna", "last_name": "Kowalska" },
    "content": "Droga Anno,\ndziękujemy za pierwsze zamówienie!",
    "font_id": "font-1"
  }'

Odpowiedź to 201 Created z "status": "draft" i "submitted_at": null. Utworzenie szkicu:

nie zużywa kredytu i nie wymaga salda;
nie wlicza się do dziennego limitu 100 pocztówek;
sprawdza każde przesłane pole (długość, format kodu pocztowego, pismo), ale nie to, czy tekst mieści się na kartce, a adres na kopercie. Te sprawdzenia odbywają się przy wysyłce.

Możesz mieć do 100 otwartych szkiców na konto w każdym trybie. Powyżej tego limitu utworzenie szkicu zwraca 422 z błędem w polu draft. Najpierw wyślij lub usuń część szkiców. Bez pola draft albo z "draft": false POST /api/postcards od razu składa zamówienie, tak jak dotychczas.

Edytuj szkic

PATCH /api/postcards/{id} zmienia tylko przesłane pola. Wyślij null, aby wyczyścić pole. address i recipient są zastępowane w całości, więc wysyłaj wszystkie ich części.

curl --request PATCH https://paperjoy.co/api/postcards/pc_MXP7a4Ni0c \
  --header "Authorization: Bearer $PAPERJOY_API_KEY" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
    "address": {
      "line_1": "ul. Marszałkowska 10",
      "postal_code": "00-001",
      "city": "Warszawa",
      "country": "PL"
    }
  }'

Odpowiedź	Kiedy
`200 OK`	Szkic został zaktualizowany.
`409 Conflict`	Pocztówka została już wysłana do realizacji. Zmieniać można tylko szkice.
`422`	Pole jest nieprawidłowe albo wysłano pole, którego pocztówka nie ma, np. `status`.

Nie możesz samodzielnie ustawić status. Szkic staje się zamówieniem dopiero po wysłaniu. Aby zobaczyć, jak wygląda szkic, użyj POST /api/postcards/preview z tymi samymi content, signature i font_id.

Wyślij szkic

POST /api/postcards/{id}/submit składa zamówienie ze szkicu. Nie wymaga body, ale wymaga nagłówka Idempotency-Key.

curl --request POST https://paperjoy.co/api/postcards/pc_MXP7a4Ni0c/submit \
  --header "Authorization: Bearer $PAPERJOY_API_KEY" \
  --header "Idempotency-Key: submit-order-1042" \
  --header "Accept: application/json"

Paperjoy sprawdza szkic dokładnie tak jak nową pocztówkę, także pod kątem zmieszczenia na kartce i kopercie. Jeśli wszystko się zgadza, pobiera jeden kredyt (tylko live), ustawia "status": "new" i submitted_at oraz uruchamia weryfikację treści.

Odpowiedź	Kiedy
`200 OK`	Zamówienie zostało złożone. Ponowienie z tym samym kluczem zwraca tę samą odpowiedź z nagłówkiem `Idempotency-Relayed` i niczego nie pobiera.
`402 Payment Required`	Tryb live i mniej niż jeden kredyt. Pocztówka zostaje szkicem.
`409 Conflict`	Pocztówka została już wysłana albo klucz został wcześniej użyty w innym żądaniu.
`422`	Szkic jest niekompletny albo się nie mieści. `errors` wskazuje pola do poprawy. Pocztówka zostaje szkicem.
`429`	Osiągnięto dzienny limit 100 pocztówek.

Szkic nigdy nie zostanie rozliczony dwa razy. Po 402 lub 422 usuń przyczynę i wyślij ponownie z tym samym kluczem.

Usuń szkic

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

204 No Content, gdy szkic został usunięty. Usunięcie jest trwałe. Wysłanych pocztówek nie można usunąć; zwracają 409.

Znajdź swoje szkice

GET /api/postcards?status=draft zwraca tylko szkice. Zobacz Śledzenie pocztówek.

Nieużywane szkice usuwamy po 30 dniach

Paperjoy trwale usuwa szkice, które nie zmieniły się przez 30 dni. Każda edycja liczy czas od nowa. Wysłane pocztówki nigdy nie są usuwane w ten sposób.

W panelu Paperjoy

W edytorze przycisk Zapisz szkic zapisuje kartkę jako szkic bez zużywania kredytu. Na pulpicie jest zakładka Szkice: otwórz szkic, aby go edytować, a potem kliknij Wyślij (1 kredyt) albo Usuń szkic. Szkice utworzone przez asystenta AI przez serwer MCP pojawiają się w tej samej zakładce, więc możesz je sprawdzić, zanim cokolwiek zostanie wysłane.

Pierwsze kroki

Sposoby wysyłki

Pocztówki

Konto

Dokumentacja API

Szkice pocztówek: przygotuj, sprawdź i wyślij później

Utwórz szkic

Edytuj szkic

Wyślij szkic

Usuń szkic

Znajdź swoje szkice

Nieużywane szkice usuwamy po 30 dniach

W panelu Paperjoy

​Utwórz szkic

​Edytuj szkic

​Wyślij szkic

​Usuń szkic

​Znajdź swoje szkice

​Nieużywane szkice usuwamy po 30 dniach

​W panelu Paperjoy

Utwórz szkic

Edytuj szkic

Wyślij szkic

Usuń szkic

Znajdź swoje szkice

Nieużywane szkice usuwamy po 30 dniach

W panelu Paperjoy