# SoluTax Bruno API Collection - Agents Documentation

## Project Overview

This is a **Bruno API collection** for testing and interacting with the **SoluTax IFS WIT API** developed by PT Sarana Prima Telematika. The collection provides integration capabilities with Indonesia's tax system (DJP - Direktorat Jenderal Pajak) for electronic withholding tax slips (Bukti Potong).

### Purpose

The API collection enables management of electronic tax withholding slips for Indonesian payroll and tax compliance:

- **PPh 21** - Employee income tax withholding (monthly/non-final)
- **PPh A0** - Permanent employee monthly withholding
- **PPh A1** - Permanent employee annual withholding

### Technologies Used

- **Bruno** - Git-friendly, offline-first API client
- **Bru** - Plain text markup language for API requests
- **Node.js** - Minimal project structure (package-lock.json present)

---

## Project Structure

```
solutax/
├── bruno.json                    # Bruno collection configuration
├── agents.md                     # This file - AI agent documentation
├── QWEN.md                       # Project overview and context
├── spesifikasi.md                 # Full API specification document (Indonesian)
├── token.bru                     # Authentication token request
├── ppha0-new.bru                 # PPh A0 - Pengesahan (Create)
├── ppha0-edit.bru               # PPh A0 - Penggantian (Replace)
├── ppha0-cancel.bru             # PPh A0 - Pembatalan (Cancel)
├── ppha0-status.bru             # PPh A0 - Periksa Status (Check)
├── ppha0-pdf.bru                # PPh A0 - Unduh PDF (Download)
├── test.bru                      # Test request file
├── package-lock.json             # Node.js lock file
├── environments/
│   ├── solutax.bru              # Development environment variables
│   └── solutax.json             # Environment configuration
└── sample result/
    ├── ppha0_new_result_sample.json
    └── token_result_sample.json
```

---

## API Endpoints Summary

### 1. Token Authentication

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/auth/gettoken` | POST | Get JWT access token using Basic Auth |

**Security**: Basic Authentication (username/password)

### 2. PPh 21 Withholding Slips (Monthly/Non-Final)

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/ifs/api/wit/bulanan/new` | POST | Create and approve new PPh 21 slip |
| `/ifs/api/wit/bulanan/edit` | POST | Replace/modify existing PPh 21 slip |
| `/ifs/api/wit/cancel` | POST | Cancel a PPh 21 slip |
| `/ifs/api/wit/status` | POST | Check status of PPh 21 slip |
| `/ifs/api/wit/pdf` | POST | Download PDF of PPh 21 slip |

### 3. PPh A0 Withholding Slips (Permanent Employee Monthly)

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/ifs/api/wit/bulanan/new` | POST | Create and approve new PPh A0 slip |
| `/ifs/api/wit/bulanan/edit` | POST | Replace/modify existing PPh A0 slip |
| `/ifs/api/wit/cancel` | POST | Cancel a PPh A0 slip |
| `/ifs/api/wit/status` | POST | Check status of PPh A0 slip |
| `/ifs/api/wit/pdf` | POST | Download PDF of PPh A0 slip |

### 4. PPh A1 Withholding Slips (Permanent Employee Annual)

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/ifs/api/wit/tahunan/new` | POST | Create and approve new PPh A1 slip |
| `/ifs/api/wit/tahunan/edit` | POST | Replace/modify existing PPh A1 slip |
| `/ifs/api/wit/cancel` | POST | Cancel a PPh A1 slip |
| `/ifs/api/wit/status` | POST | Check status of PPh A1 slip |
| `/ifs/api/wit/pdf` | POST | Download PDF of PPh A1 slip |

---

## Agent Workflows

### Workflow 1: Authentication and Token Management

**Goal**: Obtain and manage access tokens for API requests

1. **Get Token**
   - Execute `token.bru`
   - Uses Basic Auth with credentials from `auth:basic` block
   - Response contains `access_token`, `idpel`, and `expires_in`
   - Token automatically set as `accessToken` environment variable
   - Customer ID set as `idpel` environment variable

### Workflow 2: Create New Tax Slip (PPh A0 Example)

**Goal**: Create and approve a new withholding tax slip

1. **Execute ppha0-new.bru**
   - Generates new UUID for `requestID`
   - Sends monthly income data with taxpayer information
   - Includes `dataBpA0` object with tax calculation details
   - Response extracts and stores `nomorBupot` and `idBupot`

### Workflow 3: Replace/Modify Existing Slip

**Goal**: Update an existing approved tax slip

1. **Execute ppha0-edit.bru**
   - Requires existing `nomorBupot` and `idBupot`
   - Sends updated data with all required fields
   - New approval number assigned upon success

### Workflow 4: Cancel Tax Slip

**Goal**: Cancel an approved tax slip

