> ## 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.

# Utwórz pocztówkę

> Wszystkie pola POST /api/postcards, zasady walidacji i ponawianie bez ryzyka podwójnej wysyłki.

`POST /api/postcards` składa zamówienie. Aby przygotować kartkę bez zamawiania, wyślij `"draft": true`; zobacz [Szkice](https://docs.paperjoy.co/postcards/drafts.md). 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.

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

**recipient** `object` *required*

Kto otrzyma kartkę. Podaj `first_name`, `company_name` albo oba. Opcjonalnie `prefix` (do 30 znaków) i `last_name`. Zobacz [Adres i koperta](https://docs.paperjoy.co/postcards/supported-countries.md#odbiorca).

**address** `object` *required*

Polski adres: `line_1`, opcjonalnie `line_2`, `postal_code` (`00-001`), `city` i `country` (`PL`). Zobacz [Adres dostawy](https://docs.paperjoy.co/postcards/supported-countries.md#adres-dostawy).

**content** `string` *required*

Wiadomość, do 300 znaków. Podziały linii są zachowywane. Musi zmieścić się na kartce. Zobacz [Treść i wygląd kartki](https://docs.paperjoy.co/postcards/write.md).

**font\_id** `string` *required*

`font-1` (Standardowe) lub `font-2` (Szybkie). Zobacz [Pismo](https://docs.paperjoy.co/postcards/write.md#pismo).

**signature** `string`

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

**signature\_id** `string`

ID aktywnego [własnego podpisu](https://docs.paperjoy.co/postcards/custom-signatures.md), np. `sig_ZeXOkSQjTp`. Nie łącz z `signature`.

**mistake** `boolean` (default: false)

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

**draft** `boolean` (default: false)

Zapisz pocztówkę jako darmowy [szkic](https://docs.paperjoy.co/postcards/drafts.md) 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`.

```json theme={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](https://docs.paperjoy.co/postcards/list-and-retrieve.md).

## 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.

> [!TIP]
>
> 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](https://docs.paperjoy.co/reference/errors-and-rate-limits.md).

## 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](https://docs.paperjoy.co/postcards/list-and-retrieve.md).


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