Collections =========== Collections are used to have the carrier pick up shipments from a home or business address. .. seealso:: https://api-specification.myparcel.com/#tag/Collections Attributes ---------- ================== ================================================================== ========== ============================================================= Attribute Type Required Description ================== ================================================================== ========== ============================================================= address :doc:`address ` ✓ The address where the collection should take place. collection_time :doc:`collection_time ` ✓ The requested time slot for the collection. description string Description of the collection. Useful as internal reference. register boolean Indicates whether the collection should be registered. tracking_code string The tracking code of the collection. ================== ================================================================== ========== ============================================================= ================== ================================================================== ========== ============================================================= Relationships Type Required Description ================== ================================================================== ========== ============================================================= contract :doc:`contract ` ✓ The contract that is used for this collection. Its credentials will be used to create the collection at the carrier. shop :doc:`shop ` ✓ The shop to create the collection for. status :doc:`status ` ✓ The status of the collection. files array of :doc:`files ` The files that are attached to the collection. manifest :doc:`manifest ` The manifest of the shipments to be collected. shipments array of :doc:`shipments ` The shipments that are to be collected. ================== ================================================================== ========== ============================================================= Collection statuses ------------------- ================================== ========================================== Status code Description ================================== ========================================== collection-concept The collection has been created but not yet registered. It can still be edited. collection-registered The collection has been registered with the carrier. It can no longer be edited. collection-registration-failed The collection could not be registered with the carrier. collection-voided The collection has been voided. ================================== ========================================== Endpoints --------- .. raw:: html
GET /collections Retrieving a list of collections. **Scope** Any of the following scopes: - ``shipments.manage`` - ``shipments.view`` **Request** .. code-block:: http GET /collections HTTP/1.1 Accept: application/vnd.api+json Example: https://api.sandbox.myparcel.com/collections **Response** .. code-block:: json { "data": [ { "type": "collections", "id": "e26d781b-6c56-4be5-ae72-505db793d2bd", "attributes": { "description": "First Collection", "address": { "street_1": "Baker Street", "street_2": "Marylebone", "street_number": 221, "street_number_suffix": "B", "postal_code": "NW1 6XE", "city": "London", "state_code": "ENG", "country_code": "GB", "first_name": "Sherlock", "last_name": "Holmes", "company": "Holmes Investigations", "email": "s.holmes@holmesinvestigations.com", "phone_number": "+31 234 567 890" }, "collection_time": { "from": 1648110600, "to": 1648114200 }, "tracking_code": "TRC123456", "created_at": 1504801719 }, "relationships": { "contract": { "data": { "type": "contracts", "id": "2cb32706-5762-4b96-9212-327e6afaeeff" }, "links": { "related": "https://api.sandbox.myparcel.com/contracts/2cb32706-5762-4b96-9212-327e6afaeeff" } }, "files": { "data": [ { "type": "files", "id": "0f621db6-d239-4ae9-b85d-8e97469b10ce" } ], "links": { "related": "https://api.sandbox.myparcel.com/files/0f621db6-d239-4ae9-b85d-8e97469b10ce" } }, "manifest": { "data": { "type": "manifests", "id": "ce7f6752-34e0-49a1-a832-bcc209450ea8" }, "links": { "related": "https://api.sandbox.myparcel.com/manifests/ce7f6752-34e0-49a1-a832-bcc209450ea8" } }, "shipments": { "data": [ { "type": "shipments", "id": "7b808eee-bf1c-40cd-98f2-3c335a06417e" } ] }, "shop": { "data": { "type": "shops", "id": "35eddf50-1d84-47a3-8479-6bfda729cd99" }, "links": { "related": "https://api.sandbox.myparcel.com/shops/35eddf50-1d84-47a3-8479-6bfda729cd99" } }, "status": { "data": { "type": "statuses", "id": "5c868557-0827-4d21-a7f4-9820f01769f4" }, "links": { "related": "https://api.sandbox.myparcel.com/statuses/5c868557-0827-4d21-a7f4-9820f01769f4" } } }, "links": { "self": "https://api.sandbox.myparcel.com/collections/e26d781b-6c56-4be5-ae72-505db793d2bd" } } ], "meta": { "total_pages": 13, "total_records": 373 }, "included": [ { "type": "contracts", "id": "2cb32706-5762-4b96-9212-327e6afaeeff", "attributes": { "currency": "EUR", "name": "My Custom Contract", "status": "active", "created_at": 1504801719, "updated_at": 1504801719 }, "relationships": { "carrier": { "data": { "type": "carriers", "id": "be7f6752-34e0-49a1-a832-bcc209450ea9" }, "links": { "related": "https://api.sandbox.myparcel.com/carriers/be7f6752-34e0-49a1-a832-bcc209450ea9" } }, "owner": { "data": { "type": "organizations", "id": "9cdf86e8-333f-4ed9-bb31-4935c780c947" } }, "liability_coverages": { "data": [ { "type": "liability-coverages", "id": "5a7ef73a-ddea-11e9-8a34-2a2ae2dbcce4" } ] }, "template": { "data": { "type": "contracts", "id": "2cb32706-5762-4b96-9212-327e6afaeeff" }, "links": { "related": "https://api.sandbox.myparcel.com/contracts/2cb32706-5762-4b96-9212-327e6afaeeff" } } }, "links": { "self": "https://api.sandbox.myparcel.com/contracts/2cb32706-5762-4b96-9212-327e6afaeeff" } } ], "links": { "self": "https://api.sandbox.myparcel.com/collections?page[number]=3&page[size]=30", "first": "https://api.sandbox.myparcel.com/collections?page[number]=1&page[size]=30", "prev": "https://api.sandbox.myparcel.com/collections?page[number]=2&page[size]=30", "next": "https://api.sandbox.myparcel.com/collections?page[number]=4&page[size]=30", "last": "https://api.sandbox.myparcel.com/collections?page[number]=13&page[size]=30" } } .. raw:: html
GET /collections/{collection_id} Retrieve a specific collection. **Scope** Any of the following scopes: - ``shipments.manage`` - ``shipments.view`` **Request** .. code-block:: http GET /collections/{collection_id} HTTP/1.1 Accept: application/vnd.api+json Example: https://api.sandbox.myparcel.com/collections/e26d781b-6c56-4be5-ae72-505db793d2bd **Response** .. code-block:: json { "data": { "type": "collections", "id": "e26d781b-6c56-4be5-ae72-505db793d2bd", "attributes": { "description": "First Collection", "address": { "street_1": "Baker Street", "street_2": "Marylebone", "street_number": 221, "street_number_suffix": "B", "postal_code": "NW1 6XE", "city": "London", "state_code": "ENG", "country_code": "GB", "first_name": "Sherlock", "last_name": "Holmes", "company": "Holmes Investigations", "email": "s.holmes@holmesinvestigations.com", "phone_number": "+31 234 567 890" }, "collection_time": { "from": 1648110600, "to": 1648114200 }, "tracking_code": "TRC123456", "created_at": 1504801719 }, "relationships": { "contract": { "data": { "type": "contracts", "id": "2cb32706-5762-4b96-9212-327e6afaeeff" }, "links": { "related": "https://api.sandbox.myparcel.com/contracts/2cb32706-5762-4b96-9212-327e6afaeeff" } }, "files": { "data": [ { "type": "files", "id": "0f621db6-d239-4ae9-b85d-8e97469b10ce" } ], "links": { "related": "https://api.sandbox.myparcel.com/files/0f621db6-d239-4ae9-b85d-8e97469b10ce" } }, "manifest": { "data": { "type": "manifests", "id": "ce7f6752-34e0-49a1-a832-bcc209450ea8" }, "links": { "related": "https://api.sandbox.myparcel.com/manifests/ce7f6752-34e0-49a1-a832-bcc209450ea8" } }, "shipments": { "data": [ { "type": "shipments", "id": "7b808eee-bf1c-40cd-98f2-3c335a06417e" } ] }, "shop": { "data": { "type": "shops", "id": "35eddf50-1d84-47a3-8479-6bfda729cd99" }, "links": { "related": "https://api.sandbox.myparcel.com/shops/35eddf50-1d84-47a3-8479-6bfda729cd99" } }, "status": { "data": { "type": "statuses", "id": "5c868557-0827-4d21-a7f4-9820f01769f4" }, "links": { "related": "https://api.sandbox.myparcel.com/statuses/5c868557-0827-4d21-a7f4-9820f01769f4" } } }, "links": { "self": "https://api.sandbox.myparcel.com/collections/e26d781b-6c56-4be5-ae72-505db793d2bd" } }, "included": [ { "type": "contracts", "id": "2cb32706-5762-4b96-9212-327e6afaeeff", "attributes": { "currency": "EUR", "name": "My Custom Contract", "status": "active", "created_at": 1504801719, "updated_at": 1504801719 }, "relationships": { "carrier": { "data": { "type": "carriers", "id": "be7f6752-34e0-49a1-a832-bcc209450ea9" }, "links": { "related": "https://api.sandbox.myparcel.com/carriers/be7f6752-34e0-49a1-a832-bcc209450ea9" } }, "owner": { "data": { "type": "organizations", "id": "9cdf86e8-333f-4ed9-bb31-4935c780c947" } }, "liability_coverages": { "data": [ { "type": "liability-coverages", "id": "5a7ef73a-ddea-11e9-8a34-2a2ae2dbcce4" } ] }, "template": { "data": { "type": "contracts", "id": "2cb32706-5762-4b96-9212-327e6afaeeff" }, "links": { "related": "https://api.sandbox.myparcel.com/contracts/2cb32706-5762-4b96-9212-327e6afaeeff" } } }, "links": { "self": "https://api.sandbox.myparcel.com/contracts/2cb32706-5762-4b96-9212-327e6afaeeff" } } ] } .. raw:: html
POST /collections Create a new collection. **Scope** Any of the following scopes: - ``shipments.manage`` **Request** .. code-block:: http POST /collections HTTP/1.1 Accept: application/vnd.api+json Example: https://api.sandbox.myparcel.com/collections .. code-block:: json { "data": { "type": "collections", "attributes": { "description": "First Collection", "address": { "street_1": "Baker Street", "street_2": "Marylebone", "street_number": 221, "street_number_suffix": "B", "postal_code": "NW1 6XE", "city": "London", "state_code": "ENG", "country_code": "GB", "first_name": "Sherlock", "last_name": "Holmes", "company": "Holmes Investigations", "email": "s.holmes@holmesinvestigations.com", "phone_number": "+31 234 567 890" }, "register": true, "collection_time": { "from": 1648110600, "to": 1648114200 } }, "relationships": { "contract": { "data": { "type": "contracts", "id": "2cb32706-5762-4b96-9212-327e6afaeeff" } }, "shipments": { "data": [ { "type": "shipments", "id": "7b808eee-bf1c-40cd-98f2-3c335a06417e" } ] }, "shop": { "data": { "type": "shops", "id": "35eddf50-1d84-47a3-8479-6bfda729cd99" } } } } } **Response** .. code-block:: json { "data": { "type": "collections", "id": "e26d781b-6c56-4be5-ae72-505db793d2bd", "attributes": { "description": "First Collection", "address": { "street_1": "Baker Street", "street_2": "Marylebone", "street_number": 221, "street_number_suffix": "B", "postal_code": "NW1 6XE", "city": "London", "state_code": "ENG", "country_code": "GB", "first_name": "Sherlock", "last_name": "Holmes", "company": "Holmes Investigations", "email": "s.holmes@holmesinvestigations.com", "phone_number": "+31 234 567 890" }, "collection_time": { "from": 1648110600, "to": 1648114200 }, "tracking_code": "TRC123456", "created_at": 1504801719 }, "relationships": { "contract": { "data": { "type": "contracts", "id": "2cb32706-5762-4b96-9212-327e6afaeeff" }, "links": { "related": "https://api.sandbox.myparcel.com/contracts/2cb32706-5762-4b96-9212-327e6afaeeff" } }, "files": { "data": [ { "type": "files", "id": "0f621db6-d239-4ae9-b85d-8e97469b10ce" } ], "links": { "related": "https://api.sandbox.myparcel.com/files/0f621db6-d239-4ae9-b85d-8e97469b10ce" } }, "manifest": { "data": { "type": "manifests", "id": "ce7f6752-34e0-49a1-a832-bcc209450ea8" }, "links": { "related": "https://api.sandbox.myparcel.com/manifests/ce7f6752-34e0-49a1-a832-bcc209450ea8" } }, "shipments": { "data": [ { "type": "shipments", "id": "7b808eee-bf1c-40cd-98f2-3c335a06417e" } ] }, "shop": { "data": { "type": "shops", "id": "35eddf50-1d84-47a3-8479-6bfda729cd99" }, "links": { "related": "https://api.sandbox.myparcel.com/shops/35eddf50-1d84-47a3-8479-6bfda729cd99" } }, "status": { "data": { "type": "statuses", "id": "5c868557-0827-4d21-a7f4-9820f01769f4" }, "links": { "related": "https://api.sandbox.myparcel.com/statuses/5c868557-0827-4d21-a7f4-9820f01769f4" } } }, "links": { "self": "https://api.sandbox.myparcel.com/collections/e26d781b-6c56-4be5-ae72-505db793d2bd" } } } .. raw:: html
PATCH /collections/{collection_id} Update a specific collection. **Scope** Any of the following scopes: - ``shipments.manage`` **Request** .. code-block:: http PATCH /collections/{collection_id} HTTP/1.1 Accept: application/vnd.api+json Example: https://api.sandbox.myparcel.com/collections/e26d781b-6c56-4be5-ae72-505db793d2bd .. code-block:: json { "data": { "type": "collections", "id": "e26d781b-6c56-4be5-ae72-505db793d2bd", "attributes": { "description": "First Collection", "address": { "street_1": "Baker Street", "street_2": "Marylebone", "street_number": 221, "street_number_suffix": "B", "postal_code": "NW1 6XE", "city": "London", "state_code": "ENG", "country_code": "GB", "first_name": "Sherlock", "last_name": "Holmes", "company": "Holmes Investigations", "email": "s.holmes@holmesinvestigations.com", "phone_number": "+31 234 567 890" }, "register": true, "collection_time": { "from": 1648110600, "to": 1648114200 } }, "relationships": { "contract": { "data": { "type": "contracts", "id": "2cb32706-5762-4b96-9212-327e6afaeeff" } }, "shipments": { "data": [ { "type": "shipments", "id": "7b808eee-bf1c-40cd-98f2-3c335a06417e" } ] }, "shop": { "data": { "type": "shops", "id": "35eddf50-1d84-47a3-8479-6bfda729cd99" } } } } } **Response** .. code-block:: json { "data": { "type": "collections", "id": "e26d781b-6c56-4be5-ae72-505db793d2bd", "attributes": { "description": "First Collection", "address": { "street_1": "Baker Street", "street_2": "Marylebone", "street_number": 221, "street_number_suffix": "B", "postal_code": "NW1 6XE", "city": "London", "state_code": "ENG", "country_code": "GB", "first_name": "Sherlock", "last_name": "Holmes", "company": "Holmes Investigations", "email": "s.holmes@holmesinvestigations.com", "phone_number": "+31 234 567 890" }, "collection_time": { "from": 1648110600, "to": 1648114200 }, "tracking_code": "TRC123456", "created_at": 1504801719 }, "relationships": { "contract": { "data": { "type": "contracts", "id": "2cb32706-5762-4b96-9212-327e6afaeeff" }, "links": { "related": "https://api.sandbox.myparcel.com/contracts/2cb32706-5762-4b96-9212-327e6afaeeff" } }, "files": { "data": [ { "type": "files", "id": "0f621db6-d239-4ae9-b85d-8e97469b10ce" } ], "links": { "related": "https://api.sandbox.myparcel.com/files/0f621db6-d239-4ae9-b85d-8e97469b10ce" } }, "manifest": { "data": { "type": "manifests", "id": "ce7f6752-34e0-49a1-a832-bcc209450ea8" }, "links": { "related": "https://api.sandbox.myparcel.com/manifests/ce7f6752-34e0-49a1-a832-bcc209450ea8" } }, "shipments": { "data": [ { "type": "shipments", "id": "7b808eee-bf1c-40cd-98f2-3c335a06417e" } ] }, "shop": { "data": { "type": "shops", "id": "35eddf50-1d84-47a3-8479-6bfda729cd99" }, "links": { "related": "https://api.sandbox.myparcel.com/shops/35eddf50-1d84-47a3-8479-6bfda729cd99" } }, "status": { "data": { "type": "statuses", "id": "5c868557-0827-4d21-a7f4-9820f01769f4" }, "links": { "related": "https://api.sandbox.myparcel.com/statuses/5c868557-0827-4d21-a7f4-9820f01769f4" } } }, "links": { "self": "https://api.sandbox.myparcel.com/collections/e26d781b-6c56-4be5-ae72-505db793d2bd" } } } .. raw:: html
DELETE /collections/{collection_id} Delete a collection. .. note:: Collections that have been registered cannot be deleted. **Scope** Any of the following scopes: - ``shipments.manage`` **Request** .. code-block:: http DELETE /collections/{collection_id} HTTP/1.1 Accept: application/vnd.api+json Example: https://api.sandbox.myparcel.com/collections/e26d781b-6c56-4be5-ae72-505db793d2bd **Response** .. code-block:: http HTTP/1.1 204 The collection has been deleted. .. raw:: html