> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paperjoy.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Szybki start: pierwsza pocztówka przez API

> Wyślij pierwszą pocztówkę przez API w pięć minut, bezpiecznie w trybie testowym.

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](https://paperjoy.co/register) i terminala z `curl`.

**1. 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.](https://mintcdn.com/paperjoy/F1MJj4Vyrx0MCZIR/images/app/account-menu.webp?fit=max\&auto=format\&n=F1MJj4Vyrx0MCZIR\&q=85\&s=7373cd87ba02e1fd4e2df93bc78819ac)

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

**2. Utwórz testowy klucz API**

Otwórz [**Ustawienia → Klucze API**](https://paperjoy.co/settings/api-tokens), 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\_.](https://mintcdn.com/paperjoy/F1MJj4Vyrx0MCZIR/images/app/api-token-created.webp?fit=max\&auto=format\&n=F1MJj4Vyrx0MCZIR\&q=85\&s=a997ac0e3d3f99ffd7eb6d407a6d48b2)

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

```bash theme={null}
export PAPERJOY_API_KEY="pj_test_..."
```

**3. Utwórz pocztówkę testową**

```bash theme={null}
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ą:

```json theme={null}
{
  "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ę.

> [!NOTE]
>
> 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ę](https://docs.paperjoy.co/postcards/create.md#bezpieczne-ponowienia).

**4. Sprawdź status**

```bash theme={null}
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.

**5. Przejdź na live**

Gdy integracja działa:

1. Wyłącz tryb testowy w menu konta.
2. [Kup kredyty](https://paperjoy.co/billing), jeśli Twoje saldo jest puste.
3. Utwórz nowy klucz API. Zaczyna się od `pj_live_`.
4. Podmień klucz testowy w swojej integracji.

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

## Co dalej

> [card] [Treść i wygląd kartki](https://docs.paperjoy.co/postcards/write.md)
>
> Kroje pisma, podziały linii, podpisy i ile tekstu się zmieści.

> [card] [Podgląd przed zamówieniem](https://docs.paperjoy.co/postcards/preview.md)
>
> Wygeneruj darmowy obraz PNG kartki.

> [card] [Utwórz pocztówkę](https://docs.paperjoy.co/postcards/create.md)
>
> Wszystkie pola, zasady walidacji i bezpieczne ponowienia.

> [card] [Obsługa błędów](https://docs.paperjoy.co/reference/errors-and-rate-limits.md)
>
> Kody statusów, limity i co warto ponawiać.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.