Basic Guideline

Jurnal API Integration

“Can my system integrate with Jurnal?”

Jurnal Integration Team

Version 1.1 - Dec 2021
Introduction
“Can my system integrate with Jurnal?”
Since we received so many similar questions, this document is created to help you get to the
answer. While this document is intentionally made simple and would not answer all of your
questions, we hope it may help you get started and guide you to the answer: yes or maybe not.

First tip: Before continuing to read this document, it is ideal to know the final business
process/flow that your company will use after the integration. In other words, you need to at least
get the picture of why the integration with Jurnal is needed. For example, what data do you want
to see in Jurnal? Your sales transaction data? Your purchase transaction data? What about your
customer data? This will help you get more understanding of whether API integration with Jurnal
is indeed possible or not.

Second tip: Note that the APIs specifically mentioned on this document is not comprehensive, but
only the most important ones. Please refer to Jurnal API docs for the list of all public APIs.

1
Table of Contents
Introduction

Table of Contents

A. Sales Transactions

B. Purchase Transactions

C. Stock Adjustments

D. Expenses

Recommended: do experiments on a free Jurnal sandbox account

Technical: API Key or Access Token?

Closing

2
A. Sales Transactions
The most common scenario of integrating with Jurnal is so that sales transactions from your
system can seamlessly flow into Jurnal. Sales transactions in Jurnal are represented by 6
different objects depending on the flow of transactions in sequential order:

1. Sales Quote → represents your sales offering to your customer

2. Sales Order (with/out Deposit) → represents the final agreed purchase detail between
you and your customer.
3. Sales Order Payment → you receive payment from the customer before the invoice is
published or the products are delivered to the customer. A Sales Order can have multiple
Sales Order Payments
4. Sales Delivery (with/out Shipping fee) → represents the delivery process where you ship
the purchased goods to your customer. Cannot stand alone, must have a preceding Sales
Order. A Sales Order can have multiple Sales Deliveries.
5. Sales Invoice → you publish an invoice for the customer for his/her purchase. A Sales
Delivery can only have on Sales Invoice.
6. Receive Payment → you receive payment from the customer for the invoice. A Sales
Invoice can have multiple Receive Payments.
7. Sales Return → your customer returns some / all of the purchased goods to you. A Sales
Invoice can have multiple Sales Returns.
8. Credit Memo → if your customer already paid you for the Sales Transaction, you can either
refund the money or use it for the customer’s next purchase from you. In the meantime,
this amount of money is recorded in what is called a Credit Memo. Creating a Sales
Return will automatically create a Credit Memo.

While all 8 of the modules above can be integrated with Jurnal, most of our API users typically
only integrate the Sales Invoice and Receive Payment module for simplicity.

Please also note that the 8 modules above do not stand alone on their own, but consists of 4
primary and 3 secondary elements:

● Primary Elements
○ Products → the products (i.e. goods and/or services) that are sold in this Sales
Transaction
○ Warehouse → the warehouse where the products will be sourced from
○ Customer → the customer as the counterpart of this Sales Transaction
○ Tax → taxes present on the Sales Transaction

3
 ● Secondary Elements
○ Discount per line → the product-level discount on the Sales Transaction
○ Discount on invoice-level → the invoice-level discount on the Sales Transaction
○ Withholding → the withholding element which subtracts the total invoice amount

Take a look at the diagram below for the relationship between all 7 elements.

Here is a brief explanation of what the diagram means:

➔ All sales transactions must consist of one customer and at least one product
➔ A sales transaction can begin as early as Sales Quote, then move to Sales Order
➔ A Sales Order can have multiple Sales Order Payments i.e. down payment/deposit with
varying Payment Methods
➔ Independently of Sales Order Payments, a Sales Order can have multiple Sales Deliveries
➔ Multiple Sales Deliveries can be made into a Sales Invoice. On the other hand, you do not
need to have any Sales Delivery at all. A Sales Quote or a Sales Order can be converted
to a Sales Invoice right away.

