suwandy/solutax_api
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
solutax_api/agents.md
swtmath 81404db98c init
2026-03-04 13:40:32 +07:00

293 lines
9.0 KiB
Markdown
Raw Permalink Blame History

# 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
Reference in New Issue View Git Blame Copy Permalink