openapi: 3.0.0
info:
  description: >-
    The Paazl Push API pro-actively sends delivery status updates to your webshop server every time there is a change in a shipment's status. 
  version: 1.0.0
  title: Paazl Push API
tags:
  - name: endpoint
    description: receives Paazl Push API requests.
servers:
  - url: 'your_endpoint_url'
    description: >-
      must have the same value as the the "PUSH NOTIFICATIONS URL" in your Paazl web app account under Settings > Account > Status events push notifications.
paths:
  /endpoint:
    post:
      security:
        - bearerAuth: [your_security_token]
      tags:
        - endpoint
      summary: Endpoint receiving Push API requests
      description: >-
        must have the value you generated in the "SECURITY TOKEN" field in your Paazl web app account under Settings > Account > Status events push notifications
      operationId: addStatus
      requestBody:
        description: Push notification object that is sent by the Paazl Push API.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LabelStatusNotification'
          application/xml:
            schema:
              $ref: '#/components/schemas/LabelStatusNotification'
      responses:
        2XX:
          description: Status notification sucessfully received 
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  schemas:
    LabelStatusNotification:
      type: object
      properties:
        orderReference:
          description: order reference code
          type: string
          example: myOrder00123
          xml:
            prefix: ns2
        webshop:
          description: Paazl internal code for webshop
          type: integer
          format: int32
          example: 697
          xml:
            prefix: ns2
        barcode:
          description: Shipping label's barcode
          type: string
          example: AABBCCEEFFG
          xml:
            prefix: ns2
        status:
          description: Status mapped by Paazl
          type: string
          enum:
            - CREATED
            - DELETED
            - READY_TO_POST
            - SCANNED
            - AVAILABLE_AT_PICKUP_POINT
            - DELIVERED
            - DELIVEREDBB
            - RETOUR
            - PICKEDUP
            - UITLEVERING
            - UNKNOWN
            - MANCO
            - NOT_AT_HOME
          example: UITLEVERING
          xml:
            prefix: ns2
        carrierStatus:
          $ref: '#/components/schemas/CarrierStatus'
        deliveryDate:
          description: Delivery date and time
          type: string
          format: date-time
          example: '2017-07-17T16:00'
          xml:
            prefix: ns2
        trackTraceURL:
          description: Track and trace link for carrier
          type: string
          example: >-
            https://www.carrier.nl/track-trace?gclid=CPfEzday
          xml:
            prefix: ns2
        deliveryWindowStart:
          description: global start of a delivery time range
          type: string
          format: time
          example: '08:00'
          xml:
            prefix: ns2
        deliveryWindowEnd:
          description: global end of a delivery time range
          type: string
          format: time
          example: '13:00'
          xml:
            prefix: ns2
        deliveryInformation:
          description: currently not in use
          type: string
          example: If not at home, deliver at neighbor
          xml:
            prefix: ns2
      xml:
        prefix: ns2
        namespace: 'http://www.paazl.com/schemas/push'
    CarrierStatus:
      description: currently not in use
      type: object
      properties:
        name:
          description: currently not in use
          type: string
          example: Scanned
          xml:
            prefix: ns2
        description:
          description: Shipment awaiting pickup in warehouse
          type: string
          example: none
          xml:
            prefix: ns2
      xml:
        prefix: ns2
externalDocs:
  description: See Paazl Online Help
  url: 'https://support.paazl.com/hc/en-us/articles/360020981294-About-Paazl-s-Push-API'