{
  "info": {
    "name": "EFRIS External API - Complete Collection",
    "description": "## EFRIS Integration Hub — External API\n\nComplete Postman collection for all external-facing EFRIS endpoints.\n\n### 🔑 Before You Start — Set These Variables\nEdit the **collection variables** (click the collection → Variables tab) and fill in:\n\n| Variable | Description | Example |\n|---|---|---|\n| `base_url` | API server base URL | `https://efrisintegration.nafacademy.com` |\n| `api_key` | Your company X-API-Key | `efris_abc123...` |\n| `tin` | Your company TIN registered with the system | `1000000001` |\n\nThese variables are used automatically across all requests — you only need to set them once.\n\n### 📁 Folder Structure\n1. **Health & Diagnostics** — connection tests, server time\n2. **Invoices** — submit, query, list invoices\n3. **Credit Notes** — submit and query credit notes\n4. **Products** — register and query goods/services\n5. **Stock Management** — increase, decrease, transfer stock\n6. **Purchase Orders** — submit purchase orders\n7. **Reference Data** — excise duty, units, commodity categories, taxpayer info, branches (T138)\n8. **Passthrough** — raw EFRIS interface passthrough\n\n### 📖 Base URL\n`https://efrisintegration.nafacademy.com`",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
    "_postman_id": "efris-external-api-v2-complete"
  },
  "auth": {
    "type": "apikey",
    "apikey": [
      {
        "key": "key",
        "value": "X-API-Key",
        "type": "string"
      },
      {
        "key": "value",
        "value": "{{api_key}}",
        "type": "string"
      },
      {
        "key": "in",
        "value": "header",
        "type": "string"
      }
    ]
  },
  "variable": [
    {
      "key": "base_url",
      "value": "https://efrisintegration.nafacademy.com",
      "type": "string",
      "description": "Base URL of the EFRIS Integration API server"
    },
    {
      "key": "api_key",
      "value": "",
      "type": "string",
      "description": "Your company API key (X-API-Key header). Get this from your EFRIS Integration dashboard."
    },
    {
      "key": "tin",
      "value": "",
      "type": "string",
      "description": "Your company TIN as configured in the EFRIS Integration system (e.g., 1000000001)"
    }
  ],
  "item": [
    {
      "name": "1. Health & Diagnostics",
      "description": "Endpoints to test connectivity, server time, and company EFRIS configuration.",
      "item": [
        {
          "name": "Server Time (T101)",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/api/external/efris/server-time",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "efris", "server-time"]
            },
            "description": "Get current server time from URA EFRIS (T101).\n\nVerifies EFRIS connectivity and returns URA's server timestamp. Use this as a quick health check to confirm your API key works and EFRIS is reachable."
          },
          "response": []
        },
        {
          "name": "Diagnostic Self-Test",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/api/external/efris/diagnostic-test",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "efris", "diagnostic-test"]
            },
            "description": "Perform a full diagnostic test of your company's EFRIS connectivity.\n\nReturns:\n- Company configuration (TIN, device number, test mode, cert status)\n- HTTP connectivity test results for the EFRIS server URLs (production + test)\n\nUseful for troubleshooting connection issues."
          },
          "response": []
        },
        {
          "name": "Registration Details (T102)",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/api/external/efris/registration-details",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "efris", "registration-details"]
            },
            "description": "Get taxpayer profile and registration details from EFRIS (T102).\n\nReturns the registration/taxpayer metadata stored or fetched during the EFRIS handshake. Includes branch IDs needed for stock transfers."
          },
          "response": []
        }
      ]
    },
    {
      "name": "2. Invoices",
      "description": "Submit, query, and list fiscal invoices via EFRIS (T109).",
      "item": [
        {
          "name": "Submit Invoice — Standard B2C",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "options": { "raw": { "language": "json" } },
              "raw": "{\n  \"invoice_number\": \"INV-2026-001\",\n  \"invoice_date\": \"2026-06-09\",\n  \"customer_name\": \"John Doe\",\n  \"customer_tin\": \"\",\n  \"buyer_type\": \"1\",\n  \"payment_method\": \"101\",\n  \"currency\": \"UGX\",\n  \"remarks\": \"Standard retail sale\",\n  \"invoice_industry_code\": \"101\",\n  \"items\": [\n    {\n      \"item\": \"Office Chair Ergonomic\",\n      \"itemCode\": \"CHAIR-001\",\n      \"qty\": \"2\",\n      \"unitOfMeasure\": \"102\",\n      \"unitPrice\": \"300000\",\n      \"total\": \"600000\",\n      \"taxRate\": \"18\",\n      \"tax\": \"91525\",\n      \"goodsCategoryId\": \"44102906\",\n      \"vatApplicableFlag\": \"1\"\n    }\n  ]\n}"
            },
            "url": {
              "raw": "{{base_url}}/api/external/efris/submit-invoice",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "efris", "submit-invoice"]
            },
            "description": "Submit a standard B2C (Business-to-Consumer) invoice to EFRIS.\n\n**buyer_type codes:**\n- `0` = B2B (requires customer_tin)\n- `1` = B2C Individual (default)\n- `2` = Foreigner\n- `3` = B2G (Government)\n\n**payment_method codes:**\n- `101` = Cash\n- `102` = Credit\n- `103` = Cheque\n- `105` = Mobile Money\n\n**invoice_industry_code:**\n- `101` = General (default)\n- `102` = Export\n- `112` = Export Service\n\nReturns complete fiscal invoice data including FDN, QR code, seller info, and all fiscalized items."
          },
          "response": []
        },
        {
          "name": "Submit Invoice — B2B (with Customer TIN)",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "options": { "raw": { "language": "json" } },
              "raw": "{\n  \"invoice_number\": \"INV-2026-002\",\n  \"invoice_date\": \"2026-06-09\",\n  \"customer_name\": \"ABC Company Ltd\",\n  \"customer_tin\": \"1000000000\",\n  \"buyer_type\": \"0\",\n  \"payment_method\": \"102\",\n  \"currency\": \"UGX\",\n  \"remarks\": \"B2B credit sale\",\n  \"invoice_industry_code\": \"101\",\n  \"items\": [\n    {\n      \"item\": \"Laptop Computer\",\n      \"itemCode\": \"LAP-001\",\n      \"qty\": \"5\",\n      \"unitOfMeasure\": \"102\",\n      \"unitPrice\": \"2500000\",\n      \"total\": \"12500000\",\n      \"taxRate\": \"18\",\n      \"tax\": \"1906779\",\n      \"goodsCategoryId\": \"43211507\",\n      \"vatApplicableFlag\": \"1\"\n    },\n    {\n      \"item\": \"Mouse Wireless\",\n      \"itemCode\": \"MOUSE-001\",\n      \"qty\": \"5\",\n      \"unitOfMeasure\": \"102\",\n      \"unitPrice\": \"80000\",\n      \"total\": \"400000\",\n      \"taxRate\": \"18\",\n      \"tax\": \"61017\",\n      \"goodsCategoryId\": \"43211706\",\n      \"vatApplicableFlag\": \"1\"\n    }\n  ]\n}"
            },
            "url": {
              "raw": "{{base_url}}/api/external/efris/submit-invoice",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "efris", "submit-invoice"]
            },
            "description": "Submit a B2B invoice where buyer_type=0. The customer_tin field is required for B2B invoices."
          },
          "response": []
        },
        {
          "name": "Submit Invoice — Export (T102/T112)",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "options": { "raw": { "language": "json" } },
              "raw": "{\n  \"invoice_number\": \"EXP-2026-001\",\n  \"invoice_date\": \"2026-06-09\",\n  \"customer_name\": \"Kenya Imports Ltd\",\n  \"customer_tin\": \"\",\n  \"buyer_type\": \"2\",\n  \"payment_method\": \"101\",\n  \"currency\": \"USD\",\n  \"remarks\": \"Export to Kenya\",\n  \"invoice_industry_code\": \"102\",\n  \"delivery_terms_code\": \"FOB\",\n  \"customs\": {\n    \"sad_number\": \"SAD12345\",\n    \"office\": \"Busia\",\n    \"cif\": \"5000\",\n    \"ware_house_number\": \"WH001\",\n    \"ware_house_name\": \"Busia Warehouse\",\n    \"destination_country\": \"Kenya\",\n    \"origin_country\": \"Uganda\",\n    \"import_export_flag\": \"2\",\n    \"confirm_status\": \"0\",\n    \"valuation_method\": \"CIF\",\n    \"prn\": \"PRN123\"\n  },\n  \"items\": [\n    {\n      \"item\": \"Coffee Beans - Arabica\",\n      \"itemCode\": \"COFFEE-001\",\n      \"qty\": \"500\",\n      \"unitOfMeasure\": \"103\",\n      \"unitPrice\": \"10\",\n      \"total\": \"5000\",\n      \"taxRate\": \"-\",\n      \"tax\": \"0\",\n      \"goodsCategoryId\": \"50201706\",\n      \"vatApplicableFlag\": \"0\",\n      \"total_weight\": 500.0,\n      \"piece_qty\": 500,\n      \"piece_measure_unit\": \"103\",\n      \"hs_code\": \"0901110000\",\n      \"hs_name\": \"Coffee, not roasted\"\n    }\n  ]\n}"
            },
            "url": {
              "raw": "{{base_url}}/api/external/efris/submit-invoice",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "efris", "submit-invoice"]
            },
            "description": "Submit an export invoice (invoice_industry_code=102). Export invoices require additional customs fields and per-item weight/piece data.\n\n**Required extra fields for exports:**\n- `delivery_terms_code`: Incoterms (FOB, CIF, CFR, EXW, DAP, etc.)\n- `customs`: Object with SAD number, office, destination country, etc.\n- Per item: `total_weight`, `piece_qty`, `piece_measure_unit`\n\nOptional per item: `hs_code`, `hs_name`"
          },
          "response": []
        },
        {
          "name": "Submit Invoice — Zero-Rated / Tax Exempt",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "options": { "raw": { "language": "json" } },
              "raw": "{\n  \"invoice_number\": \"INV-2026-ZR-001\",\n  \"invoice_date\": \"2026-06-09\",\n  \"customer_name\": \"Farm Fresh Ltd\",\n  \"customer_tin\": \"1000000010\",\n  \"buyer_type\": \"0\",\n  \"payment_method\": \"101\",\n  \"currency\": \"UGX\",\n  \"items\": [\n    {\n      \"item\": \"Maize Grain\",\n      \"itemCode\": \"MAIZE-001\",\n      \"qty\": \"1000\",\n      \"unitOfMeasure\": \"103\",\n      \"unitPrice\": \"1500\",\n      \"total\": \"1500000\",\n      \"taxRate\": \"-\",\n      \"tax\": \"0\",\n      \"goodsCategoryId\": \"50201717\",\n      \"vatApplicableFlag\": \"0\"\n    }\n  ]\n}"
            },
            "url": {
              "raw": "{{base_url}}/api/external/efris/submit-invoice",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "efris", "submit-invoice"]
            },
            "description": "Submit a zero-rated or tax-exempt invoice. Set `taxRate` to `\"-\"` and `vatApplicableFlag` to `\"0\"` for exempt items."
          },
          "response": []
        },
        {
          "name": "Get Invoice by Number",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/api/external/efris/invoice/INV-2026-001",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "efris", "invoice", "INV-2026-001"]
            },
            "description": "Query the status and details of a specific invoice by its invoice number.\n\nLooks up the invoice from the activity logs and returns:\n- FDN (Fiscal Document Number)\n- Approval status\n- Customer name\n- Total amount and tax\n- Fiscalization timestamp\n- Error message (if rejected)"
          },
          "response": []
        },
        {
          "name": "List Invoices",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/api/external/efris/invoices?limit=50&offset=0",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "efris", "invoices"],
              "query": [
                { "key": "limit", "value": "50", "description": "Max records to return (max 100)" },
                { "key": "offset", "value": "0", "description": "Pagination offset" },
                { "key": "status", "value": "", "description": "Filter: 'success' or 'failed'", "disabled": true }
              ]
            },
            "description": "List recent invoices from the activity log with pagination.\n\n**Query Parameters:**\n- `limit` (int): Max records per page (max 100, default 50)\n- `offset` (int): Pagination offset (default 0)\n- `status` (str, optional): Filter by status — `success` or `failed`"
          },
          "response": []
        },
        {
          "name": "List Invoices — Failed Only",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/api/external/efris/invoices?status=failed&limit=50&offset=0",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "efris", "invoices"],
              "query": [
                { "key": "status", "value": "failed" },
                { "key": "limit", "value": "50" },
                { "key": "offset", "value": "0" }
              ]
            },
            "description": "List only failed invoice submissions for review and resubmission."
          },
          "response": []
        }
      ]
    },
    {
      "name": "3. Credit Notes",
      "description": "Submit credit note applications and query existing credit notes via EFRIS (T110, T112).",
      "item": [
        {
          "name": "Submit Credit Note — Simple Format",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "options": { "raw": { "language": "json" } },
              "raw": "{\n  \"credit_note_number\": \"CN-2026-001\",\n  \"credit_note_date\": \"2026-06-09\",\n  \"original_invoice_number\": \"INV-2026-001\",\n  \"original_fdn\": \"1234567890123456\",\n  \"customer_name\": \"John Doe\",\n  \"reason\": \"Product returned — defective item\",\n  \"reason_code\": \"101\",\n  \"items\": [\n    {\n      \"item_name\": \"Office Chair Ergonomic\",\n      \"item_code\": \"CHAIR-001\",\n      \"quantity\": 1,\n      \"unit_price\": 300000,\n      \"tax_rate\": 0.18,\n      \"tax_amount\": 45763,\n      \"total\": 300000\n    }\n  ],\n  \"total_amount\": 300000,\n  \"total_tax\": 45763,\n  \"currency\": \"UGX\"\n}"
            },
            "url": {
              "raw": "{{base_url}}/api/external/efris/submit-credit-note",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "efris", "submit-credit-note"]
            },
            "description": "Submit a credit note to EFRIS (T110) using the simplified format.\n\n**reason_code values:**\n- `101` = Sales Return\n- `102` = Cancelled Invoice\n- `103` = Discount Given\n- `104` = Price Adjustment\n\nThe `original_fdn` is the Fiscal Document Number from the original approved invoice."
          },
          "response": []
        },
        {
          "name": "Submit Credit Note — Pre-formatted EFRIS T110",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "options": { "raw": { "language": "json" } },
              "raw": "{\n  \"oriInvoiceId\": \"1234567890123456\",\n  \"oriInvoiceNo\": \"INV-2026-001\",\n  \"reasonCode\": \"101\",\n  \"reason\": \"Product returned — defective item\",\n  \"sellersReferenceNo\": \"CN-2026-001\",\n  \"applicationTime\": \"2026-06-09 10:00:00\",\n  \"goodsDetails\": [\n    {\n      \"item\": \"Office Chair Ergonomic\",\n      \"itemCode\": \"CHAIR-001\",\n      \"qty\": \"1\",\n      \"unitOfMeasure\": \"102\",\n      \"unitPrice\": \"300000\",\n      \"total\": \"300000\",\n      \"taxRate\": \"18\",\n      \"tax\": \"45763\",\n      \"goodsCategoryId\": \"44102906\",\n      \"vatApplicableFlag\": \"1\"\n    }\n  ],\n  \"taxDetails\": [\n    {\n      \"taxCategoryCode\": \"01\",\n      \"netAmount\": \"254237\",\n      \"taxRate\": \"18\",\n      \"taxAmount\": \"45763\",\n      \"grossAmount\": \"300000\"\n    }\n  ],\n  \"summary\": {\n    \"netAmount\": \"254237\",\n    \"taxAmount\": \"45763\",\n    \"grossAmount\": \"300000\",\n    \"currency\": \"101\"\n  },\n  \"payWay\": [\n    {\n      \"paymentMode\": \"101\",\n      \"paymentAmount\": \"300000\"\n    }\n  ],\n  \"buyerDetails\": {\n    \"buyerType\": \"1\",\n    \"buyerLegalName\": \"John Doe\",\n    \"buyerTin\": \"\",\n    \"buyerPhoneNo\": \"\",\n    \"buyerEmail\": \"\"\n  },\n  \"basicInformation\": {\n    \"currency\": \"101\",\n    \"invoiceType\": \"1\",\n    \"invoiceIndustryCode\": \"101\"\n  }\n}"
            },
            "url": {
              "raw": "{{base_url}}/api/external/efris/submit-credit-note",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "efris", "submit-credit-note"]
            },
            "description": "Submit a pre-formatted T110 credit note payload. Use this format if your ERP already builds the EFRIS T110 structure (e.g., YourBookSuit or other advanced integrators).\n\nThe endpoint auto-detects which format you're using based on the presence of top-level EFRIS fields (`reasonCode`, `goodsDetails`, `taxDetails`, `summary`)."
          },
          "response": []
        },
        {
          "name": "Query Credit Notes",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/api/external/efris/credit-notes?pageNo=1&pageSize=10",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "efris", "credit-notes"],
              "query": [
                { "key": "pageNo", "value": "1", "description": "Page number (1-indexed)" },
                { "key": "pageSize", "value": "10", "description": "Records per page" },
                { "key": "queryType", "value": "1", "description": "1=By date range (default)", "disabled": true },
                { "key": "referenceNo", "value": "", "description": "Filter by reference/credit note number", "disabled": true },
                { "key": "oriInvoiceNo", "value": "", "description": "Filter by original invoice number", "disabled": true },
                { "key": "invoiceNo", "value": "", "description": "Filter by credit note invoice number", "disabled": true },
                { "key": "approveStatus", "value": "", "description": "Filter by approval status", "disabled": true },
                { "key": "startDate", "value": "", "description": "Date range start (YYYY-MM-DD)", "disabled": true },
                { "key": "endDate", "value": "", "description": "Date range end (YYYY-MM-DD)", "disabled": true }
              ]
            },
            "description": "Query credit notes from EFRIS (T112) with optional filters.\n\n**Query Parameters (all optional):**\n- `pageNo` / `pageSize`: Pagination\n- `queryType`: `1` = by date range (default)\n- `referenceNo`: Filter by your reference number\n- `oriInvoiceNo`: Filter by original invoice number\n- `invoiceNo`: Filter by credit note FDN\n- `approveStatus`: Filter by approval status\n- `startDate` / `endDate`: Date range filter (YYYY-MM-DD format)"
          },
          "response": []
        },
        {
          "name": "Query Credit Notes — By Original Invoice",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/api/external/efris/credit-notes?oriInvoiceNo=INV-2026-001&pageNo=1&pageSize=10",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "efris", "credit-notes"],
              "query": [
                { "key": "oriInvoiceNo", "value": "INV-2026-001" },
                { "key": "pageNo", "value": "1" },
                { "key": "pageSize", "value": "10" }
              ]
            },
            "description": "Query credit notes filtered by the original invoice number."
          },
          "response": []
        }
      ]
    },
    {
      "name": "4. Products (Goods & Services)",
      "description": "Register products/services and query the goods catalogue from EFRIS (T130, T127).",
      "item": [
        {
          "name": "Register Product — Standard Goods",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "options": { "raw": { "language": "json" } },
              "raw": "{\n  \"item_code\": \"CHAIR-001\",\n  \"item_name\": \"Office Chair — Ergonomic\",\n  \"unit_price\": 300000,\n  \"commodity_code\": \"44102906\",\n  \"unit_of_measure\": \"102\",\n  \"have_excise_tax\": \"102\",\n  \"goods_type_code\": \"101\",\n  \"stock_quantity\": 50,\n  \"description\": \"Ergonomic office chair with lumbar support\"\n}"
            },
            "url": {
              "raw": "{{base_url}}/api/external/efris/register-product",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "efris", "register-product"]
            },
            "description": "Register a new product or service with EFRIS (T130).\n\n**Required fields:**\n- `item_code` (or `itemCode`): Your internal product code\n- `item_name` (or `itemName`): Product display name\n- `unit_price` (or `unitPrice`): Price in UGX\n- `commodity_code` (or `commodityCode`/`commodityCategoryId`): EFRIS commodity category code (see commodity-categories endpoint)\n\n**Optional fields:**\n- `unit_of_measure`: T115 unit code (101=Stick, 102=Piece/Litre, 103=Kg, 8B=Crate, 4C=Box, 43=Bag, BO=Bottle, etc.)\n- `have_excise_tax`: `101`=Yes, `102`=No (default)\n- `excise_duty_code`: Required ONLY when `have_excise_tax=101`\n- `goods_type_code`: `101`=Goods (default), `102`=Fuel\n- `is_service`: boolean, default false\n- `stock_quantity`: Initial stock prewarning quantity\n- `description`: Product description\n- `operationType`: `101`=New (default), `102`=Update"
          },
          "response": []
        },
        {
          "name": "Register Product — With Excise Duty",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "options": { "raw": { "language": "json" } },
              "raw": "{\n  \"item_code\": \"BEER-001\",\n  \"item_name\": \"Premium Lager Beer 500ml\",\n  \"unit_price\": 3500,\n  \"commodity_code\": \"50202302\",\n  \"unit_of_measure\": \"BO\",\n  \"have_excise_tax\": \"101\",\n  \"excise_duty_code\": \"LED190100\",\n  \"goods_type_code\": \"101\",\n  \"stock_quantity\": 1000,\n  \"description\": \"Premium quality lager beer 500ml glass bottle\"\n}"
            },
            "url": {
              "raw": "{{base_url}}/api/external/efris/register-product",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "efris", "register-product"]
            },
            "description": "Register an excisable product (e.g., beer, spirits, tobacco). When `have_excise_tax=101`, you must provide the `excise_duty_code`.\n\nGet available excise codes from the `/api/external/efris/excise-duty` endpoint."
          },
          "response": []
        },
        {
          "name": "Register Service",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "options": { "raw": { "language": "json" } },
              "raw": "{\n  \"item_code\": \"SVC-CONSULT\",\n  \"item_name\": \"IT Consulting Services\",\n  \"unit_price\": 500000,\n  \"commodity_code\": \"81111500\",\n  \"unit_of_measure\": \"102\",\n  \"have_excise_tax\": \"102\",\n  \"is_service\": true,\n  \"description\": \"Professional IT consulting and advisory services\"\n}"
            },
            "url": {
              "raw": "{{base_url}}/api/external/efris/register-product",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "efris", "register-product"]
            },
            "description": "Register a service (intangible). Set `is_service: true` to mark as a service instead of a physical good."
          },
          "response": []
        },
        {
          "name": "Register Product — With Multi-Unit (Packaging)",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "options": { "raw": { "language": "json" } },
              "raw": "{\n  \"item_code\": \"SODA-CRATE\",\n  \"item_name\": \"Soda Soft Drink — Crate of 24\",\n  \"unit_price\": 60000,\n  \"commodity_code\": \"50202300\",\n  \"unit_of_measure\": \"8B\",\n  \"have_excise_tax\": \"102\",\n  \"goods_type_code\": \"101\",\n  \"stock_quantity\": 200,\n  \"have_piece_unit\": \"101\",\n  \"piece_measure_unit\": \"BO\",\n  \"piece_unit_price\": 2500,\n  \"package_scaled_value\": \"1\",\n  \"piece_scaled_value\": \"24\",\n  \"description\": \"Soda in crates. 1 crate = 24 bottles.\"\n}"
            },
            "url": {
              "raw": "{{base_url}}/api/external/efris/register-product",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "efris", "register-product"]
            },
            "description": "Register a product with multi-unit (bulk/retail packaging) support. For example, 1 Crate = 24 Bottles.\n\n**Multi-unit fields:**\n- `have_piece_unit`: `101`=Yes\n- `piece_measure_unit`: Unit code for the smaller unit (e.g., `BO`=Bottle)\n- `piece_unit_price`: Price of the smaller unit\n- `package_scaled_value`: Amount of larger units in the package (usually `1`)\n- `piece_scaled_value`: Number of smaller units per package (e.g., `24`)"
          },
          "response": []
        },
        {
          "name": "Update Existing Product",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "options": { "raw": { "language": "json" } },
              "raw": "{\n  \"item_code\": \"CHAIR-001\",\n  \"item_name\": \"Office Chair — Ergonomic (Updated)\",\n  \"unit_price\": 350000,\n  \"commodity_code\": \"44102906\",\n  \"unit_of_measure\": \"102\",\n  \"have_excise_tax\": \"102\",\n  \"operationType\": \"102\",\n  \"description\": \"Updated ergonomic office chair with improved lumbar support\"\n}"
            },
            "url": {
              "raw": "{{base_url}}/api/external/efris/register-product",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "efris", "register-product"]
            },
            "description": "Update an existing product by setting `operationType` to `102` (Update). Use the same `item_code` as the original registration."
          },
          "response": []
        },
        {
          "name": "Query Registered Goods — All",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/api/external/efris/goods",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "efris", "goods"]
            },
            "description": "Retrieve ALL registered goods and services from EFRIS (T127). Automatically fetches all pages and returns a single unified list.\n\nReturns for each item: item_code, item_name, is_service, commodity_category, unit_of_measure, unit_price, tax_rate, excise info, stock level, and status."
          },
          "response": []
        },
        {
          "name": "Query Registered Goods — Search by Keyword",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/api/external/efris/goods?search=chair",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "efris", "goods"],
              "query": [
                { "key": "search", "value": "chair", "description": "Keyword search across item_code and item_name" }
              ]
            },
            "description": "Search registered goods by a keyword. Matches against both `goodsCode` and `goodsName` (case-insensitive partial match)."
          },
          "response": []
        },
        {
          "name": "Query Registered Goods — By Item Code",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/api/external/efris/goods?goods_code=CHAIR-001",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "efris", "goods"],
              "query": [
                { "key": "goods_code", "value": "CHAIR-001", "description": "Exact item/goods code filter" }
              ]
            },
            "description": "Filter registered goods by an exact item code."
          },
          "response": []
        },
        {
          "name": "Query Registered Goods — Services Only",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/api/external/efris/goods?service_only=true",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "efris", "goods"],
              "query": [
                { "key": "service_only", "value": "true", "description": "true=services only, false=products only, omit=all" }
              ]
            },
            "description": "Retrieve only services (intangibles) from the registered goods catalogue."
          },
          "response": []
        }
      ]
    },
    {
      "name": "5. Stock Management",
      "description": "Manage stock levels in EFRIS via increase, decrease, and branch transfers (T131, T139).",
      "item": [
        {
          "name": "Stock Increase (T131)",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "options": { "raw": { "language": "json" } },
              "raw": "{\n  \"goodsStockIn\": {\n    \"operationType\": \"101\",\n    \"supplierTin\": \"1000000001\",\n    \"supplierName\": \"Uganda Supplies Ltd\",\n    \"stockInType\": \"102\",\n    \"stockInDate\": \"2026-06-09\",\n    \"remarks\": \"Monthly stock replenishment from local supplier\"\n  },\n  \"goodsStockInItem\": [\n    {\n      \"goodsCode\": \"CHAIR-001\",\n      \"quantity\": \"50\",\n      \"unitPrice\": \"250000\",\n      \"measureUnit\": \"102\",\n      \"remarks\": \"\"\n    },\n    {\n      \"goodsCode\": \"LAP-001\",\n      \"quantity\": \"10\",\n      \"unitPrice\": \"2000000\",\n      \"measureUnit\": \"102\",\n      \"remarks\": \"\"\n    }\n  ]\n}"
            },
            "url": {
              "raw": "{{base_url}}/api/external/efris/stock-increase",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "efris", "stock-increase"]
            },
            "description": "Record a stock increase (goods received) in EFRIS (T131, operationType=101).\n\n**stockInType codes:**\n- `101` = Import\n- `102` = Local Purchase (default)\n- `103` = Manufacture\n- `104` = Opening Stock\n\nBoth `snake_case` and `camelCase` field names are accepted."
          },
          "response": []
        },
        {
          "name": "Stock Decrease (T131)",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "options": { "raw": { "language": "json" } },
              "raw": "{\n  \"goodsStockIn\": {\n    \"operationType\": \"102\",\n    \"adjustType\": \"102\",\n    \"remarks\": \"Damaged goods written off — water damage\"\n  },\n  \"goodsStockInItem\": [\n    {\n      \"goodsCode\": \"CHAIR-001\",\n      \"quantity\": \"5\",\n      \"unitPrice\": \"300000\",\n      \"measureUnit\": \"102\",\n      \"remarks\": \"Irreparably damaged in transit\"\n    }\n  ]\n}"
            },
            "url": {
              "raw": "{{base_url}}/api/external/efris/stock-decrease",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "efris", "stock-decrease"]
            },
            "description": "Record a stock decrease (write-off / wastage) in EFRIS (T131, operationType=102).\n\n**adjustType codes:**\n- `101` = Damaged\n- `102` = Expired\n- `103` = Stolen\n- `104` = Sampling\n- `105` = Others\n\nBoth `snake_case` and `camelCase` field names are accepted."
          },
          "response": []
        },
        {
          "name": "Stock Transfer Between Branches (T139)",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "options": { "raw": { "language": "json" } },
              "raw": "{\n  \"goodsStockTransfer\": {\n    \"source_branch_id\": \"206637525568955296\",\n    \"destination_branch_id\": \"206637528324276772\",\n    \"transfer_type_code\": \"101\",\n    \"remarks\": \"\",\n    \"roll_back_if_error\": \"0\",\n    \"goods_type_code\": \"101\"\n  },\n  \"goodsStockTransferItem\": [\n    {\n      \"goods_code\": \"CHAIR-001\",\n      \"measure_unit\": \"102\",\n      \"quantity\": \"10\",\n      \"remarks\": \"\"\n    }\n  ]\n}"
            },
            "url": {
              "raw": "{{base_url}}/api/external/efris/stock-transfer",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "efris", "stock-transfer"]
            },
            "description": "Transfer stock between branches/locations in EFRIS (T139).\n\n**Important:**\n- Get valid `branchId` values from the `GET /api/external/efris/registration-details` endpoint\n- Source and destination branch IDs **cannot** be the same\n- When `transfer_type_code=103` (Others), `remarks` is **mandatory**\n- Either `goods_code` or `commodity_goods_id` must be provided per item\n\n**transfer_type_code values:**\n- `101` = Out of Stock Adjust\n- `102` = Error Adjust\n- `103` = Others (requires remarks)\n\nBoth `snake_case` and `camelCase` accepted."
          },
          "response": []
        }
      ]
    },
    {
      "name": "6. Purchase Orders",
      "description": "Submit purchase orders to EFRIS (T130 - Send Purchase Order).",
      "item": [
        {
          "name": "Submit Purchase Order",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "options": { "raw": { "language": "json" } },
              "raw": "{\n  \"po_number\": \"PO-2026-001\",\n  \"po_date\": \"2026-06-09\",\n  \"vendor_name\": \"Supplier XYZ Ltd\",\n  \"vendor_tin\": \"1000000001\",\n  \"total_amount\": 12500000,\n  \"currency\": \"UGX\",\n  \"delivery_date\": \"2026-06-20\",\n  \"items\": [\n    {\n      \"item_code\": \"LAP-001\",\n      \"item_name\": \"Laptop Computer\",\n      \"quantity\": 5,\n      \"unit_price\": 2000000,\n      \"total\": 10000000,\n      \"unit_of_measure\": \"102\"\n    },\n    {\n      \"item_code\": \"MOUSE-001\",\n      \"item_name\": \"Wireless Mouse\",\n      \"quantity\": 10,\n      \"unit_price\": 80000,\n      \"total\": 800000,\n      \"unit_of_measure\": \"102\"\n    }\n  ]\n}"
            },
            "url": {
              "raw": "{{base_url}}/api/external/efris/submit-purchase-order",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "efris", "submit-purchase-order"]
            },
            "description": "Submit a purchase order to EFRIS.\n\n**Required fields:**\n- `po_number` (or `poNumber`)\n- `po_date` (or `poDate`)\n- `vendor_name` (or `vendorName` / `supplierName`)\n- `items` (or `goodsDetails`) — at least one item\n- `total_amount` (or `totalAmount`)\n- `currency`\n\n**Optional:**\n- `vendor_tin` (or `vendorTin` / `supplierTin`)\n- `delivery_date` (or `deliveryDate`)"
          },
          "response": []
        }
      ]
    },
    {
      "name": "7. Reference Data",
      "description": "Lookup endpoints for EFRIS codes, categories, taxpayer info, and units of measure.",
      "item": [
        {
          "name": "Get Excise Duty Codes (T125)",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/api/external/efris/excise-duty",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "efris", "excise-duty"],
              "query": [
                { "key": "excise_code", "value": "", "description": "Filter by specific excise duty code (e.g., LED190100)", "disabled": true },
                { "key": "excise_name", "value": "", "description": "Filter by excise duty name (e.g., beer)", "disabled": true }
              ]
            },
            "description": "Retrieve EFRIS excise duty codes and rates (T125).\n\nReturns all leaf-node excise codes with their rate, unit, currency, and excise rule.\n\n**Query Parameters (optional):**\n- `excise_code`: Filter by exact code (e.g., `LED190100`)\n- `excise_name`: Filter by name keyword (e.g., `beer`)\n\n**excise_rule in response:**\n- `1` = Ad Valorem (percentage-based)\n- `2` = Specific / Per Unit (fixed amount per litre/kg/etc.)"
          },
          "response": []
        },
        {
          "name": "Get Excise Duty Codes — Filter by Name",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/api/external/efris/excise-duty?excise_name=beer",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "efris", "excise-duty"],
              "query": [
                { "key": "excise_name", "value": "beer" }
              ]
            },
            "description": "Filter excise duty codes by name keyword (case-insensitive partial match)."
          },
          "response": []
        },
        {
          "name": "Get Units of Measure (T115)",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/api/external/efris/units-of-measure",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "efris", "units-of-measure"]
            },
            "description": "Retrieve EFRIS unit of measure codes (T115 system dictionary).\n\nUse these codes when registering products and submitting invoices.\n\nCommon codes:\n- `101` = Stick\n- `102` = Piece / Litre\n- `103` = Kilogram\n- `8B` = Crate\n- `4C` = Box\n- `43` = Bag\n- `BO` = Bottle\n- `TN` = Tin\n- `PA` = Packet\n- `3A` = Jerrican\n\nFalls back to a cached static list if EFRIS is temporarily unavailable."
          },
          "response": []
        },
        {
          "name": "Get Commodity Categories (T124)",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/api/external/efris/commodity-categories?pageNo=1&pageSize=10",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "efris", "commodity-categories"],
              "query": [
                { "key": "pageNo", "value": "1" },
                { "key": "pageSize", "value": "10" }
              ]
            },
            "description": "Retrieve EFRIS commodity category codes (T124) with pagination.\n\nUse these codes to map your products to the correct EFRIS category when registering via T130.\n\n**Query Parameters:**\n- `pageNo` (alias: `pageNo`): Page number (default 1)\n- `pageSize` (alias: `pageSize`): Records per page (default 10)"
          },
          "response": []
        },
        {
          "name": "Query Taxpayer by TIN (T119)",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/api/external/efris/taxpayer/{{tin}}",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "efris", "taxpayer", "{{tin}}"]
            },
            "description": "Query a taxpayer's business details from URA EFRIS by their TIN (T119).\n\nUseful for B2B invoice validation — verify a customer's registered business name before invoicing.\n\nThis uses the `{{tin}}` collection variable. You can also replace `{{tin}}` in the URL with any other TIN you want to look up (e.g., a customer's TIN for verification)."
          },
          "response": []
        },
        {
          "name": "Get All Branches (T138)",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/api/external/efris/branches",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "efris", "branches"]
            },
            "description": "Get all branches registered to your taxpayer (T138).\n\nReturns a list of all branches with their IDs and names. Use the `branchId` values when performing stock transfers between branches (T139).\n\n**Response Format:**\n```json\n[\n  {\n    \"branchId\": \"206637525568955296\",\n    \"branchName\": \"Mr. STEPHEN BUNJO\"\n  },\n  {\n    \"branchId\": \"206637528324276772\",\n    \"branchName\": \"ARINAIT AND SONS CO. LIMITED\"\n  }\n]\n```\n\n**Use Cases:**\n- Get valid branch IDs for stock transfer operations (T139)\n- Display available branches to end users\n- Validate branch selection before performing branch-specific operations"
          },
          "response": []
        }
      ]
    },
    {
      "name": "8. Passthrough (Advanced)",
      "description": "Generic passthrough to call any EFRIS interface code directly. For advanced integrators only.",
      "item": [
        {
          "name": "Passthrough — T101 Server Time",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "options": { "raw": { "language": "json" } },
              "raw": "{}"
            },
            "url": {
              "raw": "{{base_url}}/api/external/efris/passthrough/T101?encrypt_code=1",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "efris", "passthrough", "T101"],
              "query": [
                { "key": "encrypt_code", "value": "1", "description": "1=Encrypted (default), 2=Plain, 3=Signed only" }
              ]
            },
            "description": "Generic EFRIS passthrough for T101 (Server Time). Replace `T101` in the URL with any EFRIS interface code (T101–T187).\n\nThe middleware automatically:\n- Manages the AES session key\n- Signs the payload digitally\n- Encrypts/decrypts as required\n\n**encrypt_code query parameter:**\n- `1` = Encrypted (default)\n- `2` = Plain text\n- `3` = Signed only, no encryption"
          },
          "response": []
        },
        {
          "name": "Passthrough — T119 Taxpayer Query",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "options": { "raw": { "language": "json" } },
              "raw": "{\n  \"tin\": \"{{tin}}\"\n}"
            },
            "url": {
              "raw": "{{base_url}}/api/external/efris/passthrough/T119?encrypt_code=1",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "efris", "passthrough", "T119"],
              "query": [
                { "key": "encrypt_code", "value": "1" }
              ]
            },
            "description": "Passthrough example for T119 (Taxpayer Query). Send the raw content payload in the request body."
          },
          "response": []
        },
        {
          "name": "Passthrough — T127 Goods Query",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "options": { "raw": { "language": "json" } },
              "raw": "{\n  \"pageNo\": 1,\n  \"pageSize\": 10\n}"
            },
            "url": {
              "raw": "{{base_url}}/api/external/efris/passthrough/T127?encrypt_code=1",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "efris", "passthrough", "T127"],
              "query": [
                { "key": "encrypt_code", "value": "1" }
              ]
            },
            "description": "Passthrough example for T127 (Goods and Services Query). Send pagination parameters in the request body."
          },
          "response": []
        }
      ]
    },
    {
      "name": "9. Error Examples",
      "description": "Example requests that demonstrate common error responses for testing error handling in your ERP.",
      "item": [
        {
          "name": "Error — Missing Required Field",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "options": { "raw": { "language": "json" } },
              "raw": "{\n  \"invoice_number\": \"INV-ERR-001\",\n  \"invoice_date\": \"2026-06-09\",\n  \"items\": [\n    {\n      \"item\": \"Test Product\",\n      \"qty\": \"1\",\n      \"unitPrice\": \"10000\"\n    }\n  ]\n}"
            },
            "url": {
              "raw": "{{base_url}}/api/external/efris/submit-invoice",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "efris", "submit-invoice"]
            },
            "description": "Missing `customer_name` field — should return HTTP 422 Unprocessable Entity with validation error details."
          },
          "response": []
        },
        {
          "name": "Error — Invalid API Key (401)",
          "request": {
            "auth": {
              "type": "apikey",
              "apikey": [
                { "key": "key", "value": "X-API-Key", "type": "string" },
                { "key": "value", "value": "invalid_key_test_12345", "type": "string" },
                { "key": "in", "value": "header", "type": "string" }
              ]
            },
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/api/external/efris/server-time",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "efris", "server-time"]
            },
            "description": "Demonstrates the 401 Unauthorized response when an invalid API key is provided."
          },
          "response": []
        },
        {
          "name": "Error — Unconfigured TIN (400)",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/api/external/efris/taxpayer/9999999999",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "efris", "taxpayer", "9999999999"]
            },
            "description": "Demonstrates the 400 response when a TIN is not yet configured in the system. The middleware validates TINs in path parameters, query params, headers, and request body."
          },
          "response": []
        },
        {
          "name": "Error — Stock Transfer Same Branch (400)",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "options": { "raw": { "language": "json" } },
              "raw": "{\n  \"goodsStockTransfer\": {\n    \"source_branch_id\": \"206637525568955296\",\n    \"destination_branch_id\": \"206637525568955296\",\n    \"transfer_type_code\": \"101\"\n  },\n  \"goodsStockTransferItem\": [\n    {\n      \"goods_code\": \"CHAIR-001\",\n      \"measure_unit\": \"102\",\n      \"quantity\": \"10\"\n    }\n  ]\n}"
            },
            "url": {
              "raw": "{{base_url}}/api/external/efris/stock-transfer",
              "host": ["{{base_url}}"],
              "path": ["api", "external", "efris", "stock-transfer"]
            },
            "description": "Demonstrates 400 error when source and destination branch IDs are the same."
          },
          "response": []
        }
      ]
    }
  ]
}