> For the complete documentation index, see [llms.txt](https://payana-saas.gitbook.io/payana-saas-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://payana-saas.gitbook.io/payana-saas-docs/dokumentasi-teknis/referensi-api-backend.md).

# Referensi API Backend

Base URL: `NEXT_PUBLIC_BACKEND_URL` (lihat [Variabel Lingkungan](/payana-saas-docs/dokumentasi-teknis/variabel-lingkungan.md)). Dokumentasi interaktif (Swagger) juga tersedia langsung dari server yang berjalan, di endpoint `/api-docs`.

Kecuali disebutkan "publik", semua endpoint memerlukan header `Authorization: Bearer <access_token>` (lihat [Auth](#auth)).

## Auth

| Method         | Path                                | Akses  | Kegunaan                                                         |
| -------------- | ----------------------------------- | ------ | ---------------------------------------------------------------- |
| `POST`         | `/auth/login`                       | Publik | Login dengan signature EIP-191, terbitkan access + refresh token |
| `POST`         | `/auth/refresh`                     | Publik | Perbarui access token pakai refresh token                        |
| `POST`         | `/auth/logout`                      | Auth   | Hapus sesi                                                       |
| `POST` / `GET` | `/auth/profile`                     | Auth   | Set / ambil profil (nama, NIK, telepon — terenkripsi)            |
| `GET`          | `/auth/profile/by-address/:address` | Auth   | Ambil profil berdasarkan alamat                                  |

## Registration (pendaftaran perusahaan & karyawan)

| Method   | Path                                  | Akses  | Kegunaan                                      |
| -------- | ------------------------------------- | ------ | --------------------------------------------- |
| `POST`   | `/registration/request`               | Publik | Ajukan pendaftaran (perusahaan atau karyawan) |
| `GET`    | `/registration/status/:address`       | Publik | Cek status pendaftaran                        |
| `GET`    | `/registration/pending`               | Owner  | Daftar semua pendaftaran perusahaan menunggu  |
| `GET`    | `/registration/pending/hr/:hrAddress` | Auth   | Pendaftaran karyawan menunggu untuk satu HR   |
| `GET`    | `/registration/:address`              | Auth   | Detail satu pendaftaran                       |
| `PATCH`  | `/registration/:address/approve`      | Auth   | Setujui pendaftaran                           |
| `DELETE` | `/registration/:address`              | Auth   | Tolak/hapus pendaftaran                       |

## Invitations (undangan karyawan)

| Method  | Path                         | Akses  | Kegunaan                                     |
| ------- | ---------------------------- | ------ | -------------------------------------------- |
| `POST`  | `/invitations`               | Auth   | HR membuat undangan baru                     |
| `GET`   | `/invitations/:token`        | Publik | Lookup undangan (dipakai halaman onboarding) |
| `GET`   | `/invitations/hr/:hrAddress` | Auth   | Daftar undangan yang dibuat satu HR          |
| `PATCH` | `/invitations/:token/revoke` | Auth   | Cabut undangan                               |

## Kasbon (Gen8)

| Method | Path                        | Akses | Kegunaan                        |
| ------ | --------------------------- | ----- | ------------------------------- |
| `POST` | `/kasbon/request`           | Auth  | Karyawan mengajukan kasbon      |
| `GET`  | `/kasbon/status`            | Auth  | Status kasbon karyawan saat ini |
| `GET`  | `/kasbon/pending`           | Auth  | Daftar pengajuan menunggu (HR)  |
| `GET`  | `/kasbon/history/:employee` | Auth  | Riwayat kasbon satu karyawan    |
| `POST` | `/kasbon/approve/:employee` | Auth  | HR menyetujui pengajuan         |
| `POST` | `/kasbon/reject/:employee`  | Auth  | HR menolak pengajuan            |

## Bounty & Tip

| Method  | Path                                     | Akses | Kegunaan                        |
| ------- | ---------------------------------------- | ----- | ------------------------------- |
| `POST`  | `/bounty`                                | Auth  | Buat bounty baru                |
| `GET`   | `/bounty/hr/:hrAddress`                  | Auth  | Daftar bounty satu perusahaan   |
| `PATCH` | `/bounty/:id/close`                      | Auth  | Tutup bounty                    |
| `POST`  | `/bounty/:id/claim`                      | Auth  | Klaim bounty                    |
| `GET`   | `/bounty/:id/claims`                     | Auth  | Daftar klaim untuk satu bounty  |
| `GET`   | `/bounty/claims/me`                      | Auth  | Klaim milik karyawan yang login |
| `PATCH` | `/bounty/claim/:id/approve` \| `/reject` | Auth  | HR meninjau klaim               |
| `PATCH` | `/bounty/claim/:id/paid`                 | Auth  | Tandai klaim sudah dibayar      |
| `POST`  | `/bounty/tip`                            | Auth  | Kirim tip ke rekan kerja        |
| `GET`   | `/bounty/tips/:address`                  | Auth  | Riwayat tip satu alamat         |

## Reimburse

| Method  | Path                                  | Akses | Kegunaan                          |
| ------- | ------------------------------------- | ----- | --------------------------------- |
| `POST`  | `/reimburse`                          | Auth  | Ajukan klaim reimbursement        |
| `GET`   | `/reimburse/me`                       | Auth  | Klaim milik karyawan yang login   |
| `GET`   | `/reimburse/hr/:hrAddress`            | Auth  | Semua klaim untuk satu perusahaan |
| `PATCH` | `/reimburse/:id/approve` \| `/reject` | Auth  | HR meninjau klaim                 |

## Compliance

| Method         | Path                             | Akses | Kegunaan                                    |
| -------------- | -------------------------------- | ----- | ------------------------------------------- |
| `GET`          | `/compliance/summary/:hr`        | Auth  | Ringkasan potongan bulan berjalan           |
| `GET`          | `/compliance/export/:hr`         | Auth  | Ekspor CSV                                  |
| `GET`          | `/compliance/export-excel/:hr`   | Auth  | Ekspor Excel (template resmi)               |
| `GET` / `POST` | `/compliance/reconciliation/:hr` | Auth  | Lihat / catat rekonsiliasi pembayaran nyata |

## Termination (PHK)

| Method | Path                                   | Akses | Kegunaan                                  |
| ------ | -------------------------------------- | ----- | ----------------------------------------- |
| `POST` | `/termination/reason`                  | Auth  | Simpan alasan PHK (terenkripsi off-chain) |
| `GET`  | `/termination/reason/:employeeAddress` | Auth  | Ambil alasan PHK                          |
| `GET`  | `/termination/letter/:employeeAddress` | Auth  | Generate Surat Keputusan PHK (PDF)        |

## Dokumen (Payslip, Tax Cert, Employment Letter)

| Method  | Path                                          | Akses | Kegunaan                                      |
| ------- | --------------------------------------------- | ----- | --------------------------------------------- |
| `GET`   | `/payslip/:claimId`                           | Auth  | Data slip gaji satu klaim                     |
| `GET`   | `/tax-cert/:year`                             | Auth  | Bukti potong pajak tahunan (karyawan sendiri) |
| `GET`   | `/tax-cert/hr/:employee/:year`                | Auth  | Bukti potong pajak (dilihat HR)               |
| `POST`  | `/employment-letter/request`                  | Auth  | Ajukan surat keterangan kerja                 |
| `GET`   | `/employment-letter/me` \| `/hr`              | Auth  | Daftar pengajuan (karyawan / HR)              |
| `PATCH` | `/employment-letter/:id/approve` \| `/reject` | Auth  | HR meninjau pengajuan                         |
| `GET`   | `/employment-letter/:id/document`             | Auth  | Unduh dokumen PDF                             |

## Lainnya

| Method                    | Path                                     | Akses                | Kegunaan                                                                             |
| ------------------------- | ---------------------------------------- | -------------------- | ------------------------------------------------------------------------------------ |
| `GET`                     | `/directory/me` \| `/:hrAddress`         | Auth                 | Direktori karyawan                                                                   |
| `PATCH`                   | `/directory/:address`                    | Auth                 | Update entri direktori                                                               |
| `GET` / `PUT`             | `/company-settings`                      | Auth                 | Profil & konfigurasi perusahaan                                                      |
| `GET`                     | `/notifications`                         | Auth                 | Daftar notifikasi                                                                    |
| `PATCH`                   | `/notifications/:id/read` \| `/read-all` | Auth                 | Tandai sudah dibaca                                                                  |
| `POST`                    | `/transfer`                              | Auth                 | Catat transfer off-chain (mirror, karena Ponder tidak mengindeks `Transfer` generik) |
| `GET`                     | `/transfer/me`                           | Auth                 | Riwayat transfer                                                                     |
| `POST`                    | `/bundler/relay`                         | Auth                 | Relay UserOperation ERC-4337 ke bundler                                              |
| `GET`                     | `/bundler/status/:userOpHash`            | Auth                 | Status UserOperation                                                                 |
| `POST`                    | `/webhook/alchemy`                       | Publik (HMAC-signed) | Webhook masuk dari Alchemy                                                           |
| `GET`                     | `/security/alerts`                       | Owner                | Daftar alert keamanan (anomaly detector)                                             |
| `PATCH`                   | `/security/alerts/:id/resolve`           | Owner                | Tandai alert selesai ditangani                                                       |
| `GET` / `POST` / `DELETE` | `/suspension/*`                          | Owner                | Kelola suspensi klien (kasus pelanggaran)                                            |

{% hint style="info" %}
Endpoint `/webhook/alchemy` diverifikasi lewat HMAC (`ALCHEMY_WEBHOOK_KEY`), bukan JWT — ini satu-satunya jalur masuk yang sengaja publik tapi tetap terverifikasi secara kriptografis, bukan tanpa proteksi sama sekali.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://payana-saas.gitbook.io/payana-saas-docs/dokumentasi-teknis/referensi-api-backend.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.