PacSortDevelopers
05 / Labels & printing

Connect the API to your packing line

  1. Create the assignment

    Send POST /assignment/single. Store the returned id against your external delivery or invoice reference.

  2. Retrieve the assignment

    Call GET /assignment/single/{id} using the PacSort Online assignment ID. Inspect status and labelsUrl; do not assume the label is ready immediately.

  3. Retrieve the label when ready

    When labelsUrl is available, retrieve the label from the returned URL. Keep the assignment status for diagnostics. For an unfinished assignment, retry the GET with a delay and a bounded timeout.

  4. Scan, look up & print

    Your integration resolves the scanned external reference to the saved assignment ID, retrieves its label and passes it to the printer. Reprint the existing label instead of creating another assignment.

cURL · retrieve an assignment
curl 'https://api.pacsortonline.com/assignment/single/ASSIGNMENT_ID' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: application/json'

Status and stop conditions

Label generation is asynchronous. Use labelsUrl to decide whether a download is available. These states describe processing; they are not a guaranteed sequence or timing SLA.

StatusClient action
open, pendingWait with a bounded polling window. An open assignment may be buffered; confirm account release settings if it remains open.
validating, validation_complete, optimisingProcessing. Poll GET after a delay.
report_released, report_accepted, labels_creatingContinue bounded polling. A released report may require action in the portal.
labels_releasedDownload when labelsUrl is populated. Label-file preparation may still be pending.
cancelled, report_deniedStop automatic polling and inspect the booking. Do not POST again automatically.
completeDownload the available label. If the URL is absent, stop and inspect the existing booking.
Unknown status or polling timeoutKeep the ID and response for diagnostics; stop at your polling limit and investigate.

The public response currently omits detailed label-generation errors and download status. A missing URL does not distinguish processing from failure. Inspect the portal or contact support with the assignment ID when polling times out.

Download and print

labelsUrl points to a signed PDF download. The service requests a one-week expiry when generating the link, but storage credentials or policy can make it expire sooner. Retrieve the assignment again for a fresh URL; do not create another booking. Do not attach your API Authorization header to the download request.

LayoutMedia and verification
a4_portraitA4 portrait: 210 × 297 mm.
a4_landscapeA4 landscape: 297 × 210 mm.
zebra_big, zebra_smallCarrier label PDF; these names do not guarantee a universal stock size or ZPL output. Confirm actual PDF page dimensions for your enabled carrier and printer.
letter_windowWindow-envelope layout. Confirm PDF dimensions, envelope window position and alignment using a sample from your account.

Print at actual size (100%) with the matching paper size. Disable fit-to-page unless your agreed printing workflow requires it. Check clipping, orientation and barcode readability on the physical printer before rollout.

Runnable booking-to-PDF example

Requires Python 3.9 or later. Download the request JSON, replace its test data with account-approved values, and download label-workflow.py. Set PACSORT_BASE_URL to your environment and PACSORT_API_KEY in your server environment. Run python3 label-workflow.py pacsort-online-shipment.json booking.json label.pdf.

The script sends one POST, persists the response, polls GET and downloads the PDF. Re-running with the same booking file resumes the existing assignment. An uncertain POST leaves a marker and stops rebooking. Use a separate state file per source delivery; keep your source-to-assignment mapping in durable storage in a production integration. Polling uses up to 60 attempts; this is example client policy, not an API limit.

This example is tested against local simulated responses. A successful real carrier booking and physical print must be verified with your configured sandbox account.

Illustrative response progression

Relevant fields only; IDs and URLs below are synthetic. An early response may contain {"id":"demo-assignment","status":"validating","labelsUrl":null,"item":null}. A later response may contain {"id":"demo-assignment","status":"labels_released","labelsUrl":"https://example.com/demo-label.pdf","item":{"carrierHandle":"example-carrier"}}. These are excerpts, not complete schema examples.

Choose a label layout: a4_portrait, a4_landscape, zebra_big, zebra_small or letter_window. Set the layout in labelsSettings and check the resulting label against your printer and media.

The current public API retrieves assignments by their PacSort Online ID. Direct lookup by an external delivery or invoice ID is not an endpoint in this reference; implement that mapping in your integration.