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 for AP Invoice Processing

The API supports invoice submissions from:

  • GCRS
  • MariApps

It also exposes callback endpoints for Mule Intelligent Document Processing (IDP) once document processing is completed.

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.
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"
}
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

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.

Reviews