NAV Navbar
Logo

Overview

OnlinePajak provides a convenient and user friendly solution for corporate taxpayers to handle their taxes. OnlinePajak allows the preparation, payment and reporting of tax returns type : PPN and PPh 21. OnlinePajak for e-Faktur is also an alternative to e-Faktur desktop application for the generation of tax invoices through the e-Faktur.

The integration of OnlinePajak API can allow developers of third party software to interact with :

Our “Invoice” resources : Creates a new invoice from the submitted data (POST method) Get invoice data from an invoice number (GET method)

Introduction

Welcome to the Online Pajak OPEN API Documentation. This documentation is intended for 3rd party client integrator.

We have provide you with code example written in PHP to ease your integration process, feel free to contact us to help your integration process.

Authenticate API Client

In order to provide a clean way to access our services through the API, OnlinePajak provides an additional layer of authentication. The setup is in two steps : Creation of API key to authentify the marketplace and then, create a User ID to append a new user to the user list of this marketplace. Go to this link to proceed with the creation of API Key.

Create your Client API key

To consume the OnlinePajak API, the first step is to set up, in our API gateway, a Client API key for your marketplace/organization. This key is needs to be created once and for all, for each environment (once for staging, once for production, for example).

Staging: http://api.staging-achilles.systems

Production: https://api.online-pajak.com

You will be redirected to the “API Key Signup” page to fill the client registration form which consist of several fields to be filled out.

Parameter Description
First Name Your application name in lower_snake_case, this field is used to stamp the resource owner (e.g. onlinepajak_accounting_staging)
Last Name Your integrator name, in this case usually filled out by company/organization name (e.g. PT. Online Pajak)
Email A valid and active email address. You’re encouraged to fill it with generic email NOT personal email, because we will send downtime notification to this email (e.g. engineer@onlinepajak.com)
How you will use the API A brief description of integration purpose

After the submission of the form, your Client API key is generated. This key is a permanent key used for authenticate yourself as an authorized client to use our OPEN API. Depends on business discussion, we might limit your request based the given api key, but this api key won’t have any expiry date.

After an API key has been requested, please send an email to dev@online-pajak.com, so our development team can validate your Client API key in order for you to use it. The API key won’t be activated unless we validate it.

At this stage, you are able to use this API key to pass the gateway and access our resources. You can now get your user’s an ID in OnlinePajak.

Get a user id specifically for your api key

In order to differentiate the ownership of the resource (invoice, for example) on OnlinePajak, our system is using the User ID instead of the User Token.

The User ID is a unique integer that maps each of your users registered in OnlinePajak with your marketplace/organization’s Client API key.

Getting every of your users an ID is easy. Let’s how :

Step 1 : Redirect your user to the synchronization page

In order to obtain this User ID, your marketplace/organization has to redirect users to the link below in order to complete the synchronization.

Staging Environment :

http://invoices.staging-achilles.systems/marketplace/register/{API_KEY}?ne=Perusahaan&np=XX.XXX.XXX.X-XXX.XXX&el=user.email@xyz.org.com&callback={CALLBACK_URL}

Production Environment :

https://app.online-pajak.com/marketplace/register/{API_KEY}?ne=Perusahaan&np=XX.XXX.XXX.X-XXX.XXX&el=user.email@xyz.org.com&callback={CALLBACK_URL}

The parameters passed in the url are explained in the following table:

Parameter Description
np NPWP of user’s company with correct format “.” and “-” (e.g. 99.999.999.9-999.999)
ne Name of user’s company
el User’s email This will be used as identifier for our callback
callback Callback URL (Don’t forget the “http://” or “https://”)
  <?php
    $ch = curl_init('http://api.staging-achilles.systems/marketplace/v1/example.json?api_key=j48s9jbhg283njhj23SjwdF&user_id=1y3bs8en9sb9wmks35js8dd');       
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");                                                                     
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);                                                                      

    $result = curl_exec($ch);
    curl_close($ch);
    var_dump($result);

The above code returns Single JSON Object / JSON array of Object

[
  {
    "test": 1
  }
]

Step 2 : Parse the callback URL to get the returned parameters

As presented above, your marketplace/organization has to provide a “callback URL”. This callback URL will be returned by OnlinePajak, after your user has been synchronized. The return URL includes 2 additional parameters :
1. userId
2. email

Format : http://{CALLBACK_URL}?userId={User's ID}&email={User's email}

