Get Started

To use Citssoft E-Invoicing platform, you'll need an API key.

  1. Create an account

Use the registration form to create an account. Fill out the following fields:

  • Name - your full name
  • Email - your email adadress
  • Password - a secure password you will remember
  • Confirm Password - retype the same password
  1. Obtain an API Key
  • Log in to your account (if not already logged in)
  • Click Generate under the API Key section
  • New API key will appear in the box
  • Copy the API Key and store it safely

API Documentation

Base URL: https://einvoicing.citssoft.com/api

Onboarding API:

URL: /integration/onboard

Required fields:

  • legal_registration_name : Business name as per registered in government
  • vat : 15 digit VAT number of business
  • crn : Commercial registration number of business
  • industry : A small description of type of industry or shsop
  • location : Address or website in single line
  • otp : 6 digit OTP number obtained from ZATCA ERAD Portal

Sample CURL:

curl -X POST https://einvoicing.citssoft.com/api/integration/onboard \
    -h 'Authorization: <API_KEY>' \
    -h 'Content-Type: application/json' \
    -d '{
        "legal_registration_name": "CITSSOFT",
        "vat": "312345678900003",
        "crn": "123456789",
        "industry": "Shop",
        "location": "citssoft.com",
        "otp": 575757
    }'

Sample Output:

