External APIs to manage Invoices
Article tZWYAJ9n · sourceTitle: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
" - 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
" -
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
}
}