Add Serviceability Areas
Description
Logistics service providers often maintain data about the areas they serve at different pin codes/regions/cities. This data is commonly referred to as Serviceability. Serviceability indicates the set of regions/pin codes/cities that particular scheme can provide their pickup and delivery services. It is necessary to upload the Serviceability CSV file for creating a schemes. Once a Scheme is created, it is essential to provide serviceability data to be stored against a scheme.
Get Countries Hierarchy Data for Data Upload
The getCountries FDK method is used to get the hierarchy data of the country for which you want to upload the data.
getCountriesRequest
In the below given example request, the key "q": "India" in the request filters the response to show data specifically for India. This is useful when a seller want to upload data against different geographic divisions. For example, pincode, city, or state, which aligns with India’s administrative setup. If the "q" parameter is commented out, the API returns hierarchical data for all available countries.
basicRouter.get('/countries', async function view(req, res, next) {
try {
const partnerClient = await fdkExtension.getPartnerClient('66a0f176a257365a44f33d4c');
const response = await partnerClient.logistics.getCountries({
"organizationId": organizationId,
"onboarding": true,
"q": "india"
});
console.log(JSON.stringify(response))
res.json(response);
} catch (err) {
console.error(err);
console.log(JSON.stringify(err))
res.status(404).json({ success: false });
}
});
Response
In the below given example response, the response shows India’s hierarchy, specifying that logistics actions can be performed at the pincode, city, or state level. Additionally, the response includes general country details such as the phone code (+91), currency (Indian Rupee '₹'), and time zone (Asia/Kolkata).
{
"page": {
"size": 1,
"has_next": false,
"current": 1,
"type": "number",
"has_previous": false,
"item_total": 1
},
"items": [
{
"name": "INDIA",
"hierarchy": [
{
"display_name": "Pincode",
"slug": "pincode"
},
{
"display_name": "City",
"slug": "city"
},
{
"display_name": "State",
"slug": "state"
}
],
"phone_code": "+91",
"currency": {
"code": "INR",
"name": "Indian Rupee",
"symbol": "₹"
},
"iso3": "IND",
"iso2": "IN",
"timezones": [
"Asia/Kolkata"
],
"display_name": "India",
"longitude": "77.2167",
"type": "country",
"id": "5db290c4ce5de4cc176d935b",
"latitude": "28.6667"
}
]
}
Sample File Download
This FDK method is used to download the serviceability template file.
sampleFileServiceabilityRequest
In the previous step, the getCountries method retrieved hierarchical data for India to manage logistics at the pincode level. In the request, specifies India as the target country and “pincode” as the region.
basicRouter.get('/sample_serv_file', async function view(req, res, next) {
try {
const partnerClient = await fdkExtension.getPartnerClient('66a0f176a257365a44f33d4c');
const response = await partnerClient.logistics.sampleFileServiceability({
"organizationId": organizationId,
"body": {
"country": "INDIA",
"region": "pincode",
"type": "serviceability"
}
});
console.log(JSON.stringify(response))
res.json(response);
} catch (err) {
console.error(err);
console.log(JSON.stringify(err))
res.status(404).json({ success: false });
}
});
Response
In the response, a unique batch ID (batch_id) is generated to track the process, and the "region": "pincode" confirms the granularity at which serviceability is being assessed.
{
"file_path": null,
"batch_id": "677bcc71bd7461e3f20ea4d3",
"region": "pincode",
"status": "processing",
"failed_records": [],
"country": "INDIA",
"type": "serviceability"
}
Serviceability File Upload Process
You can skip this process if you have already uploaded the serviceability file to your existing cloud storage. Go to Serviceability Export.
Start Uploading Serviceability File
The startUpload initiates the process of uploading a serviceability file to cloud storage to upload files containing serviceability data. In response, you will receive a storage link (CDN URL) to upload the serviceability file to the file storage.
startUploadRequest
In the below given example request, details such as the file name (sample_serv_file.csv), content type (text/csv), and size are specified. The file is tagged under “serviceability” for easy identification, is defined by the namespace and subpath parameters.
basicRouter.post('/start_upload_servicability', async function view(req, res, next) {
try {
const partnerClient = await fdkExtension.getPartnerClient('66a0f176a257365a44f33d4c');
const response = await partnerClient.fileStorage.startUpload({
"namespace": "test",
"organizationId": organizationId,
"body": {
"file_name": "sample_serv_file.csv",
"content_type": "text/csv",
"size": 500,
"tags": [
"servicability",
],
"params": {
"subpath": "test"
}
}
});
console.log(JSON.stringify(response))
const uploadUrl = response.upload.url;
// Replace with the path to your local file
const filePath = path.resolve(__dirname, '../sample_serv_file.csv');
// Replace with your file's MIME type
const mimeType = "text/csv";
console.log("---------------------------------------------")
console.log(uploadUrl, filePath)
console.log("---------------------------------------------")
await uploadFileToStorage(uploadUrl, filePath, mimeType);
console.log(JSON.stringify(response))
res.json(response);
} catch (err) {
console.error(err);
console.log(JSON.stringify(err))
res.status(404).json({ success: false });
}
});
Response
The response returns essential information to store the file directly in cloud storage. This URL has an expiration period (expiry: 1800 seconds), ensuring the upload must be completed within the specified timeframe.
{
"file_name": "sample_serv_file.csv",
"operation": "putObject",
"size": 500,
"content_type": "text/csv",
"namespace": "test",
"file_path": "/test/general/free/original/sample_serv_file.csv",
"method": "PUT",
"tags": [
"servicability"
],
"upload": {
"url": "https://storage.googleapis.com/fynd-obscuro-media-new/test/general/free/original/sample_serv_file.csv?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=grindor-prod%40fynd-prod-393805.iam.gserviceaccount.com%2F20250107%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20250107T072146Z&X-Goog-Expires=1800&X-Goog-SignedHeaders=host&X-Goog-Signature=8caff9e44f8a53ee9bbf7be29c12d9d697a34e40186501001ceabb94f3b7747d535ebc4a20552374895f97c38700600d55dac9e7875a4dc8697a9af2350c0bccad285123d3529daa197f98300d7b19ce1db78bf0ae3ef340a6cc37362d9ce3c40a5d2cd54f57d82a86cf721a224cfcc66f881252b445b08c37a2d049bc91cd6f005f1a7c0e81c3382bd061d5612ee5938a113c5badf4f88a568dee11a6c310fc822d5ec7ab1666b8c4fe2d76ffed8a9c92150a8354359daa405bace12dea54d9615047accac08ae28997076758fad5a0e9b6ad72ab6d7c1bd9c2ae054fcd83081a8c9b714927940020befea7ea1a188c9f4a4786b8c5cc2029fccc4211a5c4de",
"expiry": 1800
}
}
Complete Upload Serviceability File
The completeUpload FDK method finalizes the process of uploading the serviceability file to cloud storage, providing a CDN URL for accessing the uploaded file. This step ensures that the serviceability file is correctly stored.
completeUploadRequest
In the below given example request, the parameters from the initial startUpload response (such as file name, path, and upload URL) are passed to completeUpload, confirming the file’s successful transfer to the storage location. This FDK method validates the upload and generates URLs for accessing the file via CDN.
basicRouter.post('/complete_upload_servicability', async function view(req, res, next) {
try {
const partnerClient = await fdkExtension.getPartnerClient('66a0f176a257365a44f33d4c');
const response_complte = await partnerClient.fileStorage.completeUpload({
"namespace": "test",
"organizationId": organizationId,
"body": {
"file_name": response.file_name,
"file_path": response.file_path,
"content_type": response.content_type,
"method": response.method,
"namespace": response.namespace,
"operation": response.operation,
"size": response.size,
"upload": {
"expiry": response.upload.expiry,
"url": response.upload.url
},
"tags": response.tags
}
});
console.log(JSON.stringify(response_complte))
res.json(response_complte);
} catch (err) {
console.error(err);
console.log(JSON.stringify(err))
res.status(404).json({ success: false });
}
});
Response
The response confirms the success of the operation (success: true) and returns multiple URLs linked to access the file through Fynd's networks.
Developers can use the CDN link to reference the file without re-uploading or handling additional storage configurations. The response also tracks metadata like upload time (created_on), file size, and the developer responsible for the upload.
{
"file_name": "sample_serv_file.csv",
"file_path": "/test/general/free/original/sample_serv_file.csv",
"success": true,
"namespace": "test",
"content_type": "text/csv",
"size": 500,
"operation": "putObject",
"tags": [
"servicability"
],
"cdn": {
"url": "https://cdn.fynd.com/v2/falling-surf-7c8bb8/fyprod/wrkr/test/general/free/original/sample_serv_file.csv",
"absolute_url": "https://cdn.fynd.com/v2/falling-surf-7c8bb8/fyprod/wrkr/test/general/free/original/sample_serv_file.csv",
"relative_url": "/test/general/free/original/sample_serv_file.csv"
},
"upload": {
"url": "https://storage.googleapis.com/fynd-obscuro-media-new/test/general/free/original/sample_serv_file.csv?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=grindor-prod%40fynd-prod-393805.iam.gserviceaccount.com%2F20250107%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20250107T072721Z&X-Goog-Expires=1800&X-Goog-SignedHeaders=host&X-Goog-Signature=9f71638afb0afb12c3d67617d6717890eb14fa423f192e1e54ace88c5af9b3360546699378f60f46d7960ac87c674bacde884803f7fe937d0440cd253eca748b18a8c8e4b9b3b3166cdac076bd76f8388953bd576dcfec66a4ad574c12ccb27c73f2d9b8dd0183dcd8d502f62a5c9d22e0de6d80c4489ffa8deea484bede5fc4673850a8aefe268ac02b893235ff981703c90070ec07f050ce264d72216af805a333988a61846ec3003f6f11c61a174a726fb53c2837b7902a2d19421882a0089ffb1fa46c3d9ef34844838c21ba8692fddbd5d2ee9cb5514d3d897b40da2dfd401c2542b17d773ab6f1457cb288ca558aac1815617fc01c5d1bcf906654f18b",
"expiry": 1800
},
"_id": "677cd75a14b9fb6c9cd1a4ef",
"created_by": {
"username": "6777d5612f3ce766efa51482"
},
"created_on": "2025-01-07T07:27:22.213Z",
"modified_on": "2025-01-07T07:27:22.213Z"
}
Serviceability Export
The bulkServiceability FDK method uploads a serviceability file from cloud storage to the database.
bulkServiceabilityRequest
In the below given example request, the uploaded serviceability file identified by its CDN URL (collected from completeUpload FDK method in the previous step) is passed along with metadata such as the country (India), action (import), and region (Pincode). This initiates the process of transferring the file’s contents into the database under a specified scheme (schemeId).
basicRouter.post('/upload_scheme_servicability', async function view(req, res, next) {
try {
const partnerClient = await fdkExtension.getPartnerClient('6720b51d25f94c22e87376a5');
const response = await partnerClient.logistics.bulkServiceability({
"organizationId": organizationId,
"extensionId": process.env.EXTENSION_API_KEY,
"schemeId": "Scheme_id_126",
"body": {
"file_path": "https://cdn.fynd.com/v2/falling-surf-7c8bb8/fyprod/wrkr/test/general/free/original/sample_serv_file.csv",
"country": "India",
"action": "import",
"region": "Pincode"
}
});
console.log(JSON.stringify(response))
res.json(response);
} catch (err) {
console.error(err);
console.log(JSON.stringify(err))
res.status(404).json({ success: false });
}
});
Response
A unique batch_id is generated to track the import. The response also shows metrics, such as total: 0, success: 0, failed: 0. If any errors occur during import, they will appear under failed_records.
{
"batch_id": "677cd93ca00114228ff464fa",
"action": "import",
"region": "Pincode",
"country": "India",
"total": 0,
"success": 0,
"failed_records": [],
"status": "processing",
"failed": 0,
"file_path": "https://cdn.fynd.com/v2/falling-surf-7c8bb8/fyprod/wrkr/test/general/free/original/sample_serv_file.csv"
}
Serviceability File Generator Status
The getSampleFileServiceabilityStatus FDK method is used to check the status of a previously initiated serviceability file generation process. You will get a log file that contains list of rows which are not uploaded in the database. You can download the log file and correct the serviceability file and reupload again.
getSampleFileServiceabilityStatusRequest
In the below given example request, the batchId is passed, which uniquely identifies the file generation process initiated earlier.
basicRouter.get('/sample_serv_file_status', async function view(req, res, next) {
try {
const partnerClient = await fdkExtension.getPartnerClient('66a0f176a257365a44f33d4c');
const response = await partnerClient.logistics.getSampleFileServiceabilityStatus({
"organizationId": organizationId,
"batchId": "6761363a0456c5b5dcaa3b4a"
});
console.log(JSON.stringify(response))
res.json(response);
} catch (err) {
console.error(err);
console.log(JSON.stringify(err))
res.status(404).json({ success: false });
}
});
Response
The response shows that no errors have occurred failed_records: [], and the batch is associated with generating a serviceability sample for India at the pincode level.
{
"page": {
"item_total": 1,
"has_next": false,
"type": "number",
"current": 1,
"size": 1
},
"items": [
{
"country": "INDIA",
"type": "serviceability-sample-download",
"failed_records": [],
"file_path": null,
"status": "processing",
"batch_id": "674d953ce8850ed0d9dc82a4",
"region": "pincode"
}
]
}
Get Serviceability History
This FDK method is used to get the history of uploaded serviceability.
The getBulkServiceability FDK method is used to retrieve the history and status of previously uploaded serviceability files. This functionality allows developers to track past imports.
getBulkServiceabilityRequest
In the below given example request, the method queries serviceability uploads for India at the pincode level within a defined date range (startDate to endDate). Additionally, the method targets a specific scheme (schemeId) and batch (batchId).
basicRouter.get('/scheme_serviceability_history', async function view(req, res, next) {
try {
const partnerClient = await fdkExtension.getPartnerClient('66a0f176a257365a44f33d4c');
const response = await partnerClient.logistics.getBulkServiceability({
"organizationId": organizationId,
"extensionId": process.env.EXTENSION_API_KEY,
"schemeId": "Scheme_id_126",
});
console.log(JSON.stringify(response))
res.json(response);
} catch (err) {
console.error(err);
console.log(JSON.stringify(err))
res.status(404).json({ success: false });
}
});
Response
The response indicates that no matching records were found (items: []), suggesting that no uploads met the provided criteria during the specified period.
{
"items": [],
"page": {
"current": 1,
"item_total": 0,
"type": "number",
"size": 0,
"has_next": false
}
}