ParcelOne Closing API

openapi: 3.2.0
info:
  title: Parcel.One Shipping REST Closing API
  description: 'ParcelOne https://parcel.one provides you with a REST API for implementing an interface to ParcelOne shipping services into your own shop/warehouse or, respectively, into the shops/warehouses of your customers. ___

    This documentation was created adhering to the OpenAPI 3.0 standard. We use Swagger.IO tool for display. If you prefer to use another OpenAPI-Tool or want to implement this into your own environment, you may download the underlying OpenAPI-Document from here:

    * JSON-Format

    * YAML-Format

    ___

    ## Basic Implementation Principles

    ### Sandbox and Production-Modes

    In order to be able to test your implementation without interfering production environment, we provide a SandBox-Mode as well as a Production-Mode. The URLs:

    * Sandbox: https://sandbox.parcelone.io/shippingapi/v1

    * Production: https://production.parcelone.io/shippingapi/v1


    Please, use the Sandbox mode to test your client application thoroughly before switching to Production mode. In Sandbox mode all data will be saved to a separate database. ### Dynamic Approach

    Differenty from other carriers, Parcel.one provides a products and services structure that may vary for different customers. Therefore, we strongly recommend not to use hardcoded products and services identifiers, but to use a dynamic approach using the profile-functions to get the products and services hierarchy and show it dynamically in your client UI! Also there may be several mandators and for each mandator several consigner/sender-addresses. Every mandator can have a different portfolio of products/services. So, please, strongly consider a dynamic approach! To get acquainted with the dynamic mandator, consigner, Carriers and Products/Services setup, please, start with the customer- and profile-path-functions. ___

    ## Verification and Validation process

    After we took a careful look to your shipments in our sandbox environment to validate your integration, you will be provided with access to our production environment. For the validation of your implementation, we will look for the following items, which you should consider carefully while developing your software:

    > Provision of an own string in the data field ''Software'' (including a version number) to make your implementation identifiable


    > Creation of shipping labels

    > > to various recipients

    > > including a phone and/or mobile phone number of the recipient

    > > including an eMail address of the recipient

    > > with different recipient addresses

    > > in different destination countries

    > > EU and non-EU shipments

    > > using various PARCEL.ONE products

    > > with various combinations of optional services, that can be applied

    > > with different weights for shipments

    > > providing the dimensions of the shipment, even if you intend to skip providing them or to provide default values in production use

    > > providing full customs information for all shipments to non EU countries, even if you currently do not intend to ship to such countries

    > Cancellation of shipping labels


    We are listing these points in such detail as we want to see in advance, that your implementation is capable to provide all parameters for creating shipments and that you have understood our API and the products PARCEL.ONE provides. This will save both of us a lot of trouble in the future, when production mode is going on. Please contact us as soon as you have completed your creation of your test shipments that we may start immediately with our evaluation. ___

    ## Authentification

    Authentification is provided by Basic Authentification secured over SSL. Further authentification is done via an API-Key to authenificate the provider of the software accessing the API. If you are a platform provider for Parcel.One clients, please, keep in mind, that the ApiKey is only as an identification for you and should not be provided to or even be edited in the UI by the users of your platform.'
  termsOfService: https://parcel.one/en/data-security
  contact:
    name: Contact our support
    url: https://parcel.one/en/contact
    email: support@parcel.one
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
servers:
- url: https://sandbox.parcelone.io/shippingapi/v1
  description: Parcel.One Shipping REST API - Sandbox
security:
- api_key: []
  BasicAuth: []
  Bearer_JWT: []
