Halaman ini akan membantu Anda memulai dengan API Job Offer Single Submission (JOSS).Setelah membaca dokumen ini beserta sub-dokumennya, Anda akan memahami cara untuk:Menghasilkan signature sebagai metode autentikasi
Mengintegrasikan aplikasi Anda dengan API JOSS
Prasyarat#
Untuk menggunakan informasi dalam dokumen ini, Anda perlu mengetahui hal-hal berikut:Cara kerja API RESTful, bagaimana cara memanggilnya, dan cara menginterpretasi responsnya.
Pengetahuan dasar tentang cara kerja autentikasi API.
Detail Latar Belakang Umum#
Bagian ini mencakup aspek umum untuk semua API JOSS.Endpoint API#
Karena API JOSS bersifat RESTful, pengguna mengirim permintaan HTTPS ke alamat URL untuk memanggil perintah. API JOSS memiliki dua endpoint (awalan alamat umum untuk URL perintah), satu untuk panggilan staging dan satu lagi untuk panggilan production. Anda juga menggunakan signature yang berbeda untuk mengautentikasi permintaan staging dan production, yang akan dibahas di bagian Signature.Staging: <https://sandbox.joss.kemnaker.go.id>
Production: <https://joss.kemnaker.go.id>
Semua permintaan API JOSS harus menggunakan HTTPS. Permintaan HTTP akan diarahkan secara paksa ke HTTPS.
| Http Header | Required |
|---|
| Accept | Saat ini hanya mendukung application/json dan application/xml |
| Content-Type | Header ini dibutuhkan saat menggunakan metode POST, PATCH, PUT. Saat ini hanya mendukung application/json |
| Client-Id | Client ID yang diperoleh dari Kementerian Ketenagakerjaan Republik Indonesia |
| Request-Id | String acak yang unik yang dihasilkan dari sisi klien untuk melindungi dari permintaan duplikat |
| Request-Timestamp | Timestamp permintaan dalam format UTC ISO8601 UTC+0. Artinya untuk memproses transaksi pada UTC+7 (WIB), klien perlu mengurangi waktu dengan 7. Misalnya: untuk memproses transaksi pada 22 September 2022 pukul 08:51:00 WIB, timestamp yang harus digunakan adalah 2022-09-22T01:51:00Z |
| Signature | Parameter keamanan yang perlu dihasilkan di Backend klien dan diletakkan di header permintaan untuk memastikan bahwa permintaan berasal dari klien yang valid |
Silakan merujuk ke bagian Autentikasi untuk menghasilkan signature. Kode Respons HTTP#
| Status Code | Reason |
|---|
| 200 OK | Ketika permintaan sesuai dengan yang diharapkan |
| 201 Created | Ketika permintaan sesuai dengan yang diharapkan |
| 400 Bad Request | Terjadi kesalahan logika |
| 401 Unauthorized | Signature tidak valid atau signature yang diberikan sudah kedaluwarsa |
| 403 Forbidden | Akses token tidak memiliki izin untuk memproses permintaan |
| 404 Not Found | Sumber daya yang ditentukan tidak ditemukan |
| 422 Unprocessable Entity | Terjadi kesalahan validasi |
| 429 Too Many Requests | Terlalu banyak permintaan ke server |
| 500 Internal Server Error | Terjadi kesalahan sistem atau aplikasi. Meskipun permintaan klien terlihat benar, ada yang tidak terduga di server. Anda dapat mencoba permintaan kembali dalam kasus ini |
| 503 Service Unavailable | Server tidak dapat menangani permintaan karena pemeliharaan sementara. Anda bisa mencoba lagi sedikit lebih lama |
| 504 Gateway Timeout | Server tidak dapat menangani permintaan karena pemrosesan data yang terlalu banyak. Anda bisa mencoba lagi sedikit lebih lama atau mempersingkat interval waktu dalam kasus ini |
HTTP Response Codes#
| Status Code | Reason |
|---|
| 200 OK | The request was successful and processed as expected |
| 201 Created | The request was successful and a new resource was created |
| 400 Bad Request | A logical error occurred in the request |
| 401 Unauthorized | The signature is invalid or has expired |
| 403 Forbidden | The access token does not have permission to process the request |
| 404 Not Found | The specified resource could not be found |
| 422 Unprocessable Entity | A validation error occurred |
| 429 Too Many Requests | Too many requests were sent to the server |
| 500 Internal Server Error | A system or application error occurred. Although the client request appears valid, something unexpected happened on the server. You may retry the request |
| 503 Service Unavailable | The server is unable to handle the request due to temporary maintenance. Please try again later |
| 504 Gateway Timeout | The server could not process the request due to heavy processing load. Please try again later or reduce the request time range |
Semua permintaan kecuali metode GET harus diidentifikasi secara unik dengan header Request-Id. Request-Id yang duplikat akan mengembalikan status http 409 Conflict.
