Developer Guide for KSA e-Invoicing Integration Phase
Storage (UDFs)
Company Object
|
Storage (UDFs) |
Type |
Description |
|
IsKSAPhase2Applicable |
Logical |
Enablement of the integration phase |
|
KSAPhase2ApplicableDate |
Date |
Integration phase start date |
|
KSA_Einv_Detail_VRNType |
String |
Company VRN Type Selection as per company criteria |
|
KSA_Einv_Detail_CRN |
String |
Commercial Registration No |
|
KSA_Einv_Detail_MOM |
String |
Momrah License |
|
KSA_Einv_Detail_MLSD |
String |
MHRSD License |
|
KSA_Einv_Detail_Sagia |
String |
MISA license |
|
KSA_Einv_Detail_OtherId |
String |
Other ID Name |
|
KSA_Einv_Detail_IDNumber |
String |
Other ID |
|
KSA_Einv_Detail_BuildingNo |
String |
Building No. |
|
KSA_Einv_Detail_City |
String |
City |
|
KSA_Einv_Detail_District |
String |
District |
|
KSA_Einv_Detail_700No |
String |
700 No. |
|
CMP_KSA_Pincode |
String |
Pincode |
|
Cmp_KSA_State_Arabic |
String |
State name In Arabic |
|
KSAEInvoiceArchivePathPhase2 |
String |
ZATCA Compliance XML and PDF A3 Archive Path for integration phase |
|
CMPeInvEndDate |
Date |
Generation Phase End Date |
|
GVatCMP_KSA_City |
String |
City in Arabic |
|
GVatCMP_KSA_District |
String |
District in Arabic |
|
CMPeInvApplicableDate |
Date |
Generation Phase Start Date |
|
IsCMPeInvApplicable |
logical |
Generation phase Enablement |
|
KSA_Einv_Detail_OtherId_Arabic |
String |
Storage Implemented for “Other ID” Description in Arabic Language |
Additional storage has been implemented for Arabic details in the multi-address form. The existing storage will be used for other fields. Below, we have mentioned the additional address fields specifically added for the Arabic language in the multi-address form:
|
Storage (UDFs) |
Type |
Description |
|
CompanyAddressNative_Aggr_KSA |
Aggregate |
Aggregate Used for Arabic Address in Multi-Address Form |
|
CompanyNameNative_AddrType_KSA |
String |
Arabic Name of the company |
|
CompanyAddressNative_AddrType_KSA |
Date |
Arabic Address of the company |
|
CompanyCountryNative_AddrType_KSA |
String |
City in Arabic |
Additional storage has been added for the region in English in the multi-address form:
|
StateName_AddrType_KSA |
String |
Region of the company |
Ledger Object
| Storage (UDFs) | Type | Description |
| Ledger_KSA_VRN_Type | String | Ledger VRN Type Selection as per company criteria 1) Company Registration 2) Headquarter Registration |
| LED_BuyerlD_Details_TIN | String | Tax Identification Number |
| LED_BuyerlD_Details_CRN | String | Commercial Registration No. |
| LED_BuyerlD_Details_MOM | String | Momrah License |
| LED_BuyerlD_Details_MLSD | String | MHRSD License |
| LED_BuyerlD_Details_s700 | String | 700(Only for B2C) |
| LED_BuyerlD_Details_Sagia | String | MISA License |
| LED_BuyerlD_Details_NationlID | String | National ID |
| LED_BuyerlD_Details_GCCId | String | GCC ID |
| LED_BuyerlD_Details_Iqma_Number | String | Iqama Number (IQA) |
| LED_BuyerlD_Details_PassportID | String | Passport ID |
| LED_BuyerlD_Details_OtherId | String | ID Name |
| Ledger_KSA_BuildingNo | String | Building Number |
| Ledger_KSA_City | String | Ledger City |
| Ledger_KSA_District | String | Ledger District |
| Ledger_KSA_Pincode | String | Ledger Pincode |
| LedgerCategoryReason | String | If Taxability is under Zero rated, Exempt, Not VATABLE then Reason is mandatory for e-Invoice generation (Selection is available in Ledger Master). List of code and its details added in a table below |
| LedgerCategoryReasonCode | String | If Taxability is under Zero rated, Exempt, Not VATABLE then Reason is mandatory for e-Invoice generation (Selection is available in Ledger Master). List of code and its details added in a table below |
| Ledger_TypeofCharges | String | A dropdown will be available with 172 options mapped with charge codes. (Selection is available in Ledger Master). List of code and its details added below. |
| Ledger_ChargeCode | String | A dropdown will be available with 172 options mapped with charge codes (you can find Charges Code details) for einvoice generation charges code is mandatory. Condition: This field is to be added when the parent group name is one of the following: 1. Direct Expenses 2. Direct Incomes 3. Expenses (Direct) 4. Expenses (Indirect) 5. Income (Direct) 6. Income (Indirect) 7. Indirect Expenses 8. Indirect Incomes List of code and its details added below |
| LedgerCategoryReasonArabic | String | In case of non-vatable ledger Arabic reason is mandatory |
| Ledger_KSA_AdditionalID | String | Ledger Addition ID |
| GVatLedger_KSA_City | String | Ledger City in Arabic |
| GVatLedger_KSA_District | String | District in Arabic |
| LED_BuyerlD_Details_IdNo | String | Other ID No |
| DescriptionKSAArabic | String | Arabic Description storage Added in Ledger master and item master |
| GVatLedger_KSA_state | String | Ledger State in Arabic |
| LED_BuyerlD_Details_OtherId_Arabic | String | Additional ID description in Arabic for the Party Ledger |
Stock Item Object
| Storage (UDFs) | Type | Description |
| ItemCategoryReason | String | Exempt, Not VATABLE then Reason is mandatory for e-Invoice generation (Selection is available in Item Master) (List of code and its details added below) |
| ItemCategoryReasonCode | String | If Taxability is under Zero rated, Exempt, Not VATABLE then Reason code is mandatory for e-Invoice generation (List of code and its details added below) |
| ItemCategoryReasonArabic | String | In case of non-vatable ledger Arabic reason is mandatory |
| DescriptionKSAArabic | String | Arabic Description storage Added in Ledger master and item master |
Voucher Object
| Storage (UDFs) | Type | Description |
| einvoice_generate_Status | String | Value Should be “P” if e-Invoice get generated |
| einvoice_signedInvoice | String | After successful generation of e-Invoice signedInvoice receiving from e-Invoicing system |
| einvoice_signedQRCode | String | After successful generation of e-Invoice signedQRCode receiving from e-Invoicing system |
| einvoice_qrCode | String | After successful generation of e-Invoice qrCode receiving from e-Invoicing system |
| einvoice_qrCodeData | String | After successful generation of e-Invoice qrCodeData receiving from e-Invoicing system |
| einvoice_qrCodeHash | String | After successful generation of e-Invoice qrCodeHash receiving from e-Invoicing system |
| einvoice_qrCodeUUID | String | After successful generation of e-Invoice UUID receiving from e-Invoicing system |
| OverrideCategoryReasonCode | String | The Code for the category reason, which has been overridden in the transaction |
| OverrideCategoryReason | String | The description for the category reason, which has been overridden in the transaction, in English |
| OverrideCategoryReasonArabic | String | The description for the category reason, which has been overridden in the transaction, in Arabic |
| VchWarningMsg | String | After successful generation of E-Invoice if any Warning comes then it will store in this UDF |
| VchErrorMsg | String | If any document rejected from E-Invoice System, then rejected reason will store in this UDF |
| VchRejectEinvoice | Logical | If any document rejected from E-Invoice System this method should be “yes” |
| VcheInvAmountDue | Amount | The outstanding amount that is requested to be paid. This amount is the Invoice total amount with VAT minus the pre-paid amount that has been paid in advance plus Rounding Amount. The amount is zero in case of a fully paid Invoice. |
| CreditnoteCodeKSA | String | Credit note Reason code is required for e-Invoicing (List of code and its details below) |
| ReceiptCategoryReason | String | If Taxability is under Zero rated, Exempt, Not VATABLE then Reason is mandatory for e-Invoice generation (Selection is available in receipt Transaction Advance Payment scenario) |
| ReceiptCategoryReasonCode | String | If Taxability is under Zero rated, Exempt, Not VATABLE then Reason is mandatory for e-Invoice generation (Selection is available in receipt Transaction Advance Payment scenario) |
| einvoice_generatedDateKSA | String | e-Invoice Generated Date |
| einvoice_generatedTimeKSA | String | e-Invoice Generated Time |
| KSAGVATTransNature | String | Nature of transaction UDF Added in Receipt Transaction in Advance Payment Scenario. |
| KSA_CategoryCode_Export_GCC_Excempt | String | If Party ledger belongs to unregistered and non KSA Country, then at voucher level User must select Category Code and its reason for e-Invoicing. |
| KSA_CategoryCode_Nonvatable_Reason | String | If Party ledger belongs to unregistered or non KSA Country, then at voucher level UDF Added under show e-invoice Details. |
| KSA_CategoryCode_Nonvatable_Reason_Arabic | String | If Party ledger belongs to unregistered or non KSA Country, then at voucher level UDF Added under show e-invoice Details. |
| VcheInvAdvanceAmount | Amount | Advance Amount UDF added under show e-invoice Details. |
| VCHAddressNativeAggr | String | Aggregate added in supplementary details for buyer address in Arabic under mailing details in local language |
| VchMailingNameNative | String | Mailing name in Arabic added in supplementary details under mailing details in local language |
| VCHAddressNative | String | Mailing address in Arabic added in supplementary details under mailing details in local language |
| VCHCityNative | String | City name in Arabic (party details in supplementary form) under mailing details in local language |
| VCHDistrictNative | String | district in Arabic (party details in supplementary form) under mailing details in local language |
| BasicUserDescriptionArabicAggr | String | the Arabic basic user description aggregate added below the default item description or ledger description |
| BasicUserDescriptionArabic | String | Arabic Basic User Description Storage Added below default item description or ledger description |
| ReceiptCategoryReasonArabic | String | in case of non-vatable Arabic category Reason is mandatory in advance receipt storage added for user input |
| VCHeInvTotalAmt_KSA_Integ_phase | Amount | Total invoice Amount |
| VCHeInvVATAmt_KSA_Integ_phase | Amount | Total Vat Amount |
| VCHeInvActualAmt_KSA_Integ_phase | Amount | Total invoice Amount for which e-invoice generated (to check tempered Invoice) |
| TaxNatureTrans | String | Nature of transaction in advance receipt Voucher |
| VCHeInvCompanyName | String | Company name |
| VCHeInvVATNumber | String | Party vat tin number |
| VCHeInvTime | String | Invoice generated Time |
| VCHeInvDate | String | Invoice date |
| TaxNatureTrans | String | Added nature of transaction in Advance Receipt |
| KSA_Vch_TypeofAddress | String | Added Storage for Address Type Selection in Voucher Level under ‘Show E-Invoice Details’ to Use Multi-Address value. |
Credit Note / Debit Note Reason List
| Code | Description |
| CAN | Cancellation or suspension of the supplies after its occurrence either wholly or partially |
| ASUP | In case of essential change or amendment in the supply, which leads to the change of the VAT due |
| ASUPV | Amendment of the supply value which is pre-agreed upon between the supplier and consumer |
| REF | In case of goods or services refund |
| CHG | In case of Change in Seller’s or Buyer’s information |
VAT Category Code and Text
| Exemption from Tax | |
| Code | English Text |
| VATEX_SA_29 | Financial services mentioned in Article 29 of the VAT Regulations |
| VATEX_SA_29_7 | Life insurance services mentioned in Article 29 of the VAT Regulations |
| VATEX_SA_30 | Real estate transactions mentioned in Article 30 of the VAT Regulations |
| Zero rated goods | |
| Code | English Text |
| VATEX_SA_32 | Export of goods |
| VATEX_SA_33 | Export of services |
| VATEX_SA_34_1 | The international transport of Goods |
| VATEX_SA_34_2 | International transport of passengers |
| VATEX_SA_34_3 | Services directly connected and incidental to a Supply of international passenger transport |
| VATEX_SA_34_4 | Supply of a qualifying means of transport |
| VATEX_SA_34_5 | Any services relating to Goods or passenger transportation, as defined in article twenty-five of these Regulations |
| VATEX_SA_35 | Medicines and medical equipment |
| VATEX_SA_36 | Qualifying metals |
| VATEX_SA_EDU | Private education to citizen |
| VATEX_SA_HEA | Private healthcare to citizen |
| VATEX_SA_MLTRY | Supply of qualified military goods |
|
VATEX_SA_EDU |
Private education to citizen |
|
VATEX_SA_HEA |
Private healthcare to citizen |
|
VATEX_SA_MLTRY |
Supply of qualified military goods |
|
Services outside scope of tax / Not subject to VAT/(Non Vatable) |
|
|
Code |
English Text |
|
VATEX_SA_OOS |
Reason is free text, to be provided by the taxpayer on case-to-case basis. |
Charges Ledger Master Code list
|
Code |
Ledger Name |
|
AA |
Advertising allowance |
|
AAA |
Telecommunication charges |
|
AAB |
Returned goods charges |
|
AAC |
Modification costs |
|
AAD |
Job-order production |
|
AAE |
Outlays |
|
AAF |
Off-premises surcharge |
|
AAG |
Gold surcharge |
|
AAH |
Processing surcharge |
|
AAI |
Attestation fee |
|
AAJ |
Copper surcharge |
|
AAK |
Energy surcharge |
|
AAL |
Deduction for missing parts |
|
AAM |
Rubber surcharge |
|
AAN |
Brass surcharge |
|
AAO |
Material surcharge/deduction |
|
AAP |
Lead surcharge |
|
AAQ |
Price index surcharge |
|
AAR |
Platinum surcharge |
|
AAS |
Acceptance cost |
|
AAT |
Rush delivery |
|
AAV |
Special construction charge |
|
AAY |
Airport facilities |
|
AAZ |
Concession |
|
ABA |
Compulsory storage |
|
ABB |
Fuel removal |
|
ABC |
Into plane |
|
ABD |
Overtime |
|
ABF |
Tooling |
|
ABK |
Miscellaneous |
|
ABL |
Additional packaging |
|
ABN |
Dunnage |
|
ABR |
Containerisation |
|
ABS |
Carton packing |
|
ABT |
Hessian wrapped |
|
ABU |
Polyethylene wrap packing |
|
ACF |
Miscellaneous treatment |
|
ACG |
Enamelling treatment |
|
ACH |
Heat treatment |
|
ACI |
Plating treatment |
|
ACJ |
Painting |
|
ACK |
Polishing |
|
ACL |
Priming |
|
ACM |
Preservation treatment |
|
ACS |
Fitting |
|
ADC |
Consolidation |
|
ADE |
Bill of lading |
|
ADJ |
Airbag |
|
ADK |
Transfer |
|
ADL |
Slipsheet |
|
ADM |
Binding |
|
ADN |
Repair or replacement of broken returnable package |
|
ADO |
Efficient logistics |
|
ADP |
Merchandising |
|
ADQ |
Product mix |
|
ADR |
Other services |
|
ADT |
Pick-up |
|
ADW |
Chronic illness |
|
ADY |
New product introduction |
|
ADZ |
Direct delivery |
|
AEA |
Diversion |
|
AEB |
Disconnect |
|
AEC |
Distribution |
|
AED |
Handling of hazardous cargo |
|
AEF |
Rents and leases |
|
AEH |
Location differential |
|
AEI |
Aircraft refueling |
|
AEJ |
Fuel shipped into storage |
|
AEK |
Cash on delivery |
|
AEL |
Small order processing service |
|
AEM |
Clerical or administrative services |
|
AEN |
Guarantee |
|
AEO |
Collection and recycling |
|
AEP |
Copyright fee collection |
|
AES |
Veterinary inspection service |
|
AET |
Pensioner service |
|
AEU |
Medicine free pass holder |
|
AEV |
Environmental protection service |
|
AEW |
Environmental clean-up service |
|
AEX |
National cheque processing service outside account area |
|
AEY |
National payment service outside account area |
|
AEZ |
National payment service within account area |
|
AJ |
Adjustments |
|
AU |
Authentication |
|
CA |
Cataloguing |
|
CAB |
Cartage |
|
CAD |
Certification |
|
CAE |
Certificate of conformance |
|
CAF |
Certificate of origin |
|
CAI |
Cutting |
|
CAJ |
Consular service |
|
CAK |
Customer collection |
|
CAL |
Payroll payment service |
|
CAM |
Cash transportation |
|
CAN |
Home banking service |
|
CAO |
Bilateral agreement service |
|
CAP |
Insurance brokerage service |
|
CAQ |
Cheque generation |
|
CAR |
Preferential merchandising location |
|
CAS |
Crane |
|
CAT |
Special colour service |
|
CAU |
Sorting |
|
CAV |
Battery collection and recycling |
|
CAW |
Product take back fee |
|
CD |
Car loading |
|
CG |
Cleaning |
|
CS |
Cigarette stamping |
|
CT |
Count and recount |
|
DAB |
Layout/design |
|
DAD |
Driver assigned unloading |
|
DL |
Delivery |
|
EG |
Engraving |
|
EP |
Expediting |
|
ER |
Exchange rate guarantee |
|
FAA |
Fabrication |
|
FAB |
Freight equalization |
|
FAC |
Freight extraordinary handling |
|
FC |
Freight service |
|
FH |
Filling/handling |
|
FI |
Financing |
|
GAA |
Grinding |
|
HAA |
Hose |
|
HD |
Handling |
|
HH |
Hoisting and hauling |
|
IAA |
Installation |
|
IAB |
Installation and warranty |
|
ID |
Inside delivery |
|
IF |
Inspection |
|
IR |
Installation and training |
|
IS |
nvoicing |
|
KO |
Koshering |
|
L1 |
Carrier count |
|
LA |
Labelling |
|
LAA |
Labour |
|
LAB |
Repair and return |
|
LF |
Legalisation |
|
MAE |
Mounting |
|
MI |
Mail invoice |
|
ML |
Mail invoice to each location |
|
NAA |
Non-returnable containers |
|
OA |
Outside cable connectors |
|
PA |
Invoice with shipment |
|
PAA |
Phosphatizing (steel treatment) |
|
PC |
Packing |
|
PL |
Palletizing |
|
RAB |
Repacking |
|
RAC |
Repair |
|
RAD |
Returnable container |
|
RAF |
Restocking |
|
RE |
Re-delivery |
|
RF |
Refurbishing |
|
RH |
Rail wagon hire |
|
RV |
Loading |
|
SA |
Salvaging |
|
SAA |
Shipping and handling |
|
SAD |
Special packaging |
|
SAE |
Stamping |
|
SAI |
Consignee unload |
|
SG |
Shrink-wrap |
|
SH |
Special handling |
|
SM |
Special finish |
|
SU |
Set-up |
|
TAB |
Tank renting |
|
TAC |
Testing |
|
TT |
Transportation – third party billing |
|
TV |
Transportation by vendor |
|
V1 |
Drop yard |
|
V2 |
Drop dock |
|
WH |
Warehousing |
|
XAA |
Combine all same day shipment |
|
YY |
Split pick-up |
|
ZZZ |
Mutually defined |
e-Invoice enablement for the voucher type
To enable e-Invoicing for a voucher type; new storage ‘IsVchTypeInvApplicable’ is introduced.
;; to Check e-invoice yes or no
[Field : VTYP KSAInvoiceEnable]
Use : Logical Field
Storage : IsVchTypeInvApplicable
Skip on : $HasVouchers And $IsVchTypeInvApplicable
Set Always : Yes
QR Code Part
In Comprehensive Invoice
[Part: EXPINV VATGCCQRCodeArabic]
QR Code : @SignedQrcode:Yes
SignedQrcode : @@PrintafterSaveQR (formula Added below)
Line : VATGCCQRCodeDetails
Common Border : Yes
Invisible : $$IsEmpty:@@PrintafterSaveQR
In Simple Invoice
[Part: EXPSMP VATGCCQRCode]
QR Code : @SignedQRCode:Yes
SignedQRCode : @@PrintafterSaveQR (formula Added below)
Line : EXPSMPVATGCCQRCodeDetails
Invisible : $$IsEmpty:@@PrintafterSaveQR
In POS Invoice
[Part: KSA_eInvoice PrintExp QRC]
QR Code : @SignedQrCode:Yes
SignedQrCode : @@PrintafterSaveQR
Line : Empty
Horizontal Align : Center
Invisible : $$IsEmpty:@@PrintafterSaveQR
System Formula
[System : Formula]
PrintafterSaveQR:If Not $$IsEmpty:$einvoice_signedQRCode then $einvoice_signedQRCode + ElseIf $$number:##MasterID_PrintAfterSave = $$number:$MasterID then ##QRCodeString_PrintAfterSave +
Else “”
Note : @@EInvoiceQRCodeKsa can be used to print the QR code from previously saved vouchers as required. The key difference is that if the ‘Print after save’ option is enabled in the voucher type, the QR code may not print at that moment. In such cases, you can utilize the formula mentioned above to ensure the QR code is printed.
Function – SubmitForKSAEInvoice
The function is designed to submit a transaction for e-Invoice generation by calling an external import utility or API.
The function will accept a MasterID as input, which corresponds to a specific transaction. This transaction will then be submitted for e-Invoice generation. Upon submission, the function will capture and store the success or failure response directly within the transaction
Example
$$SubmitForKsaEinvoice:(ID:324)
