External APIs to manage Invoices
- Hitesh Sarup
Analytics
Title:External APIs to manage invoices
Prerequisites (if applicable): -
Instructions:
Customer Invoice API
Details for API 1 (to generate the invoice):
Add the following header for authentication: "Authorization", "Basic <API KEY>"
Endpoint: https://app.shipsy.in//api/client/integration/customers/fetch
Request:
{ "customerCodeList" : ["TESTCUST"] , "fromDate" :"" , "toDate" :"" , "pageNumber" : 1 } |
customerCodeList (Array of Strings):
Description: An array of customer codes for which data is requested.
Example: ["TESTCUST"]
fromDate (String):
Description: The starting date for the data query (assuming it's a date in string format).
Example: "2023-01-01"
toDate (String):
Description: The ending date for the data query (assuming it's a date in string format).
Example: "2023-09-20"
pageNumber (Integer):
Description: The page number for paginated results.
Example: 1
Here's a schema table summarizing these fields:
Field Name | Data Type | Description | Example |
customerCodeList | Array of Strings | An array of customer codes for the query. | ["TESTCUST"] |
fromDate | String | The starting date for the query. | "2023-01-01" |
toDate | String | The ending date for the query. | "2023-09-20" |
pageNumber | Integer | The page number for paginated results. | 1 |
Response:
{ "status": "OK", "invoiceNumber": "TES04052023080537" } |
Details for Api 2 - To get the information in Json format
Request:
Add the following header for authentication: "Authorization", "Basic <API KEY>"
Params:
invoiceNumber (generated in the response of Api 1)
Headers:
Content-Type: application/json
Endpoint: http://app.shipsy.in/api/client/integration/invoice/get/json?invoiceNumber=TES09052023050548
Response:
If out of x requests created, only x-n are processed then we get pending status (x,n >0).
{ "status": "PENDING", "totalCount": 0, "data": [] } |
Invoice is being processed
{ "status": "PROCESSING", "data": [] } |
When no data is present in the suggested filter, we get errors in the response. FE also shows an error flag at the same time.
{ "status": "ERROR", "data": [] } |
If the data is present within the filters provided and the invoice is processed, we will get below response. All the charges configured for Hellmann will be
{ "status": "COMPLETED", "totalCount": 1, "data": [ { "referenceNumber": "MED02566", "serviceTypeId": "EXPRESS DELIVERY", "status": "delivered", "createdAt": "2023-05-09 05:34", "lastUpdatedAt": "2023-05-09", "deliveredTime": "2023-05-09", "codAmount": 0, "finalPrice": 4, "codCustomerCurrency": "INR", "chargeable_weight": "2", "freightCharge": 4, "rtoCharge": 0, "codCharge": 0, "insuranceCharge": 0, "highValueCharge": 0, "lowValueCharge": 0, "odaCharge": 0, "gpaCharge": 0, "fuelCharge": 0, "fuelChargePerKg": 0, "chargeableWeightBasedSurcharge": 0, "shipmentBasedSurcharge": 0, "valuePercentageBasedSurcharge": 0, "freightBasedPercentageSurcharge": 0, "vatCharge": 0 } ] } |
If there is a requirement of getting the invoice details via file, the user is required to call the same API with the following endpoint
Response having the file :
{
"status": "OK",
"data": {
"invoiceNumber": "TES24042023080450",
"filters": {
"dateType": "updated",
"clientIds": [
"1315561743434516416"
],
"fromDate": "2023-04-17",
"toDate": "2023-04-24",
"serviceTypeId": [],
"status": [],
"clientId": "1315561743434516416",
"clientName": "TESTCUST"
},
"status": "Completed",
"isComplete": true,
"createdAt": "2023-04-24T08:18:07.504Z",
"fileLink": "https://s3-us-west-2.amazonaws.com/sopan-master-data-testing/invoices/invoice_ocsjashanmal_TESTCUST_2023-04-17_2023-04-24_c12bd4.csv",
"pdfFileLink": "https://s3-us-west-2.amazonaws.com/sopan-master-data-testing/invoices/invoice_ocsjashanmal_TESTCUST_2023-04-17_2023-04-24_4a9c5e.pdf",
"totalInvoiceAmount": 8777.02
}
}