{ "openapi": "3.0.1", "info": { "title": "Traqa API", "description": "Traqa API to enable communication between Shippers and Load Sites for efficient exchange of data in the recycling supply chain", "version": "2.0.5", "contact": { "name": "Traqa Integrations", "url": "https://www.traqa.io", "email": "integration@traqa.io" }, "termsOfService": "https://www.traqa.io/terms-and-conditions-2/" }, "servers": [ { "url": "https://uat.api.traqa.io/v2", "description": "User Acceptance Testing Url for Traqa API V2" }, { "url": "https://api.traqa.io/v2", "description": "Production Base URL for Traqa API V2" } ], "paths": { "/getToken": { "post": { "summary": "Obtain an access token", "tags": [ "Authentication" ], "description": "Before making requests you need to authorise and exchange your username and password for an IdToken that can be passed in subsequent requests.\n* The token will expire after 60 minutes.\n* You can use the RefreshToken (which expires after 1 month).\n* To refresh: send a POST request to the getToken endpoint with the header refresh_token.", "responses": { "200": { "$ref": "#/components/responses/Token200" }, "400": { "$ref": "#/components/responses/Common400" }, "403": { "$ref": "#/components/responses/Common403" }, "404": { "$ref": "#/components/responses/Common404" }, "500": { "$ref": "#/components/responses/Common500" } }, "security": [ { "basic_auth": [] } ] } }, "/permissions": { "get": { "summary": "Retrieve all permissions", "tags": [ "Authentication" ], "description": "Retrieve the identifiers of every party which the requestor has the permission to make requests on behalf of.", "parameters": [ { "$ref": "#/components/parameters/HeaderAuthorizationToken" } ], "responses": { "200": { "$ref": "#/components/responses/Permissions" }, "400": { "$ref": "#/components/responses/Common400" }, "403": { "$ref": "#/components/responses/Common403" }, "404": { "$ref": "#/components/responses/Common404" }, "500": { "$ref": "#/components/responses/Common500" } }, "security": [] } }, "/loads": { "get": { "summary": "Retrieve loadplan(s) details", "tags": [ "Load Plans" ], "description": "Retrieve the details for a pending or completed load in Traqa.", "parameters": [ { "$ref": "#/components/parameters/HeaderAuthorizationToken" }, { "$ref": "#/components/parameters/HeaderPaginationToken" }, { "$ref": "#/components/parameters/QueryOrganizationId" }, { "$ref": "#/components/parameters/QueryLoadplanOrder" }, { "$ref": "#/components/parameters/QueryLoadplanStatus" }, { "$ref": "#/components/parameters/QueryLoadplanLimit" } ], "responses": { "200": { "$ref": "#/components/responses/Loads" }, "400": { "$ref": "#/components/responses/Common400" }, "403": { "$ref": "#/components/responses/Common403" }, "404": { "$ref": "#/components/responses/Common404" }, "500": { "$ref": "#/components/responses/Common500" } }, "security": [] }, "post": { "summary": "Post or update loadplan details", "tags": [ "Load Plans" ], "description": "Create a loadplan in Traqa, making the data available to the `loading site` for them to complete the load once the vehicle or container is loaded at site.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelLoadplan" }, "examples": { "Traqa Load Plan with PERN claim": { "value": { "shipper": { "organizationId": "GB100000000" }, "carrier": { "organizationId": "MSCU", "name": "Mediterranean Shipping Company S.A." }, "consignee": { "organizationId": "sWVgNvgjsHRD2", "name": "Acme Importer", "address": { "street": "123 Main Street", "city": "Liverpool", "state": "Merseyside", "postcode": "L1 0AA", "country": "GB" }, "contact": { "personName": "Joe Smith", "telephone": "0800 000 0000", "emailAddress": "joe@domain.com" }, "vatNumber": "GB367877431" }, "recoveryFacility": { "organizationId": "F78VO84GQ2", "name": "ACME Recovery Site Ltd", "address": { "street": "123 Main Street", "city": "Liverpool", "state": "Merseyside", "postcode": "L1 0AA", "country": "TH" }, "contact": { "personName": "Joe Smith", "telephone": "0800 000 0000", "emailAddress": "joe@domain.com" } }, "references": { "carriersReferenceNumber": "ONEY12345667", "shippersIdentifyingNumberForShipment": "400126253", "pickupReferenceNumber": "OCC-2456-1" }, "dates": { "scheduledLoadingTransportEvent": "2023-07-01T09:05:49" }, "tradeItem": [ { "harmonizeSystemCode": "4707100000", "description": "OCC 80/20" } ], "portOfLoading": { "UNLocode": "GBLIV" }, "loadingSite": { "organizationId": "GBEDMBIFA", "address": { "street": "123 Main Street", "city": "Liverpool", "state": "Merseyside", "postcode": "L1 0AA", "country": "GB" }, "name": "Acme Loading Site Ltd" }, "pern": { "percentage": 97.5 } } }, "Traqa Load Plan with NO PERN claim": { "value": { "shipper": { "organizationId": "GB123456789139" }, "carrier": { "organizationId": "ACLU", "name": "Mediterranean Shipping Company S.A." }, "consignee": { "organizationId": "GB123456789139", "name": "Acme Importer", "address": { "street": "123 Main Street", "city": "Liverpool", "state": "Merseyside", "postcode": "L1 0AA", "country": "GB" }, "contact": { "personName": "Joe Smith", "telephone": "0800 000 0000", "emailAddress": "joe@domain.com" }, "vatNumber": "GB367877431" }, "recoveryFacility": { "organizationId": "GB123456789139", "name": "ACME Recovery Site Ltd", "address": { "street": "123 Main Street", "city": "Liverpool", "state": "Merseyside", "postcode": "L1 0AA", "country": "TH" }, "contact": { "personName": "Joe Smith", "telephone": "0800 000 0000", "emailAddress": "joe@domain.com" } }, "references": { "carriersReferenceNumber": "ONEY12345667", "shippersIdentifyingNumberForShipment": "400126253", "pickupReferenceNumber": "OCC-2456-1" }, "dates": { "scheduledLoadingTransportEvent": "2023-07-01T09:05:49" }, "tradeItem": [ { "harmonizeSystemCode": "4707100000", "description": "OCC 80/20" } ], "portOfLoading": { "UNLocode": "GBLIV" }, "loadingSite": { "organizationId": "GBEDMBIFA", "address": { "street": "123 Main Street", "city": "Liverpool", "state": "Merseyside", "postcode": "L1 0AA", "country": "GB" }, "name": "Acme Loading Site Ltd" } } }, "Traqa Load Plan with customs paperwork only": { "value": { "shipper": { "organizationId": "GB123456789139" }, "carrier": { "organizationId": "ACLU", "name": "Mediterranean Shipping Company S.A." }, "consignee": { "organizationId": "GB123456789139", "name": "Acme Importer", "address": { "street": "123 Main Street", "city": "Liverpool", "state": "Merseyside", "postcode": "L1 0AA", "country": "GB" }, "contact": { "personName": "Joe Smith", "telephone": "0800 000 0000", "emailAddress": "joe@domain.com" }, "vatNumber": "GB367877431" }, "recoveryFacility": { "organizationId": "GB123456789139", "name": "ACME Recovery Site Ltd", "address": { "street": "123 Main Street", "city": "Liverpool", "state": "Merseyside", "postcode": "L1 0AA", "country": "TH" }, "contact": { "personName": "Joe Smith", "telephone": "0800 000 0000", "emailAddress": "joe@domain.com" } }, "references": { "carriersReferenceNumber": "ONEY12345667", "shippersIdentifyingNumberForShipment": "400126253", "pickupReferenceNumber": "OCC-2456-1" }, "dates": { "scheduledLoadingTransportEvent": "2023-07-01T09:05:49" }, "tradeItem": [ { "harmonizeSystemCode": "4707100000", "description": "OCC 80/20", "pricePerTonne": 10 } ], "portOfLoading": { "UNLocode": "GBLIV" }, "loadingSite": { "organizationId": "GBEDMBIFA", "address": { "street": "123 Main Street", "city": "Liverpool", "state": "Merseyside", "postcode": "L1 0AA", "country": "GB" }, "name": "Acme Loading Site Ltd" }, "pern": { "percentage": 97.5 }, "customs": { "customsDeclaration": false, "invoice": { "currency": "GBP" }, "incoterms": "CFR", "buyer": { "organizationId": "kXHCLMGJq5M", "address": { "street": "123 Main Street", "city": "Liverpool", "state": "Merseyside", "postcode": "L1 0AA", "country": "GB" }, "name": "ACME Buyer Co", "vatNumber": "GB367877431" } } } }, "Traqa Load Plan with export customs declaration": { "value": { "shipper": { "organizationId": "GB123456789139" }, "carrier": { "organizationId": "ACLU", "name": "Mediterranean Shipping Company S.A." }, "consignee": { "organizationId": "GB123456789139", "name": "Acme Importer", "address": { "street": "123 Main Street", "city": "Liverpool", "state": "Merseyside", "postcode": "L1 0AA", "country": "GB" }, "contact": { "personName": "Joe Smith", "telephone": "0800 000 0000", "emailAddress": "joe@domain.com" }, "vatNumber": "GB367877431" }, "recoveryFacility": { "organizationId": "GB123456789139", "name": "ACME Recovery Site Ltd", "address": { "street": "123 Main Street", "city": "Liverpool", "state": "Merseyside", "postcode": "L1 0AA", "country": "TH" }, "contact": { "personName": "Joe Smith", "telephone": "0800 000 0000", "emailAddress": "joe@domain.com" } }, "references": { "carriersReferenceNumber": "ONEY12345667", "shippersIdentifyingNumberForShipment": "400126253", "pickupReferenceNumber": "OCC-2456-1" }, "dates": { "scheduledLoadingTransportEvent": "2023-07-01T09:05:49" }, "tradeItem": [ { "harmonizeSystemCode": "4707100000", "description": "OCC 80/20", "pricePerTonne": 345.25 } ], "portOfLoading": { "UNLocode": "GBLIV" }, "loadingSite": { "organizationId": "GBEDMBIFA", "address": { "street": "123 Main Street", "city": "Liverpool", "state": "Merseyside", "postcode": "L1 0AA", "country": "GB" }, "name": "Acme Loading Site Ltd" }, "pern": { "percentage": 97.5 }, "customs": { "customsDeclaration": true, "declaration": { "goodsLocation": "GBAUDEUDEUDEUGVM", "customsOfficeExit": "GB000060", "countryOfDestination": "TH" }, "invoice": { "currency": "GBP" }, "incoterms": "CFR", "buyer": { "organizationId": "kXHCLMGJq5M", "address": { "street": "123 Main Street", "city": "Liverpool", "state": "Merseyside", "postcode": "L1 0AA", "country": "GB" }, "name": "ACME Buyer Co", "vatNumber": "GB367877431" } } } } } } } }, "parameters": [ { "$ref": "#/components/parameters/HeaderAuthorizationToken" } ], "responses": { "200": { "description": "Successful loads post response", "headers": { "Access-Control-Allow-Origin": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelEmpty" } } } }, "400": { "$ref": "#/components/responses/Common400" }, "403": { "$ref": "#/components/responses/Common403" }, "404": { "$ref": "#/components/responses/Common404" }, "500": { "$ref": "#/components/responses/Common500" } }, "security": [] } }, "/loads/byDate/{date}": { "get": { "summary": "Retrieve loadplan(s) details by scheduled loading date", "tags": [ "Load Plans" ], "description": "Retrieve the details for a pending or completed load in Traqa. Using the planned `loading date` as the search term.", "parameters": [ { "$ref": "#/components/parameters/HeaderAuthorizationToken" }, { "$ref": "#/components/parameters/PathScheduledLoadingDate" }, { "$ref": "#/components/parameters/HeaderPaginationToken" }, { "$ref": "#/components/parameters/QueryOrganizationId" }, { "$ref": "#/components/parameters/QueryLoadplanOrder" }, { "$ref": "#/components/parameters/QueryLoadplanStatus" }, { "$ref": "#/components/parameters/QueryLoadplanLimit" } ], "responses": { "200": { "$ref": "#/components/responses/Loads" }, "400": { "$ref": "#/components/responses/Common400" }, "403": { "$ref": "#/components/responses/Common403" }, "404": { "$ref": "#/components/responses/Common404" }, "500": { "$ref": "#/components/responses/Common500" } }, "security": [] } }, "/loads/byLoadingReference/{loadingReference}": { "get": { "summary": "Retrieve loadplan(s) details by loading reference", "tags": [ "Load Plans" ], "description": "Retrieve the details for a pending or completed load in Traqa. Using the `loading reference` as a search term.", "parameters": [ { "$ref": "#/components/parameters/HeaderAuthorizationToken" }, { "$ref": "#/components/parameters/PathLoadingReference" }, { "$ref": "#/components/parameters/HeaderPaginationToken" }, { "$ref": "#/components/parameters/QueryOrganizationId" }, { "$ref": "#/components/parameters/QueryLoadplanOrder" }, { "$ref": "#/components/parameters/QueryLoadplanStatus" }, { "$ref": "#/components/parameters/QueryLoadplanLimit" } ], "responses": { "200": { "$ref": "#/components/responses/Loads" }, "400": { "$ref": "#/components/responses/Common400" }, "403": { "$ref": "#/components/responses/Common403" }, "404": { "$ref": "#/components/responses/Common404" }, "500": { "$ref": "#/components/responses/Common500" } }, "security": [] } }, "/loads/byWeekNo/{weekNo}": { "get": { "summary": "Retrieve loadplan(s) details by scheduled loading date week number", "tags": [ "Load Plans" ], "description": "Retrieve the details for a pending or completed load in Traqa. Using the `week number` of the planned loading date as a search term.", "parameters": [ { "$ref": "#/components/parameters/HeaderAuthorizationToken" }, { "$ref": "#/components/parameters/PathWeekNumber" }, { "$ref": "#/components/parameters/QueryYear" }, { "$ref": "#/components/parameters/HeaderPaginationToken" }, { "$ref": "#/components/parameters/QueryOrganizationId" }, { "$ref": "#/components/parameters/QueryLoadplanOrder" }, { "$ref": "#/components/parameters/QueryLoadplanStatus" }, { "$ref": "#/components/parameters/QueryLoadplanLimit" } ], "responses": { "200": { "$ref": "#/components/responses/Loads" }, "400": { "$ref": "#/components/responses/Common400" }, "403": { "$ref": "#/components/responses/Common403" }, "404": { "$ref": "#/components/responses/Common404" }, "500": { "$ref": "#/components/responses/Common500" } }, "security": [] } }, "/weights": { "post": { "summary": "Post the weighing record details for a load", "tags": [ "Weights" ], "description": "Provide the weighing details from the weighbridge software to complete a load in Traqa.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelWeighingRecord" } } } }, "parameters": [ { "$ref": "#/components/parameters/HeaderAuthorizationToken" } ], "responses": { "200": { "description": "Successful weights post response", "headers": { "Access-Control-Allow-Origin": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelEmpty" } } } }, "400": { "$ref": "#/components/responses/Common400" }, "403": { "$ref": "#/components/responses/Common403" }, "404": { "$ref": "#/components/responses/Common404" }, "500": { "$ref": "#/components/responses/Common500" } }, "security": [] } }, "/documents/preAnnexvii": { "get": { "summary": "Retrieve the pre-Annex VII of a loadplan", "tags": [ "Documents" ], "description": "Retrieve the `Pre Annex VII` a pending load in Traqa. A document that represents the Annex VII before the load is completed. Historically this document would be shared to the load site ahead of loading for them to fill in by hand.", "parameters": [ { "$ref": "#/components/parameters/HeaderAuthorizationToken" }, { "$ref": "#/components/parameters/QueryLoadingReference" }, { "$ref": "#/components/parameters/QueryOrganizationId" } ], "responses": { "200": { "$ref": "#/components/responses/Document" }, "400": { "$ref": "#/components/responses/Common400" }, "403": { "$ref": "#/components/responses/Common403" }, "404": { "$ref": "#/components/responses/Common404" }, "500": { "$ref": "#/components/responses/Common500" } }, "security": [] } }, "/documents/annexvii": { "get": { "summary": "Retrieve the Annex VII of a loadplan", "tags": [ "Documents" ], "description": "Retrieve a clean copy the `Annex VII` for a completed load in Traqa. A legal document that travels with the material during transport and would be signed by the recieving facility.", "parameters": [ { "$ref": "#/components/parameters/HeaderAuthorizationToken" }, { "$ref": "#/components/parameters/QueryLoadingReference" }, { "$ref": "#/components/parameters/QueryOrganizationId" } ], "responses": { "200": { "$ref": "#/components/responses/Document" }, "400": { "$ref": "#/components/responses/Common400" }, "403": { "$ref": "#/components/responses/Common403" }, "404": { "$ref": "#/components/responses/Common404" }, "500": { "$ref": "#/components/responses/Common500" } }, "security": [] } }, "/documents/annexvii/{loadingReference}/{shipperOrganizationId}": { "post": { "summary": "Add the Annex VII of a loadplan", "tags": [ "Documents" ], "description": "Provide a copy of the `Annex VII` for a completed load in Traqa. ", "parameters": [ { "$ref": "#/components/parameters/HeaderAuthorizationToken" }, { "$ref": "#/components/parameters/PathLoadingReference" }, { "$ref": "#/components/parameters/PathShipperOrganizationId" } ], "requestBody": { "$ref": "#/components/requestBodies/FilesPost" }, "responses": { "200": { "description": "Successful document post response", "headers": { "Access-Control-Allow-Origin": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelEmpty" } } } }, "400": { "$ref": "#/components/responses/Common400" }, "403": { "$ref": "#/components/responses/Common403" }, "404": { "$ref": "#/components/responses/Common404" }, "500": { "$ref": "#/components/responses/Common500" } }, "security": [] } }, "/documents/weighbridgeCertificate": { "get": { "summary": "Retrieve the Weighbridge Certificate of a loadplan", "tags": [ "Documents" ], "description": "Retrieve the `Weighbridge Certificate/Ticket` for a completed load in Traqa. A document that is used to proove the weights and provide load details. Sometimes used as the `packing list` in customs.", "parameters": [ { "$ref": "#/components/parameters/HeaderAuthorizationToken" }, { "$ref": "#/components/parameters/QueryLoadingReference" }, { "$ref": "#/components/parameters/QueryOrganizationId" } ], "responses": { "200": { "$ref": "#/components/responses/Document" }, "400": { "$ref": "#/components/responses/Common400" }, "403": { "$ref": "#/components/responses/Common403" }, "404": { "$ref": "#/components/responses/Common404" }, "500": { "$ref": "#/components/responses/Common500" } }, "security": [] } }, "/documents/weighbridgeCertificate/{loadingReference}/{shipperOrganizationId}": { "post": { "summary": "Add the Weighbridge Certificate of a loadplan", "tags": [ "Documents" ], "description": "Provide the `Weighbridge Certificate/Ticket` for a completed load in Traqa. An optional upload by the loading site which will overwrite the Traqa produced weighbridge ticket with the load sites branded ticket. This can be a scan/image/pdf file.", "parameters": [ { "$ref": "#/components/parameters/HeaderAuthorizationToken" }, { "$ref": "#/components/parameters/PathLoadingReference" }, { "$ref": "#/components/parameters/PathShipperOrganizationId" } ], "requestBody": { "$ref": "#/components/requestBodies/FilesPost" }, "responses": { "200": { "description": "Successful document post response", "headers": { "Access-Control-Allow-Origin": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelEmpty" } } } }, "400": { "$ref": "#/components/responses/Common400" }, "403": { "$ref": "#/components/responses/Common403" }, "404": { "$ref": "#/components/responses/Common404" }, "500": { "$ref": "#/components/responses/Common500" } }, "security": [] } }, "/documents/commercialInvoice": { "get": { "summary": "Retrieve the Commercial Invoice of a loadplan", "tags": [ "Documents" ], "description": "Retrieve the `Commercial Invoice` for a completed load in Traqa. A document used and referenced in the export customs declaration. Traqa can produce these for the shipper to support the ongoing customs process.", "parameters": [ { "$ref": "#/components/parameters/HeaderAuthorizationToken" }, { "$ref": "#/components/parameters/QueryLoadingReference" }, { "$ref": "#/components/parameters/QueryOrganizationId" } ], "responses": { "200": { "$ref": "#/components/responses/Document" }, "400": { "$ref": "#/components/responses/Common400" }, "403": { "$ref": "#/components/responses/Common403" }, "404": { "$ref": "#/components/responses/Common404" }, "500": { "$ref": "#/components/responses/Common500" } }, "security": [] } }, "/documents/exportAccompanyingDocument": { "get": { "summary": "Retrieve the Export Accompanying Document of a loadplan", "tags": [ "Documents" ], "description": "Retrieve the `Export Accompanying Document (EAD)` for a completed load in Traqa. A document used and referenced in the export customs process to provide proof of a customs declaration and its outcome, contains the MRN and route from HRMC.", "parameters": [ { "$ref": "#/components/parameters/HeaderAuthorizationToken" }, { "$ref": "#/components/parameters/QueryLoadingReference" }, { "$ref": "#/components/parameters/QueryOrganizationId" } ], "responses": { "200": { "$ref": "#/components/responses/Document" }, "400": { "$ref": "#/components/responses/Common400" }, "403": { "$ref": "#/components/responses/Common403" }, "404": { "$ref": "#/components/responses/Common404" }, "500": { "$ref": "#/components/responses/Common500" } }, "security": [] } }, "/photos/byLoadingReference/{loadingReference}": { "get": { "summary": "Retrieve the photos of a loadplan", "tags": [ "Photos" ], "description": "Retrieve `loading photos` for a completed load in Traqa. Search by the `Loading Reference`.", "parameters": [ { "$ref": "#/components/parameters/HeaderAuthorizationToken" }, { "$ref": "#/components/parameters/PathLoadingReference" } ], "responses": { "200": { "$ref": "#/components/responses/Photos" }, "400": { "$ref": "#/components/responses/Common400" }, "403": { "$ref": "#/components/responses/Common403" }, "404": { "$ref": "#/components/responses/Common404" }, "500": { "$ref": "#/components/responses/Common500" } }, "security": [] } }, "/photos/byLoadingReference/{loadingReference}/{shipperOrganizationId}": { "post": { "summary": "Post photos for a loadplan", "tags": [ "Photos" ], "description": "Provide the `Loading Photos` for a given `Loading Reference` and `Shipper` to Traqa.", "parameters": [ { "$ref": "#/components/parameters/HeaderAuthorizationToken" }, { "$ref": "#/components/parameters/PathLoadingReference" }, { "$ref": "#/components/parameters/PathShipperOrganizationId" } ], "requestBody": { "$ref": "#/components/requestBodies/FilesPost" }, "responses": { "200": { "description": "Successful document post response", "headers": { "Access-Control-Allow-Origin": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelEmpty" } } } }, "400": { "$ref": "#/components/responses/Common400" }, "403": { "$ref": "#/components/responses/Common403" }, "404": { "$ref": "#/components/responses/Common404" }, "500": { "$ref": "#/components/responses/Common500" } }, "security": [] } } }, "components": { "parameters": { "HeaderPaginationToken": { "name": "PaginationToken", "in": "header", "description": "Allows pagination of response. Passing this value into subsequent requests retrieves subsequent values from a set.", "required": false, "schema": { "type": "string" }, "example": "ZXhhbXBsZQo=" }, "HeaderAuthorizationRequest": { "in": "header", "name": "Authorization", "description": "Basic authentication flow credentials", "required": true, "schema": { "type": "string", "description": "base64-encoded username:password prefixed with 'Basic'" }, "example": "Basic abkojYXNkZAQBABA==" }, "HeaderAuthorizationToken": { "in": "header", "name": "Authorization", "description": "OAuth 2.0 Access token retrieved from the token endpoint", "required": true, "schema": { "type": "string", "description": "Access token (following OAuth 2.0 standard) with no prefix" }, "example": "eyJraW..." }, "QueryOrganizationId": { "name": "organizationId", "in": "query", "required": false, "schema": { "type": "string" }, "examples": { "shipperEORI": { "$ref": "#/components/schemas/CodeEORI" }, "shipperTraqaCode": { "$ref": "#/components/schemas/CodeTraqa" }, "loadingSite": { "$ref": "#/components/schemas/CodeBICFacility" } } }, "QueryLoadplanOrder": { "name": "order", "in": "query", "required": false, "schema": { "title": "Order of loadplans", "description": "Orders retrieved loadplans by scheduled loading date. By default, in ascending order.", "type": "string", "enum": [ "asc", "desc" ] }, "examples": { "ascending": { "value": "asc", "summary": "Order loadplans in ascending order", "description": "This orders the retrieved loadplans in ascending scheduled load-date." }, "descending": { "value": "desc", "summary": "Order loadplans in descending order", "description": "This orders the retrieved loadplans in descending scheduled load-date." } } }, "QueryLoadplanStatus": { "name": "status", "in": "query", "required": false, "schema": { "title": "Status of loadplans", "description": "Filters retrieved loadplans by status. OPEN loads have yet to be loaded. COMPLETED loads are loaded. By default, retrieves loadplans of both statuses.", "type": "string", "enum": [ "OPEN", "COMPLETED" ] }, "examples": { "open": { "value": "OPEN", "summary": "Open loadplans only", "description": "This retrieves loadplans that are not yet loaded." }, "completed": { "value": "COMPLETED", "summary": "Completed loadplans only", "description": "This retrieves loadplans that are loaded." } } }, "QueryLoadplanLimit": { "name": "limit", "in": "query", "required": false, "schema": { "title": "Limit number of loadplans", "description": "Limits how many loadplans are retrieved. By default, at most 250 loadplans are retrieved", "type": "string" }, "examples": { "smallLimit": { "value": 5, "summary": "Small number of loadplans retrieved", "description": "This limits the response to 5 loadplans at most." }, "largeLimit": { "value": 100, "summary": "Large number of loadplans retrieved", "description": "This limits the response to 100 loadplans at most." } } }, "QueryYear": { "name": "year", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 2000, "maximum": 2100 }, "example": 2013 }, "QueryLoadingReference": { "name": "loadingReference", "in": "query", "required": true, "schema": { "maxLength": 35, "type": "string" }, "example": "LR12345-1" }, "QueryDatetime": { "name": "datetime", "in": "query", "required": true, "schema": { "type": "string", "description": "Date-time of notification creation in ISO 8601 format", "pattern": "^\\d{4}-[01]\\d-[0-3]\\dT[0-2]\\d:[0-5]\\d:[0-5]\\d$" }, "example": "2024-01-01T12:00:00" }, "QueryExternalQueriesAllowed": { "name": "externalQuery", "in": "query", "required": false, "schema": { "type": "boolean", "enum": [ true, false ], "default": true, "example": false }, "examples": { "externalQueriesAllowed": { "value": true, "summary": "External queries allowed", "description": "Backend will make queries to external APIs to retrieve required data." }, "externalQueriesDisallowed": { "value": false, "summary": "External queries not allowed", "description": "Backend will NOT make queries to external APIs to retrieve required data." } } }, "PathContainerNumber": { "name": "containerNumber", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EquipmentNumber" }, "example": "ABCU1234561" }, "PathScheduledLoadingDate": { "name": "date", "in": "path", "required": true, "schema": { "title": "Scheduled loading date", "pattern": "^\\d{4}-[01]\\d-[0-3]\\dT[0-2]\\d:[0-5]\\d:[0-5]\\d$", "type": "string", "description": "The planned date time of the loading at site, conform to yyyy-mm-ddThh:mm:ss", "example": "2023-07-01T09:05:49" }, "example": "2023-01-01" }, "PathLoadingReference": { "name": "loadingReference", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ReferencePickupReferenceNumber" }, "example": "LR12345-1" }, "PathWeekNumber": { "name": "weekNo", "in": "path", "required": true, "description": "ISO Week number of the year", "schema": { "type": "integer", "minimum": 1, "maximum": 53 }, "example": 5 }, "PathShipperOrganizationId": { "name": "shipperOrganizationId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "shipperEORI": { "$ref": "#/components/schemas/CodeEORI" }, "shipperTraqaCode": { "$ref": "#/components/schemas/CodeTraqa" } } }, "PathOrganizationId": { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "shipperEORI": { "$ref": "#/components/schemas/CodeEORI" }, "shipperTraqaCode": { "$ref": "#/components/schemas/CodeTraqa" }, "loadingSite": { "$ref": "#/components/schemas/CodeBICFacility" } } } }, "responses": { "Token200": { "description": "Response to an access token request", "headers": { "Access-Control-Allow-Origin": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "IdToken": { "type": "string", "description": "Access token used to make subsequent requests", "example": "eyJraWQiOiJEeU..." }, "RefreshToken": { "type": "string", "description": "Refresh token used in subsequent access token requests", "example": "eyJjdHkiOiJKV1..." } } }, "example": { "IdToken": "eyJraW...", "RefreshToken": "eyJjdH..." } } } }, "Common400": { "description": "Server cannot or will not process the request due to client error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "title": "Error Message", "type": "string", "description": "Human readable Error Message providing more information about the error.", "example": "Missing required field 'grossWeight'" } } }, "example": { "message": "Missing required field 'grossWeight'" } } } }, "Common403": { "description": "The server understood the request, but it refuses to authorize it due to insufficient permissions or authentication failure.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "title": "Error Message", "type": "string", "description": "Human readable Error Message providing more information about the error.", "example": "Unauthorized" } } }, "example": { "message": "string" } } } }, "Common404": { "description": "The requested resource could not be found on the server.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errorType": { "title": "Error Type", "type": "string", "description": "Human readable Error Type based on HTTP Status Code.", "example": "Bad request" }, "errorMessage": { "title": "Error Message", "type": "string", "description": "Human readable Error Message providing more information about the error.", "example": "Missing required field 'grossWeight'." }, "requestId": { "type": "string", "description": "A unique identifier for the request.", "example": "2cc36855-202b-44fa-920b-0b2c7bdf8aa2" }, "requestTime": { "type": "string", "description": "Date, time, and timezone at which the relevant request was made.", "example": "28/Sep/2023:10:10:44 +0000" } } }, "example": { "errorType": "Resource Not Found", "errorMessage": "string", "requestId": "2cc36855-202b-44fa-920b-0b2c7bdf8aa2", "requestTime": "28/Sep/2023:10:10:44 +0000" } } } }, "Common500": { "description": "An internal server error occurred while processing the request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "title": "Error Message", "type": "string", "description": "Human readable Error Message providing more information about the error.", "example": "Internal Server Error" } } }, "example": { "message": "Internal Server Error" } } } }, "Loads": { "description": "Loadplan Data Partial or Completed", "headers": { "Access-Control-Allow-Origin": { "schema": { "type": "string" } }, "pagination-token": { "$ref": "#/components/parameters/HeaderPaginationToken" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ModelLoadplanAny" } } } } }, "Permissions": { "description": "Information on a user's available permissions groups.", "headers": { "Access-Control-Allow-Origin": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "Groups": { "title": "Groups", "type": "array", "description": "A list of permission groups.", "items": { "type": "object", "properties": { "Name": { "type": "string" }, "Code": { "type": "string" } } } }, "Count": { "title": "Groups Count", "type": "number", "description": "The number of permission groups available." }, "DateOfRequest": { "title": "Date Retrieved", "type": "string", "pattern": "^\\d{4}-[01]\\d-[0-3]\\dT[0-2]\\d:[0-5]\\d:[0-5]\\d$", "description": "The date that the permissions information was requested in ISO 8601 format." } } }, "example": { "Groups": [ { "Name": "demo shipper 1", "Code": "TQGBDEMOA" }, { "Name": "demo shipper 2", "Code": "TQGBTESTA" } ], "Count": 2, "DateOfRequest": "2023-09-28T16:44:08" } } } }, "Photos": { "description": "An object containing a list of photos associated with a loadplan.", "headers": { "Access-Control-Allow-Origin": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "photos": { "title": "Photos List", "type": "array", "description": "A list of photos associated with a loadplan.", "items": { "title": "Photo", "type": "object", "description": "A photo associated with a loadplan.", "properties": { "photo": { "title": "Photo Link", "type": "string", "description": "Pre-signed URL for full-size photo." }, "thumbnail": { "title": "Thumbnail Link", "type": "string", "description": "Pre-signed URL for thumbnail-size photo." } } } } } }, "example": { "photos": [ { "photo": "https://prod-transportid-images/photo1.jpg", "thumbnail": "https://prod-transportid-images/thumbnail1.jpg" }, { "photo": "https://prod-transportid-images/photo2.jpg", "thumbnail": "https://prod-transportid-images/thumbnail2.jpg" }, { "photo": "https://prod-transportid-images/photo3.jpg", "thumbnail": "https://prod-transportid-images/thumbnail3.jpg" } ] } } } }, "Document": { "description": "A document retrieved for a specific load plan.", "headers": { "Access-Control-Allow-Origin": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "document": { "title": "Document pre-signed URL", "type": "string" } } }, "example": { "document": "https://prod-traqa-application-..." } } } } }, "requestBodies": { "FilesPost": { "description": "Specify the path to file(s) to be uploaded.", "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } } } } } } }, "schemas": { "PartyShipper": { "title": "Shipper", "description": "The Shipper is the party who is exporting the material and submitting the load plan into Traqa, populates Box 1 on the Annex VII", "required": [ "organizationId" ], "type": "object", "properties": { "organizationId": { "title": "A coded Identifier for the Shipper", "description": "The shipper Organization Id is usually an EORI number assigned by a government, it can in place of this be a Traqa specific reference.", "anyOf": [ { "$ref": "#/components/schemas/CodeEORI" }, { "$ref": "#/components/schemas/CodeTraqa" } ] }, "address": { "$ref": "#/components/schemas/CommonAddress" }, "name": { "title": "Shipper Name", "pattern": "^[a-zA-Z0-9\\&\\ \\-\\.\\,\\/\\_\\(\\)\\']+$", "type": "string", "description": "The Name of the Shipper", "example": "ACME Trader Ltd" } } }, "PartyBuyer": { "title": "Buyer", "description": "Buyer/receiver of shipment. Overwrites the 'buyer' party shown on the commercial invoice", "anyOf": [ { "required": [ "organizationId", "address" ] }, { "required": [ "name", "address" ] } ], "type": "object", "properties": { "organizationId": { "anyOf": [ { "$ref": "#/components/schemas/CodeEORI" }, { "$ref": "#/components/schemas/CodeBICFacility" } ] }, "address": { "$ref": "#/components/schemas/CommonAddress" }, "name": { "title": "Buyer Name", "pattern": "^[a-zA-Z0-9\\&\\ \\-\\.\\,\\/\\_\\(\\)\\']+$", "type": "string", "description": "The Name of the Buyer", "example": "ACME Buyer Co" }, "vatNumber": { "$ref": "#/components/schemas/CodeVATNumber" } } }, "PartyCarrier": { "title": "Ocean Carrier", "description": "The Ocean Carrier for use when containerised freight is moving by deep sea, this will show in Box 5b on the Annex VII", "type": "object", "required": [ "organizationId" ], "properties": { "organizationId": { "$ref": "#/components/schemas/CodeSCAC" }, "name": { "title": "The Name of the Ocean Carrier", "pattern": "^[a-zA-Z0-9\\&\\ \\-\\.\\,\\/\\_\\(\\)\\']+$", "type": "string", "description": "The Name of the carrier in freetext", "example": "Mediterranean Shipping Company S.A." } } }, "PartyConsignee": { "title": "Consignee", "description": "The Consignee is the person who will be receiving the consignment (material); they may not necessarily be the physical destination. This will show in Box 2 of the Annex VII.", "anyOf": [ { "required": [ "organizationId", "address" ] }, { "required": [ "name", "address" ] } ], "type": "object", "properties": { "organizationId": { "title": "A coded Identifier for the Consignee", "description": "The consignee Organization Id is usually an EORI number assigned by a government or a BIC Facility Code.", "anyOf": [ { "$ref": "#/components/schemas/CodeEORI" }, { "$ref": "#/components/schemas/CodeBICFacility" } ] }, "name": { "title": "Consignee Name", "type": "string", "description": "Free Text Name of the Consignee", "example": "Acme Importer" }, "address": { "title": "Address", "type": "object", "required": [ "street", "city", "state", "country" ], "properties": { "street": { "title": "Street Name", "pattern": "^[a-zA-Z0-9\\&\\ \\-\\.\\,\\/\\_\\(\\)\\']+$", "type": "string", "example": "123 Main Street" }, "city": { "title": "City", "pattern": "^[a-zA-Z0-9\\&\\ \\-\\.\\,\\/\\_\\(\\)\\']+$", "type": "string", "example": "Liverpool" }, "state": { "title": "State", "pattern": "^[a-zA-Z0-9\\&\\ \\-\\.\\,\\/\\_\\(\\)\\']+$", "type": "string", "example": "Merseyside" }, "postcode": { "title": "Post Code", "pattern": "^[a-zA-Z0-9\\ \\-]+$", "type": "string", "example": "L1 0AA" }, "country": { "$ref": "#/components/schemas/LocationsCountry" } } }, "contact": { "$ref": "#/components/schemas/CommonContact" }, "vatNumber": { "$ref": "#/components/schemas/CodeVATNumber" } } }, "PartyLoadingSite": { "title": "Loading Site", "required": [ "organizationId" ], "type": "object", "properties": { "name": { "title": "Loading Site Name", "pattern": "^[a-zA-Z0-9\\&\\ \\-\\.\\,\\/\\_\\(\\)\\']+$", "type": "string", "description": "Loading Site Name", "example": "Acme Loading Site Ltd" }, "address": { "$ref": "#/components/schemas/CommonAddress" }, "organizationId": { "$ref": "#/components/schemas/CodeBICFacility" } }, "description": "The physical Loading Site of the Material which will provide weights to Traqa. This will appear in Box 6 of the Annex VII" }, "PartyRecoveryFacility": { "title": "Recovery Facility", "type": "object", "anyOf": [ { "required": [ "organizationId", "address" ] }, { "required": [ "name", "address" ] } ], "properties": { "organizationId": { "title": "A coded identifier for the Recovery Facility", "description": "A coded value for the Recovery Facility, for UK and Europe this should be the EORI if available or if not mutually agreed with Traqa.", "anyOf": [ { "$ref": "#/components/schemas/CodeEORI" }, { "$ref": "#/components/schemas/CodeBICFacility" } ] }, "name": { "title": "Recovery Facility Name", "type": "string", "description": "Free Text Name of the Recovery Facility", "example": "ACME Recovery Site Ltd" }, "address": { "$ref": "#/components/schemas/CommonAddress" }, "contact": { "$ref": "#/components/schemas/CommonContact" }, "vatNumber": { "$ref": "#/components/schemas/CodeVATNumber" } }, "description": "The Recovery Facility should ONLY be provided when different to Box 2 (Consignee) if not provided it will default to Consignee. This will populate Box 7 on the Annex VII" }, "PartyHaulier": { "title": "Haulier", "required": [ "name", "organizationId" ], "type": "object", "properties": { "organizationId": { "title": "A coded Identifier for the Shipper", "description": "The Haulier who arrives at site to transport the goods. Populates box 5a on the Annex VII and verified with the EA", "anyOf": [ { "$ref": "#/components/schemas/CodeWasteCarrierLicense" } ] }, "name": { "title": "Name of Haulier", "pattern": "^[a-zA-Z0-9\\&\\ \\-\\.\\,\\/\\_\\(\\)\\']+$", "type": "string", "description": "Freetext for Haulier Name", "example": "Acme Haulage Co" } }, "description": "The Haulier who arrives at site to trasport the goods. Populates box 5a on the Annex VII and verified with the EA" }, "EquipmentNumber": { "title": "Equipment Number", "type": "string", "description": "The Container Number OR the Trailer number that the goods have been loaded onto", "example": "MAEU1234567" }, "EquipmentType": { "title": "Equipment Type", "pattern": "^[a-zA-Z0-9]{4}$", "type": "string", "description": "The ISO Size Type for Deep Sea Containers", "example": "45G1" }, "EquipmentSeal": { "title": "Seal Number", "type": "array", "description": "The seal number(s) used to seal the container or trailer after loading, multiple seal numbers can be present on a container, many only load with 1 or for trailers not always used.", "items": { "title": "Seal Number", "required": [ "identifier" ], "type": "object", "properties": { "identifier": { "title": "Identifier", "pattern": "^[a-zA-Z0-9\\&\\ \\-\\.\\,\\/\\_\\(\\)]+$", "type": "string", "description": "Seal Number used" } }, "description": "The seal number used on the transport equipment" } }, "DatesActualDepartureTransportEvent": { "title": "Actual Departure Transport Event", "pattern": "^\\d{4}-[01]\\d-[0-3]\\dT[0-2]\\d:[0-5]\\d:[0-5]\\d$", "type": "string", "description": "The Actual Departure of the laden vehicle from Loading Site from final weigh, populates box 4 on the Annex VII for Departure Time.", "example": "2023-07-01T09:47:38" }, "DatesActualArrivalTransportEvent": { "title": "Actual Arrival Transport Event", "pattern": "^\\d{4}-[01]\\d-[0-3]\\dT[0-2]\\d:[0-5]\\d:[0-5]\\d$", "type": "string", "description": "The Actual Arrival of the empty vehicle at Loading Site for the first weigh", "example": "2023-07-01T08:30:38" }, "DatesScheduledLoadingTransportEvent": { "title": "Scheduled Loading Transport Event", "pattern": "^\\d{4}-[01]\\d-[0-3]\\dT[0-2]\\d:[0-5]\\d:[0-5]\\d$", "type": "string", "description": "The planned date time of the loading at site, conform to yyyy-mm-ddThh:mm:ss", "example": "2023-07-01T09:05:49" }, "DatesWeighingDate": { "title": "Weighing Date Event", "pattern": "^\\d{4}-[01]\\d-[0-3]\\dT[0-2]\\d:[0-5]\\d:[0-5]\\d$", "type": "string", "description": "Date of the weighing of trailer or container at a Loading Site. Populates Box 4 on the Annex VII", "example": "2023-07-01T09:05:49" }, "ReferenceCarriersReferenceNumber": { "title": "Carriers Reference Number", "pattern": "^[a-zA-Z0-9\\ \\-\\.\\/\\_]+$", "type": "string", "description": "The Ocean Carrier Booking Number used for tracking containers after loading, only useful for deep sea movements", "example": "ONEY12345667" }, "ReferenceShippersIdentifyingNumberForShipment": { "title": "Shippers Identifying Number For Shipment", "pattern": "^[a-zA-Z0-9\\ \\-\\.\\,\\/\\_]+$", "type": "string", "description": "Sales Order number for the shipment for the Shipper to identify a collection of loads moving under same Order in Traqa.", "example": "400126253" }, "ReferenceConsignee": { "title": "Consignee Reference Number", "pattern": "^[a-zA-Z0-9\\ \\-\\.\\,\\/\\_]+$", "type": "string", "description": "A reference for the end destination (consignee) to identify the shipment on receipt", "example": "237864" }, "ReferenceLoadingSite": { "title": " Reference Number", "pattern": "^[a-zA-Z0-9\\ \\-\\.\\,\\/\\_]+$", "type": "string", "description": "A reference for the loading site to additionally identify any other references such as trading agreement or purchase order, this is used when the pickup reference differs to the loading site reference and will appear on the Annex VII", "example": "237864" }, "ReferencePickupReferenceNumber": { "title": "Pickup Reference Number", "minLength": 3, "pattern": "^[a-zA-Z0-9\\ \\-\\.\\/\\_]+$", "type": "string", "description": "The loading reference the driver will provide to site on arrival, must be unique per load this is a key identifier in Traqa that is agreed between the Load Site and the Shipper.", "example": "OCC-2456-1" }, "ReferenceVehicleIdentificationNumber": { "title": "Vehicle Identification Number", "pattern": "^[a-zA-Z0-9\\&\\ \\-\\.\\,\\/\\_\\(\\)]+$", "type": "string", "description": "The registration number of the vehicle, populates box 5a on the Annex VII", "example": "NV18 NLD" }, "ReferenceDespatchNoteNumber": { "title": "Despatch Note Number", "pattern": "^[a-zA-Z0-9\\&\\ \\-\\.\\,\\/\\_\\(\\)]+$", "type": "string", "description": "The weighbridge ticket number from the loading site.", "example": "40012" }, "ReferenceDriverName": { "title": "Driver Name", "pattern": "^[a-zA-Z0-9\\&\\ \\-\\.\\,\\/\\_\\(\\)]+$", "type": "string", "description": "Name of the driver. Populates box 5a on the Annex VII", "example": "Lee" }, "ReferencePERN": { "title": "Packaging Export Recovery Note (PERN)", "description": "Information about a PERN thats required to appear on the Annex VII in Box 15, if not claiming a PERN omit from the load plan", "type": "object", "required": [ "percentage" ], "properties": { "percentage": { "title": "Percentage of MT", "type": "number", "format": "float", "minimum": 1e-05, "maximum": 100, "description": "Percentage of MT to be issued for PERN", "example": 97.5 } } }, "ReferenceOrderReference": { "description": "ShippersIdentifyingNumberForShipment for the order plus the unique order reference in Traqa", "type": "string", "pattern": "^[a-zA-Z0-9\\ \\-\\/\\#\\.\\:\\*\\&\\+\\~_]+$", "example": "ORD-123456#550e8400-e29b-41d4-a716-446655440000" }, "NILSTaskId": { "description": "TaskId of the associated Notification (if applicable) for a loading plan in Traqa", "type": "string", "pattern": "^[a-zA-Z0-9\\ \\-\\/\\#\\.\\:\\*\\&\\+\\~_]+$", "example": "4cde67da-a3vb-49d3-8d23-h38ed8c1a485" }, "LocationsPortOfLoading": { "title": "Port Of Loading", "required": [ "UNLocode" ], "type": "object", "properties": { "UNLocode": { "oneOf": [ { "$ref": "#/components/schemas/LocationsCountry" }, { "$ref": "#/components/schemas/CodeUNLocode" } ] } }, "description": "A coded reference to the location for the port of loading, used in transport provided by the UN, populates Box 11 on the Annex VII for origin country." }, "LocationsPortOfDischarge": { "title": "Port Of Discharge", "required": [ "UNLocode" ], "type": "object", "properties": { "UNLocode": { "oneOf": [ { "$ref": "#/components/schemas/LocationsCountry" }, { "$ref": "#/components/schemas/CodeUNLocode" } ] } }, "description": "A coded reference to the location for the port of discharge, used in transport provided by the UN, populates Box 12 on the Annex VII for destination country." }, "LocationsCountry": { "title": "Country", "description": "Country ISO 3166 Alpha-2 code", "pattern": "^[a-zA-Z]{2}$", "type": "string", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "YE", "YT", "ZA", "ZM", "ZW" ], "example": "GB" }, "LocationsCountriesOfRouting": { "title": "Countries of Routing", "type": "array", "description": "Country of routing codes as an array of ISO 3166 Alpha-2 codes this must include all countries from the country of origin to destination in order", "items": { "oneOf": [ { "$ref": "#/components/schemas/LocationsCountry" } ] } }, "IdentifierGoodsItemNumber": { "title": "Good Item Number", "type": "string", "description": "The Good Item Number is a linear numeric identifier for the goods in the trade item object.", "example": "1" }, "TradeItems": { "title": "Trade Items", "description": "The details for the types of materials that are being loaded/exported", "type": "array", "minItems": 1, "required": [ "goodsItemNumber", "harmonizeSystemCode", "description", "ewcCode", "grossWeight", "quantity" ], "items": { "title": "Trade Item", "description": "The detail for the type of material that is being loaded/exported", "type": "object", "properties": { "goodsItemNumber": { "$ref": "#/components/schemas/IdentifierGoodsItemNumber" }, "harmonizeSystemCode": { "title": "Harmonize System Code", "pattern": "^[0-9]{4,10}$", "type": "string", "description": "The Harmonised Commodity Code of the material for Customs reporting purposes" }, "description": { "title": "Description of Goods", "pattern": "^[a-zA-Z0-9\\&\\ \\-\\.\\,\\/\\_\\(\\)\\']+$", "type": "string", "description": "A free text description of the type of material that is being loaded/exported. Populates Box 9 on the Annex VII" }, "ewcCode": { "title": "EWC Code", "pattern": "^[0-9]{6}$", "type": "string", "description": "The European Waste Code classification/description of the type of waste." }, "baselCode": { "title": "Basel Code", "type": "string", "description": "The Basel convention code classification/description of the type of waste." }, "grossWeight": { "$ref": "#/components/schemas/WeightTradeItemGross" }, "tareWeight": { "$ref": "#/components/schemas/WeightTradeItemTare" }, "netWeight": { "$ref": "#/components/schemas/WeightTradeItemNet" }, "quantity": { "title": "Quantity", "minimum": 1, "type": "number", "description": "Number of Bales or other that were loaded. Populates Box 3 on the Annex VII", "example": 22 }, "packageTypeCode": { "title": "Package Type Code", "type": "string", "description": "The type of packaging used for the goods, populates Box 10 on the Annex VII", "default": "BL", "externalDocs": { "description": "Full list of UK Trade Tariff kind of packages codes", "url": "https://www.gov.uk/government/publications/uk-trade-tariff-kind-of-packages-codes/uk-trade-tariff-kind-of-packages-codes" } }, "pricePerTonne": { "$ref": "#/components/schemas/CommonPricePerTonne" } } } }, "CodeBasel": { "title": "Basel Code", "description": "The Basel convention code classification/description of the type of waste.", "type": "string", "example": "B3020" }, "CodeEWC": { "title": "EWC Code", "pattern": "^[0-9]{6}$", "description": "The European Waste Code classification/description of the type of waste.", "type": "string", "example": "191201" }, "CodeRecovery": { "title": "Recovery Code", "description": "Recovery is one of the operations specified in Annex II B of Directive 2006/12/EC.", "type": "string", "pattern": "^(R[1-9]|R1[0-3])(,\\s*(R[1-9]|R1[0-3]))*$", "example": "R3" }, "WasteClassification": { "title": "Waste Classification", "description": "Traqa will determine this the waste risk classification automatically based on commodity code in accordance to government guidelines.", "type": "string", "enum": [ "GREEN", "AMBER", "RED" ], "example": "GREEN" }, "CodeIncoTerms": { "title": "Incoterms", "description": "The Incoterms code for the material movement", "type": "string", "enum": [ "CFR", "CIF", "CIP", "CPT", "DAF", "DAP", "DAT", "DDP", "DDU", "DEQ", "DES", "EXW", "FAS", "FCA", "FOB", "XXX" ] }, "CodeHarmonizeSystem": { "title": "Harmonize System Code", "pattern": "^[0-9]{4,10}$", "type": "string", "description": "The Harmonised Commodity Code of the material for Customs reporting purposes", "example": "4707100000" }, "CodeGoodsLocation": { "title": "Goods Location Code", "description": "Using the relevant codes, enter the location where the goods are located at the time they are declared and available for examination purposes. The Goods Location Code must be precise enough to allow Customs to carry out physical controls on the goods. DE 5/23 CDS, note use of CDS codes over CHIEF Codes as they are different. https://www.gov.uk/government/publications/uk-trade-tariff-cds-volume-3-export-declaration-completion-guide/group-5-dates-times-periods-places-countries-and-regions#de-523-location-of-goods-box-30-location-of-goods", "type": "string", "example": "GBAUBRKLIVBRKGVM" }, "CodeWasteCarrierLicense": { "title": "A coded Identifier for the haulier who arrives at site", "pattern": "^[/a-zA-Z0-9]{7,14}$", "type": "string", "description": "The haulier identifier is the waste carrier license number, mandated by the EA.", "example": "CBDU1234567" }, "CodeSCAC": { "title": "SCAC Code", "type": "string", "description": "Ocean Carriers use an identifying code known as SCAC", "enum": [ "ACLU", "ANRM", "AKMR", "ANNU", "APLU", "ARKU", "AROF", "NSAU", "BCLU", "CEGL", "CNIU", "CPJQ", "CMDU", "11DX", "COSU", "CMCU", "CHIW", "NSLU", "CHNJ", "DAAE", "DOLQ", "EQLI", "EIMU", "ESPU", "EUKO", "EGLV", "FESO", "GFAL", "ACSU", "GRIU", "GSLU", "UBCU", "GESC", "SUDU", "HLCU", "HDMU", "HUAU", "HRZU", "HYDU", "IILU", "IDMC", "INOC", "KKLU", "KOSL", "KMTU", "CLIB", "LGLT", "LMCU", "MAEU", "MFTU", "MRUB", "MATS", "MCCQ", "MISC", "MSCU", "NIDU", "NOSU", "NODA", "ONEY", "OOLU", "PSHI", "PCIU", "PMOL", "PLLU", "RCKI", "SAFM", "SLAQ", "SKII", "SCIU", "SMLU", "SEFN", "SEJJ", "SCYE", "SKLU", "CHVW", "THZS", "TOHO", "TOTE", "TRKU", "UALC", "USLU", "WECU", "WWSU", "22AA", "WDLS", "WLWH", "YMLU", "ZIMU" ] }, "CodePackageType": { "title": "Package", "type": "string", "enum": [ "PX", "BL" ], "description": "The package type code of the smallest external packing unit eg. BL or BN", "example": "BN" }, "CodeUnitOfMeasure": { "title": "Unit of Measure", "pattern": "^[a-zA-Z]+$", "type": "string", "description": "Units of measure. The only accepted value is `KGM`", "example": "KGM" }, "CodeVATNumber": { "title": "VAT Number", "type": "string", "pattern": "^(?:[A-Z]{2})?[0-9A-Z]{8,15}$", "example": "NL123456789B01" }, "CodeUNLocode": { "title": "UNLocode", "pattern": "^[A-Z0-9]{5}$", "type": "string", "description": "A coded reference to the location provided by the UN OR the alpha-2 (ISO 3166) country code", "example": "GBLIV" }, "CodeEORI": { "type": "string", "example": "GB123456789000", "pattern": "^[A-Z]{2}[A-Z0-9]{7,17}$", "title": "EORI Number", "description": "This format represents an EORI number. It starts with 2 digit country code e.g 'GB' followed by a 12 digit number." }, "CodeTraqa": { "type": "string", "example": "TQGBACMEL", "pattern": "^TQ[A-Z]{7}$", "title": "Traqa Code", "description": "Traqa created identifying code for a party." }, "CodeBICFacility": { "title": "Loading Site Code", "pattern": "^[A-Z]{9}$", "type": "string", "description": "A registered BIC Facility Code to identify the facility the material is being loaded at", "example": "GBEDMBIFA" }, "WeightTradeItemNet": { "allOf": [ { "$ref": "#/components/schemas/CommonWeight" } ], "title": "Material Net Weight", "description": "Weight of the Material loaded for movement, exc any pallet or packaging weight." }, "WeightTradeItemTare": { "allOf": [ { "$ref": "#/components/schemas/CommonZeroAllowedWeight" } ], "title": "Trade Item Tare Weight", "description": "Weight of the Material Packaging eg. pallet or packaging weight." }, "WeightTradeItemGross": { "allOf": [ { "$ref": "#/components/schemas/CommonWeight" } ], "title": "Material Gross Weight", "description": "Weight of the Material loaded for movement, populates Box 2 on the Annex VII" }, "WeightVerifiedGrossMass": { "title": "Verified Gross Weight", "required": [ "unit", "value", "weighingDate", "weightVerificationMethod" ], "type": "object", "properties": { "weightVerificationMethod": { "title": "Weight Verification Method", "type": "string", "description": "SOLAS VGM provides 2 methods, for all that are weighed at a weighbridge use method 1.", "enum": [ "1", "2" ] }, "unit": { "$ref": "#/components/schemas/CodeUnitOfMeasure" }, "weighingDate": { "$ref": "#/components/schemas/DatesWeighingDate" }, "value": { "title": "Value", "minimum": 1, "type": "number", "description": "The weight of the laden trailer or container including the tare weight of a container if appropriate", "example": 26350 } }, "description": "For container movements this container the Verified Gross Mass or VGM thats mandatory to enter a port for safety." }, "WeightEquipmentTareWeight": { "allOf": [ { "$ref": "#/components/schemas/CommonWeight" } ], "title": "Equipment Tare Weight", "description": "The tare weight of the equipment (container or trailer) is required for containerised movements to calculate the VGM." }, "CommonContact": { "type": "object", "title": "Contact", "properties": { "personName": { "title": "Person Name", "description": "The name, expressed as text, of this trade contact person.", "type": "string", "example": "Joe Smith" }, "telephone": { "title": "Telephone", "description": "Telephone communication information for this trade contact.", "type": "string", "example": "0800 000 0000" }, "emailAddress": { "$ref": "#/components/schemas/CommonEmailAddress" } } }, "CommonWeight": { "required": [ "unit", "value" ], "type": "object", "properties": { "unit": { "$ref": "#/components/schemas/CodeUnitOfMeasure" }, "value": { "title": "Weight Value", "minimum": 1, "type": "number", "description": "The weight of the equipment, product or other", "example": 26350 } } }, "CommonZeroAllowedWeight": { "required": [ "unit", "value" ], "type": "object", "properties": { "unit": { "$ref": "#/components/schemas/CodeUnitOfMeasure" }, "value": { "title": "Weight Value", "minimum": 0, "type": "number", "description": "The weight of the equipment, product or other", "example": 26350 } } }, "CommonEmailAddress": { "title": "Email Address", "description": "The billing email address for this account.", "type": "string", "example": "joe@domain.com" }, "CommonAddress": { "title": "Address", "description": "The provided structured address for a given party", "type": "object", "properties": { "street": { "title": "Street Name", "pattern": "^[a-zA-Z0-9\\&\\ \\-\\.\\,\\/\\_\\(\\)\\']+$", "type": "string", "example": "123 Main Street" }, "city": { "title": "City", "pattern": "^[a-zA-Z0-9\\&\\ \\-\\.\\,\\/\\_\\(\\)\\']+$", "type": "string", "example": "Liverpool" }, "state": { "title": "State", "pattern": "^[a-zA-Z0-9\\&\\ \\-\\.\\,\\/\\_\\(\\)\\']+$", "type": "string", "example": "Merseyside" }, "postcode": { "title": "Post Code", "pattern": "^[a-zA-Z0-9\\ \\-]+$", "type": "string", "example": "L1 0AA" }, "country": { "$ref": "#/components/schemas/LocationsCountry" }, "formatted": { "title": "Formatted Address", "description": "A formatted address string for display purposes", "type": "string", "example": "123 Main Street, Liverpool, Merseyside, L1 0AA, GB" } } }, "CommonPricePerTonne": { "title": "Price Per Tonne", "description": "The price per tonne of the material this is a mandatory field if customs is true.", "type": "number", "format": "float", "minimum": 1e-05, "example": 100.0 }, "ModelEmpty": { "title": "Empty Model", "type": "object" }, "ModelLoadplan": { "title": "Load Plan Model", "required": [ "consignee", "dates", "loadingSite", "portOfLoading", "references", "tradeItem" ], "type": "object", "properties": { "shipper": { "$ref": "#/components/schemas/PartyShipper" }, "loadingSite": { "$ref": "#/components/schemas/PartyLoadingSite" }, "carrier": { "$ref": "#/components/schemas/PartyCarrier" }, "consignee": { "$ref": "#/components/schemas/PartyConsignee" }, "haulier": { "$ref": "#/components/schemas/PartyHaulier" }, "recoveryFacility": { "$ref": "#/components/schemas/PartyRecoveryFacility" }, "references": { "title": "References", "description": "References for the movements in Traqa to identify the load and weighbridge ticket along with other useful references as needed and agreed between parties", "minProperties": 1, "required": [ "pickupReferenceNumber" ], "type": "object", "properties": { "carriersReferenceNumber": { "$ref": "#/components/schemas/ReferenceCarriersReferenceNumber" }, "shippersIdentifyingNumberForShipment": { "$ref": "#/components/schemas/ReferenceShippersIdentifyingNumberForShipment" }, "pickupReferenceNumber": { "$ref": "#/components/schemas/ReferencePickupReferenceNumber" }, "consigneeReference": { "$ref": "#/components/schemas/ReferenceConsignee" }, "loadingSiteReference": { "$ref": "#/components/schemas/ReferenceLoadingSite" }, "orderReference": { "$ref": "#/components/schemas/ReferenceOrderReference" }, "nilsTaskId": { "$ref": "#/components/schemas/NILSTaskId" } } }, "portOfLoading": { "$ref": "#/components/schemas/LocationsPortOfLoading" }, "portOfDischarge": { "$ref": "#/components/schemas/LocationsPortOfDischarge" }, "dates": { "title": "Dates", "required": [ "scheduledLoadingTransportEvent" ], "type": "object", "properties": { "scheduledLoadingTransportEvent": { "$ref": "#/components/schemas/DatesScheduledLoadingTransportEvent" } }, "description": "Dates that are relevent to the load plan, namely the planned date time of loading" }, "tradeItem": { "title": "Trade Items", "description": "The details for the types of materials that are being loaded/exported", "type": "array", "minItems": 1, "items": { "title": "Trade Item", "description": "The detail for the type of material that is being loaded/exported", "required": [ "description", "harmonizeSystemCode" ], "type": "object", "properties": { "ewcCode": { "$ref": "#/components/schemas/CodeEWC" }, "baselCode": { "$ref": "#/components/schemas/CodeBasel" }, "harmonizeSystemCode": { "title": "Harmonize System Code", "pattern": "^[0-9]{4,10}$", "type": "string", "description": "The Harmonised Commodity Code of the material for Customs reporting purposes" }, "description": { "title": "Description of Goods", "pattern": "^[a-zA-Z0-9\\&\\ \\-\\.\\,\\/\\_\\(\\)\\']+$", "type": "string", "description": "A free text description of the type of material that is being loaded/exported. Populates Box 9 on the Annex VII" }, "pricePerTonne": { "$ref": "#/components/schemas/CommonPricePerTonne" } } } }, "transportEquipment": { "type": "object", "properties": { "transportMeans": { "title": "Transport Means", "type": "string", "description": "The type of transport means used to move the material, either 'TRAILER' or 'CONTAINER'", "enum": [ "TRAILER", "CONTAINER" ] }, "accompanied": { "title": "Accompanied", "type": "boolean", "description": "Whether the transport equipment is accompanied by a driver", "example": true } } }, "countriesOfRouting": { "$ref": "#/components/schemas/LocationsCountriesOfRouting" }, "NILS": { "title": "Details of Loadplan NILS Flow", "type": "object", "description": "Details on state of NILS flow for load-plan. Automated field and should not be provided by shipper.", "properties": { "emailSent": { "description": "Determines whether the loadsite has been emailed with Annex VII and load-plan details prior to loading", "type": "boolean", "enum": [ true, false ], "default": false, "example": false } } }, "pern": { "$ref": "#/components/schemas/ReferencePERN" }, "customs": { "$ref": "#/components/schemas/ModelCustoms" }, "recoveryDisposalCode": { "$ref": "#/components/schemas/CodeRecovery" }, "wasteClassification": { "$ref": "#/components/schemas/WasteClassification" } }, "description": "The Load Plan that is provided by the shipper to a load site via Traqa, this will create new loads in Traqa for loading at a site." }, "ModelLoadplanCompleted": { "description": "The Load Plan that is provided by the shipper augmented with data provided by the loading site.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/ModelLoadplan" }, { "$ref": "#/components/schemas/ModelWeighingRecord" } ] }, "ModelLoadplanAny": { "description": "The Load Plan that is provided by the shipper augmented with data provided by the loading site.", "type": "object", "anyOf": [ { "$ref": "#/components/schemas/ModelLoadplan" }, { "$ref": "#/components/schemas/ModelLoadplanCompleted" } ] }, "ModelWeighingRecord": { "title": "Weighing Record Model", "required": [ "dates", "haulier", "references", "shipper", "tradeItem", "transportEquipment" ], "type": "object", "properties": { "shipper": { "$ref": "#/components/schemas/PartyShipper" }, "loadingSite": { "$ref": "#/components/schemas/PartyLoadingSite" }, "references": { "title": "References", "required": [ "pickupReferenceNumber" ], "type": "object", "properties": { "despatchNoteNumber": { "$ref": "#/components/schemas/ReferenceDespatchNoteNumber" }, "vehicleIdentificationNumber": { "$ref": "#/components/schemas/ReferenceVehicleIdentificationNumber" }, "pickupReferenceNumber": { "$ref": "#/components/schemas/ReferencePickupReferenceNumber" }, "driverName": { "$ref": "#/components/schemas/ReferenceDriverName" } }, "description": "References that are relevant to the Traqa loads and Shipper and Load Site to enable efficient exchange of loading data" }, "transportEquipment": { "title": "Transport Equipment", "description": "The Trailer or Container that is loaded with the material from load site.", "required": [ "equipmentNumber", "verifiedWeight" ], "type": "object", "properties": { "transportMeans": { "title": "Transport Means", "type": "string", "description": "The type of transport means used to move the material, either 'TRAILER' or 'CONTAINER'", "enum": [ "TRAILER", "CONTAINER" ] }, "accompanied": { "title": "Accompanied", "type": "boolean", "description": "Whether the transport equipment is accompanied by a driver", "example": true }, "verifiedWeight": { "$ref": "#/components/schemas/WeightVerifiedGrossMass" }, "equipmentTareWeight": { "$ref": "#/components/schemas/WeightEquipmentTareWeight" }, "seal": { "$ref": "#/components/schemas/EquipmentSeal" }, "equipmentNumber": { "$ref": "#/components/schemas/EquipmentNumber" }, "equipmentType": { "$ref": "#/components/schemas/EquipmentType" } } }, "haulier": { "$ref": "#/components/schemas/PartyHaulier" }, "dates": { "title": "Dates", "required": [ "actualArrivalTransportEvent", "actualDepartureTransportEvent" ], "type": "object", "properties": { "actualDepartureTransportEvent": { "$ref": "#/components/schemas/DatesActualDepartureTransportEvent" }, "actualArrivalTransportEvent": { "$ref": "#/components/schemas/DatesActualArrivalTransportEvent" } }, "description": "Dates relevant to the actual movement of material provided by the loading site " }, "tradeItem": { "title": "Trade Items", "type": "array", "minItems": 1, "items": { "title": "Trade Item", "required": [ "grossWeight", "goodsItemNumber", "quantity" ], "type": "object", "properties": { "goodsItemNumber": { "$ref": "#/components/schemas/IdentifierGoodsItemNumber" }, "grossWeight": { "$ref": "#/components/schemas/WeightTradeItemGross" }, "tareWeight": { "$ref": "#/components/schemas/WeightTradeItemTare" }, "netWeight": { "$ref": "#/components/schemas/WeightTradeItemNet" }, "quantity": { "title": "Quantity", "minimum": 1, "type": "number", "description": "Number of Bales or other that were loaded. Populates Box 3 on the Annex VII", "example": 22 }, "packageTypeCode": { "$ref": "#/components/schemas/CodePackageType" } } } } }, "description": "The Weight payload for a Loading Site to complete the weighing of planned Traqa loads, data comes from the weighbridge software. " }, "ModelCustoms": { "type": "object", "title": "Customs Model", "required": [ "invoice" ], "properties": { "declarationHistory": { "type": "object", "description": "A map of Customs Microservice Responses, keyed by unique declaration ID (UUID).", "additionalProperties": { "description": "Each entry represents a customs declaration response, keyed by unique UUID", "type": "object", "properties": { "declarationType": { "title": "Declaration Type", "type": "string", "description": "The type of customs declaration (e.g., EX for Export).", "example": "EX" }, "additionalDeclarationType": { "title": "Additional Declaration Type", "type": "string", "description": "Additional declaration type code.", "example": "A" }, "submissionRoute": { "title": "Submission Route", "type": "string", "description": "The route through which the customs declaration was submitted.", "example": "09" }, "ucr": { "title": "UCR", "type": "string", "description": "Unique Consignment Reference.", "example": "5GB594290217000-NPOCT613" }, "submissionDatetime": { "title": "Submission Date/Time", "type": "string", "format": "date-time", "description": "The date and time when the declaration was submitted.", "example": "2025-10-06T13:06:20" }, "mrn": { "title": "MRN", "type": "string", "description": "The Movement Reference Number is a unique identifier for the customs declaration.", "example": "25GBB1YCY7XP0D7AA7" }, "lrn": { "title": "LRN", "type": "string", "description": "Local Reference Number.", "example": "C67083DB977A4357" }, "submissionMethod": { "title": "Submission Method", "type": "string", "description": "The method used for submission (e.g., CDS for Customs Declaration Service).", "example": "CDS" }, "customsAction": { "title": "Customs Action", "type": "string", "description": "The action taken on the customs declaration.", "example": "SUBMIT" }, "icr": { "title": "ICR", "type": "string", "description": "Inventory Consignment Reference.", "example": "C9D2D2B9C4AF44" }, "dateOfReceipt": { "title": "Date of Receipt", "type": "string", "format": "date-time", "description": "The date and time when the declaration was received by customs.", "example": "2025-10-06T13:06:31" }, "freeTextSegments": { "title": "Free Text Segments", "type": "array", "description": "Additional information provided as free text.", "items": { "type": "string" }, "example": [ "Additional Information: A2: : []" ] }, "status": { "title": "Customs Microservice Status", "type": "string", "enum": [ "SENT", "OPEN", "UPDATED", "COMPLETED", "INTERNAL_SERVER_ERROR" ], "example": "COMPLETED" }, "errors": { "title": "Customs Errors", "type": "array", "description": "List of HMRC errors returned from customs declaration processing.", "items": { "type": "object", "properties": { "code": { "title": "Error Code", "type": "string", "description": "The error code returned by the customs microservice.", "example": "CDS10001" }, "description": { "title": "Error Description", "type": "string", "description": "The error description returned by the customs microservice.", "example": "Obligation error: Mandatory Data Element has not been provided." }, "explanation": { "title": "Error Explanation", "type": "string", "description": "The explanation of the error returned by the customs microservice.", "example": "Required details are missing." }, "details": { "title": "Error Details", "type": "string", "description": "The details of the error returned by the customs microservice.", "example": "Declaration. Consignment. Carrier. Address. Address. Country. Code" } } } }, "errorMessage": { "title": "Error Message", "type": "string", "description": "Plain text error message from the customs microservice, used when the error is not a structured HMRC error list." } } } }, "customsDeclaration": { "title": "Declare Customs", "description": "Specify whether you would like Traqa to submit a customs declaration to HMRC on your behalf for the load. Default is 'false'.", "type": "boolean", "nullable": true, "default": false, "example": false }, "declaration": { "title": "Customs Declaration Details", "description": "Customs declaration details used if Traqa has been tasked on submitting a customs declaration to HMRC on your behalf.", "type": "object", "required": [ "goodsLocation", "customsOfficeExit" ], "properties": { "goodsLocation": { "$ref": "#/components/schemas/CodeGoodsLocation" }, "customsOfficeExit": { "title": "Customs Office of Exit", "type": "string", "maxLength": 8, "description": "Using the relevant Union code, enter the customs office by which it is intended that the goods should leave the customs territory. DE 5/4 CDS", "example": "GB000001" }, "countryOfDestination": { "allOf": [ { "$ref": "#/components/schemas/LocationsCountry" } ], "description": "Destination country. If not provided, `POD` is considered destination for customs declarations." } } }, "invoice": { "required": [ "currency" ], "type": "object", "description": "Details required for the Commercial Invoice and Customs Declaration.", "properties": { "currency": { "description": "Currency code as defined by ISO 4217.", "type": "string", "example": "GBP" }, "amount": { "description": "Invoice amount. This attribute should be used if the Item Price Per Tonne is NOT used. It should not be used if Price Per Tonne IS used. Never Both.", "type": "number", "format": "float", "example": 1.0 } } }, "incoterms": { "$ref": "#/components/schemas/CodeIncoTerms" }, "buyer": { "$ref": "#/components/schemas/PartyBuyer" } } }, "ModelOrganization": { "type": "object", "properties": { "source": { "title": "Source", "type": "string", "description": "Source of organization details", "enum": [ "traqa", "eori", "vat", "wasteLicense" ], "example": "traqa" }, "identifier": { "oneOf": [ { "$ref": "#/components/schemas/CodeEORI" }, { "$ref": "#/components/schemas/CodeBICFacility" } ] }, "name": { "title": "Organization Name", "type": "string", "pattern": "^[a-zA-Z0-9\\&\\ \\-\\.\\,\\/\\_\\(\\)\\']+$", "description": "The name of the relevant organization.", "example": "ACME Trader Ltd" }, "address": { "$ref": "#/components/schemas/CommonAddress" }, "expiryDate": { "title": "Expiry Date", "type": "string", "description": "Expiry of identifier (eg. of a waste license)", "example": "2024-01-01" }, "contact": { "$ref": "#/components/schemas/CommonContact" }, "config": { "title": "Account Configuration", "type": "object", "description": "Configuration for account.", "properties": { "submitVGM": { "title": "Traqa VGM Submission Permission", "description": "Determines whether the organisation gives Traqa permission to submit VGM on their behalf.", "type": "boolean", "enum": [ true, false ], "default": false, "example": true }, "declareCustoms": { "title": "Traqa Customs Declaration Permission", "description": "Determines whether the organisation gives Traqa permission to declare customs on their behalf.", "type": "boolean", "enum": [ true, false ], "default": false, "example": true }, "digitalWasteTracking": { "title": "Traqa Digital Waste Tracking Permission", "description": "Determines whether the organisation gives Traqa permission to submit digital waste tracking data to Defra.", "type": "boolean", "enum": [ true, false ], "default": false, "example": true } } }, "identifiers": { "title": "Unique Identifiers", "type": "object", "description": "Unique identifiers of the organisation.", "properties": { "eori": { "$ref": "#/components/schemas/CodeEORI" }, "vat": { "$ref": "#/components/schemas/CodeVATNumber" }, "license": { "title": "EA Registration Number", "pattern": "^[a-zA-Z0-9]{7,13}$", "type": "string", "description": "A coded Identifier for the organisation, mandated by the EA." } } }, "billing": { "title": "Billing Configuration", "type": "object", "description": "Billing configuration for account.", "properties": { "emailAddress": { "title": "Email Address", "description": "The billing email address for this account.", "type": "string", "example": "joe@domain.com" }, "automation": { "title": "Automation billing configuration", "type": "object", "description": "Automation billing configuration for account.", "properties": { "flat": { "title": "Automation Billing is Flat Rate", "description": "Determines whether the organisation's automation billing is a monthly flat rate or not.", "type": "boolean", "enum": [ true, false ], "default": false, "example": true }, "value": { "title": "Automation Billing Value", "description": "Determines the organisation's automation billing value.", "type": "number", "example": 3.5 }, "target": { "title": "Automation Billing Target", "description": "Determines the organisation's automation target.", "type": "number", "example": 100 } } }, "customs": { "title": "Customs billing configuration", "type": "object", "description": "Customs billing configuration for account.", "properties": { "flat": { "title": "Customs Billing is Flat Rate", "description": "Determines whether the organisation's customs billing is a monthly flat rate or not.", "type": "boolean", "enum": [ true, false ], "default": false, "example": true }, "value": { "title": "Customs Billing Value", "description": "Determines the organisation's customs billing value.", "type": "number", "example": 10 }, "target": { "title": "Customs Billing Target", "description": "Determines the organisation's customs target.", "type": "number", "example": 10 } } } } }, "creatorId": { "title": "Creator's Identifier", "type": "string", "description": "Unique identifier of creator." }, "updaterId": { "title": "Updater's Identifier", "type": "string", "description": "Unique identifier of updater." }, "approverId": { "title": "Approver's Identifier", "type": "string", "description": "Unique identifier of approver." }, "xeroContactId": { "title": "Xero Contact ID", "type": "string", "description": "Unique identifier of contact in Xero." }, "role": { "title": "Organization Role", "type": "string", "enum": [ "Shipper", "LoadingSite" ], "description": "The role of the organization.", "example": "Shipper" } }, "example": { "identifier": "GB220861924000", "name": "Test Shipper for Traqa 4", "address": { "street": "1 Old Hall Street", "city": "Liverpool", "postcode": "L3 9HG", "country": "GB", "state": "Merseyside" }, "contact": { "personName": "John Smith", "telephone": "+44 0000000000", "emailAddress": "help@traqa.io" }, "config": { "submitVGM": true, "declareCustoms": true, "digitalWasteTracking": true }, "identifiers": { "eori": "GB220861924000", "license": "CBDU296918", "vat": "220861924" }, "billing": { "emailAddress": "bill@email.com", "automation": { "flat": true, "value": 25.0, "target": 100 }, "customs": { "flat": true, "value": 250.0, "target": 10 } }, "creatorId": "person@cif-consulting.co.uk", "updaterId": "person@cif-consulting.co.uk", "approverId": "person@cif-consulting.co.uk", "xeroContactId": "ea51cc52-2d3e-4e54-8686-a8904d89cf47", "role": "Shipper" } } }, "securitySchemes": { "basic_auth": { "type": "http", "scheme": "basic", "description": "Base64-encoded username:password credentials. Used to obtain a Bearer token via /getToken." }, "bearer_auth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT token obtained from /getToken. Pass as 'Bearer ' in the Authorization header." } } } }