Crowdsender API

Crowdsender API (1.0.0)

Download OpenAPI specification:Download

Crowdsender Support: support@crowdsender.io URL: https://crowdsender.io

Welcome

Welcome to the documentation for the Crowdsender API.

Getting Started

Before you can begin interacting with our API, you first need to create a Crowsender account and complete basic account setup.

For more details follow the steps describe in Getting started article to set up your account and get your api keys.

Get your account

You can create a free Crowdsender account here.

Add your couriers contracts

You need to have at least one courier contract, you can add it from here. More info about courier integrations.

Create an API key

Crowsender API use API keys for authorization. An API key is a token that a client provides when making API calls. The key should be sent as a request header called x-api-key:

GET /something HTTP/1.1 Cookie: X-API-KEY=abcdef12345.

To get an API key follow the next link.

Integrating with Crowdsender

API

The customer->Crowdsender communication will always be via API. You can use our API to create orders, generate labels or retrieve all documents of an order.

Webhooks

Crowdsender->customer communication will always be through webhooks. Crowdsender currently supports the following events to which a customer can subscribe:

Update tracking status: Every time there is a change in the tracking status of a box of an order, Crowsender will send a message with the order id, order number, box id, previous status, the new one, and the documents and the tracking id if available.

Update order status: Crowsender will send a message to the configured webhook every time an order changes status with the order id, order number, previous and new status.

Update send date: Crowsender will send a message to the configured webhook every time an order changes the shipping date with the order id, order number, previous and new value.

Update courier: Crowsender will send a message to the configured webhook every time an order changes carrier with the order id, order number, previous value, and new value.

Update Destination Address: Crowsender will send a message to the configured webhook every time an order changes carrier with the order id, the order number, and the previous and new full addresses.

Please visit our Webhook article to get more details about webhooks.

Orders

Add an order

Add an order to the platform

Request Body schema: application/json

Order to add

_id	string BSON format unique identifier used by database (Automatically assigned by our database)
orderNumber required	string Order identifier
customField1	string or null Custom field to store data refered to the order. This custom fields are configured on the client settings and are used to agroup orders into grouped documents
customField2	string or null Custom field to store data refered to the order. This custom fields are configured on the client settings and are used to agroup orders into grouped documents
customField3	string or null Custom field to store data refered to the order. This custom fields are configured on the client settings and are used to agroup orders into grouped documents
customField4	string or null Custom field to store data refered to the order. This custom fields are configured on the client settings and are used to agroup orders into grouped documents
customField5	string or null Custom field to store data refered to the order. This custom fields are configured on the client settings and are used to agroup orders into grouped documents
customField6	string or null Custom field to store data refered to the order. This custom fields are configured on the client settings and are used to agroup orders into grouped documents
	object
_client	string Client that created this order (Automatically assigned to the request sender client)
_externalReferenceId	string Unique identifier used by the client to store the order on its platform
_courierContract	string Courier contract identifier asssigned to this order to be applied
tags	Array of strings Default: [] List of tags assigned to this order
seller	string Name of the seller of the products that will be sent on this order
store	string Name of the store that sold this order
status	string Default: "REGISTERED" Enum: "REGISTERED" "PENDING_TO_SHIP" "SHIPPED" "SHIPMENT_FAILED" "COMPLETED" "CANCELED" "TO_REVIEW" Status of the order
addressValidationStatus	string Default: "UNVERIFIED" Enum: "UNVERIFIED" "VERIFIED" "PROPOSED" Address validation process status (Automatically assigned by our address validation process)
	object
lastSyncProvider	string <date-time> Last date the tracking status was updated with the carrier

Responses

Request samples

Payload

Content type

application/json

