pil-ap-invoice-processing

1.0.x
(1 review)

PIL AP Invoice Processing API

Overview

The PIL AP Invoice Processing API provides REST endpoints to validate and process Accounts Payable (AP) invoice data received from multiple source systems.

High Level Diagram

The API supports invoice submissions from:

  • GCRS
  • MariApps
  • Shanghai Terminal
  • Qingdao Terminal

It also exposes callback endpoints for Mule Intelligent Document Processing (IDP) once document processing is completed. This applicable only for Mariapp & GCRS.

All endpoints:

  • Are secured over HTTPS
  • Require Basic Authentication
  • Require a Source System Header (where applicable)
API Details

Title: pil-ap-invoice-processing

Version: 1.0.0

Protocol: HTTPS

Media Type: application/json

Security & Authentication

  • Basic Authentication is required for all secured endpoints.
  • A Source System Header must be provided to identify the upstream calling system.

GCRS

GCRS Flow Diagram

Endpoints:
POST /finance/gcrs/invoice

Description

Accepts and validates invoice details received from the GCRS system.

This endpoint performs request validation before forwarding the data for further processing.

Request

Method: POST

Content-Type: application/json

Authentication: Basic Auth

Headers: Source System Header

Request Body

 {
            "vendorName": "TRANSCEND SOLUTIONS PTE LTD",
            "purchaserEmail": "ajaysingh.sengar@sgp.pilship.com",
            "ReqMail": "ajaysingh.sengar@sgp.pilship.com",
            "recordCreated": "02/05/25 15:38:57",
            "vesselName": "PIL Corporate Requisition System",
            "invoiceNo": "TSI/26/03-149/JFB",
            "invoiceDate": "2026-03-13",
            "supplierCode": "106755",
            "dueDate": "2026-04-12",
            "arrivalDate": "2026-06-25",
            "pONo": "GCRS-202600009",
            "amount": "8085.00",
            "currency": "SGD",
            "baseAmountUSD": "6311.97",
            "GFSsupplier": "106755 - SG00ML",
            "exchangeRate": "0.7807010700",
            "po": {
                "versionNo": "1",
                "financeAccount": "71201402",
                "poDate": "2026-06-02",
                "status": "Fully Received",
                "department": "ISD",
                "type": "IT Equipt - Goods",
                "deliveryDate": "2026-06-28",
                "poAmount": "8085.00",
                "requestFor": "Office",
                "freeCode": "MELL",
                "reference": "",
                "itemsTotalUSD": "6311.97",
                "createdBy": "PILCNJESPAN",
                "BlanketPO": "0",
                "BlanketPOFinal": "0",
                "StandardPO": "1",
                "BalAmt": "8812.65"
            },
            "INV_ITEM_ID": "10675520260625T1208363931451",
            "PoLineCnt": "1",
            "VatCode": "0",
            "POVAT_SUM": "727.65",
            "CREDIT_NOTE": "0"
        }

Response

Success: 200 OK

Content-Type: application/json

{
    "status": "success",
    "correlationId": "84235fca-d4c7-4c78-b51f-b3e0400ee07a",
    "executionId": "892a71e5-16de-43ab-ab53-13710a02de09"
}

MARIAPP

Mariapp Flow Diagram

POST /finance/mariapp/invoice

Description

Accepts and validates invoice details received from the MariApps system.

This endpoint ensures the request payload conforms to the expected MariApps invoice structure before processing.

Request

Method: POST

Content-Type: application/json

Authentication: Basic Auth

Headers: Source System Header