If you provide “http://abc-marketplace.com” as the callback URL, then the returned URL will be :

http://abc-marketplace.com?userId=5&email=user.email@xyz.org.com

All you need is to save each user’s ID in a database (or session, etc), so you can easily call the OnlinePajak’s marketplace API gateway in this format.

Staging Environment : http://api.staging-achilles.systems/marketplace/v1/{ Re }?api_key={ API Key }&user_id={ User’s ID }

Production Environment : https://api.online-pajak.com/marketplace/v1/{ Resource }?api_key={ API Key }&user_id={ User’s ID }

Errors thrown by API Gateway

Example error json thrown by API Gateway

{
  "error": {
    "code": "API_KEY_INVALID",
    "message": "An invalid api_key was supplied. Get one at http://api.staging-achilles.systems"
  }
}

In the event of the API returning an error, it will return a relevant status code, along with a response containing the following information.

Name Type Example Comments
message string “The API encountered a fatal error” The error message

The kind will be one of the ones given below. Check the message for more detailed information on the specific cause of the error.

Kind Meaning
API_KEY_INVALID The Client API key is invalid. This key can be provided from our API gateway
API_KEY_UNAUTHORIZED The api_key supplied is not authorized to access the given service.

To make sure your api key have the correct permission access to the resource, please reconfirm it during api key validation process when asking our developer team to validate your api key.

Invoice

This resource endpoint will include the calculation of VAT (PPN) tax

HTTP Status Code

Example of a success HTTP Code

{
  "code": 200,
  "message": "Invoice entity has been successfully created!",
  "response": {
    "invoice": {
      "invoiceId": 1389133,
      "invoiceDate": "2017-02-27",
      "invoiceDueDate": "2017-02-28",
      "grossAmount": 600000,
      "grandTotal": 660000,
      "revision": 0,
      "taxPeriod": "02/2017"
    }
  }
}

Example of a fail HTTP Code

{
  "code": 400,
  "message": "invalid token given"
}
{
  "code": 400,
  "message": "Missing mandatory parameters (invoiceNumber, invoiceDate, dueDate, invoiceType, transactionType, transactionDetail, documentType, npwp, vendor, documentNumber, masaPajak, tahunPajak, invoiceItems, vatRate) in the request body!"
}

When the proper parameters are used and the request passes the Invoice Resource API, our APIs will always respond to each request with a relevant HTTP Status Code and description.

200 (Success)

HTTP Status Code 200 is the generic success code. Most methods will use this code.

400 (Bad Request)

The request body will contain more information. Either an array of form errors or an error object. HTTP Status Code 400 is returned when wrong parameters are passed and embedded to response body as well.

Header Content-Types

<?php
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-Type: application/json',
    'Content-Length: ' . strlen($data_string))
);

Make sure to set the Content-Type of your requests to application/json, as this is a RESTful API and should only respond to the Content-Type you use. As this API only supports JSON, you will get an error if you make a request with a different Content-Type, or if one is not given (unless you are using GET endpoint).

Request URL

Staging : http://api.staging-achilles.systems/marketplace/v1/{RESOURCE}?api_key={API_KEY}&user_id={userId}

RESOURCE depends on the type of method you want to use.

Create an Invoice

Request


{
  "invoiceNumber":"my-invoice-1234",
  "invoiceItems":[
    {
      "description":"Test Item 1",
      "quantity":"2",
      "unitPrice":"100000",
      "discount" :"0",
      "wto":""
    },
    {
      "description":"Test Item 2",
      "quantity":"2",
      "unitPrice":"200000",
      "discount" :"0",
      "wto":""
    }
  ],
  "invoiceDate":"2017-02-27",
  "dueDate":"2017-02-28",
  "paymentDate":"",
  "sspDate":"",
  "invoiceType":"A",
  "transactionType":"5",
  "transactionDetail":"1",
  "documentType":"1",
  "npwp":"01.000.521.8-093.010",
  "vendor":"PT Dreamland",
  "documentNumber":"010.000-17.00000004",
  "serialNumber":"",
  "additionalDocument":"",
  "masaPajak":"02",
  "tahunPajak":"2017",
  "revision":0,
  "vendorAddress":"Jalan Albann",
  "vendorCity":"Jakarta Selatan",
  "vendorPostCode":"12110",
  "vendorCountry":"ID",
  "vatRate":10,
  "additionalInformation":"Some blabla",
  "additionalInfoID":""
}

