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

# Statusy pocztówek

> Każdy etap od zamówienia do skrzynki odbiorcy i co oznacza każdy status.

Pole `status` pokazuje, na jakim etapie jest pocztówka. Statusy zmieniają się tylko do przodu i nie można ich ustawić przez API. [Szkic](https://docs.paperjoy.co/postcards/drafts.md) idzie dalej dopiero po wysłaniu.

```mermaid theme={null}
flowchart LR
  draft -.-> new
  new --> queued
  new --> rejected
  queued --> P["Realizacja<br/><small>pair_claimed → in_progress → pair_completed</small>"]
  P --> sent
```

## Wszystkie statusy

| Status | W panelu | Co się dzieje |
| - | - | - |
| `draft` | Szkic | [Szkic](https://docs.paperjoy.co/postcards/drafts.md). Darmowy, można go edytować i nigdy nie jest pisany. Wyślij go, aby złożyć zamówienie. |
| `new` | Nowe zamówienie | Zamówienie przyjęte. Trwa automatyczna weryfikacja treści. |
| `queued` | Przyjęto do realizacji | Weryfikacja zakończona. Czeka na wolnego robota. |
| `rejected` | Odrzucono zamówienie | Weryfikacja zakwestionowała wiadomość. Nic nie zostanie napisane. |
| `pair_claimed` | Rozpoczęto realizację | Robot pobrał kartkę i kopertę do realizacji. |
| `in_progress` | W trakcie pisania | Robot adresuje kopertę i pisze kartkę w jednym przebiegu. |
| `pair_completed` | W trakcie wysyłki | Kartka i koperta są gotowe i jadą na pocztę. |
| `sent` | Wysłano | Nadana Pocztą Polską. Pole `sent_at` jest uzupełnione. |

> [!NOTE]
>
> Mogą pojawić się nowe statusy. Każdą nieznaną wartość traktuj jako „w realizacji”, zamiast zgłaszać błąd.

## Szkice

Pocztówka utworzona z `"draft": true` zaczyna jako `draft`. Szkice są darmowe, roboty nigdy ich nie pobierają, a `submitted_at` ma wartość `null`. Gdy [wyślesz szkic](https://docs.paperjoy.co/postcards/drafts.md), Paperjoy pobiera jeden kredyt, ustawia `submitted_at`, a pocztówka przechodzi do `new`. Szkice, które nie zmieniły się przez 30 dni, są usuwane.

Każda pocztówka zamówiona bezpośrednio, bez szkicu, ma `submitted_at` równe czasowi utworzenia.

## Odrzucone

Każda wiadomość przechodzi automatyczną weryfikację treści przed realizacją. Jeśli zostanie uznana za obraźliwą lub szkodliwą, pocztówka trafia do statusu `rejected`:

* Nic nie zostanie napisane ani wysłane.
* W przypadku pocztówek live kredyt automatycznie wraca na Twoje saldo.
* Możesz wysłać przeredagowaną wiadomość jako nową pocztówkę z nowym `Idempotency-Key`.

## Pocztówki testowe

Pocztówki testowe także przechodzą weryfikację treści, więc trafiają do `queued` lub `rejected`. Nigdy nie idą dalej i nigdy nie są pisane ani wysyłane.

## Wysłane

Gdy pocztówka osiągnie status `sent`, pole `sent_at` zawiera moment przekazania jej Poczcie Polskiej. Dalej dostawa przebiega jak w przypadku zwykłego listu krajowego.

```json theme={null}
{
  "data": {
    "id": "pc_7H2nlRUb1r",
    "status": "sent",
    "sent_at": "2026-10-15T14:31:00+00:00",
    ...
  }
}
```


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