Shops ===== A user can have one or more shops and be able to read or manage attached resources like shipments. A shipment is always associated with a shop. .. seealso:: https://api-specification.myparcel.com/#tag/Shops Attributes ---------- ============== ======================================================== ======== =========== Attribute Type Required Description ============== ======================================================== ======== =========== name string ✓ Name of the shop. website string URL of the website of the shop. return_address :doc:`address ` The address a parcel is returned to when delivery fails. sender_address :doc:`address ` The address parcels for this shop are sent from. reference string A reference for this shop, given by the user. logo_url string URL of the logo of the shop. Displayed on the branded tracking page. branding object containing ``returns`` and ``tracking`` style The branding determines the logo URL and colors of the returns portal and branded tracking page. created_at integer Unix timestamp when the shop was created. ============== ======================================================== ======== =========== ============ =================================================== ======== =========== Relationship Type Required Description ============ =================================================== ======== =========== organization :doc:`organizations ` ✓ The organization the shop belongs to ============ =================================================== ======== =========== Uploading a logo ---------------- When creating or updating a shop resource, it's possible to set a logo for a shop by setting the ``logo_url`` attribute. If the image is not available on any url, it is possible to upload a file to the API. The API will then return a ``logo_url`` attribute pointing to the logo. Uploading a logo is done by specifying the ``logo`` meta property in the POST/PATCH request (see examples below). The value of this attribute should be an object with two properties: .. list-table:: :header-rows: 1 :width: 100% :widths: 20 20 10 50 * - Property - Type - Required - Description * - mime_type - string - ✓ - The mime type of the file. This should be a mime_type of an image. * - contents - string - ✓ - The contents of the file, base64 encoded. ============= Property ============= Endpoints --------- .. raw:: html
GET /shops Retrieving a list of shops. **Scope** Any of the following scopes: - ``organizations.manage`` - ``shipments.manage`` **Request** .. code-block:: http GET /shops HTTP/1.1 Accept: application/vnd.api+json Example: https://api.sandbox.myparcel.com/shops **Response** .. code-block:: json { "data": [ { "type": "shops", "id": "35eddf50-1d84-47a3-8479-6bfda729cd99", "attributes": { "name": "MyParcel.com", "return_address": { "street_1": "Baker Street", "street_2": "Marylebone", "street_number": 221, "street_number_suffix": "B", "postal_code": "NW1 6XE", "city": "London", "country_code": "GB", "first_name": "Sherlock", "last_name": "Holmes", "company": "Holmes Investigations", "phone_number": "+31 234 567 890" }, "sender_address": { "street_1": "Baker Street", "street_2": "Marylebone", "street_number": 221, "street_number_suffix": "B", "postal_code": "NW1 6XE", "city": "London", "country_code": "GB", "first_name": "Sherlock", "last_name": "Holmes", "company": "Holmes Investigations", "phone_number": "+31 234 567 890" }, "website": "https://www.myparcel.com", "created_at": 1504801719, "reference": "MyParcel.com", "branding": { "tracking": { "logo_url": "https://www.mywebsite.com/logo.png" "primary_color": "#008800", "secondary_color": "#202025", "background_color": "#fafafa", "foreground_color": "#ffffff", "accent_color": "ffba00", }, }, }, "relationships": { "organization": { "data": { "type": "organizations", "id": "9cdf86e8-333f-4ed9-bb31-4935c780c947" }, "links": { "related": "https://api.sandbox.myparcel.com/organizations/9cdf86e8-333f-4ed9-bb31-4935c780c947" } } }, "links": { "self": "https://api.sandbox.myparcel.com/shops/35eddf50-1d84-47a3-8479-6bfda729cd99" } } ], "meta": { "total_pages": 1, "total_records": 1 }, "links": { "self": "https://api.sandbox.myparcel.com/shops?page[number]=1&page[size]=30", "first": "https://api.sandbox.myparcel.com/shops?page[number]=1&page[size]=30", "last": "https://api.sandbox.myparcel.com/shops?page[number]=1&page[size]=30" } } .. raw:: html
GET /shops/{shop_id} Retrieve a specific shop. **Scope** Any of the following scopes: - ``organizations.manage`` - ``shipments.manage`` **Request** .. code-block:: http GET /shops/{shop_id} HTTP/1.1 Accept: application/vnd.api+json Example: https://api.sandbox.myparcel.com/shops/35eddf50-1d84-47a3-8479-6bfda729cd99 **Response** .. code-block:: json { "data": { "type": "shops", "id": "35eddf50-1d84-47a3-8479-6bfda729cd99", "attributes": { "name": "MyParcel.com", "return_address": { "street_1": "Baker Street", "street_2": "Marylebone", "street_number": 221, "street_number_suffix": "B", "postal_code": "NW1 6XE", "city": "London", "country_code": "GB", "first_name": "Sherlock", "last_name": "Holmes", "company": "Holmes Investigations", "phone_number": "+31 234 567 890" }, "sender_address": { "street_1": "Baker Street", "street_2": "Marylebone", "street_number": 221, "street_number_suffix": "B", "postal_code": "NW1 6XE", "city": "London", "country_code": "GB", "first_name": "Sherlock", "last_name": "Holmes", "company": "Holmes Investigations", "phone_number": "+31 234 567 890" }, "website": "https://www.myparcel.com", "created_at": 1504801719, "reference": "MyParcel.com", "branding": { "tracking": { "logo_url": "https://www.mywebsite.com/logo.png" "primary_color": "#008800", "secondary_color": "#202025", "background_color": "#fafafa", "foreground_color": "#ffffff", "accent_color": "ffba00", }, }, }, "relationships": { "organization": { "data": { "type": "organizations", "id": "9cdf86e8-333f-4ed9-bb31-4935c780c947" }, "links": { "related": "https://api.sandbox.myparcel.com/organizations/9cdf86e8-333f-4ed9-bb31-4935c780c947" } } }, "links": { "self": "https://api.sandbox.myparcel.com/shops/35eddf50-1d84-47a3-8479-6bfda729cd99" } } } .. raw:: html
POST /shops Create a shop. **Scope** - ``shops.manage`` **Request** .. code-block:: http POST /shops HTTP/1.1 Accept: application/vnd.api+json Content-Type: application/vnd.api+json Example: https://api.sandbox.myparcel.com/shops { "data": { "type": "shops", "attributes": { "name": "MyParcel.com", "return_address": { "street_1": "Baker Street", "street_2": "Marylebone", "street_number": 221, "street_number_suffix": "B", "postal_code": "NW1 6XE", "city": "London", "country_code": "GB", "first_name": "Sherlock", "last_name": "Holmes", "company": "Holmes Investigations", "phone_number": "+31 234 567 890" }, "sender_address": { "street_1": "Baker Street", "street_2": "Marylebone", "street_number": 221, "street_number_suffix": "B", "postal_code": "NW1 6XE", "city": "London", "country_code": "GB", "first_name": "Sherlock", "last_name": "Holmes", "company": "Holmes Investigations", "phone_number": "+31 234 567 890" }, "website": "https://www.myparcel.com", "reference": "MyParcel.com", "branding": { "tracking": { "logo_url": "https://www.mywebsite.com/logo.png" "primary_color": "#008800", "secondary_color": "#202025", "background_color": "#fafafa", "foreground_color": "#ffffff", "accent_color": "ffba00", }, }, }, "relationships": { "organization": { "data": { "type": "organizations", "id": "9cdf86e8-333f-4ed9-bb31-4935c780c947" } } }, "meta": { "logo": { "mime_type": "image/png", "contents": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..." } } } } **Response** .. code-block:: json { "data": { "type": "shops", "id": "35eddf50-1d84-47a3-8479-6bfda729cd99", "attributes": { "name": "MyParcel.com", "return_address": { "street_1": "Baker Street", "street_2": "Marylebone", "street_number": 221, "street_number_suffix": "B", "postal_code": "NW1 6XE", "city": "London", "country_code": "GB", "first_name": "Sherlock", "last_name": "Holmes", "company": "Holmes Investigations", "phone_number": "+31 234 567 890" }, "sender_address": { "street_1": "Baker Street", "street_2": "Marylebone", "street_number": 221, "street_number_suffix": "B", "postal_code": "NW1 6XE", "city": "London", "country_code": "GB", "first_name": "Sherlock", "last_name": "Holmes", "company": "Holmes Investigations", "phone_number": "+31 234 567 890" }, "website": "https://www.myparcel.com", "created_at": 1504801719, "reference": "MyParcel.com", "branding": { "tracking": { "logo_url": "https://www.mywebsite.com/logo.png" "primary_color": "#008800", "secondary_color": "#202025", "background_color": "#fafafa", "foreground_color": "#ffffff", "accent_color": "ffba00", }, }, }, "relationships": { "organization": { "data": { "type": "organizations", "id": "9cdf86e8-333f-4ed9-bb31-4935c780c947" }, "links": { "related": "https://api.sandbox.myparcel.com/organizations/9cdf86e8-333f-4ed9-bb31-4935c780c947" } } }, "links": { "self": "https://api.sandbox.myparcel.com/shops/35eddf50-1d84-47a3-8479-6bfda729cd99" } } } .. raw:: html
PATCH /shops/{shop_id} Update an existing shop. **Scope** - ``shops.manage`` **Request** In this example we're changing the name of the shop to "Sherlock Holmes' trinkets" .. code-block:: http PATCH /shops/{shop_id} HTTP/1.1 Accept: application/vnd.api+json Content-Type: application/vnd.api+json Example: https://api.sandbox.myparcel.com/shops/35eddf50-1d84-47a3-8479-6bfda729cd99 { "data": { "type": "shops", "id": "35eddf50-1d84-47a3-8479-6bfda729cd99", "attributes": { "name": "Sherlock Holmes' trinkets" } } } **Response** .. code-block:: json { "data": { "type": "shops", "id": "35eddf50-1d84-47a3-8479-6bfda729cd99", "attributes": { "name": "Sherlock Holmes' trinkets", "return_address": { "street_1": "Baker Street", "street_2": "Marylebone", "street_number": 221, "street_number_suffix": "B", "postal_code": "NW1 6XE", "city": "London", "country_code": "GB", "first_name": "Sherlock", "last_name": "Holmes", "company": "Holmes Investigations", "phone_number": "+31 234 567 890" }, "sender_address": { "street_1": "Baker Street", "street_2": "Marylebone", "street_number": 221, "street_number_suffix": "B", "postal_code": "NW1 6XE", "city": "London", "country_code": "GB", "first_name": "Sherlock", "last_name": "Holmes", "company": "Holmes Investigations", "phone_number": "+31 234 567 890" }, "website": "https://www.myparcel.com", "created_at": 1504801719, "reference": "MyParcel.com", "branding": { "tracking": { "logo_url": "https://www.mywebsite.com/logo.png" "primary_color": "#008800", "secondary_color": "#202025", "background_color": "#fafafa", "foreground_color": "#ffffff", "accent_color": "ffba00", }, }, }, "relationships": { "organization": { "data": { "type": "organizations", "id": "9cdf86e8-333f-4ed9-bb31-4935c780c947" }, "links": { "related": "https://api.sandbox.myparcel.com/organizations/9cdf86e8-333f-4ed9-bb31-4935c780c947" } } }, "meta": { "logo": { "mime_type": "image/png", "contents": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..." } }, "links": { "self": "https://api.sandbox.myparcel.com/shops/35eddf50-1d84-47a3-8479-6bfda729cd99" } } } .. raw:: html