Request (For export (sale) of goods/services)

{
  "invoiceNumber":"my-invoice-1234",
  "invoiceItems":[
    {
      "description":"Test Item 1",
      "quantity":"2",
      "unitPrice":"100000",
      "discount":"0",
      "wto":""
    },
    {
      "description":"Test Item 2",
      "quantity":"2",
      "unitPrice":"200000",
      "discount":"50000",
      "wto":""
    }
  ],
  "invoiceDate":"2017-02-27",
  "dueDate":"2017-02-28",
  "paymentDate":"",
  "sspDate":"",
  "invoiceType":"A",
  "transactionType":"4",
  "transactionDetail":"10",
  "documentType":"1",
  "npwp":"00.000.000.0-000.000",
  "vendor":"PT Dreamland",
  "documentNumber":"010.000-17.00000004",
  "serialNumber":"",
  "additionalDocument":"",
  "masaPajak":"06",
  "tahunPajak":"2017",
  "revision":0,
  "vendorAddress":"Rue de la Gare",
  "vendorCity":"Paris",
  "vendorPostCode":"75000",
  "vendorCountry":"FR",
  "vatRate":10,
  "additionalInformation":"Blabla",
  "additionalInfoID":""
}

Request (for import of goods/services):

{
  "invoiceNumber":"my-invoice-1234",
  "invoiceItems":[
    {
      "description":"Test Item 1",
      "quantity":"2",
      "unitPrice":"100000",
      "discount" : "0",
      "wto":""
    },
    {
      "description":"Test Item 2",
      "quantity":"2",
      "unitPrice":"200000",
      "discount" : "0",
      "wto":""
    }
  ],
  "invoiceDate":"2017-02-27",
  "dueDate":"2017-02-28",
  "paymentDate":"",
  "sspDate":"",
  "invoiceType":"B",
  "transactionType":"1",
  "transactionDetail":"10",
  "documentType":"2",
  "npwp":"00.000.000.0-000.000",
  "vendor":"PT Dreamland",
  "documentNumber":"010.000-17.00000004",
  "serialNumber":"",
  "additionalDocument":"",
  "masaPajak":"06",
  "tahunPajak":"2017",
  "revision":0,
  "vendorAddress":"Rue de la Gare",
  "vendorCity":"Paris",
  "vendorPostCode":"75000",
  "vendorCountry":"FR",
  "vatRate":10,
  "additionalInformation":"Blabla",
  "additionalInfoID":""
}

Request With old_id

  {
    "invoiceNumber":"010.018-17.73071222",
    "invoiceItems":[{"description":"DMA-0000010 Digital Maintenance - May 2017","quantity":"1","unitPrice":24000000,"total":24000000}],
    "invoiceDate":"2017-05-31",
    "dueDate":"2017-031",
    "paymentDate":"",
    "sspDate":"",
    "invoiceType":"A",
    "transactionType":"5",
    "transactionDetail":"1",
    "documentType":"1",
    "npwp":"02.115.615.2-056.000",
    "vendor":"PT. Verbus Indonesia",
    "documentNumber":"010.018-17.74071222",
    "serialNumber":"",
    "additionalDocument":"",
    "masaPajak":"05",
    "tahunPajak":"2017",
    "revision":0,
    "vendorAddress":"adada",
    "vendorCity":"Bangli",
    "vendorPostCode":"1231",
    "vendorCountry":"ID",
    "vatRate":10,
    "additionalInformation":null,
    "additionalInfoID":"",
    "old_id":10205,
    "source":null,
    "src":"1",
    "client_ref_id":null
}

Response