4
 ➔ A Sales Invoice can have multiple Receive Payments with varying Payment Methods
➔ Independently from Receive Payments, a Sales Invoice can have multiple Sales Returns.
Sales Returns relate to the products/services in the Sales Invoice rather than the Receive
Payments
➔ A Sales Return will automatically create a Credit memo

Being primary elements, Customer, Products, Warehouse, and Tax must exist first in Jurnal before
we can create any Sales Transactions. The following table lists the relevant APIs for the 4
elements:

● Customer
○ Add a Customer → note that the `display_name` must be unique across all
customers and vendors
○ Add Many Customers
○ Update a Customer
○ Delete a Customer
○ Get a Customer
○ Get a List of Customers
● Products
○ Add a Product
○ Add Many Products
○ Update a Product
○ Delete a Product
○ Get a Product
○ Get a List of Products
● Warehouse
Note: since normally a Jurnal company would not have many warehouses, warehouses
are better to be added and modified via Jurnal web instead of the API. You would only
need to refer to the warehouse_id or warehouse_name on other APIs.
○ Add a Warehouse
○ Update a Warehouse
○ Delete a Warehouse
○ Get a Warehouse
○ Get a List of Warehouses
● Tax
Note: since normally a Jurnal company would not have many tax types, taxes are better to
be added and modified via Jurnal web instead of the API. You would only need to refer to
the tax_id or tax_name on other APIs.
○ Add a Single Tax

5
 ○ Update a Single Tax
○ Get a Single Tax
○ Add a Group Tax → group tax is essentially a collection of multiple single taxes
○ Update a Group Tax
○ Get a Group Tax
○ Get List of Taxes → this includes all single taxes and group taxes

Now that all 4 primary elements have been properly configured, please take a look at the
relevant APIs to actually record your Sales Transactions in Jurnal:

1. Sales Quote
a. Add a Sales Quote
b. Update a Sales Quote
c. Delete a Sales Quote
d. Get a Sales Quote
e. Get a List of Sales Quote
2. Sales Order
a. Add a Sales Order
b. Update a Sales Order
c. Delete a Sales Order
d. Get a Sales Order
e. Get a List of Sales Order
f. Get Sales Order Payments
3. Sales Order Payment
a. Add a Sales Order Payment
b. Update a Sales Order Payment
c. Delete a Sales Order Payment
d. Get a Sales Order Payment
e. Get a List of Sales Order Payment
4. Sales Delivery
a. Add a Sales Delivery
b. Update a Sales Delivery
c. Delete a Sales Delivery
d. Get a Sales Delivery
e. Get a List of Sales Delivery
f. Convert Sales Delivery to Sales Invoice
5. Sales Invoice
a. Add a Sales Invoice
b. Update a Sales Invoice

6
 c. Delete a Sales Invoice
d. Get a Sales Invoice
e. Get a List of Sales Invoices
f. Get List of Payments from Sales Invoices
6. Receive Payment
a. Add a Receive Payment
b. Update a Receive Payment
c. Delete a Receive Payment
d. Get a Receive Payment
e. Get a List of Receive Payments

Tip: Please pay attention to the payment_method_name or payment_method_id, and the

deposit_to_name for the Receive Payment. The deposit_to_name is the Jurnal “account” to
where the customer payment will be designated to. Please consult this with your Finance team.

7. Sales Return
a. Add a Sales Return
b. Update a Sales Return
c. Delete a Sales Return
d. Get a Sales Return
e. Get a List of Sales Return
8. Credit Memo
a. Get a List of Credit Memos
b. Create Customer Credit Memo Refund → return the refunded amount of a previous
Sales Return
c. Create Customer Apply Credit Memo → use the refunded amount of a previous
Sales Return as payment for another Sales Transaction