tags:
- name: closing
paths:
  /closing/closable/{mandator}/{consigner}/{cep}/{startdate}/{enddate}:
    get:
      tags:
      - closing
      summary: get closable shipments as csv, separated by Ceps
      description: 'get closable shipments as csv files, one for each Cep/Carrier

        Closing is not necessary for availability for Shipping. It solely marks shipments as closed and returns a report for your use. For DHL it does NOT perform the actual DHL closing, this will be done automatically by DHL Background Services once a day.)

        This path-function CLOSABLE provides a list of shipments that are available for your closing. Results can be filtered by several parameters. Only shipments created by the same API-Key are considered to avoid conflicts.'
      operationId: getClosable
      parameters:
      - name: mandator
        in: path
        description: Mandator - maybe '*' for all or specific mandator
        required: true
        schema:
          type: string
          default: '*'
      - name: consigner
        in: path
        description: Consigner or Sender - maybe '*' for all or specific consigner of specified mandator
        required: true
        schema:
          type: string
          default: '*'
      - name: cep
        in: path
        description: Cep or Carrier - maybe '*' for all or specific
        required: true
        schema:
          type: string
          default: '*'
          enum:
          - '*'
          - DHL
          - PA1
          - UPS
      - name: startdate
        in: path
        description: StartDate in format 'YYYYMMDD' - maybe '*' for all or specific date
        required: true
        schema:
          type: string
          default: '*'
      - name: enddate
        in: path
        description: EndDate in format 'YYYYMMDD' - maybe '*' for all or specific date
        required: true
        schema:
          type: string
          default: '*'
      - $ref: '#/components/parameters/Lang'
      - $ref: '#/components/parameters/Getaccesstoken'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                allOf:
                - properties:
                    results:
                      type: array
                      items:
                        $ref: '#/components/schemas/Document'
                  type: object
                - $ref: '#/components/schemas/ResultSuccess'
              examples:
                ResultSuccess:
                  summary: ResultSuccess
                  value:
                    status: 200
                    success: 1
                    message: OK
                    type: success
                    instance: /closing/closable/...
                    results:
                    - DocType: PA1
                      Format:
                        Type: CSV
                        Size: null
                        Unit: null
                        Orientation: 0
                        Height: null
                        Width: null
                      Document: U2hpc... CSV-List as Base64-document ...
                    UniqId: 6499698a6f6e1
        '401':
          description: Authentification failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultError'
  /closing/stamps/{mandator}/{consigner}/{cep}/{startdate}/{enddate}:
    get:
      tags:
      - closing
      summary: get ClosedStamps as Array of Strings
      description: 'get ClosedStamps as Array of Strings

        Closing is not necessary for availability for Shipping. It solely marks shipments as closed and returns a report for your use. For DHL it does NOT perform the actual DHL closing, this will be done automatically by DHL Background Services once a day.)

        This path-function STAMPS provides a list of closing stamps for shipments that have been closed already, filtered by several parameters. Only shipments created by the same API-Key are considered to avoid conflicts.'
      operationId: getClosedStamps
      parameters:
      - name: mandator
        in: path
        description: Mandator - maybe '*' for all or specific mandator
        required: true
        schema:
          type: string
          default: '*'
      - name: consigner
        in: path
        description: Consigner or Sender - maybe '*' for all or specific consigner of specified mandator
        required: true
        schema:
          type: string
          default: '*'
      - name: cep
        in: path
        description: Cep or Carrier - maybe '*' for all or specific
        required: true
        schema:
          type: string
          default: '*'
          enum:
          - '*'
          - DHL
          - PA1
          - UPS
      - name: startdate
        in: path
        description: StartDate in format 'YYYYMMDD' - maybe '*' for all or specific date
        required: true
        schema:
          type: string
          default: '*'
      - name: enddate
        in: path
        description: EndDate in format 'YYYYMMDD' - maybe '*' for all or specific date
        required: true
        schema:
          type: string
          default: '*'
      - $ref: '#/components/parameters/Lang'
      - $ref: '#/components/parameters/Getaccesstoken'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                allOf:
                - properties:
                    results:
                      type: array
                      items:
                        type: string
                  type: object
                - $ref: '#/components/schemas/ResultSuccess'
              examples:
                ResultSuccess:
                  summary: ResultSuccess
                  value:
                    status: 200
                    success: 1
                    message: OK
                    type: success
                    instance: /closing/stamps/...
                    results:
                    - 20210217103852PA1
                    - 20210217152939PA1
                    - 20211210112408PA1
                    - 20211210112408UPS
                    UniqId: 6499698a6f6e1
        '401':
          description: Authentification failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultError'
  /closing/reprint/{closedStamp}:
    get:
      tags:
      - closing
      summary: reprint Closing List
      description: 'reprint Closing List as a CSV file or as a PDF document

        Closing is not necessary for availability for Shipping. It solely marks shipments as closed and returns a report for your use. For DHL it does NOT perform the actual DHL closing, this will be done automatically by DHL Background Services once a day.)

        This path-function REPRINT reprints a closing list by specifying the ClosedStamp as a parameter. Output may be CSV or PDF. Only shipments created by the same API-Key are considered to avoid conflicts.'
      operationId: reprintClosingList
      parameters:
      - name: closedStamp
        in: path
        description: ClosedStamp to reprint
        required: true
        schema:
          type: string
      - name: FormatType
        in: query
        description: OutputType for ClosingList - CSV file or PDF document
        required: false
        schema:
          type: string
          default: PDF
          enum:
          - CSV
          - PDF
      - $ref: '#/components/parameters/Lang'
      - $ref: '#/components/parameters/Getaccesstoken'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                allOf:
                - properties:
                    results:
                      $ref: '#/components/schemas/Document'
                  type: object
                - $ref: '#/components/schemas/ResultSuccess'
              examples:
                ResultSuccess:
                  summary: ResultSuccess
                  value:
                    status: 200
                    success: 1
                    message: OK
                    type: success
                    instance: /closing/reprint/{closedStamp}
                    results:
                      ClosedStamp: 20210217103852PA1
                      CEP: PA1
                      Document:
                        DocType: ClosedReport
                        Format:
                          Type: PDF
                          Size: A4
                          Unit: null
                          Orientation: 0
                          Height: null
                          Width: null
                        Document: JVBERi0xLjcKJe... - ClosedReport as Base64-PDF...
                    UniqId: 6499698a6f6e1
        '401':
          description: Authentification failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultError'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultError'
              examples:
                ResultError:
                  summary: ResultError
                  value:
                    status: 404
                    success: -1
                    message: Not found
                    type: error
                    instance: /closing/reprint/{closedStamp}
                    errors:
                    - ErrorNo: '1008'
                      Message: This ClosedStamp could not be found.
                      StatusCode: Invalid parameters have been provided.
                    UniqId: 6499698a6f6e1
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultError'
              examples:
                ResultError:
                  summary: ResultError
                  value:
                    status: 422
                    success: -1
                    message: Validation Error
                    type: error
                    instance: /closing/reprint/{closedStamp}
                    errors:
                    - ErrorNo: '1395'
                      Message: 'Missing parameter: ClosedStamp'
                      StatusCode: Invalid parameters have been provided.
                    UniqId: 6499698a6f6e1
  /closing:
    post:
      tags:
      - closing
      summary: Close Shipments
      description: 'Closing Shipments as filtered by given parameters, returns ClosingLists as CSV or PDF, one for each CEP/Carrier concerned.

        Closing is not necessary for availability for Shipping. It solely marks shipments as closed and returns a report for your use. For DHL it does NOT perform the actual DHL closing, this will be done automatically by DHL Background Services once a day.)

        This is the main function to perform the actual closing. You can filter shipments to close by several parameters. Only shipments created by the same API-Key are considered to avoid conflicts.'
      operationId: closeShipments
      parameters:
      - $ref: '#/components/parameters/Lang'
      - $ref: '#/components/parameters/Getaccesstoken'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                Mandator:
                  type: string
                Consigner:
                  type: string
                CEP:
                  type: string
                Format:
                  $ref: '#/components/schemas/Format'
                Shipments:
                  type: array
                  items:
                    $ref: '#/components/schemas/identifyShipment'
              type: object
              example:
                Mandator: '1'
                Consigner: '1'
                CEP: ''
                Format:
                  Type: PDF
                Shipments:
                - ShipmentRefField: TrackingID
                  ShipmentRefValue: '1234501014159'
                - ShipmentRefField: ShipmentID
                  ShipmentRefValue: '101416'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                allOf:
                - properties:
                    results:
                      type: array
                      items:
                        $ref: '#/components/schemas/ClosedResult'
                  type: object
                - $ref: '#/components/schemas/ResultSuccess'
              examples:
                ResultSuccess:
                  summary: ResultSuccess
                  value:
                    status: 200
                    success: 1
                    message: OK
                    type: success
                    instance: /closing
                    results:
                    - ClosedStamp: 20210217103852PA1
                      CEP: PA1
                      Document:
                        DocType: ClosedReport
                        Format:
                          Type: PDF
                          Size: A4
                          Unit: null
                          Orientation: 0
                          Height: null
                          Width: null
                        Document: JVBERi0xLjcKJe... - ClosedReport as Base64-PDF...
                    - ClosedStamp: 20210217103852UPS
                      CEP: UPS
                      Document:
                        DocType: ClosedReport
                        Format:
                          Type: PDF
                          Size: A4
                          Unit: null
                          Orientation: 0
                          Height: null
                          Width: null
                        Document: JVBERi0xLjcKJe... - ClosedReport as Base64-PDF...
                    UniqId: 6499698a6f6e1
        '401':
          description: Authentification failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultError'
