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

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

> Zapisuj darmowe szkice, edytuj je i podglądaj, a potem wyślij. Kredyt pobierany przy wysyłce.

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.

```mermaid theme={null}
flowchart LR
  D["draft"] -->|"wysyłka (1 kredyt)"| new
  D -->|usunięcie| X["usunięty"]
  new --> queued
```

## Utwórz szkic

Wyślij `"draft": true` do [`POST /api/postcards`](https://docs.paperjoy.co/postcards/create). Wszystkie pola są opcjonalne, więc szkic zapiszesz, zanim poznasz adres albo ostateczną treść.

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

```bash theme={null}
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`](https://docs.paperjoy.co/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`.

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

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

## 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](https://docs.paperjoy.co/integrations/mcp.md) pojawiają się w tej samej zakładce, więc możesz je sprawdzić, zanim cokolwiek zostanie wysłane.


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