1. **Execute ppha0-cancel.bru**
   - Generates new UUID for `requestID`
   - Requires `nomorBupot` and `idBupot` to cancel
   - Includes `tglPembatalan` (cancellation date)
   - Requires electronic signature credentials

### Workflow 5: Check Slip Status

**Goal**: Verify status of a tax slip (after create, edit, or cancel)

1. **Execute ppha0-status.bru**
   - Queries `taxSlipVerification` object
   - Returns status: `NORMAL-DONE`, `AMENDED`, or `CANCELLED-Done`
   - Includes verification timestamp

### Workflow 6: Download PDF

**Goal**: Retrieve PDF document of approved tax slip

1. **Execute ppha0-pdf.bru**
   - Requires `nomorBupot` and `idBupot`
   - Response contains `data` field with Base64-encoded PDF
   - File name typically matches `nomorBuktiPotong`

---

## Key Concepts

### Request Structure

All requests follow a consistent pattern:

| Field | Type | Description |
|-------|------|-------------|
| `idPel` | Number | Customer ID (extracted from token response) |
| `requestID` | String (GUID) | Unique request identifier (auto-generated) |
| `monthlyIncome` / `yearlyIncome` / `taxSlip*` | Object | Endpoint-specific data payload |

### Response Structure

All responses follow a consistent pattern:

| Field | Description |
|-------|-------------|
| `kodestatus` / `statusCode` | HTTP status code (200 = success) |
| `keterangan` / `statusMessage` | Status description |
| `data` / `result` / `taxSlipResponse` | Response payload |
| `idPel` / `responseID` | Tracking identifiers |

### Common Status Codes

| Code | Meaning |
|------|---------|
| 200 | Success |
| 401 | Unauthorized (invalid/expired token) |
| 500 | Server error (e.g., invalid User ID) |

### Slip Status Values

| Status | Meaning |
|--------|---------|
| `NORMAL-DONE` | Original slip approved |
| `AMENDED` | Slip was replaced/modified |
| `CANCELLED-Done` | Slip was cancelled |

---

## Environment Variables

The following environment variables are used:

| Variable | Description | Source |
|----------|-------------|--------|
| `accessToken` | JWT authentication token | Token response |
| `idpel` | Customer ID | Token response |
| `requestID` | Unique request GUID | Auto-generated or env |
| `nomorBupot` | Tax slip number | New/Edit response |
| `idBupot` | Tax slip ID (UUID) | New/Edit response |

---

## Configuration

### Bruno Collection Config (`bruno.json`)

```json
{
  "version": "1",
  "name": "solutax",
  "type": "collection",
  "ignore": ["node_modules", ".git", "QWEN.md", "spesifikasi.md"]
}
```

### API Base URL

```
https://ifswit-solutax-ctas-dev.spt.co.id
```

**Note**: This is the development/ctas-dev environment.

---

## Testing Workflow

### Step-by-Step Process

1. **Get Token**
   - Execute `token.bru` first
   - Verify `accessToken` is set in environment

2. **Create Slip**
   - Execute `ppha0-new.bru`
   - Note the `nomorBupot` and `idBupot` from response

3. **Verify Status**
   - Execute `ppha0-status.bru`
   - Confirm `statusBupot` is `NORMAL-DONE`

4. **Download PDF** (optional)
   - Execute `ppha0-pdf.bru`
   - Decode Base64 data to PDF file

5. **Modify Slip** (if needed)
   - Execute `ppha0-edit.bru`
   - Verify new `nomorBupot` assigned

6. **Cancel Slip** (if needed)
   - Execute `ppha0-cancel.bru`
   - Verify `statusBupot` becomes `CANCELLED-Done`

---

## Important Notes

1. **Language**: All API documentation and field names are in Indonesian (Bahasa Indonesia)

2. **Environment**: This is a development/DEV environment (CTAS-DEV)

3. **Token Expiration**: Monitor `expires_in` field; tokens will expire and require renewal

4. **NPWP Validation**: Tax ID numbers (NPWP) are validated on all endpoints

5. **Electronic Signature**: Passphrase required for penandatangan (signatory) on create/edit/cancel operations

6. **Pre-request Scripts**: Some files auto-generate UUIDs for `requestID` using JavaScript

7. **Post-response Scripts**: Some files extract and store response values as environment variables

---

## Documentation References

- [spesifikasi.md](./spesifikasi.md) - Complete API specification (Indonesian)
- [QWEN.md](./QWEN.md) - Project overview and context
- [Official Bruno Docs](https://docs.usebruno.com/)
- [SoluTax API Specification](https://ifswit-solutax-ctas-dev.spt.co.id) - API base URL

---

## Contact Information

**Developer**: PT Sarana Prima Telematika  
**Year**: 2026  
**Version**: 1.0