ShipServ's Invoicing APIs will allow Suppliers and Buyers to send and receive invoices, credit-notes and supporting documents electronically between systems.
Use cases
As a Buyer, you will be able to perform the following activities directly from your system:
-
Get the list of new invoices and credit-notes.
-
Import all new invoices, credit-notes and supporting documents into your invoicing system.
-
Mark a document as exported which will serve as an acknowledgment to your suppliers.
-
Basic Filtering & Sorting - retrieve paged list, filter by header information such as reference number, PO number, Supplier, vessel IMO and more.
As a Supplier, you will be able to perform the following activities:
-
f you have an integration with ShipServ, you will be able to send invoices, credit-notes and related documents directly from your system.
-
If you do not have an integration with ShipServ, you will still be able to upload and send the invoices, credit-notes and supporting documents use ShipServ's Trade Platform.
-
Receive a "READ" status, which will serve as an acknowledgment response from your buyer.
API Reference
Whether you want to know how to perform a request or what attributes you can look for, we have a more detailed page for you to read. Please click here.
Get list of invoices
As a Buyer I would like to GET the list of invoices that have been submitted by my suppliers:
Using curl
curl --location --request GET 'https://test.shipserv.com/invoicing/documents?type=Invoice' \
--header 'Authorization: Bearer Bosrrp9irkAEt8AnWquHIbPX3M2StcMA’
And you should get a response which should look like this:
{
"content": [
{
"id": "60114dc7628dca000822a5d9",
"buyerTnId": 100004,
"buyerName": "API Test Buyer",
"supplierTnId": 300371,
"supplierName": "API Test Supplier",
"referenceNumber": "INVOICE_TEST_001",
"purchaseOrderReferenceNumber": "ReferenceNumber_PO_001",
"amountTotal": 260.0,
"status": "Invoiced",
"issuedDate": "2021-01-27T11:25:59+00:00",
"exported": true,
"exportedDate": "2021-01-29T10:21:26+00:00"
}
],
"pageNumber": 1,
"pageSize": 20,
"numberOfElements": 1,
"totalElements": 1,
"totalPages": 1
}
Get a specific invoice
As a buyer I would like to get a specific invoice that has been submitted by my supplier:
Using curl
curl --location --request GET 'https://test.shipserv.com/invoicing/documents/60114dc7628dca000822a5d9?type=Invoice' \
--header 'Authorization: Bearer lcN39C7PW49cs2FGToNtnzhLzJlOUN4j'
And you should get a response which should look like this:
{
"id": "60114dc7628dca000822a5d9",
"buyer": {
"id": 6460402,
"tnId": 100004,
"name": "API Test Buyer"
},
"vessel": {
"name": "Test Vessel Name",
"imo": "1234567"
},
"supplier": {
"id": 6460400,
"tnId": 300371,
"name": "API Test Supplier"
},
"notes": "TESTING NOTE",
"referenceNumber": "INVOICE_TEST_001",
"creditNotes": [],
"purchaseOrder": {
"id": "c0c926b6-0dbb-464d-851b-70805fbe80d0",
"referenceNumber": "ReferenceNumber_PO_001",
"currency": {
"name": null,
"code": null
},
"total": null
},
"purchaseOrderConfirmation": {
"id": "901e27d5-2e62-42de-8fa7-1ececcdf54ab",
"referenceNumber": "TESTPOC002",
"currency": {
"name": null,
"code": "AED"
},
"total": null
},
"amount": {
"currency": {
"name": null,
"code": null
},
"subTotal": null,
"freightCost": null,
"additionalCost": 0,
"discount": {
"type": "VALUE",
"value": 0
},
"total": 260
},
"status": "Invoiced",
"createdDate": "2021-01-27T11:26:00.112Z",
"issuedDate": "2021-01-27T11:25:59.000Z",
"dueDate": "2021-01-27T11:15:31.000Z",
"exported": true,
"exportedById": 3924,
"exportedDate": "2021-01-29T10:21:26.234Z",
"type": "Invoice"
}
Create an Invoice
As a Supplier, you can send your invoices, credit-notes and supporting documents to your Buyers using ShipServ APIs.
Using curl
curl --location --request POST 'https://test.shipserv.com/api/invoicing/documents' \
--header 'Authorization: Bearer vT2lT3tFjRIGi2qyC4AFVc35dukl0lky'
You should receive a response as below:
{
"code": "success",
"message": "document created",
"data": {
"id": "2b44849b-d96f-4a36-88d9-62dc6bd0e4cd",
"correlationId": "bdf8e7f6-8c27-427c-b04c-6f12436c740c"
}
}
Mark an invoice as exported
As a buyer I would like to mark the invoice as exported: An invoice/credit-note should be mark-as-exported once it is successfully downloaded in the Buyers system. This will also act as an indicator to the suppliers that their invoices have been received by the Buyers.
Using curl
curl --location --request GET 'https://test.shipserv.com/invoicing/documents/6013e4e21cb0c6000aa917fa/mark-as-exported?type=Invoice' \
--header 'Authorization: Bearer lcN39C7PW49cs2FGToNtnzhLzJlOUN4j'
You should receive a response as below:
{
"Code": "success",
"Message": "document marked as exported",
"Data": {
"Id": "60117e6b1cb0c6000aa917c7",
"CorrelationId": "67ac48fe-49e3-49b4-9d95-b069a5a0c312"
}
}
Filtering
Filtering invoices from a list of documents: With the filter options available on the APIs, you can now filter the documents which are exported or not exported.
See below example which filters documents which are not marked as exported
Using curl
curl --location --request GET 'https://test.shipserv.com/invoicing/documents?type=Invoice&exported=false' \
--header 'Authorization: Bearer lcN39C7PW49cs2FGToNtnzhLzJlOUN4j'
You should receive a response as below:
{
"content": [
{
"id": "60114dc7628dca000822a5d9",
"buyerTnId": 100004,
"buyerName": "Aus API Test Buyer",
"supplierTnId": 300371,
"supplierName": "Aus API test Supplier",
"referenceNumber": "INVOICE_TEST_001",
"purchaseOrderReferenceNumber": "ReferenceNumber_PO_001",
"amountTotal": 260.0,
"status": "Invoiced",
"issuedDate": "2021-01-27T11:25:59+00:00",
"exported": false,
"exportedDate": "null"
},
{
"id": "60117e6b1cb0c6000aa917c7",
"buyerTnId": 100004,
"buyerName": "Aus API Test Buyer",
"supplierTnId": 300371,
"supplierName": "Aus API test Supplier",
"referenceNumber": "INVOICE_TEST_003",
"purchaseOrderReferenceNumber": "ReferenceNumber_PO_003",
"amountTotal": 232.0,
"status": "Invoiced",
"issuedDate": "2021-01-27T14:53:31+00:00",
"exported": false,
"exportedDate": "null"
},
{
"id": "6013e4e21cb0c6000aa917fa",
"buyerTnId": 100004,
"buyerName": "Aus API Test Buyer",
"supplierTnId": 300371,
"supplierName": "Aus API test Supplier",
"referenceNumber": "API_INV_TEST_001",
"purchaseOrderReferenceNumber": "API_INV_TEST_001",
"amountTotal": 257.0,
"status": "Invoiced",
"issuedDate": "2021-01-29T10:35:14+00:00",
"exported": false,
"exportedDate": "null"
},
{
"id": "60117e301cb0c6000aa917c2",
"buyerTnId": 100004,
"buyerName": "Aus API Test Buyer",
"supplierTnId": 300371,
"supplierName": "Aus API test Supplier",
"referenceNumber": "INVOICE_TEST_002",
"purchaseOrderReferenceNumber": "ReferenceNumber_PO_002",
"amountTotal": 267.0,
"status": "Invoiced",
"issuedDate": "2021-01-27T14:52:32+00:00",
"exported": false,
"exportedDate": null
}
],
"PageNumber": 1,
"PageSize": 20,
"NumberOfElements": 4,
"TotalElements": 4,
"TotalPages": 1
}