{ "info": { "_postman_id": "b0d7ee6d-d9f2-4435-bd78-81255eb70e60", "name": "EFRIS Gateway — ERP Integration", "description": "Requests for connecting an accounting system, POS or ERP to URA's EFRIS through the EFRIS Gateway. Use it with the ERP Integration Guide.\n\n**Setup**\n\n1. Open the collection's **Variables** and set `apiKey` to the key your EFRIS provider gave you. Leave `baseUrl` as it is unless your provider gives you another address.\n2. Run **1. Connecting → Check the connection** until it succeeds.\n3. Work through the folders in order: products, stock, then sales.\n\nKeep the base URL and API key in your system's settings, not in its code: both can change.\n\n**Helpers**\n\n- Each sale gets a new invoice number, and `{{today}}` is today's date.\n- After a successful sale, its `fdn` and `efrisInvoiceId` are saved, so the credit note requests refer to it without editing.\n- Every failure carries `detail`: what is wrong and what to do. Show it to your user.", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "auth": { "type": "apikey", "apikey": [ { "key": "key", "value": "X-API-Key", "type": "string" }, { "key": "value", "value": "{{apiKey}}", "type": "string" }, { "key": "in", "value": "header", "type": "string" } ] }, "event": [ { "listen": "prerequest", "script": { "type": "text/javascript", "exec": [ "pm.collectionVariables.set('today', new Date().toISOString().slice(0, 10));" ] } } ], "variable": [ { "key": "baseUrl", "value": "https://efrisgateway.com/api/efris" }, { "key": "apiKey", "value": "YOUR_API_KEY" }, { "key": "today", "value": "" }, { "key": "fdn", "value": "", "description": "Saved from the last successful sale" }, { "key": "efrisInvoiceId", "value": "", "description": "Saved from the last successful sale" }, { "key": "invoiceNumber", "value": "", "description": "Saved from the last successful sale" }, { "key": "referenceNo", "value": "", "description": "Saved from the last credit note" }, { "key": "creditNoteFdn", "value": "", "description": "The fiscal document number of an issued credit note, to cancel it" }, { "key": "sourceBranchId", "value": "", "description": "From Lookups → Branches" }, { "key": "destinationBranchId", "value": "", "description": "From Lookups → Branches" } ], "item": [ { "name": "1. Connecting", "description": "Check your account and the connection before anything else.", "item": [ { "name": "Check the connection", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/diagnostics", "host": [ "{{baseUrl}}" ], "path": [ "diagnostics" ] }, "description": "Shows your account's details and whether the connection to URA works. If `success` is `false`, the response says why — pass it to your provider. Do not go further until this passes." }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const r = pm.response.json();", "pm.test('Succeeded', () => pm.expect(r.success, r.detail).to.eql(true));" ] } } ], "response": [ { "name": "Connected", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/diagnostics", "host": [ "{{baseUrl}}" ], "path": [ "diagnostics" ] }, "description": "Shows your account's details and whether the connection to URA works. If `success` is `false`, the response says why — pass it to your provider. Do not go further until this passes." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"configuration\": {\n \"companyName\": \"Nakawa Traders Ltd\",\n \"tin\": \"1000000001\",\n \"deviceNumber\": \"1000000001_02\",\n \"environment\": \"sandbox\",\n \"apiCallsToday\": 12,\n \"dailyLimit\": 5000,\n \"licenceEnds\": \"2027-06-30\"\n }\n}" } ] } ] }, { "name": "2. Products", "description": "A product must be registered before it can be sold or stocked.", "item": [ { "name": "Register a product", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/register-product", "host": [ "{{baseUrl}}" ], "path": [ "register-product" ] }, "description": "Register each product once. `unit_price` is tax-inclusive; `commodity_code` comes from Lookups → Commodity categories; `unit_of_measure` from Lookups → Units of measure.", "body": { "mode": "raw", "raw": "{\n \"operationType\": \"101\",\n \"item_code\": \"WTR-500\",\n \"item_name\": \"Bottled water 500ml\",\n \"unit_price\": \"1500\",\n \"commodity_code\": \"50202301\",\n \"unit_of_measure\": \"101\",\n \"is_service\": false,\n \"stock_prewarning\": \"10\"\n}", "options": { "raw": { "language": "json" } } } }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const r = pm.response.json();", "pm.test('Succeeded', () => pm.expect(r.success, r.detail).to.eql(true));" ] } } ], "response": [ { "name": "Registered", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/register-product", "host": [ "{{baseUrl}}" ], "path": [ "register-product" ] }, "description": "Register each product once. `unit_price` is tax-inclusive; `commodity_code` comes from Lookups → Commodity categories; `unit_of_measure` from Lookups → Units of measure.", "body": { "mode": "raw", "raw": "{\n \"operationType\": \"101\",\n \"item_code\": \"WTR-500\",\n \"item_name\": \"Bottled water 500ml\",\n \"unit_price\": \"1500\",\n \"commodity_code\": \"50202301\",\n \"unit_of_measure\": \"101\",\n \"is_service\": false,\n \"stock_prewarning\": \"10\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"message\": \"The product was registered with EFRIS.\",\n \"productCode\": \"WTR-500\",\n \"efrisResponse\": null\n}" } ] }, { "name": "Update a product", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/register-product", "host": [ "{{baseUrl}}" ], "path": [ "register-product" ] }, "description": "Send the same `item_code` with `operationType` `102` when the price or description changes.", "body": { "mode": "raw", "raw": "{\n \"operationType\": \"102\",\n \"item_code\": \"WTR-500\",\n \"item_name\": \"Bottled water 500ml\",\n \"unit_price\": \"1600\",\n \"commodity_code\": \"50202301\",\n \"unit_of_measure\": \"101\"\n}", "options": { "raw": { "language": "json" } } } }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const r = pm.response.json();", "pm.test('Succeeded', () => pm.expect(r.success, r.detail).to.eql(true));" ] } } ] }, { "name": "Register a product with piece units", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/register-product", "host": [ "{{baseUrl}}" ], "path": [ "register-product" ] }, "description": "For goods sold both in bulk and singly — here a crate of 24 bottles. Invoice such a product with `package_scaled`, `piece_scaled` and `piece_qty` on each line.", "body": { "mode": "raw", "raw": "{\n \"operationType\": \"101\",\n \"item_code\": \"WTR-CRATE\",\n \"item_name\": \"Bottled water crate (24)\",\n \"unit_price\": \"34000\",\n \"commodity_code\": \"50202301\",\n \"unit_of_measure\": \"101\",\n \"have_piece_unit\": \"101\",\n \"package_scaled_value\": \"1\",\n \"piece_scaled_value\": \"24\",\n \"piece_measure_unit\": \"101\",\n \"piece_unit_price\": \"1500\"\n}", "options": { "raw": { "language": "json" } } } }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const r = pm.response.json();", "pm.test('Succeeded', () => pm.expect(r.success, r.detail).to.eql(true));" ] } } ] }, { "name": "Register a product with excise duty (percentage)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/register-product", "host": [ "{{baseUrl}}" ], "path": [ "register-product" ] }, "description": "For an excise code with a percentage rate. Look codes up with Lookups → Excise duty codes.", "body": { "mode": "raw", "raw": "{\n \"operationType\": \"101\",\n \"item_code\": \"BELL-500\",\n \"item_name\": \"Bell Lager 500ml\",\n \"unit_price\": \"4720\",\n \"commodity_code\": \"2203001000\",\n \"unit_of_measure\": \"102\",\n \"have_piece_unit\": \"102\",\n \"have_excise_tax\": \"101\",\n \"excise_duty_code\": \"LED190100\"\n}", "options": { "raw": { "language": "json" } } } }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const r = pm.response.json();", "pm.test('Succeeded', () => pm.expect(r.success, r.detail).to.eql(true));" ] } } ] }, { "name": "Register a product with excise duty (fixed amount per unit)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/register-product", "host": [ "{{baseUrl}}" ], "path": [ "register-product" ] }, "description": "For an excise code with a fixed amount per unit, `have_piece_unit` must be `101`, with `piece_measure_unit` as the excise unit and `piece_unit_price` as `unit_price ÷ piece_scaled_value`.", "body": { "mode": "raw", "raw": "{\n \"operationType\": \"101\",\n \"item_code\": \"WATER-1L\",\n \"item_name\": \"Mineral Water 1L\",\n \"unit_price\": \"2000\",\n \"commodity_code\": \"50202310\",\n \"unit_of_measure\": \"102\",\n \"have_piece_unit\": \"101\",\n \"piece_measure_unit\": \"102\",\n \"piece_scaled_value\": \"1\",\n \"package_scaled_value\": \"1\",\n \"piece_unit_price\": \"2000\",\n \"have_excise_tax\": \"101\",\n \"excise_duty_code\": \"LED190400\"\n}", "options": { "raw": { "language": "json" } } } }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const r = pm.response.json();", "pm.test('Succeeded', () => pm.expect(r.success, r.detail).to.eql(true));" ] } } ] }, { "name": "Register many products", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/register-products", "host": [ "{{baseUrl}}" ], "path": [ "register-products" ] }, "description": "Each entry takes the same fields as a single registration. If any are refused, `detail` names each one and why.", "body": { "mode": "raw", "raw": "{\n \"products\": [\n {\n \"item_code\": \"WTR-500\",\n \"item_name\": \"Bottled water 500ml\",\n \"unit_price\": \"1500\",\n \"commodity_code\": \"50202301\",\n \"unit_of_measure\": \"101\"\n },\n {\n \"item_code\": \"WTR-1L\",\n \"item_name\": \"Bottled water 1L\",\n \"unit_price\": \"2500\",\n \"commodity_code\": \"50202301\",\n \"unit_of_measure\": \"101\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const r = pm.response.json();", "pm.test('Succeeded', () => pm.expect(r.success, r.detail).to.eql(true));" ] } } ] } ] }, { "name": "3. Stock", "description": "Record stock before selling, unless negative stock is allowed for your business.", "item": [ { "name": "Stock received", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/stock-increase", "host": [ "{{baseUrl}}" ], "path": [ "stock-increase" ] }, "description": "`stockInType`: `101` import, `102` local purchase, `103` manufacture (no supplier; send `productionBatchNo` and `productionDate`), `104` opening stock.", "body": { "mode": "raw", "raw": "{\n \"goodsStockIn\": {\n \"supplierName\": \"Crown Beverages Ltd\",\n \"supplierTin\": \"1000001234\",\n \"stockInType\": \"102\",\n \"stockInDate\": \"{{today}}\",\n \"goodsTypeCode\": \"101\"\n },\n \"goodsStockInItem\": [\n {\n \"goodsCode\": \"WTR-500\",\n \"quantity\": \"240\",\n \"unitPrice\": \"1000\",\n \"measureUnit\": \"101\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const r = pm.response.json();", "pm.test('Succeeded', () => pm.expect(r.success, r.detail).to.eql(true));" ] } } ], "response": [ { "name": "Recorded", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/stock-increase", "host": [ "{{baseUrl}}" ], "path": [ "stock-increase" ] }, "description": "`stockInType`: `101` import, `102` local purchase, `103` manufacture (no supplier; send `productionBatchNo` and `productionDate`), `104` opening stock.", "body": { "mode": "raw", "raw": "{\n \"goodsStockIn\": {\n \"supplierName\": \"Crown Beverages Ltd\",\n \"supplierTin\": \"1000001234\",\n \"stockInType\": \"102\",\n \"stockInDate\": \"{{today}}\",\n \"goodsTypeCode\": \"101\"\n },\n \"goodsStockInItem\": [\n {\n \"goodsCode\": \"WTR-500\",\n \"quantity\": \"240\",\n \"unitPrice\": \"1000\",\n \"measureUnit\": \"101\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"message\": \"The stock increase was recorded.\",\n \"efrisResponse\": []\n}" } ] }, { "name": "Opening stock", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/stock-increase", "host": [ "{{baseUrl}}" ], "path": [ "stock-increase" ] }, "description": "Use when first going live.", "body": { "mode": "raw", "raw": "{\n \"goodsStockIn\": {\n \"supplierName\": \"Opening balance\",\n \"stockInType\": \"104\",\n \"stockInDate\": \"{{today}}\"\n },\n \"goodsStockInItem\": [\n {\n \"goodsCode\": \"WTR-500\",\n \"quantity\": \"500\",\n \"unitPrice\": \"1000\",\n \"measureUnit\": \"101\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const r = pm.response.json();", "pm.test('Succeeded', () => pm.expect(r.success, r.detail).to.eql(true));" ] } } ] }, { "name": "Stock written down", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/stock-decrease", "host": [ "{{baseUrl}}" ], "path": [ "stock-decrease" ] }, "description": "`adjustType` is required: `101` expired, `102` damaged, `103` personal use, `104` others (`remarks` required), `105` raw materials.", "body": { "mode": "raw", "raw": "{\n \"goodsStockIn\": {\n \"adjustType\": \"102\",\n \"remarks\": \"Damaged in the warehouse\"\n },\n \"goodsStockInItem\": [\n {\n \"goodsCode\": \"WTR-500\",\n \"quantity\": \"12\",\n \"unitPrice\": \"1000\",\n \"measureUnit\": \"101\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const r = pm.response.json();", "pm.test('Succeeded', () => pm.expect(r.success, r.detail).to.eql(true));" ] } } ] }, { "name": "Transfer between branches", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/stock-transfer", "host": [ "{{baseUrl}}" ], "path": [ "stock-transfer" ] }, "description": "Set `sourceBranchId` and `destinationBranchId` in the collection variables, from Lookups → Branches. `transferTypeCode`: `101` out-of-stock adjust, `102` error adjust, `103` other (`remarks` required). `rollBackIfError` `\"1\"` cancels the whole transfer if any line fails.", "body": { "mode": "raw", "raw": "{\n \"goodsStockTransfer\": {\n \"sourceBranchId\": \"{{sourceBranchId}}\",\n \"destinationBranchId\": \"{{destinationBranchId}}\",\n \"transferTypeCode\": \"101\",\n \"remarks\": \"\",\n \"rollBackIfError\": \"0\",\n \"goodsTypeCode\": \"101\"\n },\n \"goodsStockTransferItem\": [\n {\n \"goodsCode\": \"WTR-500\",\n \"measureUnit\": \"101\",\n \"quantity\": \"48\",\n \"remarks\": \"\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const r = pm.response.json();", "pm.test('Succeeded', () => pm.expect(r.success, r.detail).to.eql(true));" ] } } ] } ] }, { "name": "4. Invoices and receipts", "description": "A business registered for VAT issues tax invoices, every item with a tax type (`18` standard, `0` zero-rated, `\"-\"` exempt); one without VAT issues receipts, with no VAT on the items. The wrong document, a receipt with VAT, or an invoice item with no tax type is refused with what to fix — nothing is changed for you. Always send `\"format\": \"simple\"` and tax-inclusive prices. Never resend a sale that timed out without looking it up first (Lookups → Search invoices).", "item": [ { "name": "Tax invoice", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/submit-invoice", "host": [ "{{baseUrl}}" ], "path": [ "submit-invoice" ] }, "description": "For a business registered for VAT. `tax_rate` is required on every item: `18` standard, `0` zero-rated, `\"-\"` exempt — each kept as sent. `buyer_type`: `0` business (`customer_tin` required), `1` individual, `2` foreigner, `3` government. Store the whole response: it is everything needed to print the document.", "body": { "mode": "raw", "raw": "{\n \"format\": \"simple\",\n \"invoice_number\": \"INV-{{$timestamp}}\",\n \"invoice_date\": \"{{today}}\",\n \"customer_name\": \"Nakawa Traders Ltd\",\n \"customer_tin\": \"1000999888\",\n \"customer_email\": \"accounts@nakawatraders.ug\",\n \"customer_phone\": \"0772000000\",\n \"buyer_type\": \"0\",\n \"payment_method\": \"102\",\n \"currency\": \"UGX\",\n \"operator\": \"Jane Kasule\",\n \"remarks\": \"Thank you for your business\",\n \"items\": [\n {\n \"item_name\": \"Bottled water 500ml\",\n \"item_code\": \"WTR-500\",\n \"unit_price\": 1500,\n \"unit_of_measure\": \"101\",\n \"goods_category_id\": \"50202301\",\n \"quantity\": 12,\n \"tax_rate\": 18\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const r = pm.response.json();", "if (r.success) {", " pm.collectionVariables.set('fdn', r.fdn);", " pm.collectionVariables.set('efrisInvoiceId', (r.fiscalData || {}).efrisInvoiceId || '');", " pm.collectionVariables.set('invoiceNumber', r.invoiceNumber);", "}", "pm.test('Fiscalised', () => pm.expect(r.success, r.detail).to.eql(true));" ] } } ], "response": [ { "name": "Fiscalised", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/submit-invoice", "host": [ "{{baseUrl}}" ], "path": [ "submit-invoice" ] }, "description": "For a business registered for VAT. `tax_rate` is required on every item: `18` standard, `0` zero-rated, `\"-\"` exempt — each kept as sent. `buyer_type`: `0` business (`customer_tin` required), `1` individual, `2` foreigner, `3` government. Store the whole response: it is everything needed to print the document.", "body": { "mode": "raw", "raw": "{\n \"format\": \"simple\",\n \"invoice_number\": \"INV-{{$timestamp}}\",\n \"invoice_date\": \"{{today}}\",\n \"customer_name\": \"Nakawa Traders Ltd\",\n \"customer_tin\": \"1000999888\",\n \"customer_email\": \"accounts@nakawatraders.ug\",\n \"customer_phone\": \"0772000000\",\n \"buyer_type\": \"0\",\n \"payment_method\": \"102\",\n \"currency\": \"UGX\",\n \"operator\": \"Jane Kasule\",\n \"remarks\": \"Thank you for your business\",\n \"items\": [\n {\n \"item_name\": \"Bottled water 500ml\",\n \"item_code\": \"WTR-500\",\n \"unit_price\": 1500,\n \"unit_of_measure\": \"101\",\n \"goods_category_id\": \"50202301\",\n \"quantity\": 12,\n \"tax_rate\": 18\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"message\": \"The invoice was fiscalised.\",\n \"invoiceNumber\": \"INV-2026-000412\",\n \"fdn\": \"325043056477\",\n \"verificationCode\": \"234893273725405146366\",\n \"qrCode\": \"iVBORw0KGgo…\",\n \"fiscalisedAt\": \"2026-09-25T08:30:00.000Z\",\n \"seller\": {\n \"tin\": \"1000000001\",\n \"legalName\": \"Nakawa Traders Ltd\",\n \"tradeName\": \"Nakawa Traders Ltd\",\n \"address\": \"Plot 1, Kampala Road, Kampala\",\n \"referenceNumber\": \"INV-2026-000412\",\n \"servedBy\": \"Jane Kasule\"\n },\n \"fiscalData\": {\n \"documentType\": \"Original\",\n \"invoiceKind\": \"1\",\n \"fdn\": \"325043056477\",\n \"verificationCode\": \"234893273725405146366\",\n \"deviceNumber\": \"1000000001_02\",\n \"efrisInvoiceId\": \"8741236598741236\",\n \"issuedDate\": \"2026-09-25\",\n \"issuedTime\": \"11:30:00\",\n \"qrCode\": \"iVBORw0KGgo…\"\n },\n \"buyer\": {\n \"name\": \"Nakawa Traders Ltd\",\n \"tin\": \"1000999888\",\n \"buyerType\": \"0\"\n },\n \"items\": [\n {\n \"item\": \"Bottled water 500ml\",\n \"itemCode\": \"WTR-500\",\n \"qty\": \"12\",\n \"unitOfMeasure\": \"101\",\n \"unitPrice\": \"1500.00\",\n \"total\": \"18000.00\",\n \"taxRate\": \"0.18\",\n \"tax\": \"2745.76\",\n \"taxCategoryCode\": \"01\",\n \"discountFlag\": \"2\",\n \"orderNumber\": \"0\"\n }\n ],\n \"taxDetails\": [\n {\n \"taxCategoryCode\": \"01\",\n \"netAmount\": \"15254.24\",\n \"taxRate\": \"0.18\",\n \"taxAmount\": \"2745.76\",\n \"grossAmount\": \"18000.00\",\n \"taxRateName\": \"Standard Rate (18%)\"\n }\n ],\n \"summary\": {\n \"netAmount\": 15254.24,\n \"taxAmount\": 2745.76,\n \"grossAmount\": 18000,\n \"amountPayable\": 18000,\n \"amountInWords\": \"Eighteen thousand shillings only\",\n \"paymentMode\": \"Cash\",\n \"currency\": \"UGX\",\n \"itemCount\": 1,\n \"remarks\": \"Thank you for your business\"\n }\n}" }, { "name": "Refused: item not registered", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/submit-invoice", "host": [ "{{baseUrl}}" ], "path": [ "submit-invoice" ] }, "description": "For a business registered for VAT. `tax_rate` is required on every item: `18` standard, `0` zero-rated, `\"-\"` exempt — each kept as sent. `buyer_type`: `0` business (`customer_tin` required), `1` individual, `2` foreigner, `3` government. Store the whole response: it is everything needed to print the document.", "body": { "mode": "raw", "raw": "{\n \"format\": \"simple\",\n \"invoice_number\": \"INV-{{$timestamp}}\",\n \"invoice_date\": \"{{today}}\",\n \"customer_name\": \"Nakawa Traders Ltd\",\n \"customer_tin\": \"1000999888\",\n \"customer_email\": \"accounts@nakawatraders.ug\",\n \"customer_phone\": \"0772000000\",\n \"buyer_type\": \"0\",\n \"payment_method\": \"102\",\n \"currency\": \"UGX\",\n \"operator\": \"Jane Kasule\",\n \"remarks\": \"Thank you for your business\",\n \"items\": [\n {\n \"item_name\": \"Bottled water 500ml\",\n \"item_code\": \"WTR-500\",\n \"unit_price\": 1500,\n \"unit_of_measure\": \"101\",\n \"goods_category_id\": \"50202301\",\n \"quantity\": 12,\n \"tax_rate\": 18\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "status": "Bad Request", "code": 400, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": \"Bad request\",\n \"detail\": \"EFRIS error 2122: goodsDetails-->itemCode:Item code and Name is not configured with URA. What to do: This item is not registered with URA. Register the product (item code and name) first, then send the invoice again.\",\n \"ura\": {\n \"code\": \"2122\",\n \"message\": \"goodsDetails-->itemCode:Item code and Name is not configured with URA.\",\n \"field\": \"Items → item code\",\n \"hint\": \"This item is not registered with URA. Register the product (item code and name) first, then send the invoice again.\"\n }\n}" }, { "name": "Refused: item with no tax type", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/submit-invoice", "host": [ "{{baseUrl}}" ], "path": [ "submit-invoice" ] }, "description": "For a business registered for VAT. `tax_rate` is required on every item: `18` standard, `0` zero-rated, `\"-\"` exempt — each kept as sent. `buyer_type`: `0` business (`customer_tin` required), `1` individual, `2` foreigner, `3` government. Store the whole response: it is everything needed to print the document.", "body": { "mode": "raw", "raw": "{\n \"format\": \"simple\",\n \"invoice_number\": \"INV-{{$timestamp}}\",\n \"invoice_date\": \"{{today}}\",\n \"customer_name\": \"Nakawa Traders Ltd\",\n \"customer_tin\": \"1000999888\",\n \"customer_email\": \"accounts@nakawatraders.ug\",\n \"customer_phone\": \"0772000000\",\n \"buyer_type\": \"0\",\n \"payment_method\": \"102\",\n \"currency\": \"UGX\",\n \"operator\": \"Jane Kasule\",\n \"remarks\": \"Thank you for your business\",\n \"items\": [\n {\n \"item_name\": \"Bottled water 500ml\",\n \"item_code\": \"WTR-500\",\n \"unit_price\": 1500,\n \"unit_of_measure\": \"101\",\n \"goods_category_id\": \"50202301\",\n \"quantity\": 12,\n \"tax_rate\": 18\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "status": "Bad Request", "code": 400, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": \"Bad request\",\n \"detail\": \"This business is registered for VAT, so each item on its tax invoice must state its VAT. No tax rate was given for: Bottled water 500ml. Set the VAT on the item in your system (18 standard, 0 zero-rated, \\\"-\\\" exempt) and send the sale again, so your books match the invoice URA issues.\"\n}" } ] }, { "name": "Receipt", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/submit-receipt", "host": [ "{{baseUrl}}" ], "path": [ "submit-receipt" ] }, "description": "For a business not registered for VAT: no VAT on any item (leave `tax_rate` out, or send `0`). The response has the same shape as an invoice's, with `fiscalData.invoiceKind` `\"2\"` — print it as a receipt. Such a business sending a tax invoice is refused and told to issue receipts.", "body": { "mode": "raw", "raw": "{\n \"format\": \"simple\",\n \"invoice_number\": \"RCPT-{{$timestamp}}\",\n \"invoice_date\": \"{{today}}\",\n \"customer_name\": \"Walk-in Customer\",\n \"payment_method\": \"102\",\n \"operator\": \"Jane Kasule\",\n \"items\": [\n {\n \"item_name\": \"Bottled water 500ml\",\n \"item_code\": \"WTR-500\",\n \"unit_price\": 1500,\n \"unit_of_measure\": \"101\",\n \"goods_category_id\": \"50202301\",\n \"quantity\": 12\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const r = pm.response.json();", "if (r.success) {", " pm.collectionVariables.set('fdn', r.fdn);", " pm.collectionVariables.set('efrisInvoiceId', (r.fiscalData || {}).efrisInvoiceId || '');", " pm.collectionVariables.set('invoiceNumber', r.invoiceNumber);", "}", "pm.test('Fiscalised', () => pm.expect(r.success, r.detail).to.eql(true));" ] } } ], "response": [ { "name": "Refused: VAT charged on a receipt", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/submit-receipt", "host": [ "{{baseUrl}}" ], "path": [ "submit-receipt" ] }, "description": "For a business not registered for VAT: no VAT on any item (leave `tax_rate` out, or send `0`). The response has the same shape as an invoice's, with `fiscalData.invoiceKind` `\"2\"` — print it as a receipt. Such a business sending a tax invoice is refused and told to issue receipts.", "body": { "mode": "raw", "raw": "{\n \"format\": \"simple\",\n \"invoice_number\": \"RCPT-{{$timestamp}}\",\n \"invoice_date\": \"{{today}}\",\n \"customer_name\": \"Walk-in Customer\",\n \"payment_method\": \"102\",\n \"operator\": \"Jane Kasule\",\n \"items\": [\n {\n \"item_name\": \"Bottled water 500ml\",\n \"item_code\": \"WTR-500\",\n \"unit_price\": 1500,\n \"unit_of_measure\": \"101\",\n \"goods_category_id\": \"50202301\",\n \"quantity\": 12\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "status": "Bad Request", "code": 400, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": \"Bad request\",\n \"detail\": \"A receipt carries no VAT - it is what URA issues a business that is not registered for VAT. VAT was charged on: Bottled water 500ml (18%). Remove the VAT in your system (set the item to no VAT) and send the sale again, so your books match the receipt URA issues.\"\n}" } ] }, { "name": "Sale to an individual", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/submit-invoice", "host": [ "{{baseUrl}}" ], "path": [ "submit-invoice" ] }, "description": "A walk-in sale: `buyer_type` `1`, no customer TIN.", "body": { "mode": "raw", "raw": "{\n \"format\": \"simple\",\n \"invoice_number\": \"INV-{{$timestamp}}\",\n \"invoice_date\": \"{{today}}\",\n \"customer_name\": \"Walk-in Customer\",\n \"buyer_type\": \"1\",\n \"payment_method\": \"105\",\n \"items\": [\n {\n \"item_name\": \"Bottled water 500ml\",\n \"item_code\": \"WTR-500\",\n \"unit_price\": 1500,\n \"unit_of_measure\": \"101\",\n \"goods_category_id\": \"50202301\",\n \"quantity\": 2,\n \"tax_rate\": 18\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const r = pm.response.json();", "if (r.success) {", " pm.collectionVariables.set('fdn', r.fdn);", " pm.collectionVariables.set('efrisInvoiceId', (r.fiscalData || {}).efrisInvoiceId || '');", " pm.collectionVariables.set('invoiceNumber', r.invoiceNumber);", "}", "pm.test('Fiscalised', () => pm.expect(r.success, r.detail).to.eql(true));" ] } } ] }, { "name": "Sale of a zero-rated item", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/submit-invoice", "host": [ "{{baseUrl}}" ], "path": [ "submit-invoice" ] }, "description": "Zero-rated (`0`) and exempt (`\"-\"`) are tax types of their own, kept exactly as sent — goods zero-rated for local sale stay zero-rated.", "body": { "mode": "raw", "raw": "{\n \"format\": \"simple\",\n \"invoice_number\": \"INV-{{$timestamp}}\",\n \"invoice_date\": \"{{today}}\",\n \"customer_name\": \"Walk-in Customer\",\n \"buyer_type\": \"1\",\n \"payment_method\": \"102\",\n \"items\": [\n {\n \"item_name\": \"Hoe\",\n \"item_code\": \"HOE-01\",\n \"quantity\": 2,\n \"unit_price\": 15000,\n \"tax_rate\": 0,\n \"unit_of_measure\": \"101\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const r = pm.response.json();", "if (r.success) {", " pm.collectionVariables.set('fdn', r.fdn);", " pm.collectionVariables.set('efrisInvoiceId', (r.fiscalData || {}).efrisInvoiceId || '');", " pm.collectionVariables.set('invoiceNumber', r.invoiceNumber);", "}", "pm.test('Fiscalised', () => pm.expect(r.success, r.detail).to.eql(true));" ] } } ] }, { "name": "Sale with a discount", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/submit-invoice", "host": [ "{{baseUrl}}" ], "path": [ "submit-invoice" ] }, "description": "`discount` is the tax-inclusive amount off the line. It appears as its own line on the document.", "body": { "mode": "raw", "raw": "{\n \"format\": \"simple\",\n \"invoice_number\": \"INV-{{$timestamp}}\",\n \"invoice_date\": \"{{today}}\",\n \"customer_name\": \"Walk-in Customer\",\n \"buyer_type\": \"1\",\n \"payment_method\": \"102\",\n \"items\": [\n {\n \"item_name\": \"Bottled water 500ml\",\n \"item_code\": \"WTR-500\",\n \"unit_price\": 24000,\n \"unit_of_measure\": \"101\",\n \"goods_category_id\": \"50202301\",\n \"quantity\": 5,\n \"tax_rate\": 18,\n \"discount\": 10000\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const r = pm.response.json();", "if (r.success) {", " pm.collectionVariables.set('fdn', r.fdn);", " pm.collectionVariables.set('efrisInvoiceId', (r.fiscalData || {}).efrisInvoiceId || '');", " pm.collectionVariables.set('invoiceNumber', r.invoiceNumber);", "}", "pm.test('Fiscalised', () => pm.expect(r.success, r.detail).to.eql(true));" ] } } ] }, { "name": "Sale with excise duty", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/submit-invoice", "host": [ "{{baseUrl}}" ], "path": [ "submit-invoice" ] }, "description": "`excise_rule` `1` percentage (`excise_rate` `10` means 10%) or `2` fixed amount per unit (`excise_rate` is the amount, `excise_unit` the unit). `excise_tax` is the line's excise amount, as your system calculates it.", "body": { "mode": "raw", "raw": "{\n \"format\": \"simple\",\n \"invoice_number\": \"INV-{{$timestamp}}\",\n \"invoice_date\": \"{{today}}\",\n \"customer_name\": \"Walk-in Customer\",\n \"buyer_type\": \"1\",\n \"payment_method\": \"102\",\n \"items\": [\n {\n \"item_name\": \"Bell Lager 500ml\",\n \"item_code\": \"BELL-500\",\n \"quantity\": 24,\n \"unit_price\": 4720,\n \"tax_rate\": 18,\n \"unit_of_measure\": \"101\",\n \"excise_flag\": \"1\",\n \"category_id\": \"BEV001\",\n \"category_name\": \"Beer & Malt Beverages\",\n \"excise_rule\": \"2\",\n \"excise_rate\": \"650\",\n \"excise_tax\": \"7800\",\n \"excise_unit\": \"102\",\n \"excise_currency\": \"UGX\",\n \"package_scaled\": \"1\",\n \"piece_scaled\": \"500\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const r = pm.response.json();", "if (r.success) {", " pm.collectionVariables.set('fdn', r.fdn);", " pm.collectionVariables.set('efrisInvoiceId', (r.fiscalData || {}).efrisInvoiceId || '');", " pm.collectionVariables.set('invoiceNumber', r.invoiceNumber);", "}", "pm.test('Fiscalised', () => pm.expect(r.success, r.detail).to.eql(true));" ] } } ] }, { "name": "Sale with deemed VAT", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/submit-invoice", "host": [ "{{baseUrl}}" ], "path": [ "submit-invoice" ] }, "description": "For businesses supplying under a deemed-VAT project. `vat_project_id` and `vat_project_name` come from URA's project registry. `deemed_exempt_code`: see the guide's appendix.", "body": { "mode": "raw", "raw": "{\n \"format\": \"simple\",\n \"invoice_number\": \"INV-{{$timestamp}}\",\n \"invoice_date\": \"{{today}}\",\n \"customer_name\": \"Ministry of Works\",\n \"customer_tin\": \"1000555444\",\n \"buyer_type\": \"3\",\n \"payment_method\": \"101\",\n \"items\": [\n {\n \"item_name\": \"Consulting services\",\n \"item_code\": \"SVC-CONSULT-01\",\n \"quantity\": 1,\n \"unit_price\": 5000000,\n \"tax_rate\": 18,\n \"goods_category_id\": \"73110000\",\n \"deemed_flag\": \"1\",\n \"deemed_exempt_code\": \"101\",\n \"vat_project_id\": \"893997229738400343\",\n \"vat_project_name\": \"Strategic Investor Project\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const r = pm.response.json();", "if (r.success) {", " pm.collectionVariables.set('fdn', r.fdn);", " pm.collectionVariables.set('efrisInvoiceId', (r.fiscalData || {}).efrisInvoiceId || '');", " pm.collectionVariables.set('invoiceNumber', r.invoiceNumber);", "}", "pm.test('Fiscalised', () => pm.expect(r.success, r.detail).to.eql(true));" ] } } ] }, { "name": "Export invoice", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/submit-invoice", "host": [ "{{baseUrl}}" ], "path": [ "submit-invoice" ] }, "description": "`invoice_industry_code` `102` export goods, `112` export service. `delivery_terms_code`, and `total_weight` (net kg), `piece_qty` and `piece_measure_unit` on every line, are required; export goods also need the `customs` block.", "body": { "mode": "raw", "raw": "{\n \"format\": \"simple\",\n \"invoice_number\": \"EXP-{{$timestamp}}\",\n \"invoice_date\": \"{{today}}\",\n \"customer_name\": \"Nairobi Traders Ltd\",\n \"buyer_type\": \"2\",\n \"payment_method\": \"107\",\n \"currency\": \"USD\",\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_name\": \"Green coffee beans\",\n \"item_code\": \"COFFEE-001\",\n \"quantity\": 500,\n \"unit_price\": 12000,\n \"tax_rate\": 0,\n \"unit_of_measure\": \"103\",\n \"total_weight\": 500,\n \"piece_qty\": 500,\n \"piece_measure_unit\": \"103\",\n \"hs_code\": \"0901110000\",\n \"hs_name\": \"Coffee, not roasted, not decaffeinated\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const r = pm.response.json();", "if (r.success) {", " pm.collectionVariables.set('fdn', r.fdn);", " pm.collectionVariables.set('efrisInvoiceId', (r.fiscalData || {}).efrisInvoiceId || '');", " pm.collectionVariables.set('invoiceNumber', r.invoiceNumber);", "}", "pm.test('Fiscalised', () => pm.expect(r.success, r.detail).to.eql(true));" ] } } ] }, { "name": "Export invoice status", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/export-invoice-status?invoiceNo={{fdn}}", "host": [ "{{baseUrl}}" ], "path": [ "export-invoice-status" ], "query": [ { "key": "invoiceNo", "value": "{{fdn}}", "description": "Fiscal document number of the export" } ] }, "description": "The status of an export, by its fiscal document number." }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const r = pm.response.json();", "pm.test('Succeeded', () => pm.expect(r.success, r.detail).to.eql(true));" ] } } ] } ] }, { "name": "5. Credit notes", "description": "A credit note is an application to URA: a successful response means URA received it. Send positive quantities and amounts, and credit each item as it was sold — the same item code, unit price and tax rate.", "item": [ { "name": "Credit note", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/submit-credit-note", "host": [ "{{baseUrl}}" ], "path": [ "submit-credit-note" ] }, "description": "Credits the last sale made in this collection (`{{fdn}}`). Against a tax invoice every item states its tax type, as on the invoice. `reason_code`: `101` return of products, `102` cancellation of purchase, `103` amount wrongly stated, `104` waive-off, `105` other (explain in `reason`).", "body": { "mode": "raw", "raw": "{\n \"credit_note_number\": \"CN-{{$timestamp}}\",\n \"credit_note_date\": \"{{today}}\",\n \"original_invoice_number\": \"{{fdn}}\",\n \"original_fdn\": \"{{fdn}}\",\n \"customer_name\": \"Nakawa Traders Ltd\",\n \"customer_tin\": \"1000999888\",\n \"buyer_type\": \"0\",\n \"reason\": \"Goods returned\",\n \"reason_code\": \"101\",\n \"items\": [\n {\n \"item_name\": \"Bottled water 500ml\",\n \"item_code\": \"WTR-500\",\n \"quantity\": 2,\n \"unit_price\": 1500,\n \"tax_rate\": 18,\n \"unit_of_measure\": \"101\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const r = pm.response.json();", "if (r.success) pm.collectionVariables.set('referenceNo', r.referenceNo);", "pm.test('Submitted', () => pm.expect(r.success, r.detail).to.eql(true));" ] } } ], "response": [ { "name": "Submitted", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/submit-credit-note", "host": [ "{{baseUrl}}" ], "path": [ "submit-credit-note" ] }, "description": "Credits the last sale made in this collection (`{{fdn}}`). Against a tax invoice every item states its tax type, as on the invoice. `reason_code`: `101` return of products, `102` cancellation of purchase, `103` amount wrongly stated, `104` waive-off, `105` other (explain in `reason`).", "body": { "mode": "raw", "raw": "{\n \"credit_note_number\": \"CN-{{$timestamp}}\",\n \"credit_note_date\": \"{{today}}\",\n \"original_invoice_number\": \"{{fdn}}\",\n \"original_fdn\": \"{{fdn}}\",\n \"customer_name\": \"Nakawa Traders Ltd\",\n \"customer_tin\": \"1000999888\",\n \"buyer_type\": \"0\",\n \"reason\": \"Goods returned\",\n \"reason_code\": \"101\",\n \"items\": [\n {\n \"item_name\": \"Bottled water 500ml\",\n \"item_code\": \"WTR-500\",\n \"quantity\": 2,\n \"unit_price\": 1500,\n \"tax_rate\": 18,\n \"unit_of_measure\": \"101\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"message\": \"The credit note application was submitted.\",\n \"referenceNo\": \"24092500001\",\n \"creditNoteNumber\": \"CN-2026-001\",\n \"amount\": 3000,\n \"itemCount\": 1,\n \"submittedAt\": \"2026-09-25T09:10:00.000Z\",\n \"efrisResponse\": {\n \"referenceNo\": \"24092500001\"\n }\n}" } ] }, { "name": "Credit note against a receipt", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/submit-credit-note", "host": [ "{{baseUrl}}" ], "path": [ "submit-credit-note" ] }, "description": "No VAT, as the receipt had none: leave `tax_rate` out, or send `0`.", "body": { "mode": "raw", "raw": "{\n \"credit_note_number\": \"CN-{{$timestamp}}\",\n \"credit_note_date\": \"{{today}}\",\n \"original_invoice_number\": \"{{fdn}}\",\n \"original_fdn\": \"{{fdn}}\",\n \"customer_name\": \"Walk-in Customer\",\n \"reason\": \"Goods returned\",\n \"reason_code\": \"101\",\n \"items\": [\n {\n \"item_name\": \"Bottled water 500ml\",\n \"item_code\": \"WTR-500\",\n \"quantity\": 2,\n \"unit_price\": 1500,\n \"unit_of_measure\": \"101\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const r = pm.response.json();", "if (r.success) pm.collectionVariables.set('referenceNo', r.referenceNo);", "pm.test('Submitted', () => pm.expect(r.success, r.detail).to.eql(true));" ] } } ], "response": [ { "name": "Refused: VAT on a credit note against a receipt", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/submit-credit-note", "host": [ "{{baseUrl}}" ], "path": [ "submit-credit-note" ] }, "description": "No VAT, as the receipt had none: leave `tax_rate` out, or send `0`.", "body": { "mode": "raw", "raw": "{\n \"credit_note_number\": \"CN-{{$timestamp}}\",\n \"credit_note_date\": \"{{today}}\",\n \"original_invoice_number\": \"{{fdn}}\",\n \"original_fdn\": \"{{fdn}}\",\n \"customer_name\": \"Walk-in Customer\",\n \"reason\": \"Goods returned\",\n \"reason_code\": \"101\",\n \"items\": [\n {\n \"item_name\": \"Bottled water 500ml\",\n \"item_code\": \"WTR-500\",\n \"quantity\": 2,\n \"unit_price\": 1500,\n \"unit_of_measure\": \"101\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "status": "Bad Request", "code": 400, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"error\": \"Bad request\",\n \"detail\": \"This credit note is against a receipt, and a receipt carries no VAT - so its credit note carries none either. VAT was charged on: Bottled water 500ml (18%). Remove the VAT from the credit note in your system (set the item to no VAT) and send it again, so your books match URA's.\"\n}" } ] }, { "name": "Invoices that can be credited", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/creditable-invoices?page=1&pageSize=10", "host": [ "{{baseUrl}}" ], "path": [ "creditable-invoices" ], "query": [ { "key": "page", "value": "1", "description": "" }, { "key": "pageSize", "value": "10", "description": "" }, { "key": "invoiceNo", "value": "", "description": "Fiscal document number", "disabled": true }, { "key": "buyerTin", "value": "", "description": "", "disabled": true }, { "key": "startDate", "value": "", "description": "YYYY-MM-DD", "disabled": true }, { "key": "endDate", "value": "", "description": "YYYY-MM-DD", "disabled": true } ] }, "description": "Invoices a credit note can still be raised against." }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const r = pm.response.json();", "pm.test('Succeeded', () => pm.expect(r.success, r.detail).to.eql(true));" ] } } ] }, { "name": "What remains creditable on an invoice", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/invoice-remain-details?invoiceNo={{fdn}}", "host": [ "{{baseUrl}}" ], "path": [ "invoice-remain-details" ], "query": [ { "key": "invoiceNo", "value": "{{fdn}}", "description": "Fiscal document number of the invoice" } ] }, "description": "Quantities and amounts still creditable on each line." }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const r = pm.response.json();", "pm.test('Succeeded', () => pm.expect(r.success, r.detail).to.eql(true));" ] } } ] }, { "name": "Track a credit note", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/credit-notes?referenceNo={{referenceNo}}", "host": [ "{{baseUrl}}" ], "path": [ "credit-notes" ], "query": [ { "key": "referenceNo", "value": "{{referenceNo}}", "description": "From the credit note response" } ] }, "description": "The status of a credit note application." }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const r = pm.response.json();", "pm.test('Succeeded', () => pm.expect(r.success, r.detail).to.eql(true));" ] } } ] }, { "name": "Cancel a credit note", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/cancel-credit-note", "host": [ "{{baseUrl}}" ], "path": [ "cancel-credit-note" ] }, "description": "`ori_invoice_id` is the original invoice's `fiscalData.efrisInvoiceId`; `invoice_no` is the credit note's fiscal document number (set `creditNoteFdn`). `reason_code`: `101` buyer refused it as incorrect, `102` not delivered as incorrect, `103` other (`reason` required). `invoice_apply_category_code` `104` cancels a credit note.", "body": { "mode": "raw", "raw": "{\n \"ori_invoice_id\": \"{{efrisInvoiceId}}\",\n \"invoice_no\": \"{{creditNoteFdn}}\",\n \"reason_code\": \"103\",\n \"reason\": \"Credit note issued in error\",\n \"invoice_apply_category_code\": \"104\"\n}", "options": { "raw": { "language": "json" } } } }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const r = pm.response.json();", "pm.test('Succeeded', () => pm.expect(r.success, r.detail).to.eql(true));" ] } } ] } ] }, { "name": "6. Lookups", "description": "Reference data for filling in the fields above, and finding past documents.", "item": [ { "name": "Registration details and branches", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/registration-details", "host": [ "{{baseUrl}}" ], "path": [ "registration-details" ] }, "description": "Your registration details and branches." }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const r = pm.response.json();", "pm.test('Succeeded', () => pm.expect(r.success, r.detail).to.eql(true));" ] } } ] }, { "name": "Branches", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/branches", "host": [ "{{baseUrl}}" ], "path": [ "branches" ] }, "description": "Branch ids, for stock transfers." }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const r = pm.response.json();", "pm.test('Succeeded', () => pm.expect(r.success, r.detail).to.eql(true));" ] } } ] }, { "name": "Units of measure", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/units-of-measure", "host": [ "{{baseUrl}}" ], "path": [ "units-of-measure" ] }, "description": "Units of measure, currencies and excise units." }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const r = pm.response.json();", "pm.test('Succeeded', () => pm.expect(r.success, r.detail).to.eql(true));" ] } } ] }, { "name": "Payment methods", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/payment-methods", "host": [ "{{baseUrl}}" ], "path": [ "payment-methods" ] }, "description": "URA's current payment methods, as codes and names - the codes a sale's `payment_method` takes. Use it to fill your system's payment dropdown." }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const r = pm.response.json();", "pm.test('Succeeded', () => pm.expect(r.success, r.detail).to.eql(true));" ] } } ], "response": [ { "name": "URA's list", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/payment-methods", "host": [ "{{baseUrl}}" ], "path": [ "payment-methods" ] }, "description": "URA's current payment methods, as codes and names - the codes a sale's `payment_method` takes. Use it to fill your system's payment dropdown." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": true,\n \"result\": [\n {\n \"code\": \"101\",\n \"name\": \"Credit\"\n },\n {\n \"code\": \"102\",\n \"name\": \"Cash\"\n }\n ],\n \"returnCode\": \"00\"\n}" } ] }, { "name": "Commodity categories", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/commodity-categories?page=1&pageSize=50", "host": [ "{{baseUrl}}" ], "path": [ "commodity-categories" ], "query": [ { "key": "page", "value": "1", "description": "" }, { "key": "pageSize", "value": "50", "description": "" } ] }, "description": "Commodity category codes, for product registration." }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const r = pm.response.json();", "pm.test('Succeeded', () => pm.expect(r.success, r.detail).to.eql(true));" ] } } ] }, { "name": "Excise duty codes", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/excise-duty?name=beer", "host": [ "{{baseUrl}}" ], "path": [ "excise-duty" ], "query": [ { "key": "name", "value": "beer", "description": "Part of the name" }, { "key": "code", "value": "", "description": "An exact code, e.g. LED190100", "disabled": true } ] }, "description": "Excise duty codes and rates. Filter by `name` or `code`." }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const r = pm.response.json();", "pm.test('Succeeded', () => pm.expect(r.success, r.detail).to.eql(true));" ] } } ] }, { "name": "HS codes", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/hs-codes", "host": [ "{{baseUrl}}" ], "path": [ "hs-codes" ] }, "description": "HS tariff codes, for exports." }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const r = pm.response.json();", "pm.test('Succeeded', () => pm.expect(r.success, r.detail).to.eql(true));" ] } } ] }, { "name": "Buyer by TIN", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/taxpayer/:tin", "host": [ "{{baseUrl}}" ], "path": [ "taxpayer", ":tin" ], "variable": [ { "key": "tin", "value": "1000999888", "description": "The buyer's TIN" } ] }, "description": "A buyer's registered details, for business sales." }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const r = pm.response.json();", "pm.test('Succeeded', () => pm.expect(r.success, r.detail).to.eql(true));" ] } } ] }, { "name": "Exchange rate", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/exchange-rate?currency=USD", "host": [ "{{baseUrl}}" ], "path": [ "exchange-rate" ], "query": [ { "key": "currency", "value": "USD", "description": "Required" }, { "key": "issueDate", "value": "{{today}}", "description": "YYYY-MM-DD", "disabled": true } ] }, "description": "The rate for one currency." }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const r = pm.response.json();", "pm.test('Succeeded', () => pm.expect(r.success, r.detail).to.eql(true));" ] } } ] }, { "name": "Registered products", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/goods?page=1&pageSize=10", "host": [ "{{baseUrl}}" ], "path": [ "goods" ], "query": [ { "key": "goodsCode", "value": "", "description": "", "disabled": true }, { "key": "goodsName", "value": "", "description": "", "disabled": true }, { "key": "page", "value": "1", "description": "" }, { "key": "pageSize", "value": "10", "description": "" } ] }, "description": "Your registered products." }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const r = pm.response.json();", "pm.test('Succeeded', () => pm.expect(r.success, r.detail).to.eql(true));" ] } } ] }, { "name": "Negative stock setting", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/negative-stock-configuration", "host": [ "{{baseUrl}}" ], "path": [ "negative-stock-configuration" ] }, "description": "Whether selling without recorded stock is allowed." }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const r = pm.response.json();", "pm.test('Succeeded', () => pm.expect(r.success, r.detail).to.eql(true));" ] } } ] }, { "name": "One invoice", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/invoice/:fdn", "host": [ "{{baseUrl}}" ], "path": [ "invoice", ":fdn" ], "variable": [ { "key": "fdn", "value": "{{fdn}}", "description": "Fiscal document number" } ] }, "description": "One fiscalised document's details, by its fiscal document number." }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const r = pm.response.json();", "pm.test('Succeeded', () => pm.expect(r.success, r.detail).to.eql(true));" ] } } ] }, { "name": "Search invoices", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/invoices?startDate={{today}}&endDate={{today}}&page=1&pageSize=20", "host": [ "{{baseUrl}}" ], "path": [ "invoices" ], "query": [ { "key": "startDate", "value": "{{today}}", "description": "YYYY-MM-DD" }, { "key": "endDate", "value": "{{today}}", "description": "YYYY-MM-DD" }, { "key": "page", "value": "1", "description": "" }, { "key": "pageSize", "value": "20", "description": "" }, { "key": "invoiceNo", "value": "", "description": "Fiscal document number", "disabled": true }, { "key": "buyerLegalName", "value": "", "description": "", "disabled": true }, { "key": "invoiceKind", "value": "", "description": "1 tax invoice, 2 receipt", "disabled": true } ] }, "description": "Find a sale whose submission timed out before resending it: search the day and match on your invoice number." }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const r = pm.response.json();", "pm.test('Succeeded', () => pm.expect(r.success, r.detail).to.eql(true));" ] } } ] } ] } ] }