{"orderNumber": "DC00333",
"status": "REGISTERED",
"orderType": "OVERHARVEST",
"customField1": "REHKA775",
"shipment": {"shipTo": {"address": {"country": "es",
"name": "pepe",
"surnames": "pepe",
"street": "Calle de Granada",
"number": "3",
"details": "3B",
"zip": "28014",
"city": "Madrid",
"province": "Madrid",
"phone": {"prefix": "+34",
"number": "666776655"
},
"email": "pepe.pepe@gmail.com"
}
},
"boxes": [{"_boxId": "62739041d7226e71caeb2d68",
"customField1": "avocado tree Lamb Hass (2.5kg)",
"products": [{"description": "Mini avocados (Box of 2.5kg)",
"amount": 1,
"price": 15.7,
"taric": "080999",
"netWeight": {"value": 2,
"unit": "kg"
}
}
],
"physicalProperties": {"boxesPerPallet": 224,
"customWeight": {"value": 2.5,
"unit": "kg"
},
"weight": {"value": 3.5,
"unit": "kg"
}
}
}
],
"sendDate": "2022-05-13T00:00:00.000+0000",
"arrivalEstimateDate": "2022-05-13T00:00:00.000+0000",
"shipFrom": {"vatNumber": "B93748515",
"address": {"name": "Francisco José",
"surnames": "Marín Salgado",
"phone": {"prefix": "+34",
"number": "609679733"
},
"street": "Calle Alfredo Kraus",
"number": "1",
"details": "Local C",
"city": "Vélez-Málaga",
"zip": "29700",
"province": "Málaga",
"country": "es"
}
},
"language": "en"
},
"_orderManager": "613889ec10c7786c87d118f2",
"_courierContract": "620cda48590c8227ac0fa5a9",
"seller": "company-test",
"store": "6229c67ed92d8f22a4fb833a",
"_externalReferenceId": "62739041d7226e71caeb2d69"
}

Response samples

Content type

application/json

{"code": 201,
"info": "OK",
"data": {"_id": "6324560dfdc88d2b8246809d",
"orderNumber": "DC00333",
"status": "REGISTERED",
"orderType": "OVERHARVEST",
"customField1": "REHKA775",
"shipment": {"shipTo": {"address": {"country": "es",
"name": "pepe",
"surnames": "pepe",
"street": "Calle de Granada",
"number": "3",
"details": "3B",
"zip": "28014",
"city": "Madrid",
"province": "Madrid",
"phone": {"prefix": "+34",
"number": "666776655"
},
"email": "pepe.pepe@gmail.com"
}
},
"boxes": [{"_boxId": "62739041d7226e71caeb2d68",
"customField1": "avocado tree Lamb Hass (2.5kg)",
"products": [{"description": "Mini avocados (Box of 2.5kg)",
"amount": 1,
"price": 15.7,
"taric": "080999",
"netWeight": {"value": 2,
"unit": "kg"
},
"scanned": false
}
],
"physicalProperties": {"boxesPerPallet": 224,
"customWeight": {"value": 2.5,
"unit": "kg"
},
"weight": {"value": 3.5,
"unit": "kg"
}
},
"_id": "6324560cfdc88d2b8246809c",
"unified": "not unified",
"reprint": false,
"scanned": false,
"customerFiles": [ ],
"tracking": {"status": "waiting",
"manualStatus": false,
"notificated": false,
"testLabelDate": null,
"delivered": false,
"doubleScan": false,
"error": false,
"errorMessage": null,
"uniqueLabel": false,
"documents": [ ]
}
}
],
"sendDate": "2022-05-13T00:00:00.000Z",
"arrivalEstimateDate": "2022-05-13T00:00:00.000Z",
"shipFrom": {"vatNumber": "B93748515",
"address": {"name": "Juan",
"surnames": "Delgado",
"phone": {"prefix": "+34",
"number": "687546798"
},
"street": "Calle pepe",
"number": "1",
"details": "C",
"city": "Málaga",
"zip": "29700",
"province": "Málaga",
"country": "es"
}
},
"language": "en",
"autoGenerate": false
},
"_orderManager": "613889ec10c7786c87d118f2",
"_courierContract": "620cda48590c8227ac0fa5a9",
"seller": "company-test",
"store": "6229c67ed92d8f22a4fb833a",
"_externalReferenceId": "62739041d7226e71caeb2d69",
"_client": "8c655972cf492d4dbca82969",
"addressValidationStatus": "VERIFIED",
"tags": [ ],
"active": true,
"deleted": false,
"createdAt": "2022-09-16T10:55:09.029Z",
"updatedAt": "2022-09-16T10:55:09.029Z"
}
}

Update order data

Update an order to the platform

path Parameters

orderId

required

string

Example: 62739041d7226e71caeb2d69

Order internal ID