Tip: Please note that you do not need to start from the Sales Quote or Sales Order. You can start
from the Sales Invoice to only record the final transaction details which have been agreed
between you and your customers. However, this really depends on your company’s workflow in
Jurnal.

7
B. Purchase Transactions
Another scenario of integrating with Jurnal is so that purchase transactions from your system
can seamlessly flow into Jurnal. Purchase transactions here means your company purchase
products (goods and services) from your vendors.

Essentially, Purchase Transactions are very similar to Sales Transactions – even on the building
blocks.

Purchase Transactions in Jurnal are represented by 6 different objects depending on the flow of
transactions in sequential order:

1. Purchase Quote → represents your vendor offering to you

2. Purchase Order (with/out Deposit) → represents the final agreed purchase detail
between your vendor and your company
3. Purchase Order Payment → you pay the vendor before you receive the purchased goods
or services. A Purchase Order can have multiple Purchase Order Payments.
4. Purchase Delivery (with/out Shipping fee) → represents the delivery process where your
vendor ship the goods to you
5. Purchase Invoice → your vendor publishes an invoice to you for your purchase
6. Purchase Payment → you pay your vendor for the Purchase Invoice. A Purchase Invoice
can have multiple Purchase Payments
7. Purchase Return → you return some / all of the purchased goods to your vendor. A
Purchase Invoice can have multiple Purchase Returns
8. Debit Memo → if you already paid your vendor for the Purchase Transaction and you
return some of the goods or services, then you would have a deposit on your vendor
which is recorded in what is called a Debit Memo. Creating a Purchase Return will
automatically create a Debit Memo.

While all 8 of the modules above can be integrated with Jurnal, most of our API users typically
only integrate the Purchase Invoice and Purchase Payment module for simplicity.

Similar to Sales Transactions, the 8 modules above do not stand alone on their own, but consists
of 4 primary and 3 secondary elements:

● Primary Elements
○ Products → the products (i.e. goods and/or services) that you buy in this Purchase
Transaction

8
 ○ Warehouse → the warehouse where the products will be stored at when they
arrive
○ Vendor → the vendor as the counterpart of this Purchase Transaction
○ Tax → taxes present on the Purchase Transaction
● Secondary Elements
○ Discount per line → the product-level discount on the Sales Transaction
○ Discount on invoice-level → the invoice-level discount on the Sales Transaction
○ Withholding → the withholding element which subtracts the total invoice amount

Take a look at the diagram below for the relationship between all 7 elements.

Here is a brief explanation of what the diagram means:

➔ All purchase transactions must consist of one vendor and at least one product
➔ A purchase transaction can begin as early as Purchase Quote, then move to Purchase
Order

9
 ➔ A Purchase Order can have multiple Purchase Order Payments i.e. down payment/deposit
with varying Payment Methods
➔ Independently of Purchase Order Payments, a Purchase Order can have multiple
Purchase Deliveries
➔ Multiple Purchase Deliveries can be made into a Purchase Invoice. On the other hand,
you do not need to have any Purchase Delivery at all. A Purchase Quote or a Purchase
Order can be converted to a Purchase Invoice right away.
➔ A Purchase Invoice can have multiple Purchase Payments with varying Payment Methods
➔ Independently from Purchase Payments, a Purchase Invoice can have multiple Purchase
Returns. Purchase Returns relate to the products/services in the Purchase Invoice rather
than the Purchase Payments
➔ A Purchase Return will automatically create a Debit memo

Being primary elements, Vendor, Products, Warehouse, and Tax must exist first in Jurnal before
we can create any Purchase Transactions. The following table lists the relevant APIs for the 4
elements:

● Vendor
○ Add a Vendor → note that the `display_name` must be unique across all customers
and vendors
○ Update a Vendor
○ Delete a Vendor
○ Get a Vendor
○ Get a List of Vendors
● Products
○ Add a Product
○ Add Many Products
○ Update a Product
○ Delete a Product
○ Get a Product
○ Get a List of Products
● Warehouse
Note: since normally a Jurnal company would not have many warehouses, warehouses
are better to be added and modified via Jurnal web instead of the API. You would only
need to refer to the warehouse_id or warehouse_name on other APIs.
○ Add a Warehouse
○ Update a Warehouse
○ Delete a Warehouse
○ Get a Warehouse

