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

# Lista pocztówek

> Zwraca Twoje pocztówki z trybu klucza API, od najnowszych, po jednej stronie naraz. Użyj `page` i `per_page`, aby przechodzić przez listę, i pobieraj `links.next`, dopóki nie będzie `null`. Wymaga uprawnienia `postcards:read`.



## OpenAPI

````yaml /openapi.yaml get /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:
    get:
      tags:
        - Pocztówki
      summary: Lista pocztówek
      description: >-
        Zwraca Twoje pocztówki z trybu klucza API, od najnowszych, po jednej
        stronie naraz. Użyj `page` i `per_page`, aby przechodzić przez listę, i
        pobieraj `links.next`, dopóki nie będzie `null`. Wymaga uprawnienia
        `postcards:read`.
      operationId: listPostcards
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PerPage'
        - $ref: '#/components/parameters/StatusFilter'
      responses:
        '200':
          description: Jedna strona pocztówek z trybu klucza API.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostcardList'
              example:
                data:
                  - id: pc_7H2nlRUb1r
                    test_mode: false
                    address:
                      line_1: ul. Piotrkowska 100
                      line_2: null
                      postal_code: 90-001
                      country: PL
                      city: Łódź
                    recipient:
                      prefix: null
                      first_name: Tomasz
                      last_name: Lewandowski
                      company_name: null
                    content: Dziękujemy, że jesteś z nami od roku!
                    signature: Marta z Kwiaciarni Pod Lipą
                    signature_id: null
                    font_id: font-1
                    mistake: false
                    status: sent
                    submitted_at: '2026-10-11T14:31:00+00:00'
                    sent_at: '2026-10-15T14:31:00+00:00'
                    created_at: '2026-10-11T14:31:00+00:00'
                    updated_at: '2026-10-15T14:31:00+00:00'
                links:
                  first: https://paperjoy.co/api/postcards?page=1
                  last: https://paperjoy.co/api/postcards?page=1
                  prev: null
                  next: null
                meta:
                  current_page: 1
                  from: 1
                  last_page: 1
                  links:
                    - url: null
                      label: '« Previous'
                      page: null
                      active: false
                    - url: https://paperjoy.co/api/postcards?page=1
                      label: '1'
                      page: 1
                      active: true
                    - url: null
                      label: Next »
                      page: null
                      active: false
                  path: https://paperjoy.co/api/postcards
                  per_page: 50
                  to: 1
                  total: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  parameters:
    Page:
      name: page
      in: query
      required: false
      description: Numer strony, od 1. Strona za końcem listy zwraca pustą tablicę `data`.
      schema:
        type: integer
        minimum: 1
        default: 1
    PerPage:
      name: per_page
      in: query
      required: false
      description: Liczba pocztówek na stronie.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 50
    StatusFilter:
      name: status
      in: query
      required: false
      description: Zwraca tylko pocztówki o tym statusie, np. `draft`.
      schema:
        $ref: '#/components/schemas/PostcardStatus'
  schemas:
    PostcardList:
      type: object
      description: Jedna strona pocztówek z linkami i metadanymi stronicowania Laravela.
      required:
        - data
        - links
        - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Postcard'
        links:
          $ref: '#/components/schemas/PaginationLinks'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    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
    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
    PaginationLinks:
      type: object
      description: >-
        Adresy sąsiednich stron. `prev` i `next` mają wartość `null` na końcach
        listy.
      required:
        - first
        - last
        - prev
        - next
      properties:
        first:
          type: string
          format: uri
        last:
          type: string
          format: uri
        prev:
          type:
            - string
            - 'null'
          format: uri
        next:
          type:
            - string
            - 'null'
          format: uri
    PaginationMeta:
      type: object
      description: Położenie tej strony w całej liście.
      required:
        - current_page
        - from
        - last_page
        - links
        - path
        - per_page
        - to
        - total
      properties:
        current_page:
          type: integer
          minimum: 1
        from:
          type:
            - integer
            - 'null'
          description: >-
            Pozycja pierwszej pocztówki na tej stronie albo `null`, gdy strona
            jest pusta.
        last_page:
          type: integer
          minimum: 1
        links:
          type: array
          description: >-
            Linki do budowy paginacji: poprzednia strona, kolejne numery stron,
            następna strona.
          items:
            type: object
            required:
              - url
              - label
              - page
              - active
            properties:
              url:
                type:
                  - string
                  - 'null'
                format: uri
              label:
                type: string
              page:
                type:
                  - integer
                  - 'null'
              active:
                type: boolean
        path:
          type: string
          format: uri
          description: Adres listy bez parametrów zapytania.
        per_page:
          type: integer
          minimum: 1
          maximum: 100
        to:
          type:
            - integer
            - 'null'
          description: >-
            Pozycja ostatniej pocztówki na tej stronie albo `null`, gdy strona
            jest pusta.
        total:
          type: integer
          minimum: 0
          description: Liczba pocztówek w trybie klucza API.
    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
    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
    FontId:
      type: string
      enum:
        - font-1
        - font-2
      description: >-
        `font-1` to czytelne, zaokrąglone pismo (Standardowe). `font-2` to
        szybsze pismo łączone (Szybkie).
  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.
  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.