Legacy v2 Parcel Documents surface for retrieving labels and customs paperwork.
Sendcloud Parcel Documents API v2 is one of 20 APIs that Sendcloud publishes on the APIs.io network, described by a machine-readable OpenAPI specification.
Tagged areas include Documents, Customs, and Legacy. The published artifact set on APIs.io includes API documentation and an OpenAPI specification.
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: [email protected]
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.