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

9.0 KiB
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)

{
  "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

Contact Information

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

Reference in New Issue View Git Blame Copy Permalink