# External APIs to manage Invoices

Module: Rates and Contracts
Module slug: rates-and-contracts
Source URL: https://helpcentre.shipsy.io/en-US/shipsy/article/tZWYAJ9n-external-apis-to-manage-invoices
Article ID: tZWYAJ9n
Breadcrumbs: Rates and Contracts > Customer Contracts > External APIs to manage Invoices

---
**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](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](http://app.shipsy.in/api/client/integration/invoice/get/json?invoiceNumber=TES09052023050548)

**Response:**

1. If out of x requests created, only x-n are processed then we get pending status (x,n >0).

|  |
| --- |
| {     "status": "PENDING",     "totalCount": 0,     "data": []  } |

2. Invoice is being processed

|  |
| --- |
| {     "status": "PROCESSING",     "data": []  } |

3. 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": []  } |

4. 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

* [http://app.shipsy.in/api/client/integration/invoice/get?invoiceNumber=TES09052023050548](http://app.shipsy.in/api/client/integration/invoice/get?invoiceNumber=TES09052023050548)

**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](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](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

    }

}