# Profitaa ERP — Federal Inland Revenue Service (FIRS) MBS API Integration

Welcome to the Profitaa integration specs. This reference outlines how multi-tenant business nodes programmatically interact with the Merchant Buyer Solution (MBS) core ledger for real-time electronic invoice pre-clearance and cryptographic validation.

## 1. Protocol Architecture
– **Transport**: HTTPS POST over TLS 1.3
– **Data Formats**: UBL XML 2.1 / PEPPOL BIS Billing 3.0 (with fallback JSON schema mapping structures)
– **Authentication**: Stateless Tenant Header Injection (`x-api-key`, `x-api-secret`)

## 2. Core Operational Endpoints

### Real-Time Invoice Signing & Registration
– **Route**: `POST /api/v1/invoice/sign`
– **Description**: Submits finalized transaction arrays natively to the ledger. This route computes macro monetary total calculations, maps standard HSN tariff matrix filters, validates output tax lines, and permanently saves documents to the merchant account portal view dashboard.

– **Success Status**: `201 Created` / `200 OK`

 

### Stateless dry-run Dry Validation
– **Route**: `POST /api/v1/invoice/validate`
– **Description**: Validates data type arrays, element lengths, and calculation balances statelessly in memory without modifying backend storage histories.

### Invoice Lifecycle Amendments (Debit/Credit Notes)
– **Route**: `PATCH /api/v1/invoice/update`
– **Description**: Issues immutable correction adjustments.
– InvoiceTypeCode `381`: Credit Note (Full/Partial reversals referencing original parent IRN codes)
– InvoiceTypeCode `383`: Debit Note (Additional adjustments)

## 3. Local Cryptographic Hashing Protocol
To safeguard offline operability and system speed, the platform encodes the verification QR code string values on the fly within the local runtime scope:
1. Concatenates the registered unique `IRN` code with a current UNIX timestamp: `{IRN}.{TIMESTAMP}`
2. Encrypts the raw string package using local RSA-PKCS1 public-key encryption.
3. Base64-encodes the ciphertext output payload. This string variable dynamically populates the high-density print QR code element inside the customer invoice template layouts.