{
    "comp_bin_sec_token": "TUlJQ0lqQ0NBY2lnQXdJQkFnSUdBWVIxaHU2N01Bb0dDQ3FHU000OUJBTUNNQlV4RXpBUkJnTlZCQU1NQ21WSmJuWnZhV05wYm1jd0hoY05Nakl4TVRFME1EazBORFF6V2hjTk1qY3hNVEV6TWpFd01EQXdXakJpTVFzd0NRWURWUVFHRXdKVFFURVRNQkVHQTFVRUN3d0tkR1Z5YldsdVlXd3RPVEVSTUE4R0ExVUVDZ3dJUTBsVVUxTlBSbFF4S3pBcEJnTlZCQU1NSWtOSlZGTlRUMFpVTFRFeU16UTFOamM0T1Mwek1USXpORFUyTnpnNU1EQXdNRE13VmpBUUJnY3Foa2pPUFFJQkJnVXJnUVFBQ2dOQ0FBVFBuSVhDd2kySXpZSUhydWNOcUwrcGJQYUdVLzlkMFprWGRTMm1lOHM5bWZlWjhiT2JkUWF1S2RBSnl4NTVPNy9YUWw5Y1dsTW1aYnA2R0lWZTlOdWdvNEc1TUlHMk1Bd0dBMVVkRXdFQi93UUNNQUF3Z2FVR0ExVWRFUVNCblRDQm1xU0JsekNCbERFOE1Eb0dBMVVFQkF3ek1TMXphV2R0WVhOdmJIVjBhVzl1Y3k1amIyMHVZbVI4TWkxNllYUmpZV1ZwYm5admFXTnBibWQyTW53ekxURXdNREE0TVI4d0hRWUtDWkltaVpQeUxHUUJBUXdQTXpFeU16UTFOamM0T1RBd01EQXpNUTB3Q3dZRFZRUU1EQVF4TVRFeE1SVXdFd1lEVlFRYURBeGphWFJ6YzI5bWRDNWpiMjB4RFRBTEJnTlZCQThNQkZOb2IzQXdDZ1lJS29aSXpqMEVBd0lEU0FBd1JRSWhBTlFYSkQ4RDQ4RkUxY2FKckpRcVVmekN0ZnBZVVZFWWhyU1JGdkszQUlmTkFpQkJ1MmlxSFpHZCtmbTdVVnliVHhXcm5HQ3VEbnFwQ1lYc040YVJaMFpyUlE9PQ==",
    "comp_cert": "MIICIjCCAcigAwIBAgIGAYR1hu67MAoGCCqGSM49BAMCMBUxEzARBgNVBAMMCmVJbnZvaWNpbmcwHhcNMjIxMTE0MDk0NDQzWhcNMjcxMTEzMjEwMDAwWjBiMQswCQYDVQQGEwJTQTETMBEGA1UECwwKdGVybWluYWwtOTERMA8GA1UECgwIQ0lUU1NPRlQxKzApBgNVBAMMIkNJVFNTT0ZULTEyMzQ1Njc4OS0zMTIzNDU2Nzg5MDAwMDMwVjAQBgcqhkjOPQIBBgUrgQQACgNCAATPnIXCwi2IzYIHrucNqL+pbPaGU/9d0ZkXdS2me8s9mfeZ8bObdQauKdAJyx55O7/XQl9cWlMmZbp6GIVe9Nugo4G5MIG2MAwGA1UdEwEB/wQCMAAwgaUGA1UdEQSBnTCBmqSBlzCBlDE8MDoGA1UEBAwzMS1zaWdtYXNvbHV0aW9ucy5jb20uYmR8Mi16YXRjYWVpbnZvaWNpbmd2MnwzLTEwMDA4MR8wHQYKCZImiZPyLGQBAQwPMzEyMzQ1Njc4OTAwMDAzMQ0wCwYDVQQMDAQxMTExMRUwEwYDVQQaDAxjaXRzc29mdC5jb20xDTALBgNVBA8MBFNob3AwCgYIKoZIzj0EAwIDSAAwRQIhANQXJD8D48FE1caJrJQqUfzCtfpYUVEYhrSRFvK3AIfNAiBBu2iqHZGd+fm7UVybTxWrnGCuDnqpCYXsN4aRZ0ZrRQ==",
    "comp_secret": "7nNBCnRkSIi+rNipjsJxJNPYCVgFaa1HpbTzXYEQTco=",
    "comp_request_id": 1234567890123,
    "prod_bin_sec_token": "TUlJRDJ6Q0NBNENnQXdJQkFnSVRid0FBZHFEbUlocXNqcG01Q3dBQkFBQjJvREFLQmdncWhrak9QUVFEQWpCak1SVXdFd1lLQ1pJbWlaUHlMR1FCR1JZRmJHOWpZV3d4RXpBUkJnb0praWFKay9Jc1pBRVpGZ05uYjNZeEZ6QVZCZ29Ka2lhSmsvSXNaQUVaRmdkbGVIUm5ZWHAwTVJ3d0dnWURWUVFERXhOVVUxcEZTVTVXVDBsRFJTMVRkV0pEUVMweE1CNFhEVEl5TURNeU9ERTFORFl6TWxvWERUSXlNRE16TURFMU5EWXpNbG93VFRFTE1Ba0dBMVVFQmhNQ1UwRXhEakFNQmdOVkJBb1RCVXBoY21seU1Sb3dHQVlEVlFRTEV4RktaV1JrWVdnZ1FuSmhibU5vTVRJek5ERVNNQkFHQTFVRUF4TUpNVEkzTGpBdU1DNHhNRll3RUFZSEtvWkl6ajBDQVFZRks0RUVBQW9EUWdBRUQvd2IybGhCdkJJQzhDbm5adm91bzZPelJ5bXltVTlOV1JoSXlhTWhHUkVCQ0VaQjRFQVZyQnVWMnhYaXhZNHFCWWY5ZGRlcnprVzlEd2RvM0lsSGdxT0NBaW93Z2dJbU1JR0xCZ05WSFJFRWdZTXdnWUNrZmpCOE1Sd3dHZ1lEVlFRRURCTXlNakl5TWpNeU5EUTBNelF6YW1abU5ETXlNUjh3SFFZS0NaSW1pWlB5TEdRQkFRd1BNekV3TVRjMU16azNOREF3TURBek1RMHdDd1lEVlFRTURBUXhNREV4TVJFd0R3WURWUVFhREFoVFlXMXdiR1VnUlRFWk1CY0dBMVVFRHd3UVUyRnRjR3hsSUVKMWMzTnBibVZ6Y3pBZEJnTlZIUTRFRmdRVWhXY3NiYkpoakQ1WldPa3dCSUxDK3dOVmZLWXdId1lEVlIwakJCZ3dGb0FVZG1DTSt3YWdyR2RYTlozUG1xeW5LNWsxdFM4d1RnWURWUjBmQkVjd1JUQkRvRUdnUDRZOWFIUjBjRG92TDNSemRHTnliQzU2WVhSallTNW5iM1l1YzJFdlEyVnlkRVZ1Y205c2JDOVVVMXBGU1U1V1QwbERSUzFUZFdKRFFTMHhMbU55YkRDQnJRWUlLd1lCQlFVSEFRRUVnYUF3Z1owd2JnWUlLd1lCQlFVSE1BR0dZbWgwZEhBNkx5OTBjM1JqY213dWVtRjBZMkV1WjI5MkxuTmhMME5sY25SRmJuSnZiR3d2VkZOYVJXbHVkbTlwWTJWVFEwRXhMbVY0ZEdkaGVuUXVaMjkyTG14dlkyRnNYMVJUV2tWSlRsWlBTVU5GTFZOMVlrTkJMVEVvTVNrdVkzSjBNQ3NHQ0NzR0FRVUZCekFCaGg5b2RIUndPaTh2ZEhOMFkzSnNMbnBoZEdOaExtZHZkaTV6WVM5dlkzTndNQTRHQTFVZER3RUIvd1FFQXdJSGdEQWRCZ05WSFNVRUZqQVVCZ2dyQmdFRkJRY0RBZ1lJS3dZQkJRVUhBd013SndZSkt3WUJCQUdDTnhVS0JCb3dHREFLQmdnckJnRUZCUWNEQWpBS0JnZ3JCZ0VGQlFjREF6QUtCZ2dxaGtqT1BRUURBZ05KQURCR0FpRUF5Tmh5Y1EzYk5sTEZkT1BscVlUNlJWUVRXZ25LMUdoME5IZGNTWTRQZkMwQ0lRQ1NBdGhYdnY3dGV0VUw2OVdqcDhCeG5MTE13ZXJ4WmhCbmV3by9nRjNFSkE9PQ==",
    "prod_cert": "MIID2zCCA4CgAwIBAgITbwAAdqDmIhqsjpm5CwABAAB2oDAKBggqhkjOPQQDAjBjMRUwEwYKCZImiZPyLGQBGRYFbG9jYWwxEzARBgoJkiaJk/IsZAEZFgNnb3YxFzAVBgoJkiaJk/IsZAEZFgdleHRnYXp0MRwwGgYDVQQDExNUU1pFSU5WT0lDRS1TdWJDQS0xMB4XDTIyMDMyODE1NDYzMloXDTIyMDMzMDE1NDYzMlowTTELMAkGA1UEBhMCU0ExDjAMBgNVBAoTBUphcmlyMRowGAYDVQQLExFKZWRkYWggQnJhbmNoMTIzNDESMBAGA1UEAxMJMTI3LjAuMC4xMFYwEAYHKoZIzj0CAQYFK4EEAAoDQgAED/wb2lhBvBIC8CnnZvouo6OzRymymU9NWRhIyaMhGREBCEZB4EAVrBuV2xXixY4qBYf9dderzkW9Dwdo3IlHgqOCAiowggImMIGLBgNVHREEgYMwgYCkfjB8MRwwGgYDVQQEDBMyMjIyMjMyNDQ0MzQzamZmNDMyMR8wHQYKCZImiZPyLGQBAQwPMzEwMTc1Mzk3NDAwMDAzMQ0wCwYDVQQMDAQxMDExMREwDwYDVQQaDAhTYW1wbGUgRTEZMBcGA1UEDwwQU2FtcGxlIEJ1c3NpbmVzczAdBgNVHQ4EFgQUhWcsbbJhjD5ZWOkwBILC+wNVfKYwHwYDVR0jBBgwFoAUdmCM+wagrGdXNZ3PmqynK5k1tS8wTgYDVR0fBEcwRTBDoEGgP4Y9aHR0cDovL3RzdGNybC56YXRjYS5nb3Yuc2EvQ2VydEVucm9sbC9UU1pFSU5WT0lDRS1TdWJDQS0xLmNybDCBrQYIKwYBBQUHAQEEgaAwgZ0wbgYIKwYBBQUHMAGGYmh0dHA6Ly90c3RjcmwuemF0Y2EuZ292LnNhL0NlcnRFbnJvbGwvVFNaRWludm9pY2VTQ0ExLmV4dGdhenQuZ292LmxvY2FsX1RTWkVJTlZPSUNFLVN1YkNBLTEoMSkuY3J0MCsGCCsGAQUFBzABhh9odHRwOi8vdHN0Y3JsLnphdGNhLmdvdi5zYS9vY3NwMA4GA1UdDwEB/wQEAwIHgDAdBgNVHSUEFjAUBggrBgEFBQcDAgYIKwYBBQUHAwMwJwYJKwYBBAGCNxUKBBowGDAKBggrBgEFBQcDAjAKBggrBgEFBQcDAzAKBggqhkjOPQQDAgNJADBGAiEAyNhycQ3bNlLFdOPlqYT6RVQTWgnK1Gh0NHdcSY4PfC0CIQCSAthXvv7tetUL69Wjp8BxnLLMwerxZhBnewo/gF3EJA==",
    "prod_secret": "f9YRhopN/G7x0TECOY6nKSCHLNYlb5riAHSFPICo4qw=",
    "prod_request_id": 30368
}

