# Technical Specification: Coretax Bridge Microservice (Indonesia 2026)

## 1. System Overview
Build a high-performance PHP-based microservice acting as a middleware between a Core ERP and the Indonesian DJP Coretax System. The service must handle digital signing, tax logic for complex industries, and asynchronous processing for high-volume transactions.

## 2. Technical Stack Requirements
- **Language**: PHP 8.2+ (Typed)
- **Database**: MySQL/MariaDB (for logs and idempotency)
- **Cache/Queue**: Redis (for background jobs and rate limiting)
- **Security**: OpenSSL for P12 certificate handling.

## 3. Database Schema (Core Tables)
Generate migrations for:
- `tax_configs`: Store NITKU, P12 certificates (encrypted), and industry-specific flags.
- `tax_idempotency`: Track `request_hash` (unique_key) to prevent double filing.
- `tax_transactions`: Main log for all tax filings (Request, Response, Status, QR_URL).
- `tax_queue`: Managed by Redis for asynchronous retries.

## 4. Industry-Specific Business Logic (The Complex Modules)

### A. Retail Module (FMCG & Chain Stores)
- **Target**: 1,000+ Outlets.
- **Complexity**: NITKU Mapping & VAT Centralization.
- **Logic**:
    - Automatic detection of "Pemusatan PPN" status.
    - If Centralized: Internal transfers generate 0% VAT journals but must be logged for "Laporan Mutasi Barang".
    - If Decentralized: Automatically generate Tax Invoices (Faktur Pajak) for every inter-branch move.
    - High-concurrency handler for peak sale hours (07.00 - 10.00).

### B. Manufacturing Module (Kawasan Berikat / Bonded Zone)
- **Target**: Export-oriented factories.
- **Complexity**: PPN 07 (Fasilitas Tidak Dipungut).
- **Logic**:
    - Validation engine for Bea Cukai (BC) Documents (BC 2.3, BC 4.0, BC 2.7).
    - Logic to switch tax codes from 01 (Standard) to 07 (Fasilitas) based on the "Destination Zone" attribute.
    - Automatic attachment of "Keterangan Bebas Pajak" metadata in the Coretax payload.

### C. Construction & Professional Services Module
- **Target**: Project-based companies.
- **Complexity**: Withholding Tax (PPh 23 & PPh 4(2)).
- **Logic**:
    - Multi-tier tax rate calculation (e.g., 2% for NPWP, 4% for Non-NPWP).
    - Logic for "Gross-up" vs "Nett" tax calculations.
    - Automatic generation of "Bukti Potong" (Bupot) for vendors during the payment settlement phase.

## 5. Core Engine Features (The "Builder" Instructions)

### 1. Digital Signature Engine
Implement a class `SignatureService` that:
- Reads `.p12` certificates using `openssl_pkcs12_read`.
- Performs SHA-256 signing on the JSON payload.
- Injects the `X-DJP-Signature` header.

### 2. Idempotency Guard
Implement a middleware that:
- Generates a SHA-1 hash of the incoming request body.
- Rejects duplicate requests within a 24-hour window if status is already 'Success' or 'Processing'.

### 3. Reliability & Retry Logic
- Use **Exponential Backoff**: Retry 1 (30s), Retry 2 (5m), Retry 3 (30m).
- Circuit Breaker: If DJP returns 503 (Service Unavailable) 5 times, stop all outgoing requests for 10 minutes and alert via Webhook.

## 6. API Endpoints to Generate
- `POST /v1/tax/process`: Main entry point for ERP.
- `GET /v1/tax/status/{ref_no}`: Poll status.
- `POST /v1/config/nitku`: Manage branch NITKU data.
- `GET /v1/health`: Check connection to Redis and DJP Sandbox.