10
 ○ Get a List of Warehouses
● Tax
Note: since normally a Jurnal company would not have many tax types, taxes are better to
be added and modified via Jurnal web instead of the API. You would only need to refer to
the tax_id or tax_name on other APIs.
○ Add a Single Tax
○ Update a Single Tax
○ Get a Single Tax
○ Add a Group Tax → group tax is essentially a collection of multiple single taxes
○ Update a Group Tax
○ Get a Group Tax
○ Get a List of Taxes → this includes all single taxes and group taxes

Now that all 4 primary elements have been properly configured, please take a look at the
relevant APIs to actually record your Purchase Transactions in Jurnal:

1. Purchase Quote
d. Add a Purchase Quote
e. Update a Purchase Quote
f. Delete a Purchase Quote
g. Get a Purchase Quote
h. Get a List of Purchase Quotes
i. Convert Purchase Quote to Purchase Order
j. Convert Purchase Quote to Purchase Invoice
2. Purchase Order
a. Add a Purchase Order
b. Update a Purchase Order
c. Delete a Purchase Order
d. Get a Purchase Order
e. Get a List of Purchase Orders
f. Get Purchase Order Payments
g. Convert Purchase Order to Purchase Delivery
h. Convert Purchase Order to Purchase Invoice
3. Purchase Order Payment
a. Add a Purchase Order Payment
b. Update a Purchase Order Payment
c. Delete a Purchase Order Payment
d. Get a Purchase Order Payment
e. Get a List of Purchase Order Payment

11
 4. Purchase Delivery
a. Add a Purchase Delivery
b. Update a Purchase Delivery
c. Delete a Purchase Delivery
d. Get a Purchase Delivery
e. Get a List of Purchase Deliveries
f. Convert Purchase Delivery to Purchase Invoice
5. Purchase Invoice
a. Add a Purchase Invoice
b. Update a Purchase Invoice
c. Delete a Purchase Invoice
d. Get a Purchase Invoice
e. Get a List of Purchase Invoices
f. Get a List of Payments from Purchase Invoices
6. Purchase Payment
a. Add a Purchase Payment
b. Update a Purchase Payment
c. Delete a Purchase Payment
d. Get a Purchase Payment
e. Get a List of Purchase Payments

Tip: Please pay attention to the payment_method_name or payment_method_id, and the

refund_from_name for the Purchase Payment. The refund_from_name is the Jurnal “account”
from where you pay the vendor. Please consult this with your Finance team.

7. Purchase Return
a. Add a Purchase Return
b. Update a Purchase Return
c. Delete a Purchase Return
d. Get a Purchase Return
e. Get a List of Purchase Return
8. Purchase Memo
a. Get a List of Debit Memos
b. Create Vendor Debit Memo Refund → return the refunded amount of a previous
Purchase Return
c. Create Vendor Apply Debit Memo → use the refunded amount of a previous
Purchase Return as payment for another Purchase Transaction

12
Tip: Please note that you do not need to start from the Purchase Quote or Purchase Order. You
can start from the Purchase Invoice to only record the final transaction details which have been
agreed between you and your vendors. However, this really depends on your company’s
workflow in Jurnal.

13
C. Stock Adjustments
The Jurnal Stock Adjustment module is useful when you want to sync the inventory count
between your system and Jurnal. There are 6 relevant endpoints for recording, updating,
deleting, and getting the list of Stock Adjustment.

● Add a Stock Adjustment

● Update a Stock Adjustment
● Delete a Stock Adjustment
● Get a Stock Adjustment
● Get a List of Stock Adjustments
● Get a List of Stock Adjustments by Date

