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

# Podgląd pocztówki

> Renderuje stronę kartki z odręcznym tekstem jako PNG. Podgląd jest darmowy i nigdy nie tworzy zamówienia. Wymaga uprawnienia `postcards:write`.



## OpenAPI

````yaml /openapi.yaml post /api/postcards/preview
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/preview:
    post:
      tags:
        - Pocztówki
      summary: Podgląd pocztówki
      description: >-
        Renderuje stronę kartki z odręcznym tekstem jako PNG. Podgląd jest
        darmowy i nigdy nie tworzy zamówienia. Wymaga uprawnienia
        `postcards:write`.
      operationId: previewPostcard
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PreviewPostcardRequest'
            example:
              content: |-
                Droga Anno,
                dziękujemy za pierwsze zamówienie!
              signature: Marta z Kwiaciarni Pod Lipą
              font_id: font-1
              mistake: false
      responses:
        '200':
          description: Obraz PNG kartki.
          content:
            image/png:
              schema:
                type: string
                contentEncoding: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  schemas:
    PreviewPostcardRequest:
      type: object
      required:
        - content
        - font_id
      properties:
        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'
    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ę.
    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
  responses:
    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.
    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.
    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.