Request Body schema: application/json

_courierContract	string Courier contract identifier asssigned to this order to be applied
customField1	string Custom field to store data refered to the box. This custom fields are configured on the client settings and are used to agroup orders into grouped documents
customField2	string Custom field to store data refered to the box. This custom fields are configured on the client settings and are used to agroup orders into grouped documents
customField3	string Custom field to store data refered to the box. This custom fields are configured on the client settings and are used to agroup orders into grouped documents
customField4	string Custom field to store data refered to the box. This custom fields are configured on the client settings and are used to agroup orders into grouped documents
customField5	string Custom field to store data refered to the box. This custom fields are configured on the client settings and are used to agroup orders into grouped documents
customField6	string Custom field to store data refered to the box. This custom fields are configured on the client settings and are used to agroup orders into grouped documents
status	string Default: "REGISTERED" Enum: "REGISTERED" "PENDING_TO_SHIP" "SHIPPED" "SHIPMENT_FAILED" "COMPLETED" "CANCELED" "TO_REVIEW" Status of the order
addressValidationStatus	string Default: "UNVERIFIED" Enum: "UNVERIFIED" "VERIFIED" "PROPOSED" Address validation process status (Automatically assigned by our address validation process)
	object

Responses

Request samples

Payload

Content type

application/json

{"shipment": {"sendDate": "2022-05-13T00:00:00.000+0000"
}
}

Response samples

Content type

application/json

{"code": 200,
"info": "OK",
"data": "63b2f5306b59da0257703f13"
}

Labels

Trigger the label generation process

Trigger the label generation process for the orders that meet the query parameters

query Parameters

query

required

string

Example: query=seller=dona-ana%26shipment.sendDate=2022-02-24T00:00:00.000Z

Query filters that will be applied in order to generate labels of certain orders. Use this operators on the order model attributes using flattened format.

The allowed fields to filter are: 'addressValidationStatus', 'customField1', 'customField2', 'customField3', 'customField4', 'customField5', 'customField6', '_id', 'orderNumber', 'seller', 'shipment.boxes', 'shipment.boxes.customField1', 'shipment.boxes.customField2', 'shipment.boxes.customField3', 'shipment.boxes.customField4', 'shipment.boxes.customField5', 'shipment.boxes.customField6', 'shipment.boxes.scanDate', 'shipment.boxes.scanned', 'shipment.boxes._downloadableId', 'shipment.boxes.tracking.status', 'shipment.boxes.tracking.trackId', 'shipment.boxes.tracking.error', 'shipment.sendDate', 'shipment.shipFrom.companyName', 'shipment.shipTo.address.country', 'status', 'store', 'tags', '_courierContract'

For more info check the library documentation used to parse this parameter into database queries:

https://github.com/loris/api-query-params#readme

MongoDB	URI	Example	Result
$eq	key=val	type=public	{type: 'public'}
$gt	key>val	count>5	{count: {$gt: 5}}
$gte	key>=val	rating>=9.5	{rating: {$gte: 9.5}}
$lt	key<val	createdAt<2016-01-01	{createdAt: {$lt: Fri Jan 01 2016 01:00:00 GMT+0100 (CET)}}
$lte	key<=val	score<=-5	{score: {$lte: -5}}
$ne	key!=val	status!=success	{status: {$ne: 'success'}}
$in	key=val1,val2	country=GB,US	{country: {$in: ['GB', 'US']}}
$nin	key!=val1,val2	lang!=fr,en	{lang: {$nin: ['fr', 'en']}}
$exists	key	phone	{phone: {$exists: true}}
$exists	!key	!email	{email: {$exists: false}}
$regex	key=/value/	email=/@gmail.com$/i	{email: /@gmail.com$/i}
$regex	key!=/value/	phone!=/^06/	{phone: { $not: /^06/}}

Request Body schema: application/json

Parameters that configure the label generation process

grouped	boolean Default: false The labels will be generated grouped by the groupValues or on a single document
groupValues	Array of strings Default: [] Items Enum: "sendDate" "seller" "courier" "country" "orderCustomField1" "orderCustomField2" "orderCustomField3" "orderCustomField4" "orderCustomField5" "orderCustomField6" "boxCustomField1" "boxCustomField2" "boxCustomField3" "boxCustomField4" "boxCustomField5" "boxCustomField6" Orders fields selected to be grouped by