Tip: Please pay attention to the warehouse_id or warehouse_code, and also the maintain_actual
property

14
D. Expenses
Jurnal Expense module is useful when you want to record your company’s expenses, and the
integration is quite straightforward. There are only 5 relevant endpoints for recording, updating,
deleting, and getting the list of expenses.

● Add an Expense
● Update an Expense
● Delete an Expense
● Get an Expense
● Get a List of Expenses

Tip: Expense also supports payment method and a single withholding element.

15
Recommended: do experiments on a free Jurnal sandbox
account
Please note that this document only outlines the relevant endpoints to the most common
integration scenario we have found until the moment of this writing. You need to experiment with
Jurnal Web and the API on Jurnal sandbox environment to have a fuller understanding of what
each endpoint does.

To play around with Jurnal API, you can register a free Jurnal sandbox account and use Postman,
Insomnia, or other API request builder.

The proper way to plan for the integration is as follows:

1. Perform the operation on the Jurnal web sandbox account (e.g. create a product, a Sales
Invoice) then see the result
2. Try to perform the same operation on the Jurnal sandbox API, then try to achieve the
same result as the manual operation number 1
3. Then repeat for each operation on your integration scenario
4. Only then you should begin the integration development effort

Note that there is no difference whatsoever between Jurnal production and sandbox account in
functionalities, so you can freely test as much as you want.

Tip: While free, Jurnal sandbox accounts will expire after 14 days from the day of account
creation. Should you need an extended period to test your API, then please contact us via Live
Chat or send an email to [email protected] while providing your sandbox Company ID to
have your account extended by our administrators.

16
Technical: API Key or Access Token?
Jurnal supports 2 authentication methods: API Key and Access Token.

Simply put, if the integration you are trying to build is strictly for your own company’s internal
needs, then do use the API Key method.

However, if the integration is for commercial purposes e.g. sending your customer’s data to
Jurnal in case of a POS system, omnichannel system, etc., then you have to use the Access
Token method.

The table below outlines the difference between API Key and Access Token methods:

API Key Access Token

Integration Your own internal company’s Integrating your customers’ data to

purpose needs Jurnal for your company’s commercial
purposes

Integration 1. Log into your Jurnal company 1. Register as a developer at Jurnal

process account using the owner user Developer Center
credentials 2. Create a Jurnal add-on and set the
2. Get the API Credentials configuration
3. Use the API Key on the header 3. Copy the sandbox link of your
of your API requests to Jurnal add-on and install it on a Jurnal
4. When you have finished sandbox account that you have
building your integration, then created
you can just use it immediately 4. Get the Access Token specific to
without notifying the Jurnal your newly created add-on and
team Jurnal sandbox account
5. Use the Access Token on the
header of your API requests to
Jurnal
6. When you have finished building
your integration, then you need to
submit a publish request to the
Jurnal team so that your add-on
can be used by your customers
7. The Jurnal team will contact you
back to review and decide
whether your add-on has fulfilled
the necessary criteria to be
published

17
 8. If everything goes well, then the
Jurnal team will publish your
add-on on the Jurnal Marketplace

Access limitation Full access to the entire Jurnal Limited access to Jurnal company
company data data, as configured on the add-on
creation on Jurnal Developer Center

Example https://api.jurnal.id/core/api/v1/sal https://api.jurnal.id/partner/core/api/v

endpoint es_invoices 1/sales_invoices

Where to put the Request header, authorization Request header, authorization as

credentials using API Key with key = “apikey”, Bearer Token
and value = <<your Jurnal
company’s API Key>>

18
Closing
“Can my system integrate with Jurnal?”
We hope that this document helps you to answer that initial question better. If not, or if there are
any more questions or unclear parts, please reach out to us via Jurnal Live Chat or send an email
to [email protected]. We will gladly help you on your integration journey with Jurnal.

Thank you!

19