--- updatedAt: 2026-04-24T07:39:03.000Z agentTools: projectIndex: https://developer.xentral.com/llms.txt --- # Get shipment The request a Xentral instance makes to an external carrier service to get a shipment. # OpenAPI definition ```json { "openapi": "3.0.0", "info": { "title": "Carrier Integration Service Contract", "version": "v0.1", "description": "The Carrier Integration Service Contract defines the interface for setting up custom shipping methods inside of Xentral based on external carrier services. This contract is used by partners to implement the required endpoints to integrate their carrier services with Xentral. The contract defines the following endpoints:\n\n- **GET /xentral/liveness**: Check the liveness of the service\n- **GET /xentral/carriers**: A list of available carriers and their products\n- **POST /xentral/shippingLabel**: Get a shipping label\n\nThe contract also defines the request and response bodies for each endpoint.", "contact": { "name": "Xentral", "url": "https://xentral.com", "email": "api@xentral.com" } }, "tags": [ { "name": "Carrier Integration Service Contract", "description": "All endpoints required to be implemented by partners to integrate their carrier services with Xentral." } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Bearer token obtained in POST /tokens endpoint or pregenerated in the system." } } }, "security": [ { "BearerAuth": [] } ], "servers": [ { "url": "https://{domain}", "description": "The carrier integration service URL", "variables": { "domain": { "default": "xentral.example-carrier-service.com" } } } ], "x-readme": { "samples-languages": [] }, "paths": { "/xentral/shipments/{id}": { "get": { "tags": [ "Carrier Integration Service Contract" ], "operationId": "xentral.carrierIntegrationService.shipmentGet", "summary": "Get shipment", "description": "The request a Xentral instance makes to an external carrier service to get a shipment.", "parameters": [ { "name": "id", "in": "path", "description": "The ID of the shipment.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Response body for generating a shipment.", "content": { "application/json": { "schema": { "required": [ "shippingLabels", "id", "carrier" ], "type": "object", "properties": { "shippingLabels": { "type": "array", "items": { "type": "object", "required": [ "parcelId", "trackingId", "trackingUrl", "label" ], "properties": { "parcelId": { "type": "string", "description": "The Unique ID of the parcel that this shipping label belongs to.", "example": "675ea55c-ab95-425a-977f-c70da64aa3e2" }, "trackingId": { "type": "string", "description": "The tracking ID for the shipment", "example": "123456789" }, "trackingUrl": { "description": "The tracking URL for the shipment", "type": "string", "example": "https://tracking.post.ch/track/123456789" }, "label": { "type": "object", "required": [ "type", "data" ], "description": "A representation of a label that can be printed for a shipment. It contains information about the file format and the file itself.", "example": { "type": "pdf", "data": "iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAACXBIWXMAAAsTAAALEwEAmpwYAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAADOSURBVHgB1ZZpDoUwCITxnaT3v1SP0mdN49YNEDJKbPxhmfnSBVwS0frg4kfguAKEQBTjuibJZ2Tt7HGO/XMIxzvGZB5Z8+xRfA+A+wRLiJZ2BdCb6GGeowkwSrA0HwLMEi3MpwAcgSfmLACukDaHBSARlM5lA3CFpaslApgZaLZKDNAz0h5WFUALQntT1AB3CG2tKLnwdvyxLYAeQug1hBYiaCmGNiNoO35iztV45y+ZpfkMogLwMB9BVABe5j2ICsDTvAVRxrJRAAPejv8TASt8b/v+egAAAABJRU5ErkJggg==" }, "properties": { "type": { "type": "string", "example": "pdf", "enum": [ "pdf", "png", "zpl", "gif", "jpg" ] }, "data": { "type": "string", "description": "The data of the label. If the label is PDF, PNG, or GIF, the data is base64 encoded. If the label is ZPL, the data is the ZPL code.", "example": "iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAACXBIWXMAAAsTAAALEwEAmpwYAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAADOSURBVHgB1ZZpDoUwCITxnaT3v1SP0mdN49YNEDJKbPxhmfnSBVwS0frg4kfguAKEQBTjuibJZ2Tt7HGO/XMIxzvGZB5Z8+xRfA+A+wRLiJZ2BdCb6GGeowkwSrA0HwLMEi3MpwAcgSfmLACukDaHBSARlM5lA3CFpaslApgZaLZKDNAz0h5WFUALQntT1AB3CG2tKLnwdvyxLYAeQug1hBYiaCmGNiNoO35iztV45y+ZpfkMogLwMB9BVABe5j2ICsDTvAVRxrJRAAPejv8TASt8b/v+egAAAABJRU5ErkJggg==" } } } } } }, "id": { "type": "string", "description": "The Unique ID of the shipment. This ID is used to cancel the shipment and must be unique across all shipments generated by the service.", "example": "675ea55c-ab95-425a-977f-c70da64aa3e2" }, "carrier": { "type": "object", "description": "Information about the carrier", "example": { "name": "Post Swiss" }, "properties": { "name": { "type": "string", "description": "The name of the carrier", "example": "Post Swiss" } } }, "customsDocuments": { "type": "array", "description": "Optional list of customs documents (e.g. CN22, CN23, COO) returned by the carrier. Each document includes typeCode, optional fileName, and base64-encoded fileContent.", "items": { "type": "object", "required": [ "typeCode", "fileContent" ], "properties": { "typeCode": { "type": "string", "description": "Document type code (e.g. COO, CN22, CN23)", "example": "CN23" }, "fileName": { "type": "string", "description": "Optional file name for the document", "example": "CN23_form.pdf" }, "fileContent": { "type": "string", "description": "Base64-encoded document content (e.g. PDF)", "format": "byte" } } } } } } } } }, "400": { "description": "IETF RFC 9457 Problem API compliant response", "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "type", "title", "violations" ], "properties": { "type": { "type": "string", "enum": [ "https://api.xentral.biz/problems/request-validation" ] }, "title": { "type": "string", "minLength": 1, "example": "Request payload validation failed." }, "violations": { "oneOf": [ { "type": "array", "items": { "type": "object", "example": { "username": [ "This value should not be blank." ], "email": [ "This value is not a valid email address." ] } }, "description": "This field will be a mirrored request payload with only invalid fields and values replaced by error messages." }, { "type": "object", "example": { "_": [ "This value should contain at most `9` elements." ] }, "description": "This field will be a mirrored request payload with only invalid fields and values replaced by error messages." } ] } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "title", "messages" ], "properties": { "type": { "type": "string", "enum": [ "https://api.xentral.biz/problems/generic-validation" ] }, "title": { "type": "string", "minLength": 1 }, "messages": { "type": "array", "items": { "type": "string" } } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "title", "messages" ], "properties": { "type": { "type": "string", "enum": [ "https://api.xentral.biz/problems/conflict" ] }, "title": { "type": "string", "minLength": 1 }, "messages": { "type": "array", "items": { "type": "string" } } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "title", "items" ], "properties": { "type": { "type": "string", "enum": [ "https://api.xentral.biz/problems/conflictItems" ] }, "title": { "type": "string", "minLength": 1 }, "items": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "title", "messages" ], "properties": { "id": { "type": "integer" }, "title": { "type": "string", "minLength": 1 }, "messages": { "type": "array", "items": { "type": "string" } } } } } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "title", "scopes" ], "properties": { "type": { "type": "string", "enum": [ "https://developer.xentral.com/reference/problems#token-scopes" ] }, "title": { "type": "string", "minLength": 1 }, "scopes": { "type": "array", "items": { "type": "string" } } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "title", "messages" ], "properties": { "type": { "type": "string", "enum": [ "https://api.xentral.biz/problems/generic-validation" ] }, "title": { "type": "string", "minLength": 1 }, "messages": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } } ] } } } }, "401": { "description": "Unable to authenticate the client", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message explaining why the request failed.", "example": "Missing required scopes: customer:create." } } }, "example": { "message": "Missing required scopes: customer:create." } }, "text/html": { "schema": { "type": "string", "example": "Unauthorized" } } } }, "403": { "description": "Unable to authorize the client" }, "404": { "description": "Resource was not found or not enough access privileges" } } } } } } ```