Responses

Request samples

Payload

Content type

application/json

{"grouped": true,
"groupValues": ["seller",
"boxCustomField1",
"sendDate",
"orderCustomField1"
]
}

Response samples

Content type

application/json

{"code": 200,
"info": "OK",
"data": {"response": "logistics queued as grouped batch project",
"batchId": ["63245f42fdc88d2b824680a6",
"63245f42fdc88d2b824680a9"
]
}
}

Documents

Get the necessary documents to prepare and send the order

obtains the necessary documents to prepare and send the order that meet the query parameters

query Parameters

query

required

string

Example: query=metadata.orderNumber=abc%26skip=0%26limit=10

Query filters that will be applied in order to get documents. Use this operators on the document model attributes using flattened format

The allowed fields to filter are: 'grouped', 'extensionType', 'directory', 'filename', 'type', 'url', 'tags', 'createdAt', 'createdBy', 'createdBy.name', 'createdBy._idUser', 'metadata.groupValues', 'metadata._batchId', 'metadata._boxId', 'metadata._externalBoxId', 'metadata._orderId', 'metadata.orderNumber'

For more info check the library documentation used to parse this parameter into database queries:

https://github.com/loris/api-query-params#readme

MongoDB	URI	Example	Result
$eq	key=val	type=public	{type: 'public'}
$gt	key>val	count>5	{count: {$gt: 5}}
$gte	key>=val	rating>=9.5	{rating: {$gte: 9.5}}
$lt	key<val	createdAt<2016-01-01	{createdAt: {$lt: Fri Jan 01 2016 01:00:00 GMT+0100 (CET)}}
$lte	key<=val	score<=-5	{score: {$lte: -5}}
$ne	key!=val	status!=success	{status: {$ne: 'success'}}
$in	key=val1,val2	country=GB,US	{country: {$in: ['GB', 'US']}}
$nin	key!=val1,val2	lang!=fr,en	{lang: {$nin: ['fr', 'en']}}
$exists	key	phone	{phone: {$exists: true}}
$exists	!key	!email	{email: {$exists: false}}
$regex	key=/value/	email=/@gmail.com$/i	{email: /@gmail.com$/i}
$regex	key!=/value/	phone!=/^06/	{phone: { $not: /^06/}}

Responses

Response samples

Content type

application/json

{"code": 200,
"info": "OK",
"data": {"count": 15,
"list": [{"_id": "634633b3a3a55ee29f01c96f",
"directory": "D:\\\\home\\\\site\\\\wwwroot\\\\src\\\\public\\\\documents\\\\",
"filename": "1665545139576-e89a937e-90c1-40e0-9a0c-205939fd4d6b.pdf",
"type": "LABEL",
"_client": "5c655972cf402d4dbca82969",
"seller": ["musterman"
],
"extensionType": "PDF",
"grouped": false,
"metadata": {"orderNumber": "O-2201092247",
"_orderId": "633ef928c8a4eaae4c655ec7",
"_boxId": "633ef928c8a4eaae4c655ec6",
"_externalBoxId": "633ef90fccdce819d0a4b961",
"_batchId": null,
"groupValues": [ ]
},
"createdBy": {"name": "Crowdsender"
},
"url": "https://common.crowdsender.io/labels/1665485839-e89a937e-90c1-49999-9a0c-205939fd4d6b.pdf",
"count": 1,
"tags": [ ],
"active": true,
"deleted": false,
"createdAt": "2022-10-12T03:25:39.607Z",
"updatedAt": "2022-10-12T03:25:39.607Z"
}
]
}
}

Crowdsender API (1.0.0)

Welcome

Getting Started

Get your account

Add your couriers contracts

Create an API key

Integrating with Crowdsender

API

Webhooks

Orders

Add an order

Request Body schema: application/json

Responses

Request samples

Response samples

Update order data

path Parameters

Request Body schema: application/json

Responses

Request samples

Response samples

Labels

Trigger the label generation process

query Parameters

Request Body schema: application/json

Responses

Request samples

Response samples

Documents

Get the necessary documents to prepare and send the order

query Parameters

Responses

Response samples

Company

Product

Resources

Company