Request Body

 {
            "vendorName": "MARINETRANS SINGAPORE PTE LTD",
            "purchaserEmail": "joyce.lim@sgp.pilship.com",
            "recordCreated": "4/3/2025 8:06:16 PM",
            "vesselName": "FORWARDER",
            "invoiceNo": "SIN-105092",
            "invoiceDate": "2025-12-29",
            "supplierCode": "13388",
            "dueDate": "2026-01-29",
            "arrivalDate": "2026-03-18",
            "pONo": "FWD-202600044",
            "amount": "15526.90",
            "currency": "SGD",
            "baseAmountUSD": "12251.95",
            "GFSsupplier": "13388",
            "exchangeRate": "0.7890791450",
            "po": {
                "versionNo": "3",
                "financeAccount": "750SR03",
                "account": "",
                "poDate": "2026-03-11",
                "status": "Fully Received",
                "department": "ENGINE",
                "type": "Spares",
                "deliveryDate": "2025-12-31",
                "poAmount": "15526.91",
                "requestFor": "Vessel",
                "freeCode": "N/A",
                "reference": "",
                "itemsTotalUSD": "12251.96",
                "createdBy": "LIMJOY"
            },
            "attachment": {
              "invoiceDoc": "base64 string",
              "invoiceDocName": "invoice.pdf",
              "grnDoc": "base64 string",
              "grnDocName": "grn.pdf"
            }
        }

Response

Success: 200 OK

Content-Type: application/json

{
    "status": "success",
    "correlationId": "84235fca-d4c7-4c78-b51f-b3e0400ee07a",
    "executionId": "892a71e5-16de-43ab-ab53-13710a02de09"
}

Base Resource: /idp

The /idp resources are used to receive callback notifications from Mule Intelligent Document Processing (IDP) once document extraction and processing is completed.

These endpoints support multiple HTTP methods to accommodate different callback invocation patterns.

PATCH /idp/callback

Description

Receives callback notifications from Mule IDP indicating completion of document processing.

Request

Method: PATCH

Content-Type: application/json

{
  "file": {
    "filename": "APINV_Invoice_12345.pdf",
    "contentType": "application/pdf",
    "content": "<PDF_BINARY>"
  },
  "callback": {
    "noAuthUrl": "https://<callback-host>/idp/callback?apikey=Base64(clientId:clientSecret)&sourceSystem=GCRS"
  }
}

Response

Success: 200 OK

Content-Type: application/json

{
    "id": "0a2029d3-c00e-4fd8-8dce-c8b042c8775d",
    "documentName": "DO260796 (2).pdf"
}
POST /idp/callback /*** Currently no in use****/

Description

Receives callback notifications from Mule IDP indicating completion of document processing.

Request

Method: POST

Content-Type: application/json

Response

Success: 200 OK

Content-Type: application/json

GET /idp/callback /*** Currently no in use****/

Description

Receives callback notifications from Mule IDP indicating completion of document processing.

Used primarily for validation or testing purposes.

Request

Method: GET

Content-Type: application/json

Response

Success: 200 OK

Content-Type: application/json

Shanghai Terminal

###

Shanghai

Endpoints:

POST terminal/shanghai/invoice

Description

Accepts and validates invoice details received from the Shanghai terminal system.

This endpoint performs request validation before forwarding the data for further processing.

Request

Method: POST

Content-Type: application/json

Authentication: Basic Auth

Headers: Source System Header

Request Body

 {
    "totalRow": 225,
    "pageIndex": 1,
    "pageSize": 200,
    "pageNums": 2,
    "totalPage": 2,
    "hasPreviousPage": false,
    "hasNextPage": true,
    "isLastPage": false,
    "data": [
        {
            "bctCntrno": "PIDU2006870",
            "bctVoyagecnname": "铃城",
            "bctVoyageenname": null,
            "bctVoyage": "1000E",
            "bctVoyageiefg": "E",
            "bctLine": "南美",
            "bctServiceline": "太平、万海、阳明南美线",
            "bctVesselcompany": "0PIL",
            "bctVesselagent": "0CPSA",
            "bctSize": "20",
            "bctCommcode": "GP",
            "bctGoodstype": "普通",
            "bctBusFlag": "N",
            "bctCstmcd": "0PIL",
            "bctCopercd": "太平船务（中国）有限公司",
            "bctCstatuscd": "出口重箱",
            "bctCntrgroupFg": "N",
            "bctStandard": "Y",
            "bctFrom": null,
            "bctTo": null,
            "bctLdtermcd": null,
            "bctCweight": 19520,
            "bctDnggcd": null,
            "bctSettmpt": null,
            "bctOvlmtcd": null,
            "bctPotldport": "上海",
            "bctPotldunldport": "釜山",
            "bctDstnportregion": null,
            "bctTransvesselname": null,
            "bctTransvoyage": null,
            "bctIntime": "2025-12-12 04:39:58",
            "bctOuttime": "2025-12-13 19:47:38",
            "bctBillno": "SHRA50113800",
            "bctTransmode": null,
            "bctOverdays": 0,
            "bctStoredays": 2,
            "bctRefrigerateddays": 0,
            "bctIlne": null,
            "bctElne": null
        }]
}

