# Getting started

> Sumber: https://www.sipajak.com/developers/getting-started
> Dokumentasi API Sipajak · Versi 1.8 · Modul Memulai
> Ditulis oleh Tim Pajak Sipajak · Diperbarui 29 Desember 2025
> Publisher: Sipajak (PT Hexa Sarana Intermedia), PJAP resmi yang terdaftar dan diawasi DJP.

Mulai integrasi dengan Sipajak API dalam hitungan menit: kenali environment staging dan production, cara autentikasi HTTP Basic, header npwp wajib, dan aturan versioning URL. Kredensial API diberikan oleh tim Sipajak, ajukan lewat tombol Minta Akses API.

## 2.1 Base URLs

The API is available in two environments:

| Environment | Base URL | Notes |
| --- | --- | --- |
| Production | https://gateway-integration.sipajak.com | Live DJP integration |
| Staging | https://staging-gateway-integration.sipajak.com | Mirrors production surface; integrates with DJP non-production |

Staging is the only environment available for integration testing. Do not run automated tests against production.

## 2.2 Authentication

The API uses HTTP Basic Authentication at the transport layer. Credentials (username and password) are issued privately by the Sipajak team after your access request is approved — there is no self-service signup and no credential is published in this documentation or in any public Postman workspace. To get credentials, use the **Minta Akses API** button; staging credentials come first, production credentials after your staging integration is verified. Credentials are long-lived and not rotated automatically; store them in a secret manager and rotate them yourself if your security policy requires it.

```
Authorization: Basic base64(username:password)
```

A single credential pair can serve multiple NPWPs belonging to the same client. The active NPWP for each request is selected via the npwp header (see next section). New NPWPs must be registered against the credential before they can be used, by calling POST /v1/organization (covered in a later revision).

## 2.3 The npwp header

Every request must include the npwp header naming the organisation the call is acting on behalf of.

```
npwp: 1234567890123000
```

Requests without this header, or with an NPWP not registered to the authenticated credential, will be rejected with HTTP 403.

## 2.4 URL versioning

Paths are prefixed with a version segment (/v1/, /v2/). Versions coexist; clients may mix them in the same session. Newer endpoints generally live under /v2/. Each endpoint reference in this document states its version explicitly.

## Pertanyaan umum

### Bagaimana cara mendapatkan kredensial API?

Ajukan lewat tombol Minta Akses API. Tidak ada pendaftaran mandiri: kredensial staging diberikan lebih dulu, kredensial production setelah integrasi staging kamu terverifikasi.

### Environment mana yang dipakai untuk pengujian?

Staging (`https://staging-gateway-integration.sipajak.com`) adalah satu-satunya environment untuk integration testing. Jangan jalankan automated test di production.

### Apa fungsi header npwp?

Setiap request wajib menyertakan header `npwp` yang menyebut organisasi yang diwakili. Request tanpa header ini, atau dengan NPWP yang belum terdaftar pada kredensial kamu, ditolak dengan HTTP 403.

### Apakah satu kredensial bisa dipakai untuk beberapa NPWP?

Bisa, untuk NPWP milik klien yang sama. NPWP baru harus didaftarkan dulu ke kredensial lewat `POST /v1/organization`.

### Bolehkah memakai endpoint /v1/ dan /v2/ bersamaan?

Boleh. Kedua versi berjalan berdampingan dan bisa dicampur dalam satu sesi; endpoint yang lebih baru umumnya ada di `/v2/`.

---
Akses API: minta kredensial staging lewat https://www.sipajak.com/developers (tombol "Minta Akses API"). Semua modul: https://www.sipajak.com/developers.md · Peta konten: https://www.sipajak.com/sitemap.md
