> ## 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ę > Tworzy pocztówkę w trybie klucza API. Klucz `pj_live_` składa prawdziwe zamówienie i zużywa jeden kredyt. Klucz `pj_test_` tworzy darmową pocztówkę testową, która nigdy nie zostanie napisana ani wysłana. Z `"draft": true` zapisuje darmowy szkic: wszystkie pola są opcjonalne, kredyt nie jest pobierany, a szkic nie wlicza się do dziennego limitu. Możesz mieć do 100 otwartych szkiców w każdym trybie. Wyślij szkic przez `POST /api/postcards/{id}/submit`. Dla każdej nowej pocztówki wyślij unikalny nagłówek `Idempotency-Key`. Wymaga uprawnienia `postcards:write`. ## OpenAPI ````yaml /openapi.yaml post /api/postcards openapi: 3.1.0 info: title: Paperjoy API version: '2026-10-19' description: >- Twórz, podglądaj i śledź prawdziwe, ręcznie pisane pocztówki. Klucz API decyduje, czy żądanie działa w trybie testowym, czy live. termsOfService: https://paperjoy.co/regulamin license: name: Proprietary url: https://paperjoy.co/regulamin servers: - url: https://paperjoy.co security: - bearerAuth: [] tags: - name: Konto description: Uwierzytelnione konto i saldo kredytów. - name: Pocztówki description: Tworzenie, podgląd, lista i pobieranie pocztówek. - name: Podpisy description: Własne podpisy odręczne Twojej organizacji. paths: /api/postcards: post: tags: - Pocztówki summary: Utwórz pocztówkę description: > Tworzy pocztówkę w trybie klucza API. Klucz `pj_live_` składa prawdziwe zamówienie i zużywa jeden kredyt. Klucz `pj_test_` tworzy darmową pocztówkę testową, która nigdy nie zostanie napisana ani wysłana. Z `"draft": true` zapisuje darmowy szkic: wszystkie pola są opcjonalne, kredyt nie jest pobierany, a szkic nie wlicza się do dziennego limitu. Możesz mieć do 100 otwartych szkiców w każdym trybie. Wyślij szkic przez `POST /api/postcards/{id}/submit`. Dla każdej nowej pocztówki wyślij unikalny nagłówek `Idempotency-Key`. Wymaga uprawnienia `postcards:write`. operationId: createPostcard parameters: - name: Idempotency-Key in: header required: true description: >- Unikalny klucz tej pocztówki, np. UUID. Paperjoy pamięta klucze przez 7 dni. Ponowienie z tym samym kluczem i tym samym body zwraca pierwotną odpowiedź bez tworzenia kolejnej pocztówki. schema: type: string maxLength: 255 example: 4f1c2a9e-6b0d-4d7e-9a51-3c8e2f7b1d20 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePostcardRequest' examples: typed_signature: summary: Podpis wpisany value: 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, dzię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 custom_signature: summary: Własny podpis value: address: line_1: ul. Długa 5 postal_code: 80-001 country: PL city: Gdańsk recipient: company_name: Studio Forma content: >- Dziękujemy za wspólny projekt. Było nam bardzo miło pracować z całym zespołem. signature_id: sig_ZeXOkSQjTp font_id: font-2 draft: summary: Szkic value: draft: true recipient: first_name: Anna content: |- Droga Anno, dziękujemy za pierwsze zamówienie! responses: '201': description: Pocztówka została utworzona. headers: Idempotency-Relayed: description: >- Obecny, gdy odpowiedź jest odtworzeniem wcześniejszej odpowiedzi dla tego samego `Idempotency-Key`. Zawiera ten klucz. schema: type: string content: application/json: schema: $ref: '#/components/schemas/PostcardResponse' example: data: id: pc_MXP7a4Ni0c test_mode: true 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, dzię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' '400': $ref: '#/components/responses/MissingIdempotencyKey' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/IdempotencyConflict' '422': $ref: '#/components/responses/ValidationError' '429': $ref: '#/components/responses/TooManyRequests' components: schemas: CreatePostcardRequest: type: object description: >- Pola `address`, `recipient`, `content` i `font_id` są wymagane, chyba że wysyłasz `draft` z wartością `true`. required: - address - recipient - content - font_id properties: address: $ref: '#/components/schemas/Address' recipient: $ref: '#/components/schemas/Recipient' content: $ref: '#/components/schemas/Content' signature: $ref: '#/components/schemas/TypedSignature' signature_id: $ref: '#/components/schemas/SignatureIdInput' font_id: $ref: '#/components/schemas/FontId' mistake: $ref: '#/components/schemas/Mistake' draft: type: boolean default: false description: >- `true` zapisuje darmowy szkic zamiast składać zamówienie. Pozostałe pola stają się wtedy opcjonalne. PostcardResponse: type: object required: - data properties: data: $ref: '#/components/schemas/Postcard' Address: type: object required: - line_1 - postal_code - country - city properties: line_1: type: string maxLength: 255 description: Ulica i numer budynku. examples: - ul. Marszałkowska 10 line_2: type: - string - 'null' maxLength: 255 description: Numer lokalu, piętro lub inna informacja. examples: - m. 4 postal_code: type: string pattern: ^\d{2}-\d{3}$ examples: - 00-001 country: type: string enum: - PL city: type: string maxLength: 255 examples: - Warszawa Recipient: type: object description: Podaj `first_name`, `company_name` albo oba pola. properties: prefix: type: - string - 'null' maxLength: 30 examples: - Pani first_name: type: - string - 'null' maxLength: 255 last_name: type: - string - 'null' maxLength: 255 company_name: type: - string - 'null' maxLength: 255 Content: type: string maxLength: 300 description: >- Odręczna wiadomość. Znaki nowej linii (`\n`) i puste linie są zachowywane. Tekst musi zmieścić się na kartce; zobacz błąd walidacji `card_fit`. TypedSignature: type: - string - 'null' maxLength: 50 description: >- Podpis zapisany w jednej linii na dole kartki. Nie wysyłaj razem z `signature_id`. SignatureIdInput: type: - string - 'null' description: >- ID aktywnego własnego podpisu z `GET /api/signatures`. Wymaga planu z własnymi podpisami. Nie wysyłaj razem z `signature`. examples: - sig_ZeXOkSQjTp FontId: type: string enum: - font-1 - font-2 description: >- `font-1` to czytelne, zaokrąglone pismo (Standardowe). `font-2` to szybsze pismo łączone (Szybkie). Mistake: type: boolean default: false description: >- Przekreśl jedno słowo i napisz je ponownie, jak zrobiłby to człowiek. Ta sama wiadomość zawsze dostaje tę samą poprawkę. Postcard: type: object required: - id - test_mode - recipient - signature - signature_id - mistake - status - submitted_at - sent_at - created_at - updated_at properties: id: type: string examples: - pc_MXP7a4Ni0c test_mode: type: boolean description: >- `true` dla pocztówki testowej. Pocztówki testowe są darmowe i nigdy nie są pisane ani wysyłane. address: description: Adres dostawy. Może być `null` tylko w szkicu. oneOf: - $ref: '#/components/schemas/Address' - type: 'null' recipient: oneOf: - $ref: '#/components/schemas/Recipient' - type: 'null' content: type: - string - 'null' maxLength: 300 description: Treść kartki. Może być `null` tylko w szkicu. signature: type: - string - 'null' maxLength: 50 description: Wpisany podpis albo `null`, gdy pocztówka używa własnego podpisu. signature_id: type: - string - 'null' description: Własny podpis użyty na pocztówce albo `null`. examples: - sig_ZeXOkSQjTp font_id: description: Pismo. Może być `null` tylko w szkicu. oneOf: - $ref: '#/components/schemas/FontId' - type: 'null' mistake: type: boolean description: >- Czy jedno słowo jest przekreślone i napisane ponownie, aby kartka wyglądała naturalnie. status: $ref: '#/components/schemas/PostcardStatus' submitted_at: type: - string - 'null' format: date-time description: Moment złożenia zamówienia. `null`, dopóki pocztówka jest szkicem. sent_at: type: - string - 'null' format: date-time description: >- Moment nadania pocztówki. `null`, dopóki status nie zmieni się na `sent`. created_at: type: - string - 'null' format: date-time updated_at: type: - string - 'null' format: date-time Error: type: object required: - message properties: message: type: string ValidationError: type: object required: - message - errors properties: message: type: string errors: type: object additionalProperties: type: array items: type: string PostcardStatus: type: string description: >- Etap realizacji pocztówki. Nieznane wartości traktuj jako „w realizacji”. enum: - draft - new - queued - rejected - pair_claimed - in_progress - pair_completed - sent responses: MissingIdempotencyKey: description: Brakuje nagłówka `Idempotency-Key`. content: application/json: schema: $ref: '#/components/schemas/Error' example: message: Idempotency-Key header is required to create or submit a postcard. Unauthorized: description: Brak klucza API albo klucz jest nieprawidłowy, unieważniony lub wygasł. content: application/json: schema: $ref: '#/components/schemas/Error' example: message: Unauthenticated. PaymentRequired: description: >- Konto ma mniej niż jeden kredyt. Saldo jest sprawdzane tylko w trybie live. content: application/json: schema: $ref: '#/components/schemas/Error' example: message: You need at least 1 credit to create a postcard. Forbidden: description: >- Klucz API nie ma wymaganego uprawnienia albo zasób należy do kogoś innego. content: application/json: schema: $ref: '#/components/schemas/Error' example: message: This action is unauthorized. IdempotencyConflict: description: '`Idempotency-Key` został już użyty z innym body żądania.' content: application/json: schema: $ref: '#/components/schemas/Error' example: message: >- Idempotency-Key has already been used with a different postcard creation payload. ValidationError: description: >- Pole jest nieprawidłowe, tekst nie mieści się na kartce lub kopercie albo `Idempotency-Key` jest dłuższy niż 255 znaków. content: application/json: schema: anyOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/Error' examples: field: summary: Nieprawidłowe pole value: message: The selected font id is invalid. errors: font_id: - The selected font id is invalid. card_fit: summary: Wiadomość nie mieści się na kartce value: message: >- The content does not fit on the postcard. Shorten it or remove blank lines. errors: content: - >- The content does not fit on the postcard. Shorten it or remove blank lines. envelope_fit: summary: Adres nie mieści się na kopercie value: message: The sender or recipient address does not fit on the envelope. errors: address: - >- The sender or recipient address does not fit on the envelope. draft_limit: summary: Za dużo otwartych szkiców value: message: >- You already have 100 open drafts. Submit or delete some of them before saving another draft. errors: draft: - >- You already have 100 open drafts. Submit or delete some of them before saving another draft. signature_unavailable: summary: Własny podpis jest niedostępny value: message: >- The selected signature is unavailable or is not active for your plan. errors: signature_id: - >- The selected signature is unavailable or is not active for your plan. TooManyRequests: description: Przekroczono limit żądań. Odczekaj przed ponowieniem. headers: Retry-After: description: Liczba sekund, po której można ponowić żądanie. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' example: message: Too Many Attempts. securitySchemes: bearerAuth: type: http scheme: bearer description: >- Klucz API Paperjoy. Klucze z prefiksem `pj_test_` działają w trybie testowym, a z `pj_live_` w trybie live. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.