Earnings/Deductions API

  • Print
14 November 2023
Payroll
Written by Himanshu Lande
627
0

Description 

 

This document gives detailed information about How to add earnings and deductions of users via API. Records are imported with 500 max records by default, this max records can be changed from configuration. All the data is inserted as a new record. Multiple records of the same user can be saved in the record with a unique biometric code.

 

API Endpoint

https://<your_instance>/api.php/attendance/attendancedb/pushUsersEarningsandDeductions

Bearer Token 

 

Please refer to the token generation documentation for generating API tokens to invoke uKnowva APIs. (Token Generation Docs)

 

Method Type

 

  •  POST

Mandatory Fields

“type” : “earnings” or “deductions” only, “group”, “month”, “year” , “username”

Example Request

cURL

curl --location 'https://<your_instance>/api.php/attendance/attendancedb/pushUsersEarningsandDeductions'
\--header 'Content-Type: application/json'
\--header 'Authorization: provided_token'\
--data'{"pendingcount1":
[{
"type":"earnings","group": "Car Allowance","amount": 10000,"username": "pendingcount1","month": 9,"year": 2023,"description": "Test1 description","is_non_taxable": "yes"},{"type": "deductions","group": "Car Allowance","amount": 10000,"username": "pendingcount1","month": 9,"year": 2023,"description": "Test2 description"}],"test123":[{"type": "deductions","group": "Car Allowance","amount": 10000,"username": "test123","month": 9,"year": 2023,"description": "Test2 description"}
]}'

PHP Code Snippet

<?php
$curl = curl_init();
  curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://<your_instance>/api.php/attendance/attendancedb/pushUsersEarningsandDeductions',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "pendingcount1": [
        {
        "type": "earnings",   
        "group": "Car Allowance",   
        "amount": 10000,      
        "username": "pendingcount1",    
        "month": 9,       
        "year": 2023,       
        "description": "Test1 description", 
        "is_non_taxable": "yes"   
    },
    {
        "type": "deductions", 
        "group": "Car Allowance",     
        "amount": 10000,        
        "username": "pendingcount1",      
        "month": 9,         
        "year": 2023,         
        "description": "Test2 description"    
    }
    ],
    "test123":[
        {
         "type": "deductions",  
        "group": "Car Allowance",     
        "amount": 10000,        
        "username": "test123",      
        "month": 9,         
        "year": 2023,         
        "description": "Test2 description"    
        }
    ]
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
     'Authorization: Bearer Token'
  ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;

Python Code Snippet

import requests
import json
url = "https://<your_instance>/api.php/attendance/attendancedb/pushUsersEarningsandDeductions"
payload = json.dumps({
  "pendingcount1": [
    {
      "type": "earnings",
      "group": "Car Allowance",
      "amount": 10000,
      "username": "pendingcount1",
      "month": 9,
      "year": 2023,
      "description": "Test1 description",
      "is_non_taxable": "yes"
    },
    {
      "type": "deductions",
      "group": "Car Allowance",
      "amount": 10000,
      "username": "pendingcount1",
      "month": 9,
      "year": 2023,
      "description": "Test2 description"
    }
  ],
  "test123": [
    {
      "type": "deductions",
      "group": "Car Allowance",
      "amount": 10000,
      "username": "test123",
      "month": 9,
      "year": 2023,
      "description": "Test2 description"
    }
  ]
})
headers = {
  'Content-Type': 'application/json',
  'Authorization: Bearer Token'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)

Java Code Snippet 

OkHttpClient client = new OkHttpClient().newBuilder().build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{"pendingcount1": [{"type": "earnings",t tn"group": "Car Allowance",ttn"amount": 10000,tttn"username": "pendingcount1",ttn"month": 9,"year": 2023,"description": "Test1 description",tn"is_non_taxable": "yes"ttn},{"type": "deductions",tn"group": "Car Allowance",tttn"amount": 10000,"username": "pendingcount1",tttn"month": 9,t"year": 2023,t"description": "Test2 description"ttn}],"test123":[{ "type": "deductions",tn"group": "Car Allowance",tttn"amount": 10000,"username": "test123",tttn"month": 9,t"year": 2023,t"description": "Test2 description"ttn}]}");
Request request = new Request.Builder()
.url("https://<your_instance>/api.php/attendance/attendancedb/pushUsersEarningsandDeductions")
.method("POST", body)
.addHeader("Content-Type", "application/json")
.addHeader("Authorization", "Bearer Token")
.build();
Response response = client.newCall(request).execute();

Payload 

{
    "pendingcount1": [
        {
        "type": "earnings",   //Type should be “earnings” or “deductions” only Mandatory
        "group": "Car Allowance",   //Group is Mandatory
        "amount": 10000,      //Amount is Non-Mandatory
        "username": "pendingcount1",    //username is Mandatory
        "month": 9,       //Month is Mandatory
        "year": 2023,       //Year is Mandatory
        "description": "Test1 description", //Description is Non-Mandatory
        "is_non_taxable": "yes"   //Optional and present in “earnings” condition only
    },
    {
        "type": "deductions", //Type should be “earnings” or “deductions” only Mandatory
        "group": "Car Allowance",     //Group is Mandatory
        "amount": 10000,        //Amount is Non-Mandatory
        "username": "pendingcount1",      //username is Mandatory
        "month": 9,         //Month is Mandatory
        "year": 2023,         //Year is Mandatory
        "description": "Test2 description"    //Description is Non-Mandatory
    }
    ],
    "test123":[
        {
         "type": "deductions",  //Type should be “earnings” or “deductions” only Mandatory
        "group": "Car Allowance",     //Group is Mandatory
        "amount": 10000,        //Amount is Non-Mandatory
        "username": "test123",      //username is Mandatory
        "month": 9,         //Month is Mandatory
        "year": 2023,         //Year is Mandatory
        "description": "Test2 description"    //Description is Non-Mandatory
        }
    ]
}

Sample Response

  • Success
  1. “All records imported successfully” for successfully importing all the records.
  2. “Bearer Token is not correct” when the token is wrong.
  3. “No Data Present” when no data is sent.
  4. “Records count is <the_data> which is greater than allowed records <record_set_in_config>” when records to be imported are greater than the set records.
  5. “No User found with the provided <biometric_code> - ” when the API has different biometric code then the set biometric code set in config.
  6. “Either month or year not found for the - ” when no month and year are sent in the API.
  7. “Either month or year are in the wrong format, Please enter in number for - ” when the month or year is not present in numeric form.
  8. “Type can only be either earnings or deductions only <biometric_code> - ” when “type” other than “earnings” or “deductions” are sent.
  9. “Group cannot be empty for the <biometric_code> - ” when “group” sent is empty.
  10. “Invalid earnings group for the <biometric_code> - ” when the “group” send is not present for “earnings” type.
  11. “Invalid deductions group for the <biometric_code> - ” when the “group” send is not present for “deductions” type.
  12. “Amount should be greater than 0 for the <biometric_code> - ” when the “amount” sent is smaller than zero.
  13. “Username cannot be empty for the <biometric_code> - ” when the “username” sent is empty.
  14. “Invalid username for <biometric_code> - ” when the username is different from the biometric code id of that user.

Sample Collection

Download Earnings/Deductions API Collection

In case you face any problems, then please write to This email address is being protected from spambots. You need JavaScript enabled to view it., our awesome support team will surely help you!

Was this Article helpful?