ParcelOne Customs API

openapi: 3.2.0
info:
  title: Parcel.One Shipping REST Customs 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: customs
paths:
  /customs/reprint/{ShipmentRefField}/{ShipmentRefValue}:
    get:
      tags:
      - customs
      summary: reprint Customs Documents by Shipment Identification
      description: 'Reprint Customs Documents by Shipment Identification.

        Availabe formats are CN22 or CN23 (two documents per page). The CN22-document may contain up to 7 customs detail lines, the CN23-document will print up to 17 detail lines. If more than 7 detail lines, CN23 will be printed automatically.'
      operationId: reprintCustomsDocumentsForShipment
      parameters:
      - $ref: '#/components/parameters/ShipmentRefField'
      - $ref: '#/components/parameters/ShipmentRefValue'
      - $ref: '#/components/parameters/FormatType'
      - name: FormatSize
        in: query
        description: Desired Size of returned Document - CN23 or CN22
        required: false
        schema:
          type: string
          default: CN23
          enum:
          - CN22
          - CN23
      - $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/ShipmentDocumentsResult'
                  type: object
                - $ref: '#/components/schemas/ResultSuccess'
              examples:
                ResultSuccess:
                  summary: ResultSuccess
                  value:
                    status: 200
                    success: 1
                    message: OK
                    type: success
                    instance: /customs/reprint/trackingid/1234501016092
                    results:
                    - ShipmentID: '101610'
                      PackageID: '1'
                      TrackingID: '1234501016092'
                      DocType: CN23
                      Format:
                        Type: PDF
                        Size: A4
                        Unit: null
                        Orientation: null
                        Height: null
                        Width: null
                      Document: JVBERi0xLjcKJeLj...CN23-Document as Base64-String ...
                      Charges: null
                      PackageRef: null
                      PackageTrackingID: null
                      ActionResult: null
                    UniqId: 6499698a6f6e1
        '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: /customs/reprint/trackingid/1234501016092/packageid/1
                    errors:
                    - ErrorNo: '1003'
                      Message: This Shipment could not be uniquely identified.
                      StatusCode: Invalid parameters have been provided.
                    UniqId: 6499698a6f6e1
        '401':
          description: Authentification failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultError'
  /customs/reprint/{ShipmentRefField}/{ShipmentRefValue}/{PackageRefField}/{PackageRefValue}:
    get:
      tags:
      - customs
      summary: reprint Customs Documents by Shipment and Package Identification
      description: 'Reprint Customs Documents by Shipment and Package Identification.

        Availabe formats are CN22 or CN23 (two documents per page). The CN22-document may contain up to 7 customs detail lines, the CN23-document will print up to 17 detail lines. If more than 7 detail lines, CN23 will be printed automatically.'
      operationId: reprintCustomsDocumentsShipmentPackageID
      parameters:
      - $ref: '#/components/parameters/ShipmentRefField'
      - $ref: '#/components/parameters/ShipmentRefValue'
      - $ref: '#/components/parameters/PackageRefField'
      - $ref: '#/components/parameters/PackageRefValue'
      - $ref: '#/components/parameters/FormatType'
      - name: FormatSize
        in: query
        description: Desired Size of returned Document - CN23 or CN22
        required: false
        schema:
          type: string
          default: CN23
          enum:
          - CN22
          - CN23
      - $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/ShipmentDocumentsResult'
                  type: object
                - $ref: '#/components/schemas/ResultSuccess'
              examples:
                ResultSuccess:
                  summary: ResultSuccess
                  value:
                    status: 200
                    success: 1
                    message: OK
                    type: success
                    instance: /customs/reprint/trackingid/1234501016092/packageid/1
                    results:
                    - ShipmentID: '101610'
                      PackageID: '1'
                      TrackingID: '1234501016092'
                      DocType: CN23
                      Format:
                        Type: PDF
                        Size: A4
                        Unit: null
                        Orientation: null
                        Height: null
                        Width: null
                      Document: JVBERi0xLjcKJeLj...CN23-Document as Base64-String ...
                      Charges: null
                      PackageRef: null
                      PackageTrackingID: null
                      ActionResult: null
                    UniqId: 6499698a6f6e1
        '404':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultError'
              examples:
                ResultError:
                  summary: ResultError
                  value:
                    status: 404
                    success: -1
                    message: Not found
                    type: error
                    instance: /customs/reprint/trackingid/1234501016092/packageid/1
                    errors:
                    - ErrorNo: '1003'
                      Message: This Shipment could not be uniquely identified.
                      StatusCode: Invalid parameters have been provided.
                    UniqId: 6499698a6f6e1
        '401':
          description: Authentification failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultError'
  /customs:
    post:
      tags:
      - customs
      summary: Register Customs Data
      description: 'Register Customs Data for a Shipment that has been already created.

        Customs information may be either registered immediately when registering a shipment, or registered afterwards for a created shipment with this path-function. A CN22 or CN23-document (two documents per page) will be returned. The CN22-document may contain up to 7 customs detail lines, the CN23-document will print up to 17 detail lines. If more than 7 detail lines, CN23 will be printed automatically.

        For customs detail lines, you can either provide netweight and itemvalue as a sum for the specified item quantity or specify netweightperitem and itemvalueperitem for a quantity of 1. In this case - but only if netweight and itemvalue fields are null or 0 - the netweight and itemvalue will be multiplied by provided quantity automatically.'
      operationId: registerCustomsData
      parameters:
      - $ref: '#/components/parameters/Lang'
      - $ref: '#/components/parameters/Getaccesstoken'
      requestBody:
        description: Provide International Customs Data for a specific already existing Shipment/Package
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IntDocData'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                allOf:
                - properties:
                    results:
                      type: array
                      items:
                        $ref: '#/components/schemas/ShipmentDocumentsResult'
                  type: object
                - $ref: '#/components/schemas/ResultSuccess'
              examples:
                ResultSuccess:
                  summary: ResultSuccess
                  value:
                    status: 200
                    success: 1
                    message: OK
                    type: success
                    instance: /customs
                    results:
                    - ShipmentID: '101610'
                      PackageID: '1'
                      TrackingID: '1234501016092'
                      DocType: CN23
                      Format:
                        Type: PDF
                        Size: A4
                        Unit: null
                        Orientation: null
                        Height: null
                        Width: null
                      Document: JVBERi0xLjcKJeLj...CN23-Document as Base64-String ...
                      Charges: null
                      PackageRef: null
                      PackageTrackingID: null
                      ActionResult: null
                    UniqId: 6499698a6f6e1
        '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: /customs/reprint/trackingid/1234501016092/packageid/1
                    errors:
                    - ErrorNo: '1003'
                      Message: This Shipment could not be uniquely identified.
                      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: /customs/reprint/trackingid/1234501016092/packageid/1
                    errors:
                    - ErrorNo: '1014'
                      Message: The following fields exceed the allowed maximal fieldlength or value:...
                      StatusCode: Invalid parameters have been provided.
                    UniqId: 6499698a6f6e1
        '401':
          description: Authentification failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultError'
