H2H Web Service Specification Document - EVFS
Version History:
Version Date Author Reviewed By Changes
No
0.1 18-Nov-2021 VIvek Sehanaz Initial Draft
Table of Contents
1. PURPOSE.................................................................................................................................4
2. BENEFITS TO BUSINESS...........................................................................................................4
3. ACRONYMNS..........................................................................................................................4
4. WEBSERVICES.........................................................................................................................4
4.1API AND ENCRYPTION PROCESS.........................................................................................4
1. PURPOSE
To explain the specification of the web service hosted by SCFU Application as part of H2H between SCFU
and Corporates/Vendors. The service will be hosted in SCFU and will serve to push the invoice file into
the system.
2. BENEFITS TO BUSINESS
This web service is developed for EVFS to push the invoice files for processing in SCFU Application.
3. ACRONYMNS
Acronym Explanation
SCFU Supply Chain Finance Unit
DB Database
Ops Operations
EVFS E-Vendor Finance System
H2H Host to Host
AES Advanced Encryption Standard
CBC Cipher Block Chaining
4. WEBSERVICES
4.1 API and Encryption Process
Authentication: All API published by SCFU will be Authenticated using user credentials which is based on
User Name and Password while calling API URL.
User name This will be shared to concern person over mail separately
Password
How to enable API payload encryption mode?
API payload encryption is a combination of RSA + AES algorithms. It consist of five parts: Request Id,
KEY, Data, User Credentials and Signature.
Request Id: Unique request identifier
KEY: Will be encrypted using RSA public Key
Data: will be encrypted using Random AES-256 bit Key
User Credentials: will be encrypted using Random AES-256 bit Key
Signing: will be encrypted using Random AES-256 bit Key
Encryption Steps:
Step 1 Generate AES key and IV KEY Encryption Logic
Step 2 Encode Step 1 with Base64 separately
Step 3 Generate KEY JSON as in Example
Step 4 Encode Step 3 with Base64
Step 5 Encrypt Step 4 with HUL RSA public key
Step 6 Encode Step 5 with Base64 Data part encryption Logic
Step 7 Base 64 Encoding of DATA
Step 8 AES-CBC-256(IV) encryption of Step7
Step 9 Encode Step8 with Base64 Digital signature + encryption of
Step 10 Use Signature Algorithm (SHA256withRSA) & Sign Signature
the Data in step 9
Step 11 Base 64 Encoding of Step 10
Step 12 AES-CBC-256(IV) encryption of Step11
Step 13 Encode Step12 with Base64
JSON Encryption Format:
{
"REQUEST_ID": "Unique Request Identifier",
"KEY": "RSA encrypted KEY JSON",
"INVOICE_DATA": "AES Encrypted JSON Data",
"USER_CREDS": "AES Encrypted JSON Data",
"SIGNATURE": "AES Encrypted (RSA(Digital signature)"
}
JSON Encryption Example:
Base64 AES Key QptAv+WSvkLnNlr0dRIrITjYy2AceMhEMuFWbqBb4m0=
Base64 IV ego0r5v9DPMZbzj86PJ32w==
KEY JSON {
"AES_Key":"QptAv+WSvkLnNlr0dRIrITjYy2AceMhEMuFWbqBb4m0=",
"IV":"ego0r5v9DPMZbzj86PJ32w=="
}
INVOICE_DATA JSON {
"IM_CODE" : "DIM87654",
"INVOICES": [
{
"INVOICE_NUMBER": "20A2060029294373",
"INVOICE_AMOUNT": "2000",
"INVOICE_DATE": "19/07/2020",
"VENDOR_CODE": "186837",
"VENDOR_NAME": "MOTORADES 186837",
},
{
"INVOICE_NUMBER": "20A2060029294374",
"INVOICE_AMOUNT": "3000",
"INVOICE_DATE": "20/07/2020",
"VENDOR_CODE": "292283",
"VENDOR_NAME": "VEER VANSH PETRO",
}
]
}
USER_CREDS JSON {
"USER_NAME": "username",
"PASSWORD ": "password"
}
Base64 RSA Encrypted AaG5vJ/V3dz+rTiLx+hgXIX9UrUY+nWwUzPPMlvVV5St/
Base64(KEY JSON) Q9Fe4ssuxZZKIBsRbMxpa0xX++zVaDu0X/
gkpxn+XCPbj3fWXXqyk1BovSH2vXQAqMSzewpO4y/
GwBk4AETn74RYMwI0YZCj32FszpleKgqSGlCL1b74LOLArw6GMtH3Wskp
u/v6Wp9d1YWUNKwfyu/
GtZjHIWmrzRA+wgtjKz1fOohW0o1n0wEFEOdW/Q==
Base64 (AES-CBC Encrypted Z8xrS5gHUOo4Dhjhl128BjH5scYdA4b2Ms46tUacuEvrFqcxYHCO6usHD1
(Base64 (INVOICE_DATA OeNdICJacOGPDWoaxEoEpBOHOlRzD7SBDOxG3RN0M9e85SMY/
json))) d9B/W3d779jl1LejQUcSH9shNgdjiuvWO/
e84ILaenKmrplLLziIlqjH8pnizNkugF0HoFwyA2CmqPC5yGEtv42OHGN0+
NIW3xzfC6M+WXyHPxlBIBKkuoxm4MwUsd8GwaarggZ5xA5Shu4oHdQr
0ruK3bfIXeTzX6zosSFuJuf10c1cS7bVZi6NV/
k5no7TBMPDAAyhYjUYe8gmPAvlIi8=
Base64 (Signature) T76W+2jFPT3Ktu01IiI/
4eZe0Z4nRSuSnEzW3dCoYdGejkA4d8CwvQNfD1gIG9XuyttDOEODxsoHf
4gLD810eulQTca6CRDS4aewLiaH5NptyaIVcmhtMhktiCYUhNp8gZnYqJd
KBL6NOXg6Lq6/5uj1/lIXTZNf11RLWQc7PhpIM2iEMzP3CbTnv/
K6DmJ6kiiXPfWm8oZtMohGUXO3F7JBo3EPjq7DYHFIqxVjBllG2dkXf5JF7
Alj/Njw2SxIlxu75ZxtipsXiwfNDuN/AwNLRkrRaEVulSEGVMd
Y67Li9YFhre+j6wdAEOBBbBwD8M50kVcr6EJsP7OdxblTFw==
Base64(AES(Base64(Signat JbUnU3aLQRMFc8k8Yf7KVryUdbFY1i1IP4T+hlV1nDP7YqQSfVeHRZZEWx
ure)) HzIKV/VKUBgkGiQAcrUhxGFDVJbd11QemKjxiA/6qRFsssD/+QZ4t/
Iqnm7f/
uhdO+L4fPh9WHMgpKYydG4aMJ2XU5IzsehYNHzAICeE6V9oSUSV8sZQV
vfmP5CVwXDNfhBnkD7eHwnYQ24RwYBT0kQZhSPC4NvIE4KxAtTDd0oj2
rMhkmSGGXrZxsu3nvamF5SJuCqdkLA==
Base64 (AES-CBC Encrypted WEYxJ858yzbgPvskXVODYeQPmK+MYWyk1NMXYXLET3VnK+am0gOYTz
(Base64 (USER_CREDS TwyuolhSJNrqaKJEGZ1nIgy54dPz4gODNxWp0gGZ3fwPpnAHTB4vCMvE
json))) AMLh6H//k7s/A3YSbK
API Request Format {
"REQUEST_ID":"SCFU1234567891234",
"KEY":"AaG5vJ/V3dz+rTiLx+hgXIX9UrUY+nWwUzPPMlvVV5St/
Q9Fe4ssuxZZKIBsRbMxpa0xX++zVaDu0X/
gkpxn+XCPbj3fWXXqyk1BovSH2vXQAqMSzewpO4y/
GwBk4AETn74RYMwI0YZCj32FszpleKgqSGlCL1b74LOLArw6GMtH3Wskp
u/v6Wp9d1YWUNKwfyu/
GtZjHIWmrzRA+wgtjKz1fOohW0o1n0wEFEOdW/Q==",
"INVOICE_DATA":”
Z8xrS5gHUOo4Dhjhl128BjH5scYdA4b2Ms46tUacuEvrFqcxYHCO6usHD1
OeNdICJacOGPDWoaxEoEpBOHOlRzD7SBDOxG3RN0M9e85SMY/
d9B/W3d779jl1LejQUcSH9shNgdjiuvWO/
e84ILaenKmrplLLziIlqjH8pnizNkugF0HoFwyA2CmqPC5yGEtv42OHGN0+
NIW3xzfC6M+WXyHPxlBIBKkuoxm4MwUsd8GwaarggZ5xA5Shu4oHdQr
0ruK3bfIXeTzX6zosSFuJuf10c1cS7bVZi6NV/
k5no7TBMPDAAyhYjUYe8gmPAvlIi8=",
"USER_CREDS":"mJ2aAzP3y23/
dFCfVp87cOFLMngKdEGtLjhSiq65y1Dcc3xH+/cyRfgF3praPSkGUBn/
PabxFhle0zidUwrwNvA6qZq7NrZDInpVxUJVBEY=",
"SIGNATURE":"
JbUnU3aLQRMFc8k8Yf7KVryUdbFY1i1IP4T+hlV1nDP7YqQSfVeHRZZEWx
HzIKV/VKUBgkGiQAcrUhxGFDVJbd11QemKjxiA/6qRFsssD/+QZ4t/
Iqnm7f/
uhdO+L4fPh9WHMgpKYydG4aMJ2XU5IzsehYNHzAICeE6V9oSUSV8sZQV
vfmP5CVwXDNfhBnkD7eHwnYQ24RwYBT0kQZhSPC4NvIE4KxAtTDd0oj2
rMhkmSGGXrZxsu3nvamF5SJuCqdkLA=="
}
ERROR JSON {
"ERROR_CODE": "401",
"DESCRIPTION": " Invalid User Credentials"
}
INVOICE_RESP JSON {
"INVOICE_FILE_REF_NO": "75756775"
}
API Response Format {
"KEY":"AaG5vJ/V3dz+rTiLx+hgXIX9UrUY+nWwUzPPMlvVV5St/
Q9Fe4ssuxZZKIBsRbMxpa0xX+6RwRGUCORTiQO5vNm6DZTStisevgMRb
vg7daTYyumndydfPRdZGDWdFniAaUMJqEYyTpzqhdkNKEM8Xn1paOrjp
t5CeK0ltDYGlC5nFwdg2+zVaDu0X/
gkpxn+XCPbj3fWXXqyk1BovSH2vXQAqMSzewpO4y/
GwBk4AETn74RYMwI0YZCj32FszpleKgqSGlCL1b74LOLArw6GMtH3Wskp
u/v6Wp9d1YWUNKwfyu/
GtZjHIWmrzRA+wgtjKz1fOohW0o1n0wEFEOdW/Q==",
"INVOICE_RESP":”h+cVJ6efE1Xr5uP0plvwufKlbb7fIQGH3jst+lnaeM9
8nmxtFiLBGEMCudEGDBqTvp93KprnYI/
kYKFGHOX3+Xzh17MWQAXKPZNrw9caLu0= ”,
"ERROR": null
}
Content Type:
application/json
API Details:
Host to be configured: scfuat.sbi (IP Address will be shared later)
Environment URL
SIT Will be shared later
UAT Will be shared later
PRE-PROD Will be shared later
Request Parameters:
User:
Parameters Values Mandatory Description
USER_NAME STRING Yes User Name for authentication
PASSWORD STRING Yes Password for authentication
Invoice:
Parameters Values Mandatory Length Decimal Description
IM_CODE STRING YES 20 IM code to be
provided to identify
the IM for
authentication
process
INVOICE_NUMBER STRING Yes 100 Invoice No for bill
discounting
INVOICE_AMOUNT STRING YES 14 2 Invoice Amount
INVOICE_DATE DATE YES 20 Invoice Date
(dd/MM/yyyy)
VENDOR_CODE STRING YES 20 Vendor Code to be
provided.
VENDOR_NAME STRING NO 100 Vendor Name
If required, additional parameters can be added as per the requirement.
Response Parameters:
Parameters Values Mandatory Length Description
INVOICE_FILE_REF_NO STRING YES 10 Reference Number for
the Invoice Posted
Error Code and Description:
HTTP STATUS CODE ERROR CODE DESCRIPTION
200 OK
404 SERVICE NOT AVAILABLE
503 Service Unavailable
200 401 Invalid User Credentials
200 402 Invalid Maker
200 405 Decryption Failure
200 406 Invalid Request Data Format
200 407 Request Id should not be
blank or null and must starts
with SCFU and length must
be 17
200 408 Request Id must be
alphanumeric
200 409 Duplicate Request Id
