Przegląd API Paperjoy

API Paperjoy to API JSON przez HTTPS do tworzenia i śledzenia odręcznych pocztówek. Zaczynasz? Przejdź do Szybkiego startu.

Adres bazowy

https://paperjoy.co/api

W każdym żądaniu wyślij klucz API jako token bearer:

Authorization: Bearer pj_live_...

Klucz pj_test_ wykonuje każde żądanie w trybie testowym, a klucz pj_live_ w trybie live. Ścieżki i body są identyczne w obu trybach.

Metoda	Ścieżka	Działanie
`GET`	`/api/user`	Twoje konto i saldo kredytów.
`POST`	`/api/postcards`	Utworzenie pocztówki.
`POST`	`/api/postcards/preview`	Obraz PNG kartki.
`GET`	`/api/postcards`	Lista Twoich pocztówek, od najnowszych, po jednej stronie naraz.
`GET`	`/api/postcards/{id}`	Jedna pocztówka.
`GET`	`/api/signatures`	Lista Twoich własnych podpisów.
`GET`	`/api/signatures/{id}`	Jeden podpis.
`DELETE`	`/api/signatures/{id}`	Usunięcie podpisu.

Szczegóły każdego endpointu znajdziesz w sekcji Endpointy API w menu.

Nagłówki. W każdym żądaniu wysyłaj Accept: application/json, a z body Content-Type: application/json. Endpoint podglądu zwraca image/png.
Koperta odpowiedzi. Poprawne odpowiedzi JSON zawierają wynik w polu data.
ID. Identyfikatory to nieprzezroczyste ciągi z prefiksem: pc_ dla pocztówek, sig_ dla podpisów, user_ dla użytkowników. Przechowuj je jako tekst.
Daty. ISO 8601 z przesunięciem UTC, np. 2026-10-17T14:31:48+00:00. Pola dotyczące zdarzeń, które jeszcze nie nastąpiły, mają wartość null.
Idempotency. POST /api/postcards wymaga nagłówka Idempotency-Key. Zobacz Bezpieczne ponowienia.
Błędy. Body JSON z message oraz errors przy błędach walidacji. Komunikaty są po angielsku. Zobacz Błędy i limity.
Zgodność. Możemy dodawać pola i wartości statusów. Ignoruj pola, których nie używasz, i obsługuj nieznane statusy bez błędu.