openapi: 3.1.0
info:
  title: Parcel Documents
  description: >
    For international shipments, customs documentation is generated alongside
    the shipping label. These documents can be downloaded separately from the
    shipping label in various formats and resolutions via this endpoint.
  version: 2.0.0
  contact:
    name: Sendcloud API Support
    url: https://www.sendcloud.dev
    email: contact@sendcloud.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
  - url: https://panel.sendcloud.sc/api/v2
    description: Sendcloud Production
tags:
  - name: Parcel Documents
paths:
  /parcels/{id}/documents/{type}:
    get:
      summary: Retrieve parcel documents
      x-mint:
        href: /api/v2/parcel-documents/retrieve-parcel-documents
        content: >-
          <Warning>
            **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3).
          </Warning>


          For international shipments, a commercial invoice, CN23 or CN22
          (+CP71) form must be attached (either physically or
          [digitally](https://support.sendcloud.com/hc/en-us/articles/4417349714452-Send-your-customs-documents-digitally-via-Paperless-Trade-)
          for some carriers) to the shipment for customs officials to access.
          The type of document required depends on the shipping method and value
          of the shipment.


          When you use the [Create a parcel or
          parcels](/api/v2/parcels/create-a-parcel-or-parcels) endpoint,
          Sendcloud generates the correct type of document for your shipment if
          you have filled in all the information related to the parcel contents,
          value, and invoice. Use this endpoint to retrieve these documents in
          your preferred format.


          The supported document types are as follows:


          - `air-waybill`

          - `cn23`

          - `cn23-default`

          - `commercial-invoice`

          - `cp71`

          - `label`

          - `qr`
      description: >-
        Retrieve a document for a given parcel by providing the parcel `id` and
        document `type`.
      tags:
        - Parcel Documents
      responses:
        '200':
          description: Requested parcel document file
          content:
            application/pdf:
              schema:
                type: string
                format: binary
            application/zpl:
              schema:
                type: string
                format: binary
            image/png:
              schema:
                type: string
                format: binary
        '404':
          description: Document type requested is not available for the parcel
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: integer
                        description: HTTP error code
                        example: 404
                      request:
                        type: string
                        description: Endpoint URL that was requested
                        example: api/v2/parcels/1/documents/commercial-invoice
                      message:
                        type: string
                        description: A human readable error message
                        example: No Parcel matches the given query.
              examples:
                NotFound:
                  summary: Parcel Document Not Found
                  value:
                    error:
                      code: 404
                      request: api/v2/parcels/1/documents/commercial-invoice
                      message: No Parcel matches the given query.
                document_type_not_found:
                  summary: Document Type Not Found
                  value:
                    error:
                      code: 404
                      request: api/v2/parcels/1/documents/not-existing-document-type
                      message: Not found.
      operationId: sc-public-v2-scp-get-retrieve_parcel_documents
      security:
        - HTTPBasicAuth: []
        - OAuth2ClientCreds: []
      parameters:
        - $ref: '#/components/parameters/dpi'
        - $ref: '#/components/parameters/rendering_format'
        - $ref: '#/components/parameters/raw'
    parameters:
      - $ref: '#/components/parameters/id'
      - $ref: '#/components/parameters/type'
components:
  securitySchemes:
    HTTPBasicAuth:
      type: http
      description: >-
        Basic Authentication using API key and secrets is currently the main
        authentication mechanism.
      scheme: basic
    OAuth2ClientCreds:
      type: oauth2
      description: >-
        OAuth2 is a standardized protocol for authorization that allows users to
        share their private resources stored on one site with another site
        without having to provide their credentials. OAuth2 Client Credentials
        Grant workflow. This workflow is typically used for server-to-server
        interactions that require authorization to access specific resources.
      flows:
        clientCredentials:
          tokenUrl: https://account.sendcloud.com/oauth2/token/
          scopes:
            api: Default OAuth scope required to access Sendcloud API.
  parameters:
    id:
      name: id
      in: path
      schema:
        type: integer
        example: 1
        minimum: 1
      description: Identifier of the parcel which you want to retrieve a document from
      required: true
    type:
      name: type
      in: path
      schema:
        type: string
        example: commercial-invoice
        enum:
          - air-waybill
          - cn23
          - cn23-default
          - commercial-invoice
          - cp71
          - label
          - qr
      description: Document type you want to retrieve for this parcel
      required: true
    dpi:
      name: dpi
      in: query
      required: false
      schema:
        type: integer
        default: 72
        enum:
          - 72
          - 150
          - 203
          - 300
          - 600
        example: 300
        minimum: 1
      description: >
        DPI refers to the printing resolution of your shipping labels. It's
        important that labels are printed at a high enough resolution to ensure
        the clarity of address details and the barcode for scanning purposes.

        Use following amounts for appropriate result:

        <table>
          <thead>
            <tr>
              <th>File format</th>
              <th>Default DPI</th>
              <th>Valid DPI</th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <td>pdf</td>
              <td>72</td>
              <td>72</td>
            </tr>
            <tr>
              <td>png</td>
              <td>300</td>
              <td>150, 300</td>
            </tr>
          </tbody>
        </table>

        ZPL labels are not affected by the DPI setting, as the resolution is
        determined by the carrier itself. Most carriers use a resolution of 203
        DPI. Zebra printers need to be configured to print at the specific DPI
        of the label if they have higher resolution capabilities.
    rendering_format:
      name: Accept
      in: header
      required: false
      schema:
        type: string
        default: application/pdf
        enum:
          - application/pdf
          - application/zpl
          - image/png
        example: image/png
      description: The returned format of the document
    raw:
      name: raw
      in: query
      required: false
      schema:
        type: boolean
      description: >-
        There have been identified cases where custom documents, internally
        rendered, will only include some of the necessary information, mainly
        due to some restrictions. Using the raw query param, one can request to
        receive the document in the originally received format by the carrier.
        This temporary solution to the problem allows the normal operations of
        the affected customers. As such, you can expect this property to be
        sunsetted shortly once the necessary changes have been implemented.