components:
  parameters:
    ShipmentRefValue:
      name: ShipmentRefValue
      in: path
      description: Value of Reference for search
      required: true
      schema:
        type: string
    ShipmentRefField:
      name: ShipmentRefField
      in: path
      description: Kind of Reference search field
      required: true
      schema:
        type: string
        default: trackingid
        enum:
        - shipmentid
        - shipmentref
        - trackingid
    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'
    FormatType:
      name: FormatType
      in: query
      description: Format Type for PrintDocument
      required: true
      schema:
        type: string
        default: PDF
        enum:
        - GIF
        - PDF
        - ZPL203
        - ZPL300
    Lang:
      name: Lang
      in: header
      description: Header-flag to control multilingual properties
      required: false
      schema:
        type: string
        default: en
        enum:
        - en
        - de
        - es
    PackageRefField:
      name: PackageRefField
      in: path
      description: Kind of Reference search field
      required: true
      schema:
        type: string
        default: trackingid
        enum:
        - packageid
        - packageref
        - packagetrackingid
    PackageRefValue:
      name: PackageRefValue
      in: path
      description: Value of Reference for search
      required: true
      schema:
        type: string
  schemas:
    ShipmentError:
      properties:
        ErrorNo:
          description: '- MaxLen 4'
          type: string
        Message:
          description: '- no Maxlimit'
          type: string
        StatusCode:
          description: '- MaxLen 20'
          type: string
      type: object
      xml: {}
    AddInfo:
      description: 'for Customs and CustomsDetails so far: Key: free definable additional Info, Value: free definalbe additional values for customs handling'
      properties:
        Key:
          type: string
        Value:
          type: string
      type: object
    IntDoc:
      description: InternationalDocumentFormat:Type PDF,GIF,ZPL203 or ZPL300, Size CN22,CN23
      properties:
        PrintInternationalDocuments:
          description: '- bool'
          type: integer
          example: 1
        InternationalDocumentFormat:
          $ref: '#/components/schemas/Format'
        ConsignerCustomsID:
          description: '- MaxLen 20'
          type: string
          example: '1234567890'
        ShipToRef:
          description: '- MaxLen 80'
          type: string
          example: 'Phone: +49 123123123'
        CustomDetails:
          type: array
          items:
            $ref: '#/components/schemas/IntDocContents'
        Postage:
          description: '- Format 9999999999.99'
          type: string
          example: 2.34
        TotalValue:
          description: '- Format 9999999999.99'
          type: string
          example: 236.34
        Currency:
          description: '- MaxLen 3'
          type: string
          example: EUR
        TotalWeightkg:
          description: '- Format 999999999.999'
          type: string
          example: 12.345
        ItemCategory:
          description: '- 1-Gift, 2-Documents, 3-Commercial Sample, 4-Returned Goods, 5-Other'
          type: integer
          example: 3
        Explanation:
          description: '- MaxLen 100'
          type: string
          example: Explanation
        OfficeOfOrigin:
          description: '- MaxLen 40'
          type: string
          example: OfficeOfOrigin
        Comments:
          description: '- MaxLen 40'
          type: string
          example: Comments
        Date:
          description: '- Format YYYYY-MM-DD'
          type: string
          example: '2022-01-11'
        License:
          description: '- bool'
          type: integer
          example: 0
        LicenseNo:
          description: '- MaxLen 25'
          type: string
          example: ''
        Certificate:
          description: '- bool'
          type: integer
          example: 0
        CertificateNo:
          description: '- MaxLen 25'
          type: string
          example: ''
        Invoice:
          description: '- bool'
          type: integer
          example: 1
        InvoiceNo:
          description: '- MaxLen 25'
          type: string
          example: 'Ivoice: 123456789'
        NonDeliveryInstruction:
          description: '- MaxLen 50'
          type: string
          example: ''
        ServiceLevel:
          description: '- MaxLen 10'
          type: string
          example: ''
        ValidatedForExport:
          description: '- bool'
          type: integer
          example: ''
        AdditionalInfo:
          description: '- additionalInfo'
          type: array
          items:
            $ref: '#/components/schemas/AddInfo'
          example: ''
      type: object
    IntDocContents:
      description: Customs Details - if you only specify ItemValuePerItem and NetWeightPerItem, NetWeight and ItemValue will be multiplied by Quantity automatically.
      properties:
        Contents:
          description: '- MaxLen 60'
          type: string
          example: Item of Contents of the Package
        Quantity:
          type: integer
          example: 33
        NetWeightPerItem:
          description: '- Format 999999999.999'
          type: string
          example: 3.456
        NetWeight:
          description: '- Format 999999999.999'
          type: string
          example: 3.456
        ItemValuePerItem:
          description: '- Format 9999999999.99'
          type: string
          example: 13.33
        ItemValue:
          description: '- Format 9999999999.99'
          type: string
          example: 13.33
        TariffNumber:
          description: '- MaxLen 15'
          type: string
          example: '1234567890'
        Origin:
          description: '- MaxLen 40'
          type: string
          example: DE
        AdditionalInfo:
          description: '- additionalInfo'
          type: array
          items:
            $ref: '#/components/schemas/AddInfo'
          example: ''
      type: object
    ShipmentDocumentsResult:
      properties:
        ShipmentID:
          description: '- MaxLen 20'
          type: string
        PackageID:
          description: '- MaxLen 20'
          type: string
        TrackingID:
          description: '- MaxLen 20'
          type: string
        DocType:
          description: '- MaxLen 25'
          type: string
        Format:
          $ref: '#/components/schemas/Format'
        Document:
          description: '- no Maxlimit'
          type: string
        Charges:
          type: array
          items:
            $ref: '#/components/schemas/Amount'
        PackageRef:
          description: '- MaxLen 20'
          type: string
        PackageTrackingID:
          description: '- MaxLen 20'
          type: string
        ActionResult:
          $ref: '#/components/schemas/ShipmentActionResult'
        DocumentID:
          description: '- MaxLen 50'
          type: string
      type: object
      xml: {}
    identifyPackage:
      properties:
        PackageRefField:
          description: '- MaxLen 20'
          type: string
          default: trackingid
          enum:
          - packageid
          - packageref
          - packagetrackingid
          example: packageid
        PackageRefValue:
          description: '- MaxLen 20'
          type: string
          example: '1'
      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
    ShipmentWarning:
      properties:
        WarningNo:
          description: '- MaxLen 4'
          type: string
        Message:
          description: '- no Maxlimit'
          type: string
        StatusCode:
          description: '- MaxLen 20'
          type: string
      type: object
      xml: {}
    IntDocData:
      properties:
        IDShipment:
          $ref: '#/components/schemas/identifyShipment'
        IDPackage:
          $ref: '#/components/schemas/identifyPackage'
        IntDocData:
          $ref: '#/components/schemas/IntDoc'
      type: object
      xml: {}
    ShipmentActionResult:
      description: Additional ActionResult for detailed information about shipments or errors
      properties:
        ShipmentID:
          description: '- MaxLen 20'
          type: string
          example: '101415'
        ShipmentRef:
          description: '- MaxLen 20'
          type: string
          example: custref_123
        TrackingID:
          description: '- MaxLen 20'
          type: string
          example: '1234501014159'
        Success:
          description: '- bool'
          type: integer
          example: 1
        Errors:
          type: array
          items:
            $ref: '#/components/schemas/ShipmentError'
        Warnings:
          type: array
          items:
            $ref: '#/components/schemas/ShipmentWarning'
      type: object
    Amount:
      description: Amount common format
      required:
      - Currency
      - Value
      properties:
        Currency:
          description: '- MaxLen 3 - ISO 4217'
          type: string
        Value:
          description: '- Format 9999999999.99'
          type: string
        Description:
          description: '- no Maxlimit'
          type: string
      type: object
    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
    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: {}
    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
  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