Generate Invoice API:

URL: /invoice/simplifiedInvoice - for simplified invoice (b2c)
URL: /invoice/simplifiedCredit - for simplified credit note (b2c)
URL: /invoice/simplifiedDebit - for simplified debit note (b2c)
URL: /invoice/standardInvoice - for standard invoice (b2b)
URL: /invoice/standardCredit - for standard credit note (b2b)
URL: /invoice/standardDebit - for standard debit note (b2b)

Sample CURL:

curl -X POST https://einvoicing.citssoft.com/api/invoice/simplifiedInvoice \
    -h 'Authorization: <API_KEY>' \
    -h 'Content-Type: application/json' \
    -d '{
        "prod_cert": "MIID2zCCA4CgAwIBAgITbwAAdqDmIhqsjpm5CwABAAB2oDAKBggqhkjOPQQDAjBjMRUwEwYKCZImiZPyLGQBGRYFbG9jYWwxEzARBgoJkiaJk/IsZAEZFgNnb3YxFzAVBgoJkiaJk/IsZAEZFgdleHRnYXp0MRwwGgYDVQQDExNUU1pFSU5WT0lDRS1TdWJDQS0xMB4XDTIyMDMyODE1NDYzMloXDTIyMDMzMDE1NDYzMlowTTELMAkGA1UEBhMCU0ExDjAMBgNVBAoTBUphcmlyMRowGAYDVQQLExFKZWRkYWggQnJhbmNoMTIzNDESMBAGA1UEAxMJMTI3LjAuMC4xMFYwEAYHKoZIzj0CAQYFK4EEAAoDQgAED/wb2lhBvBIC8CnnZvouo6OzRymymU9NWRhIyaMhGREBCEZB4EAVrBuV2xXixY4qBYf9dderzkW9Dwdo3IlHgqOCAiowggImMIGLBgNVHREEgYMwgYCkfjB8MRwwGgYDVQQEDBMyMjIyMjMyNDQ0MzQzamZmNDMyMR8wHQYKCZImiZPyLGQBAQwPMzEwMTc1Mzk3NDAwMDAzMQ0wCwYDVQQMDAQxMDExMREwDwYDVQQaDAhTYW1wbGUgRTEZMBcGA1UEDwwQU2FtcGxlIEJ1c3NpbmVzczAdBgNVHQ4EFgQUhWcsbbJhjD5ZWOkwBILC+wNVfKYwHwYDVR0jBBgwFoAUdmCM+wagrGdXNZ3PmqynK5k1tS8wTgYDVR0fBEcwRTBDoEGgP4Y9aHR0cDovL3RzdGNybC56YXRjYS5nb3Yuc2EvQ2VydEVucm9sbC9UU1pFSU5WT0lDRS1TdWJDQS0xLmNybDCBrQYIKwYBBQUHAQEEgaAwgZ0wbgYIKwYBBQUHMAGGYmh0dHA6Ly90c3RjcmwuemF0Y2EuZ292LnNhL0NlcnRFbnJvbGwvVFNaRWludm9pY2VTQ0ExLmV4dGdhenQuZ292LmxvY2FsX1RTWkVJTlZPSUNFLVN1YkNBLTEoMSkuY3J0MCsGCCsGAQUFBzABhh9odHRwOi8vdHN0Y3JsLnphdGNhLmdvdi5zYS9vY3NwMA4GA1UdDwEB/wQEAwIHgDAdBgNVHSUEFjAUBggrBgEFBQcDAgYIKwYBBQUHAwMwJwYJKwYBBAGCNxUKBBowGDAKBggrBgEFBQcDAjAKBggrBgEFBQcDAzAKBggqhkjOPQQDAgNJADBGAiEAyNhycQ3bNlLFdOPlqYT6RVQTWgnK1Gh0NHdcSY4PfC0CIQCSAthXvv7tetUL69Wjp8BxnLLMwerxZhBnewo/gF3EJA==",
        "prod_secret": "f9YRhopN/G7x0TECOY6nKSCHLNYlb5riAHSFPICo4qw=",
        "invoice_no": "0024",
        "issue_date_time": "2022-11-26 12:53:00",
        "icv": "10",
        "pih": "Fv64wF9voDs26nIUfPg+OvSy9w2gc0SMLapXZt68+jg=",
        "supplier": {
            "legal_registration_name": "CITSSOFT",
            "vat_no": "312345678900003",
            "crn": "123456789",
            "postal_address": {
                "country": "SA",
                "state": "Makkah",
                "district": "District",
                "city": "Makkah",
                "street": "Street 123",
                "plot": "4321",
                "building": "1234",
                "zip": "12101"
            }
        },
        "payment_means": ["cash"],
        "items": [
            {
                "name": "ALBAIK Broast",
                "unit": "piece",
                "unit_price": 30.00,
                "tax_category": "standard_rate",
                "tax_percent": 15,
                "base_quantity": 1,
                "quantity": 2,
                "per_unit_discount": 0,
                "all_unit_discount": 0
            },
            {
                "name": "ALBAIK Chicken Sandwitch",
                "unit": "piece",
                "unit_price": 10.00,
                "tax_category": "standard_rate",
                "tax_percent": 15,
                "base_quantity": 1,
                "quantity": 5,
                "per_unit_discount": 0,
                "all_unit_discount": 0
            },
        ],
        "overall_discount": 0
    }'

Note: For standardInvoice, standardCredit and standardDebit, the following fields are also required:

  • delivery_date_time : The date and time of actual delivery of supply
  • customer : (customer fields)
    • legal_registration_name : customer party legal registred name in VAT
    • vat_no : 15 digit VAT number of customer
    • crn : commercial registration number of customer
    • email : email address of customer, for sharing einvoice by email
    • postal_address : (customer address fields)
      • country
      • state
      • district
      • city
      • street
      • plot
      • building
      • zip

Note: For simplifiedCredit, simplifiedDebit, standardCredit, and standardDebit, the following fields are also required

  • cr_dr_reason : A textual reason for the credit or debit note, e.g "Bad items returned", "Items are added"
  • cr_dr_invoice_ref_no : The original invoice number as the reference / parent invoice for this credit / debit note