Partial Open API Accounting Integration

The Partial API Integration Approach, also known as the Journal APIs approach, lets your ERP retrieve fully prepared journal entries directly from Jisr. Unlike the Full API Integration Approach, you don't need to build journal construction logic in your ERP: Jisr generates the journals , applies account mappings, and applies accounting rules based on your file-based accounting integration configuration. Your ERP simply requests the journals and imports them.

This approach is best suited for organizations that want a faster implementation and are comfortable managing their chart of accounts, journal structure, and account mapping inside Jisr rather than in custom ERP logic.

Prerequisites:
 

Before you can call any Jisr Open API, you need an API Key and an Access Token. For more explanation on how to perform these steps, refer to this article.
 

Notes:

1- When creating the API key, make sure to select the following API permissions under the Financial section:
   - List Paygroups
   - Create Journal Export Request
   - Get Journal Export Request

2- Use the Authentication API to generate an Access Token, following the API documentation detailed in this technical documentation. This API response returns an Access Token to use in every subsequent request

Integration steps:

1- Retrieve Paygroups:

Paygroup information is required to start the integration process.

Use the endpoint: GET /openapi/v1/paygroup, following the details in the technical documentation.

Request Headers:

Header	Value
slug	Your organization slug
api-key	Generated API Key
api-version	1
Access-Token	Access Token

2- Configure File-Based Accounting Integration:
Before requesting journals via API, you must first configure how those journals will be built. This is done through Jisr's File-Based Accounting Integration setup. For the detailed steps on how to do this, refer to the help articles found here
At minimum, configure the following:
- Chart of Accounts (COA)
- Journal Structure
- Account Mapping
Once this configuration is complete, you're ready to use the Journal APIs.
 

3- Create a Journal Export Request:
This call kicks off journal preparation for a specific payroll period and journal type.

Use the endpoint: POST /openapi/v1/accounting/journals , following the details in the technical documentation.

Request Headers:

Header	Value
slug	Your organization slug
api-key	Generated API Key
api-version	1
Access-Token	Access Token

Request Parameters:

Parameter	Example	Description
journal_type	regular	Journal type
paygroup_id	ce08a73b-f296-4852-9f17-84541ad2cf7a	Paygroup ID
pay_period_from	2024-04-01	First day of payroll period

Journal Types:

The supported journal_type values are documented and maintained in the API Swagger documentation. Always refer to the latest API documentation for the complete and up-to-date list of supported journal types.

Sample Response:

{
 "success": true,
 "data": {
   "journal_export_request": {
     "status": "pending",
     "id": "402fabbd*******",
     "journal_preparation_errors": null
   }
 }
}

Important Response Fields:

Field	Description
status	Current preparation status
id	Request identifier used to retrieve journal data

Save the id returned here, as you'll need it in the next step to retrieve the finished journal.

4- Retrieve the Journal Entries:
Journal preparation happens asynchronously, so the export request won't necessarily be ready right when you create it. Always check the status field before trying to use the results.

Use the endpoint: GET /openapi/v1/accounting/journals/{id} , following the details in the technical documentation. The request parameter that you'll use here is the request id that was returned in the previous step.

Request Headers:

Header	Value
slug	Your organization slug
api-key	Generated API Key
api-version	1
Access-Token	Access Token

Possible returned statuses:

Status	Meaning	Action
Pending	Journal preparation is still in progress	the client application should wait for a short period and retry the request using the same request_id
Completed	Journal entries have been successfully generated, and are available in the response	you can parse the `journals` array and import the journal lines directly into your ERP. No further account mapping or rule logic is needed on your side, since Jisr has already applied it.
Failed	Journal preparation failed.	review the journal_preparation_errors field for details.

Sample Response:

{
 "success": true,
 "data": {
   "journal_export_request": {
     "journals": [
       {
         "journal_type": "Monthly Payroll",
         "subsidiary": "MainOrg",
         "journal_lines": [
           {
             "account_id": "11",
             "account_name": "Test",
             "transaction_name": "Payroll Salary Payable",
             "credit_amount": 3333625583821.5,
             "debit_amount": 0.0
           }
         ]
       }
     ]
   }
 }
}

5- Automate with Webhooks (Optional):

Webhooks let Jisr notify your ERP automatically when relevant payroll events occur, instead of you polling on a schedule.
For more details on how to use webhooks, refer to this article.