Swiss Post API

openapi: 3.1.0
info:
  title: Swiss Post API
  version: '2026-10-28'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-10-28: 14 operation(s) read from 5 public documentation page(s) (each operation
    names its page in x-source). This is not the provider''s published contract; Swiss Post has published no machine-readable contract that the
    pipeline could find. Engine: local.'
  x-evidence-tiers:
    code-example: 3
    documentation: 11
    pages-with-code: 4
    pages-read: 5
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-10-28'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://developer.post.ch/en/technical-specifications-of-postcard-api
  - https://developer.post.ch/en/digital-commerce-api
  - https://developer.post.ch/en/webstamp-web-service-soap
  - https://developer.post.ch/en/webstamp-web-service-soap/webstamp-web-service-soap-version-v06-04
  - https://developer.post.ch/en/webstamp-web-service-soap/webstamp-web-service-soap-version-v06-03
servers:
- url: https://api.post.ch
paths:
  /OAuth/token:
    post:
      operationId: post_OAuth_token
      tags:
      - Oauth
      summary: POST /OAuth/token
      x-source: https://developer.post.ch/en/digital-commerce-api
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: http
        snippet: " POST /OAuth/token HTTP/1.1 \nHost: api.post.ch/OAuth/token \nContent-Type: application/x-www-form-urlencoded \ngrant_type=authorization_code&\
          \ \nclient_id=dcapi-dummy-id& \nclient_secret=dcapi-dummy-secret& \nredirect_uri=https%3A%2F%2Flocalhost %3A8080%2Ffake-shop%2F& \n\
          code=iUkxvid_e4k813KgLWcNvYj2KAqK60r0ixe8W4kiMPY \n Copy \n Please note: you should never send the client_secret as query parameters\
          \ on t"
  /api/v1/postcards:
    post:
      operationId: post_api_v1_postcards
      tags:
      - Api
      summary: Create a Post card resource via the versioned API (POST /api/v1/postcards).
      x-source: https://developer.post.ch/en/technical-specifications-of-postcard-api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1PostcardsRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1PostcardsResponse'
      x-evidence:
        kind: documentation
  /api/v1/postcards/{cardkey}/branding/qrtag:
    put:
      operationId: put_api_v1_postcards_cardkey_branding_qrtag
      tags:
      - Api
      summary: Add a branding block of type QR‑Tag with text (PUT /api/v1/postcards/{cardKey}/branding/qrtag).
      x-source: https://developer.post.ch/en/technical-specifications-of-postcard-api
      parameters:
      - name: cardkey
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutApiV1PostcardsCardkeyBrandingQrtagRequest'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PutApiV1PostcardsCardkeyBrandingQrtagResponse'
      x-evidence:
        kind: documentation
  /orders:
    post:
      operationId: post_orders
      tags:
      - Orders
      summary: Create a order resource
      description: Create a order resource (POST /orders) minimally providing the pickupAddress and a parcel.
      x-source: https://developer.post.ch/en/digital-commerce-api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostOrdersRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostOrdersResponse'
      x-evidence:
        kind: documentation
  /orders/{orderkey}/approval:
    post:
      operationId: post_orders_orderkey_approval
      tags:
      - Orders
      summary: Set the approval for the order
      description: Set the approval for the order (POST /orders/{orderKey}/approval). Order can't be updated after this call.
      x-source: https://developer.post.ch/en/digital-commerce-api
      parameters:
      - name: orderkey
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostOrdersOrderkeyApprovalResponse'
      x-evidence:
        kind: documentation
  /postcards:
    post:
      operationId: post_postcards
      tags:
      - Postcards
      summary: Create a Post card resource (POST /postcards) minimally providing the recipientAddress.
      x-source: https://developer.post.ch/en/technical-specifications-of-postcard-api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostPostcardsRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostPostcardsResponse'
      x-evidence:
        kind: documentation
  /postcards/{cardkey}/approval:
    post:
      operationId: post_postcards_cardkey_approval
      tags:
      - Postcards
      summary: Set the approval for printing the post card (POST /postcards/{cardKey}/approval).
      x-source: https://developer.post.ch/en/technical-specifications-of-postcard-api
      parameters:
      - name: cardkey
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostPostcardsCardkeyApprovalResponse'
      x-evidence:
        kind: documentation
  /postcards/{cardkey}/branding/image:
    put:
      operationId: put_postcards_cardkey_branding_image
      tags:
      - Postcards
      summary: Add a branding block of type image (PUT /postcards/{cardKey}/branding/image).
      x-source: https://developer.post.ch/en/technical-specifications-of-postcard-api
      parameters:
      - name: cardkey
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutPostcardsCardkeyBrandingImageRequest'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PutPostcardsCardkeyBrandingImageResponse'
      x-evidence:
        kind: documentation
  /postcards/{cardkey}/branding/qrtag:
    put:
      operationId: put_postcards_cardkey_branding_qrtag
      tags:
      - Postcards
      summary: Add a branding block of type QR‑Tag with text (PUT /postcards/{cardKey}/branding/qrtag).
      x-source: https://developer.post.ch/en/technical-specifications-of-postcard-api
      parameters:
      - name: cardkey
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutPostcardsCardkeyBrandingQrtagRequest'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PutPostcardsCardkeyBrandingQrtagResponse'
      x-evidence:
        kind: documentation
  /postcards/{cardkey}/branding/stamp:
    put:
      operationId: put_postcards_cardkey_branding_stamp
      tags:
      - Postcards
      summary: Add a stamp image (PUT /postcards/{cardKey}/branding/stamp).
      x-source: https://developer.post.ch/en/technical-specifications-of-postcard-api
      parameters:
      - name: cardkey
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutPostcardsCardkeyBrandingStampRequest'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PutPostcardsCardkeyBrandingStampResponse'
      x-evidence:
        kind: documentation
  /postcards/{cardkey}/branding/text:
    put:
      operationId: put_postcards_cardkey_branding_text
      tags:
      - Postcards
      summary: Add a branding block of type text (PUT /postcards/{cardKey}/branding/text).
      x-source: https://developer.post.ch/en/technical-specifications-of-postcard-api
      parameters:
      - name: cardkey
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutPostcardsCardkeyBrandingTextRequest'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PutPostcardsCardkeyBrandingTextResponse'
      x-evidence:
        kind: documentation
  /postcards/{cardkey}/image:
    put:
      operationId: put_postcards_cardkey_image
      tags:
      - Postcards
      summary: Add an image (PUT /postcards/{cardKey}/image).
      x-source: https://developer.post.ch/en/technical-specifications-of-postcard-api
      parameters:
      - name: cardkey
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutPostcardsCardkeyImageRequest'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PutPostcardsCardkeyImageResponse'
      x-evidence:
        kind: documentation
  /userinfo:
    get:
      operationId: get_userinfo
      tags:
      - Userinfo
      summary: GET /userinfo
      x-source: https://developer.post.ch/en/digital-commerce-api
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl -H Authorization: Bearer \neyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMjU2R0NNIn0.XpENWZLOwkvlwiY0TWCUZ2LTAbdP895E1BlAClqm- \nB3oHTehtMGkXCNudURQtwc\
          \ \nCVR23dYalRYLDP_huIHqwNjHoAYip2CsyiTrYQySp4wZzRb5Cm1QKvTq2yGfFUcK2qIqr7nFD_CEei8_ \nEpVHanYSE3srnWZkVEI8btQOg32bKOaidwLBaP \nLgFHfgom6l7n6ewh7UFv1WcRjk9Ug48oHUrpVQEBnu1pXr8gFEtEpmTZhT1TUCwUsyxzH36dkgzSZ4DHCvuIPDOtWpurQZQiu0OQVWd3ih2z7jSECXzUD7\
          \ \n9oIxqzN_pWNVeb4j"
  /wsws/soap/v6:
    get:
      operationId: get_wsws_soap_v6
      tags:
      - Wsws
      summary: GET /wsws/soap/v6
      x-source: https://developer.post.ch/en/webstamp-web-service-soap
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl https://cert.webstamp.post.ch/wsws/soap/v6 Target not accessible \n--cert certificate.pem:”*******” \n--data @soap-request.xml\
          \ \n Please note \n The default method is identification of the user with WS customer ID and WSWS password without signing. Implementation\
          \ with signing must always be agreed in advance with those responsible. \n If this method of identification is chosen, the system can\
          \ be s"
