# TaxCore Service Configuration Guide

## Overview

This guide explains how to configure the TaxCore service with your VSDC URL, PIN, certificate, and other settings.

## Configuration Files

### For Docker Deployments

**File:** `.env` or `.env.docker` (at project root)

```bash
# ===== TaxCore Service Configuration =====

# Service Port (default: 3001)
TAXCORE_SERVICE_PORT=3001

# TaxCore API URLs
# Tax rates endpoint (usually production API)
TAXCORE_TAX_URL=https://api.sandbox.vms.frcs.org.fj/api

# V-SDC endpoint (your specific instance URL)
TAXCORE_VSDC_URL=http://devesdc.sandbox.vms.frcs.org.fj:8888/20f351f3-9b39-4c63-b9e0-d8a00b6e93fb/api

# Certificate Configuration
# Filename only (file must be in FRCS_Certs_Install/ directory)
TAXCORE_PFX_FILE=LK2VRSH4-DeveloperAuthenticationCertificate.pfx
TAXCORE_PFX_PASSWORD=2CBP6HMW

# PIN for authentication
TAXCORE_PIN_JSON=3840

# Debug Mode (true/false)
TAXCORE_DEBUG=true
```

### For Manual/Development Deployments

**File:** `websocket-server/.env` (create if doesn't exist)

```bash
# TaxCore Service Port
TAXCORE_SERVICE_PORT=3001

# TaxCore API URLs
TAXCORE_TAX_URL=https://api.sandbox.vms.frcs.org.fj/api
TAXCORE_VSDC_URL=http://devesdc.sandbox.vms.frcs.org.fj:8888/20f351f3-9b39-4c63-b9e0-d8a00b6e93fb/api

# Certificate Configuration (full path)
TAXCORE_PFX_PATH=/var/www/html/TAF/FRCS_Certs_Install/LK2VRSH4-DeveloperAuthenticationCertificate.pfx
TAXCORE_PFX_PASSWORD=2CBP6HMW

# PIN for authentication
TAXCORE_PIN_JSON=3840

# Debug Mode
TAXCORE_DEBUG=true
```

## Configuration Parameters Explained

### 1. TAXCORE_SERVICE_PORT
**Default:** `3001`  
**Description:** Port the Node.js TaxCore service listens on  
**Example:** `3001`, `3002`, etc.

```bash
TAXCORE_SERVICE_PORT=3001
```

---

### 2. TAXCORE_TAX_URL
**Default:** `https://api.sandbox.vms.frcs.org.fj/api`  
**Description:** TaxCore Tax Rates API endpoint  
**Used for:** Fetching tax rates via `/v1/tax-rates`

**Sandbox:**
```bash
TAXCORE_TAX_URL=https://api.sandbox.vms.frcs.org.fj/api
```

**Production:**
```bash
TAXCORE_TAX_URL=https://api.vms.frcs.org.fj/api
```

---

### 3. TAXCORE_VSDC_URL ⭐ Important
**Default:** `http://devesdc.sandbox.vms.frcs.org.fj:8888/{YOUR-UUID}/api`  
**Description:** Your specific V-SDC instance endpoint  
**Used for:** Creating invoices via `/v3/invoices`

**Format:**
```
http://{VSDC_HOST}:{PORT}/{YOUR_INSTANCE_UUID}/api
```

**How to get your URL:**
1. Register your business with FRCS
2. Receive your V-SDC instance credentials
3. You'll get a URL like:
   ```
   http://devesdc.sandbox.vms.frcs.org.fj:8888/20f351f3-9b39-4c63-b9e0-d8a00b6e93fb/api
   ```

**Example configurations:**

**Development/Sandbox:**
```bash
TAXCORE_VSDC_URL=http://devesdc.sandbox.vms.frcs.org.fj:8888/YOUR-UUID-HERE/api
```

**Production:**
```bash
TAXCORE_VSDC_URL=https://vsdc.vms.frcs.org.fj/YOUR-UUID-HERE/api
```

---

### 4. TAXCORE_PFX_FILE / TAXCORE_PFX_PATH
**Description:** Path to your PFX/P12 certificate file  
**Used for:** Mutual TLS authentication with TaxCore API

**For Docker (use TAXCORE_PFX_FILE):**
```bash
# Just the filename (file must be in FRCS_Certs_Install/)
TAXCORE_PFX_FILE=LK2VRSH4-DeveloperAuthenticationCertificate.pfx
```

The full path in container will be:
```
/usr/src/app/certs/LK2VRSH4-DeveloperAuthenticationCertificate.pfx
```

**For Manual deployment (use TAXCORE_PFX_PATH):**
```bash
# Full absolute path
TAXCORE_PFX_PATH=/var/www/html/TAF/FRCS_Certs_Install/YOUR-CERTIFICATE.pfx
```

**How to get your certificate:**
1. Register with FRCS
2. Download your authentication certificate (PFX/P12 format)
3. Place in `FRCS_Certs_Install/` directory
4. Update the filename in `.env`

---

### 5. TAXCORE_PFX_PASSWORD
**Description:** Password for your PFX certificate  
**Security:** Keep this secret!

```bash
TAXCORE_PFX_PASSWORD=YOUR_CERTIFICATE_PASSWORD
```

**Example:**
```bash
TAXCORE_PFX_PASSWORD=2CBP6HMW
```

---

### 6. TAXCORE_PIN_JSON
**Description:** PIN for TaxCore API authentication  
**Used for:** Initial authentication with V-SDC

```bash
TAXCORE_PIN_JSON=YOUR_PIN
```

**Example:**
```bash
TAXCORE_PIN_JSON=3840
```

**How to get your PIN:**
1. Provided by FRCS during registration
2. Usually a 4-digit number
3. Required for first-time authentication

---

### 7. TAXCORE_DEBUG
**Default:** `true`  
**Description:** Enable detailed logging  
**Values:** `true` or `false`

**Development:**
```bash
TAXCORE_DEBUG=true
```

**Production:**
```bash
TAXCORE_DEBUG=false
```

## Environment-Specific Configurations

### Development/Testing (Sandbox)

```bash
# .env or .env.docker
TAXCORE_SERVICE_PORT=3001
TAXCORE_TAX_URL=https://api.sandbox.vms.frcs.org.fj/api
TAXCORE_VSDC_URL=http://devesdc.sandbox.vms.frcs.org.fj:8888/YOUR-DEV-UUID/api
TAXCORE_PFX_FILE=DEV-Certificate.pfx
TAXCORE_PFX_PASSWORD=DEV_PASSWORD
TAXCORE_PIN_JSON=1234
TAXCORE_DEBUG=true
```

### Staging

```bash
# .env.staging
TAXCORE_SERVICE_PORT=3001
TAXCORE_TAX_URL=https://api.sandbox.vms.frcs.org.fj/api
TAXCORE_VSDC_URL=http://stagingvsdc.sandbox.vms.frcs.org.fj:8888/YOUR-STAGING-UUID/api
TAXCORE_PFX_FILE=STAGING-Certificate.pfx
TAXCORE_PFX_PASSWORD=STAGING_PASSWORD
TAXCORE_PIN_JSON=5678
TAXCORE_DEBUG=true
```

### Production

```bash
# .env.production
TAXCORE_SERVICE_PORT=3001
TAXCORE_TAX_URL=https://api.vms.frcs.org.fj/api
TAXCORE_VSDC_URL=https://vsdc.vms.frcs.org.fj/YOUR-PROD-UUID/api
TAXCORE_PFX_FILE=PRODUCTION-Certificate.pfx
TAXCORE_PFX_PASSWORD=PROD_PASSWORD
TAXCORE_PIN_JSON=9876
TAXCORE_DEBUG=false
```

## Important: Separate Environment Files

**The TaxCore service uses SEPARATE environment configuration from PHP:**

- **PHP Application:** Uses `/var/www/html/TAF/.env` (parsed by PHP)
- **TaxCore Service (Docker):** Uses `.env` at project root → passed to Docker Compose
- **TaxCore Service (Manual):** Uses `websocket-server/.env` or exports environment variables

**⚠️ DO NOT add TaxCore variables to the PHP `.env` file - they must be separate!**

See `websocket-server/ENVIRONMENT.md` for detailed environment configuration.

---

## Setup Instructions

### Method 1: Docker (Recommended)

1. **Copy environment file:**
   ```bash
   cd /var/www/html/TAF
   cp .env.docker .env
   ```

2. **Edit `.env` with your TaxCore settings ONLY:**
   ```bash
   nano .env
   ```

3. **Update these variables:**
   ```bash
   TAXCORE_VSDC_URL=http://devesdc.sandbox.vms.frcs.org.fj:8888/YOUR-UUID-HERE/api
   TAXCORE_PFX_FILE=YOUR-CERTIFICATE-FILE.pfx
   TAXCORE_PFX_PASSWORD=YOUR-PASSWORD
   TAXCORE_PIN_JSON=YOUR-PIN
   ```
   
   **Note:** This `.env` is ONLY for Docker Compose, not for PHP!

4. **Place certificate:**
   ```bash
   # Copy your certificate to FRCS_Certs_Install/
   cp /path/to/your/certificate.pfx FRCS_Certs_Install/
   
   # Verify it's there
   ls -la FRCS_Certs_Install/*.pfx
   ```

5. **Start services:**
   ```bash
   docker-compose up --build -d
   ```

6. **Verify configuration:**
   ```bash
   # Check TaxCore service logs
   docker-compose logs taxcore-service
   
   # Should see:
   # [TaxCore Service] Service started on port 3001
   # [TaxCore Service] Certificate found at: /usr/src/app/certs/YOUR-CERT.pfx
   # [TaxCore Service] VSDC URL: http://devesdc...YOUR-UUID.../api
   ```

### Method 2: Manual Setup

1. **Create environment file:**
   ```bash
   cd /var/www/html/TAF/websocket-server
   cp ../.env.example .env
   ```

2. **Edit `.env`:**
   ```bash
   nano .env
   ```

3. **Update variables:**
   ```bash
   TAXCORE_VSDC_URL=http://devesdc.sandbox.vms.frcs.org.fj:8888/YOUR-UUID-HERE/api
   TAXCORE_PFX_PATH=/var/www/html/TAF/FRCS_Certs_Install/YOUR-CERT.pfx
   TAXCORE_PFX_PASSWORD=YOUR-PASSWORD
   TAXCORE_PIN_JSON=YOUR-PIN
   ```

4. **Start service:**
   ```bash
   cd /var/www/html/TAF/websocket-server
   npm run taxcore
   ```

5. **Verify:**
   ```bash
   curl http://localhost:3001/health
   ```

## Testing Your Configuration

### 1. Health Check
```bash
curl http://localhost:3001/health
```

**Expected response:**
```json
{"status":"ok","service":"TaxCore Service"}
```

### 2. Tax Rates Test
```bash
curl http://localhost:3001/tax-rates
```

**Expected response:**
```json
{
  "success": true,
  "data": [
    {"taxLabel": "A", "taxRate": 15.0},
    {"taxLabel": "G", "taxRate": 0.0},
    ...
  ]
}
```

### 3. Invoice Test (via Browser)
1. Open POS: `http://localhost:8080`
2. Complete a sale
3. Check logs:
   ```bash
   # Docker
   docker-compose logs -f taxcore-service
   
   # Manual
   tail -f /usr/src/logs/taxcore-service.log
   ```

4. Should see:
   ```
   Received sale request: {...}
   Using cashier from payload: John Doe
   TaxCore response: {invoiceNumber: "...", ...}
   ```

## Troubleshooting

### "Certificate not found"

**Check certificate exists:**
```bash
# Docker
docker-compose exec taxcore-service ls -la /usr/src/app/certs/

# Manual
ls -la /var/www/html/TAF/FRCS_Certs_Install/*.pfx
```

**Solution:**
- Verify certificate file is in correct location
- Check filename matches `TAXCORE_PFX_FILE` or `TAXCORE_PFX_PATH`
- Check file permissions: `chmod 644 FRCS_Certs_Install/*.pfx`

### "Connection refused" or "ECONNREFUSED"

**Check VSDC URL:**
```bash
# Test with curl
curl http://devesdc.sandbox.vms.frcs.org.fj:8888/YOUR-UUID/api/v1/tax-rates
```

**Solution:**
- Verify `TAXCORE_VSDC_URL` is correct
- Check network connectivity
- Verify UUID is correct
- Check if VSDC service is running

### "Invalid certificate" or "SSL error"

**Check certificate password:**
```bash
# Test certificate manually
openssl pkcs12 -in FRCS_Certs_Install/YOUR-CERT.pfx -nodes -passin pass:YOUR-PASSWORD
```

**Solution:**
- Verify `TAXCORE_PFX_PASSWORD` is correct
- Check certificate hasn't expired
- Ensure certificate is for correct environment (dev/prod)

### "PIN authentication failed"

**Check PIN:**
- Verify `TAXCORE_PIN_JSON` is correct
- Contact FRCS if PIN is expired
- Check if PIN is required for your V-SDC instance

### "Wrong invoice numbers" or "Unexpected behavior"

**Check environment mixing:**
- Ensure all settings (URL, certificate, PIN) are from same environment
- Don't mix sandbox certificate with production URL
- Verify UUID matches your certificate

## Security Best Practices

### 1. Never Commit Secrets

```bash
# Add to .gitignore
echo ".env" >> .gitignore
echo ".env.production" >> .gitignore
echo "FRCS_Certs_Install/*.pfx" >> .gitignore
```

### 2. Use Environment-Specific Files

```bash
.env              # Local development
.env.docker       # Docker development
.env.staging      # Staging environment
.env.production   # Production (never commit!)
```

### 3. Restrict File Permissions

```bash
# Certificate files
chmod 600 FRCS_Certs_Install/*.pfx

# Environment files
chmod 600 .env*
```

### 4. Use Docker Secrets (Production)

```yaml
# docker-compose.prod.yaml
services:
  taxcore-service:
    secrets:
      - taxcore_pfx_password
      - taxcore_pin

secrets:
  taxcore_pfx_password:
    external: true
  taxcore_pin:
    external: true
```

## Quick Reference Card

```bash
# ========================================
# TaxCore Configuration Quick Reference
# ========================================

# Service Port
TAXCORE_SERVICE_PORT=3001

# API Endpoints
TAXCORE_TAX_URL=https://api.sandbox.vms.frcs.org.fj/api
TAXCORE_VSDC_URL=http://devesdc.sandbox.vms.frcs.org.fj:8888/{YOUR-UUID}/api

# Certificate (Docker)
TAXCORE_PFX_FILE=YOUR-CERTIFICATE.pfx

# Certificate (Manual)
TAXCORE_PFX_PATH=/full/path/to/YOUR-CERTIFICATE.pfx

# Credentials
TAXCORE_PFX_PASSWORD=YOUR-CERT-PASSWORD
TAXCORE_PIN_JSON=YOUR-PIN

# Debug
TAXCORE_DEBUG=true

# ========================================
# Test Configuration
# ========================================

# Health check
curl http://localhost:3001/health

# Tax rates
curl http://localhost:3001/tax-rates

# Logs (Docker)
docker-compose logs -f taxcore-service

# Logs (Manual)
tail -f /usr/src/logs/taxcore-service.log
```

## Getting Help

If you need your VSDC URL, PIN, or certificate:
1. Contact FRCS support
2. Provide your business registration details
3. Request V-SDC instance credentials

**FRCS Contact:**
- Website: https://www.frcs.org.fj/
- Email: support@frcs.org.fj
- Phone: (Check FRCS website for current contact)

---

**Last Updated:** October 2, 2025  
**Related Docs:**
- `docs/TaxCore_Docker_Setup.md` - Docker configuration
- `docs/TaxCore_Quick_Start.md` - Quick start guide
- `websocket-server/TAXCORE_SERVICE.md` - Service documentation