{
  "code": 200,
  "message": "Invoice entity has been succesfully created!",
  "response": {
    "invoice": {
      "invoiceId": 1389133,
      "invoiceDate": "2017-02-27",
      "invoiceDueDate": "2017-02-28",
      "grossAmount": 600000,
      "grandTotal": 660000,
      "revision": 0,
      "taxPeriod": "02/2017"

}

Request Parameters Required

No Input Params Type Mandatory Remarks
1 invoiceNumber String (255) YES Commercial invoice number (e.g. FP/2015/03/0000235)
2 invoiceItems string YES Array of invoice items (description, quantity, unitPrice, WTO, discount). The discount means total discount for the item, example: if the unit price is 50000, quantity is 4 and then discount 30000, the total would be 170000.
3 invoiceDate string YES Invoice date, in yyyy-mm-dd format
4 dueDate string YES Invoice due date, in yyyy-mm-dd format
5 paymentDate string NO Invoice payment date, in yyyy-mm-dd format
6 sspDate string NO Surat Setoran Pajak date, in yyyy-mm-dd format (Only in some vat combination)
7 invoiceType string YES Invoice Type (A or B). A : Sales, B: Purchase
8 transactionType string YES Transaction Type: 1. For Invoice Type B : “1”, “2” or “3” 2. For Invoice Type A : “4” or “5”
9 transactionDetail string YES Transaction Detail (OnlinePajak second option VAT Combination Number, refer to app.online-pajak.com)
10 documentType string NO Tax Document Type available are: 1 - Normal, 2 - PIB dan SSP, 3 - Surat Setoran Pajak, 5 - Dokumen yang Dipersamakan dengan Faktur Pajak, 8 - Pemberitahuan impor barang (PIB)
11 npwp string YES NPWP (tax ID) of the transaction counterpart. For Invoice type A (Sales), this is the ‘Customer” NPWP while in the case of invoice type B (Purchase), this is the “Supplier” NPWP. The NPWP number formatting is 15 digits, with correct format (e.g. 03.133.868.4-012.000).
12 vendor string YES Vendor name (case sensitive) is the name of the transaction counterpart : customer or supplier (for example “PT Contoh”). The vendor name must perfectly match with user’s Vendor List
13 documentNumber string YES Tax invoice number from tax office / nomor faktur pajak (e.g. 010.002-15.71117182) Nomor Seri Faktur Pajak: XXX-XX.XXXXXXXX * 3 digit adalah Kode Cabang. * 2 digit adalah Tahun Penerbitan. * 8 digit adalah Nomor Urut.
14 serialNumber string NO (Only for credit note)
15 additionalDocument string NO Additional document type, only for credit note, replacement invoice, and cancellation invoice
16 masaPajak string YES Tax period month ‘mm’ format
17 tahunPajak string YES Tax period year ‘yyyy’ format
18 revision integer YES Tax revision number, single digit
19 vendorAddress string\NO Optional, vendor address
20 vendorCity string NO Optional, vendor city
21 vendorPostCode string NO Optional, vendor postal code
22 vendorRegion string NO Optional, vendor region (e.g. DKI Jakarta, Jawa Barat, etc)
23 vendorCountry string NO Optional, vendor country in 2 digits alphabet (e.g. FR, ID, AO, etc.)
24 vendorPhone string NO Optional, vendor phone number
25 vendorEmail string NO Optional, vendor email
26 vatRate string YES Tax VAT rate that will be used in tax calculation
27 additionalInformation string NO Additional information for efaktur reference field
28 additionalInfoID string NO Additional information for combination 5-7-x and 5-8-x, only required if the combination match the following
29 imported string NO Source invoice import
30 old_id string NO Enter the id of a draft created previously, to update the information. If you leave empty, it will create a duplicate, if the draft with the same tax invoice number already exists

Function: To create an invoice, perform a HTTP POST with the required parameters (below) in the body as JSON.

Staging URL : http://api.staging-achilles.systems/marketplace/v1/invoices?api_key=ABCD&user_id=XY

Live URL:

To learn how to get an API key and obtain a User_id, please refer to our document here

Get Invoice Data

Request:


  {
    "invoiceNumber":"my-invoice-1234",
  }

Response:


  {
    "code": 200,
    "message": "Invoice entity has been succesfully created!",
    "response": {
      "invoice": {
        "invoiceId": 1389133,
        "invoiceDate": "2017-02-27",
        "invoiceDueDate": "2017-02-28",
        "grossAmount": 600000,
        "grandTotal": 660000,
        "revision": 0,
        "taxPeriod": "02/2017"
      }
    }
  }

Function: To get invoice data, perform a HTTP GET with the required parameters (below) in the body as JSON.

Staging URL : http://api.staging-achilles.systems/marketplace/v1/invoices?api_key=ABCD&user_id=XY

Live URL:

To learn how to get an API key and obtain a User ID, please refer to our document here

Request Parameters Required

No Input Params Type Mandatory Remarks
1 invoiceNumber String (255) YES Commercial invoice number (e.g. FP/2015/03/0000235)

Additional

If you have any question or trouble using our API, please send an email directly to invoice.team@online-pajak.com or support@online-pajak.com.