Response

Success: 200 OK

Content-Type: application/json

{
  "statusCode": "200",
  "status": "success",
  "correlationId": "55754908-9bd4-4e16-8a51-387c1a57f6c3",
}

Qingdao Terminal

Endpoints:

POST /terminal/qingdao/receive-statements

Description

Accepts and validates electronic statement information received from the Qingdao Terminal system.

This endpoint performs request validation before forwarding the statement information for downstream processing and reconciliation.

Request

Method: POST

Content-Type: application/json

Authentication: Basic Auth

Headers: Source System Header

Request Body

{
  "id": "1234567890abcdef1234567890abcdef",
  "sender": "QINGDAO_TERMINAL",
  "recipient": "PIL",
  "action": "original",
  "billNumber": "BILL20260001",
  "carrier": "PIL",
  "company": "PILSG",
  "portOfBillingEvent": "QINGDAO",
  "remarks": "Monthly statement",
  "creationDatetime": "2026-08-06T10:00:00",
  "amount": 1000.00,
  "taxAmount": 90.00,
  "totalAmount": 1090.00,
  "currency": "CNY",
  "transport": {
    "voyage": "PIL001E",
    "imoNumber": "1234567",
    "vesselName": "KOTA ABC",
    "vesselLocalName": "远洋轮",
    "arrivalDatetime": "2026-08-01T08:00:00",
    "departureDatetime": "2026-08-03T20:00:00"
  },
  "itemList": [
    {
      "itemId": "ITEM001",
      "tariffCode": "STO",
      "tariffDesc": "Storage Charge",
      "quantity": 2,
      "quantityUnit": "DAY",
      "unitPrice": 500,
      "amount": 1000,
      "taxRate": 0.09,
      "taxAmount": 90,
      "totalAmount": 1090,
      "currency": "CNY",
      "remarks": ""
    }
  ],
  "cntrList": [
    {
      "cntrNumber": "PILU1234567",
      "blNumber": "BL123456",
      "cntrSizeType": "40HC",
      "cntrStatus": "IMPORT",
      "isFullIndicator": true,
      "cargoNature": "GENERAL",
      "remarks": ""
    }
  ],
  "chargePeriod": {
    "startDate": "2026-08-01",
    "endDate": "2026-08-31"
  }
}

Response

Success: 200 OK

Content-Type: application/json

{
    "status": "success",
    "correlationId": "6d8f6f8c-6cc7-4b67-ad78-32cdb4bb3797",
    "message": "Receive Statement received successfully"
}
POST /terminal/qingdao/confirm-statements

Description

Accepts and validates electronic statement information received from the Qingdao Terminal system.

This endpoint performs request validation before forwarding the statement information for downstream processing and reconciliation.

Request

Method: POST

Content-Type: application/json

Authentication: Basic Auth

Headers: Source System Header

Request Body

{
  "id": "1234567890abcdef1234567890abcdef",
  "billCompany": "PILSG",
  "billNumber": "BILL20260001"
}

Response

Success: 200 OK

Content-Type: application/json

{
    "status": "success",
    "correlationId": "6d8f6f8c-6cc7-4b67-ad78-32cdb4bb3797",
    "message": "Statement confirmation received successfully"
}
Error Handling
  • Standard HTTP status codes are used to indicate success or failure.
  • Validation errors, authentication failures, and unexpected processing issues return appropriate error responses.
Notes for Consumers
  • Ensure authentication credentials and required headers are provided for all secured endpoints.
  • Request payloads must strictly adhere to the data types defined in the respective RAML type libraries.
  • IDP callback endpoints are invoked asynchronously by Mule IDP once document processing is completed for the applicable source system.

Reviews