components:
  schemas:
    PostApiV1PostcardsRequest:
      type: object
      properties:
        recipientAddress:
          type: object
        senderAddress:
          type: object
        campaignKey:
          type: string
          description: Key identifying the campaign.
      required:
      - recipientAddress
      - campaignKey
    PostApiV1PostcardsResponse:
      type: object
      properties:
        cardKey:
          type: string
        errors:
          type: array
        warnings:
          type: array
    PutApiV1PostcardsCardkeyBrandingQrtagRequest:
      type: object
      properties:
        BRANDING_QR_ENCODED_TEXT:
          type: string
        BRANDING_QR_ACCOMPANYING_TEXT:
          type: string
        BRANDING_QR_TEXTCOLOR:
          type: string
        BRANDING_QR_BACKGROUND_COLOR:
          type: string
      required:
      - BRANDING_QR_ENCODED_TEXT
    PutApiV1PostcardsCardkeyBrandingQrtagResponse:
      type: object
      properties:
        cardKey:
          type: string
        warnings:
          type: array
    PostOrdersRequest:
      type: object
      properties:
        pickupAddress:
          type: object
          description: Address where the parcel will be picked up
        parcel:
          type: object
          description: Details of the parcel to be shipped
      required:
      - pickupAddress
      - parcel
    PostOrdersResponse:
      type: object
      properties:
        orderKey:
          type: string
          description: Unique identifier of the created order
        errors:
          type: array
          description: Array of error objects if the request failed validation
        warnings:
          type: array
          description: Array of warning objects
    PostOrdersOrderkeyApprovalResponse:
      type: object
      properties:
        orderKey:
          type: string
          description: Identifier of the approved order
        errors:
          type: array
          description: Array of error objects if approval failed
        warnings:
          type: array
          description: Array of warning objects
    PostPostcardsRequest:
      type: object
      properties:
        recipientAddress:
          type: object
          description: Recipient address fields (see address field list).
        senderAddress:
          type: object
          description: Sender address fields, required only if not pre‑configured in the campaign.
      required:
      - recipientAddress
    PostPostcardsResponse:
      type: object
      properties:
        cardKey:
          type: string
          description: Identifier of the created postcard.
        errors:
          type: array
          description: List of error objects if creation failed.
        warnings:
          type: array
          description: List of warning objects.
    PostPostcardsCardkeyApprovalResponse:
      type: object
      properties:
        cardKey:
          type: string
        status:
          type: string
          description: Approval status.
        warnings:
          type: array
    PutPostcardsCardkeyBrandingImageRequest:
      type: object
      properties:
        brandingImage:
          type: string
          description: JPEG or PNG image (777 × 295 px).
      required:
      - brandingImage
    PutPostcardsCardkeyBrandingImageResponse:
      type: object
      properties:
        cardKey:
          type: string
        warnings:
          type: array
    PutPostcardsCardkeyBrandingQrtagRequest:
      type: object
      properties:
        BRANDING_QR_ENCODED_TEXT:
          type: string
          description: Text to encode in QR (max 100 characters).
        BRANDING_QR_ACCOMPANYING_TEXT:
          type: string
          description: Accompanying text (max 250 characters).
        BRANDING_QR_TEXTCOLOR:
          type: string
          description: Hex color for QR text.
        BRANDING_QR_BACKGROUND_COLOR:
          type: string
          description: Hex background color for QR.
      required:
      - BRANDING_QR_ENCODED_TEXT
    PutPostcardsCardkeyBrandingQrtagResponse:
      type: object
      properties:
        cardKey:
          type: string
        warnings:
          type: array
    PutPostcardsCardkeyBrandingStampRequest:
      type: object
      properties:
        stampImage:
          type: string
          description: JPEG or PNG image (343 × 248 px).
      required:
      - stampImage
    PutPostcardsCardkeyBrandingStampResponse:
      type: object
      properties:
        cardKey:
          type: string
        warnings:
          type: array
    PutPostcardsCardkeyBrandingTextRequest:
      type: object
      properties:
        BRANDING_TEXT_TEXT:
          type: string
          description: Branding text (max 250 characters).
        BRANDING_TEXT_TEXTCOLOR:
          type: string
          description: 'Hex color value (e.g. #FFFFFF).'
        BRANDING_TEXT_BACKGROUND_COLOR:
          type: string
          description: Hex background color value.
      required:
      - BRANDING_TEXT_TEXT
    PutPostcardsCardkeyBrandingTextResponse:
      type: object
      properties:
        cardKey:
          type: string
        warnings:
          type: array
    PutPostcardsCardkeyImageRequest:
      type: object
      properties:
        imageFile:
          type: string
          description: JPEG or PNG image (1819 × 1311 px, 300 dpi).
      required:
      - imageFile
    PutPostcardsCardkeyImageResponse:
      type: object
      properties:
        cardKey:
          type: string
        warnings:
          type: array
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
security:
- bearer: []
tags:
- name: Api
- name: Oauth
- name: Orders
- name: Postcards
- name: Userinfo
- name: Wsws