components:
  schemas:
    ResultSuccess:
      description: Success Result basic structure - extended by individual Results
      properties:
        status:
          description: '- 3 digits http-Status-Code'
          type: integer
          example: 200
        success:
          description: '- 1 for Success'
          type: integer
          format: int32
          example: 1
        message:
          description: '- Short Message of http-Status'
          type: string
          example: OK
        type:
          description: '- value ''success'''
          type: string
          example: success
        instance:
          description: '- URL Request Path'
          type: string
          example: '...your request path...'
        UniqId:
          description: '- Unique Request Id for Log Reference'
          type: string
          example: 649956bfd9eb0
      type: object
    ShipmentError:
      properties:
        ErrorNo:
          description: '- MaxLen 4'
          type: string
        Message:
          description: '- no Maxlimit'
          type: string
        StatusCode:
          description: '- MaxLen 20'
          type: string
      type: object
      xml: {}
    ResultError:
      description: Error-Result
      properties:
        status:
          description: '- 3 digits http-Status-Code'
          type: integer
          format: int32
          example: 401
        success:
          description: '- -1 for Error'
          type: integer
          format: int32
          example: -1
        message:
          description: '- Short Message of http-Status'
          type: string
          example: Unauthorized
        type:
          description: '- value ''error'''
          type: string
          example: error
        instance:
          description: '- URL Request Path'
          type: string
          example: '...your request path...'
        errors:
          description: '- Detailed Errors'
          type: array
          items:
            $ref: '#/components/schemas/ShipmentError'
          example:
          - ErrorNo: 4012
            Message: Wrong ApiKey for access to WebService.
            StatusCode: Authentification failed
        UniqId:
          description: '- Unique Request Id for Log Reference'
          type: string
          example: 649956bfd9eb0
      type: object
    identifyShipment:
      properties:
        ShipmentRefField:
          description: '- MaxLen 20'
          type: string
          default: trackingid
          enum:
          - shipmentid
          - shipmentref
          - trackingid
          example: trackingid
        ShipmentRefValue:
          description: '- MaxLen 20'
          type: string
          example: '1234501045644'
      type: object
      xml: {}
    Document:
      properties:
        DocType:
          description: '- MaxLen 25'
          type: string
        Format:
          $ref: '#/components/schemas/Format'
        Document:
          description: '- no Maxlimit'
          type: string
      type: object
      xml: {}
    Format:
      description: common Format
      properties:
        Type:
          description: '- MaxLen 10 - for printing in most cases: GIF,PDF, ZPL203, ZPL300'
          type: string
          example: PDF
        Size:
          description: '- no Maxlimit - for printing of Customs documents: CN22, CN23, in other cases so far no effects on fixed return formats'
          type: string
          example: A4
        Unit:
          description: '- no Maxlimit - for future use'
          type: string
          example: ''
        Orientation:
          description: '- 0=Portrait, 1=Landscape'
          type: integer
          default: 0
          enum:
          - 0
          - 1
          example: 0
        Height:
          description: '- Format 9999999999.99 - for future use'
          type: string
          example: ''
        Width:
          description: '- Format 9999999999.99 - for future use'
          type: string
          example: ''
      type: object
    ClosedResult:
      properties:
        ClosedStamp:
          description: '- MaxLen 20'
          type: string
        CEP:
          description: '- MaxLen 3'
          type: string
        Document:
          $ref: '#/components/schemas/Document'
      type: object
      xml: {}
  parameters:
    Getaccesstoken:
      name: Getaccesstoken
      in: header
      description: Header-flag to return JWT Access Token, insert 'true' to send this header
      required: false
      schema:
        type: string
        enum:
        - 'true'
    Lang:
      name: Lang
      in: header
      description: Header-flag to control multilingual properties
      required: false
      schema:
        type: string
        default: en
        enum:
        - en
        - de
        - es
  securitySchemes:
    api_key:
      type: apiKey
      name: Apikey
      in: header
    BasicAuth:
      type: http
      scheme: basic
    Bearer_JWT:
      type: http
      bearerFormat: JWT
      scheme: bearer
externalDocs:
  description: Find out more about Parcel.One
  url: http://parcel.one