{"openapi":"3.0.3","info":{"title":"EFRIS Integration API","version":"1.0.0","description":"Submit invoices, credit notes, products and stock movements to the Uganda Revenue\nAuthority EFRIS service without implementing the EFRIS protocol yourself.\n\n## Authentication\n\nEvery request carries your API key in the `X-API-Key` header. Keys are issued per\ntaxpayer, and the taxpayer they belong to determines which TIN documents are filed\nunder — the TIN is never taken from the request body.\n\n## Field naming\n\nRequest fields are accepted in either `snake_case` or `camelCase`. Use whichever\nyour system already produces.\n\n## Amounts and tax\n\nPrices are treated as tax-inclusive, which is how they are quoted in Uganda. Send\n`\"format\": \"simple\"` and the gateway derives the net, the tax and the EFRIS tax\nbreakdown from the quantity, unit price and rate. Send pre-computed EFRIS fields\ninstead and they are used as given.\n\n## Errors\n\nFailures return a JSON body with `success: false`, a short `error` label and a\n`detail` sentence. When URA rejects a document, `detail` carries its return code\nand the specific per-line reason where one was given."},"servers":[{"url":"https://efrisgateway.com","description":"This deployment"}],"tags":[{"name":"Invoices","description":"Fiscalise and retrieve invoices"},{"name":"Credit notes","description":"Reverse part or all of an invoice"},{"name":"Products","description":"Register goods and services with URA"},{"name":"Stock","description":"Record stock movements and transfers"},{"name":"Reference data","description":"Codes, rates and taxpayer lookups"},{"name":"Fuel stations","description":"Electronic dispensing controllers (EDC)"},{"name":"Device","description":"Device registration, TCS upgrades and onboarding"},{"name":"Diagnostics","description":"Connectivity and configuration checks"}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"The API key issued for your taxpayer account."}},"schemas":{"Error":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Bad request"},"detail":{"type":"string","example":"EFRIS error 2253: The reference number has already been issued."},"details":{"description":"Field-level problems, when the failure was a validation one."}},"required":["success","error","detail"]},"InvoiceItem":{"type":"object","required":["item_name","quantity","unit_price"],"properties":{"item_name":{"type":"string","example":"Bottled water 500ml"},"item_code":{"type":"string","description":"The product code registered with URA.","example":"WTR-500"},"quantity":{"type":"number","example":12},"unit_price":{"type":"number","description":"Tax-inclusive price per unit.","example":1500},"tax_rate":{"description":"Percentage or fraction. Use 0 for zero-rated and \"-\" for exempt.","example":18,"oneOf":[{"type":"number"},{"type":"string"}]},"discount":{"type":"number","description":"Discount on this line. A separate EFRIS discount line is generated.","example":0},"unit_of_measure":{"type":"string","example":"102"},"goods_category_id":{"type":"string","description":"Commodity category code. Left out, the product's registered category is used.","example":"50202306"},"excise_flag":{"type":"string","enum":["1","2"],"description":"1 when excise applies."},"excise_rate":{"type":"number"},"excise_tax":{"type":"number"},"deemed_flag":{"type":"string","enum":["1","2"]}}},"InvoiceRequest":{"type":"object","required":["invoice_number","invoice_date","customer_name","items"],"properties":{"format":{"type":"string","enum":["simple"],"description":"Send \"simple\" to have every EFRIS field derived from the fields below."},"invoice_number":{"type":"string","description":"Your own document number. URA requires it to be unique per taxpayer.","example":"INV-2026-000412"},"invoice_date":{"type":"string","format":"date","example":"2026-08-21"},"customer_name":{"type":"string","example":"Nakawa Traders Ltd"},"customer_tin":{"type":"string","description":"Required when buyer_type is \"0\".","example":"1000012345"},"customer_address":{"type":"string"},"customer_email":{"type":"string","format":"email"},"customer_phone":{"type":"string"},"buyer_type":{"type":"string","enum":["0","1","2","3"],"default":"1","description":"0 business, 1 individual, 2 foreigner, 3 government."},"payment_method":{"type":"string","enum":["101","102","103","104","105","106","107","108","109","110"],"default":"101","description":"101 credit, 102 cash, 105 mobile money, 106 card."},"currency":{"type":"string","default":"UGX"},"remarks":{"type":"string"},"invoice_industry_code":{"type":"string","enum":["101","102","112"],"default":"101","description":"101 general, 102 export, 112 export service."},"delivery_terms_code":{"type":"string","description":"An Incoterm such as FOB or CIF. Required on export documents."},"items":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceItem"},"minItems":1}}},"InvoiceResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"invoiceNumber":{"type":"string","description":"The reference URA accepted. It differs from the one sent only if that one was already used."},"fdn":{"type":"string","description":"The fiscal document number assigned by URA.","example":"325043056477"},"verificationCode":{"type":"string","example":"234893273725405146366"},"qrCode":{"type":"string","description":"Base64 QR code image for the printed document."},"fiscalisedAt":{"type":"string","format":"date-time"},"seller":{"type":"object"},"buyer":{"type":"object"},"items":{"type":"array","items":{"type":"object"}},"taxDetails":{"type":"array","items":{"type":"object"}},"summary":{"type":"object","properties":{"netAmount":{"type":"number"},"taxAmount":{"type":"number"},"grossAmount":{"type":"number"},"amountPayable":{"type":"number","description":"Net plus every tax, excise included. This is what the buyer pays."},"amountInWords":{"type":"string"},"paymentMode":{"type":"string"},"itemCount":{"type":"integer"}}}}},"CreditNoteRequest":{"type":"object","required":["credit_note_number","original_invoice_number","customer_name","reason","items"],"properties":{"credit_note_number":{"type":"string","example":"CN-2026-0031"},"credit_note_date":{"type":"string","format":"date"},"original_invoice_number":{"type":"string","example":"INV-2026-000412"},"original_fdn":{"type":"string","description":"The original invoice's fiscal document number. Strongly recommended."},"customer_name":{"type":"string"},"customer_tin":{"type":"string"},"reason":{"type":"string","example":"Goods returned"},"reason_code":{"type":"string","enum":["101","102","103","104","105"],"description":"Derived from the reason text when omitted."},"currency":{"type":"string","default":"UGX"},"items":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceItem"},"minItems":1}}},"ProductRequest":{"type":"object","required":["item_code","item_name","unit_price","commodity_code"],"properties":{"item_code":{"type":"string","example":"WTR-500"},"item_name":{"type":"string","example":"Bottled water 500ml"},"unit_price":{"type":"number","example":1500},"commodity_code":{"type":"string","description":"URA commodity category code.","example":"50202306"},"unit_of_measure":{"type":"string","default":"102"},"description":{"type":"string"},"is_service":{"type":"boolean","default":false},"have_excise_tax":{"type":"string","enum":["101","102"],"default":"102"},"excise_duty_code":{"type":"string","description":"Required when have_excise_tax is \"101\"."},"stock_prewarning":{"type":"string","description":"Low-stock threshold for physical goods."},"operationType":{"type":"string","enum":["101","102"],"default":"101","description":"101 registers a new product, 102 updates an existing one."}}},"StockRequest":{"type":"object","required":["goodsStockIn","goodsStockInItem"],"properties":{"goodsStockIn":{"type":"object","properties":{"supplierTin":{"type":"string"},"supplierName":{"type":"string"},"stockInType":{"type":"string","enum":["101","102","103","104"],"description":"101 import, 102 local purchase, 103 manufacture, 104 opening stock."},"stockInDate":{"type":"string","format":"date"},"adjustType":{"type":"string","enum":["101","102","103","104","105"],"description":"Required when reducing stock: 101 expired, 102 damaged, 103 personal use."},"remarks":{"type":"string"}}},"goodsStockInItem":{"type":"array","minItems":1,"items":{"type":"object","required":["goodsCode","quantity"],"properties":{"goodsCode":{"type":"string"},"quantity":{"type":"string"},"unitPrice":{"type":"string"},"measureUnit":{"type":"string"}}}}}},"Acknowledgement":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"efrisResponse":{"description":"URA's decoded response body."}}}},"responses":{"Unauthorized":{"description":"The API key is missing, unrecognised, or disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Rejected":{"description":"The request was refused, either by validation here or by URA.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"The account has used its daily request quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Upstream":{"description":"URA could not be reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"security":[{"ApiKey":[]}],"paths":{"/api/efris/invoice-remain-details":{"get":{"tags":["Invoices"],"summary":"Amounts still remaining on an invoice","description":"Interface T186. What is left to credit after any earlier credit notes.","parameters":[{"name":"invoiceNo","in":"query","required":true,"description":"Fiscal document number.","schema":{"type":"string"}}],"responses":{"200":{"description":"Amounts still remaining on an invoice","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/export-invoice-status":{"get":{"tags":["Invoices"],"summary":"Customs status of an export document","description":"Interface T187.","parameters":[{"name":"invoiceNo","in":"query","required":true,"description":"Fiscal document number.","schema":{"type":"string"}}],"responses":{"200":{"description":"Customs status of an export document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/invoice-checks":{"post":{"tags":["Invoices"],"summary":"Reconcile local invoices against URA","description":"Interface T117. Returns the documents that disagree or are unknown; an empty result means everything matches. invoiceType: 1 invoice or receipt, 2 credit note against a known original, 4 debit note, 5 credit note without one.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"invoices":[{"invoiceNo":"325043056477","invoiceType":"1"}]}}}},"responses":{"200":{"description":"Reconcile local invoices against URA","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/batch-invoice-upload":{"post":{"tags":["Invoices"],"summary":"Submit pre-signed invoices in bulk","description":"Interface T129. For offline capture replayed in bulk. A normal integration should use the single-invoice endpoint.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"invoices":[{"invoiceContent":"","invoiceSignature":""}]}}}},"responses":{"200":{"description":"Submit pre-signed invoices in bulk","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/z-report":{"post":{"tags":["Invoices"],"summary":"Daily Z-report","description":"Interface T116.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{}}}},"responses":{"200":{"description":"Daily Z-report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/credit-note-application-details":{"get":{"tags":["Credit notes"],"summary":"One application in full","description":"Interface T118.","parameters":[{"name":"id","in":"query","required":true,"description":"Application id.","schema":{"type":"string"}}],"responses":{"200":{"description":"One application in full","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/credit-note-approval":{"post":{"tags":["Credit notes"],"summary":"Approve or reject an application","description":"Interface T113. approveStatus is \"101\" to approve and \"103\" to reject.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"referenceNo":"","approveStatus":"101","taskId":"","remark":"Approved"}}}},"responses":{"200":{"description":"Approve or reject an application","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/cancel-credit-note":{"post":{"tags":["Credit notes"],"summary":"Cancel a credit note","description":"Interface T114. invoiceApplyCategoryCode \"103\" opens an approval workflow for a debit note; \"104\" and \"105\" change the document status directly.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"oriInvoiceId":"","invoiceNo":"","reasonCode":"102","invoiceApplyCategoryCode":"104","reason":""}}}},"responses":{"200":{"description":"Cancel a credit note","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/void-credit-debit-note-application":{"post":{"tags":["Credit notes"],"summary":"Void a pending application","description":"Interface T120.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"businessKey":"","referenceNo":""}}}},"responses":{"200":{"description":"Void a pending application","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/cancel-credit-note-details":{"get":{"tags":["Credit notes"],"summary":"Detail of a cancelled credit note","description":"Interface T122.","parameters":[{"name":"invoiceNo","in":"query","required":true,"description":"Fiscal document number of the cancelled note.","schema":{"type":"string"}}],"responses":{"200":{"description":"Detail of a cancelled credit note","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/goods-by-code":{"get":{"tags":["Products"],"summary":"Look up products by code","description":"Interface T144.","parameters":[{"name":"goodsCode","in":"query","required":true,"description":"One or more codes, comma separated.","schema":{"type":"string","example":"WTR-500,WTR-1L"}},{"name":"tin","in":"query","required":false,"description":"Principal agent TIN.","schema":{"type":"string"}}],"responses":{"200":{"description":"Look up products by code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/goods-stock-quantity":{"get":{"tags":["Products"],"summary":"Stock level for one product","description":"Interface T128.","parameters":[{"name":"goodsId","in":"query","required":true,"description":"Product id assigned by URA.","schema":{"type":"string"}},{"name":"branchId","in":"query","required":false,"description":"Restrict to one branch.","schema":{"type":"string"}}],"responses":{"200":{"description":"Stock level for one product","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/stock-records":{"get":{"tags":["Stock"],"summary":"Stock records","description":"Interface T145. At least one of the three filters must be supplied.","parameters":[{"name":"page","in":"query","required":false,"description":"Page number, counting from 1.","schema":{"type":"string","example":"1"}},{"name":"pageSize","in":"query","required":false,"description":"Records per page. URA caps this at 100.","schema":{"type":"string","example":"10"}},{"name":"productionBatchNo","in":"query","required":false,"description":"Production batch number.","schema":{"type":"string"}},{"name":"invoiceNo","in":"query","required":false,"description":"Related invoice number.","schema":{"type":"string"}},{"name":"referenceNo","in":"query","required":false,"description":"Stock-in reference number.","schema":{"type":"string"}}],"responses":{"200":{"description":"Stock records","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/branch-stock-records":{"get":{"tags":["Stock"],"summary":"Stock records for the current branch","description":"Interface T147.","parameters":[{"name":"page","in":"query","required":false,"description":"Page number, counting from 1.","schema":{"type":"string","example":"1"}},{"name":"pageSize","in":"query","required":false,"description":"Records per page. URA caps this at 100.","schema":{"type":"string","example":"10"}},{"name":"keywords","in":"query","required":false,"description":"Matches reference number or supplier name.","schema":{"type":"string"}},{"name":"stockInType","in":"query","required":false,"description":"101 import, 102 local purchase, 103 manufacture, 104 opening.","schema":{"type":"string"}},{"name":"startDate","in":"query","required":false,"description":"yyyy-MM-dd","schema":{"type":"string"}},{"name":"endDate","in":"query","required":false,"description":"yyyy-MM-dd","schema":{"type":"string"}},{"name":"supplierTin","in":"query","required":false,"description":"Filter by supplier TIN.","schema":{"type":"string"}}],"responses":{"200":{"description":"Stock records for the current branch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/stock-record-detail":{"get":{"tags":["Stock"],"summary":"One stock-in record in full","description":"Interface T148.","parameters":[{"name":"id","in":"query","required":true,"description":"Record id.","schema":{"type":"string"}}],"responses":{"200":{"description":"One stock-in record in full","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/stock-adjust-records":{"get":{"tags":["Stock"],"summary":"Stock adjustments","description":"Interface T149.","parameters":[{"name":"page","in":"query","required":false,"description":"Page number, counting from 1.","schema":{"type":"string","example":"1"}},{"name":"pageSize","in":"query","required":false,"description":"Records per page. URA caps this at 100.","schema":{"type":"string","example":"10"}},{"name":"referenceNo","in":"query","required":false,"description":"Adjustment reference.","schema":{"type":"string"}},{"name":"startDate","in":"query","required":false,"description":"yyyy-MM-dd","schema":{"type":"string"}},{"name":"endDate","in":"query","required":false,"description":"yyyy-MM-dd","schema":{"type":"string"}}],"responses":{"200":{"description":"Stock adjustments","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/stock-adjust-detail":{"get":{"tags":["Stock"],"summary":"One adjustment in full","description":"Interface T160.","parameters":[{"name":"id","in":"query","required":true,"description":"Adjustment id.","schema":{"type":"string"}}],"responses":{"200":{"description":"One adjustment in full","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/stock-transfers":{"get":{"tags":["Stock"],"summary":"Branch transfers","description":"Interface T183.","parameters":[{"name":"page","in":"query","required":false,"description":"Page number, counting from 1.","schema":{"type":"string","example":"1"}},{"name":"pageSize","in":"query","required":false,"description":"Records per page. URA caps this at 100.","schema":{"type":"string","example":"10"}},{"name":"referenceNo","in":"query","required":false,"description":"Transfer reference.","schema":{"type":"string"}},{"name":"sourceBranchId","in":"query","required":false,"description":"Filter by source branch.","schema":{"type":"string"}},{"name":"destinationBranchId","in":"query","required":false,"description":"Filter by destination branch.","schema":{"type":"string"}}],"responses":{"200":{"description":"Branch transfers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/stock-transfer-detail":{"get":{"tags":["Stock"],"summary":"One transfer in full","description":"Interface T184.","parameters":[{"name":"id","in":"query","required":true,"description":"Transfer id.","schema":{"type":"string"}}],"responses":{"200":{"description":"One transfer in full","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/negative-stock-configuration":{"get":{"tags":["Stock"],"summary":"Negative stock configuration","description":"Interface T177. Whether URA permits this taxpayer to invoice goods into a negative stock position.","responses":{"200":{"description":"Negative stock configuration","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/commodity-category-list":{"get":{"tags":["Reference data"],"summary":"Commodity categories, full list","description":"Interface T123. Large. Prefer the paginated form.","responses":{"200":{"description":"Commodity categories, full list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/commodity-category-updates":{"get":{"tags":["Reference data"],"summary":"Commodity category changes since a version","description":"Interface T134.","parameters":[{"name":"version","in":"query","required":false,"description":"The version held locally.","schema":{"type":"string","example":"1.0"}}],"responses":{"200":{"description":"Commodity category changes since a version","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/category-excise-by-date":{"get":{"tags":["Reference data"],"summary":"Category or excise in force on a date","description":"Interface T146. Needed when re-issuing a document for an earlier period.","parameters":[{"name":"categoryCode","in":"query","required":true,"description":"Commodity category or excise duty code.","schema":{"type":"string"}},{"name":"issueDate","in":"query","required":true,"description":"yyyy-MM-dd HH:mm:ss","schema":{"type":"string"}},{"name":"type","in":"query","required":false,"description":"1 commodity category, 2 excise duty.","schema":{"type":"string","example":"1"}}],"responses":{"200":{"description":"Category or excise in force on a date","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/hs-codes":{"get":{"tags":["Reference data"],"summary":"HS tariff codes","description":"Interface T185. Used on export documents.","responses":{"200":{"description":"HS tariff codes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/exchange-rates":{"get":{"tags":["Reference data"],"summary":"All currency rates against UGX","description":"Interface T126.","parameters":[{"name":"issueDate","in":"query","required":false,"description":"Rate date, as yyyy-MM-dd.","schema":{"type":"string"}}],"responses":{"200":{"description":"All currency rates against UGX","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/taxpayer-exempt-status":{"get":{"tags":["Reference data"],"summary":"Taxpayer exempt or deemed status","description":"Interface T137. Determines whether a line should carry deemed_flag.","parameters":[{"name":"tin","in":"query","required":true,"description":"Taxpayer TIN.","schema":{"type":"string"}},{"name":"commodityCategoryCode","in":"query","required":false,"description":"Codes, comma separated.","schema":{"type":"string"}}],"responses":{"200":{"description":"Taxpayer exempt or deemed status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/agent-relations":{"get":{"tags":["Reference data"],"summary":"Agent relations","description":"Interface T179.","parameters":[{"name":"tin","in":"query","required":false,"description":"Principal agent TIN.","schema":{"type":"string"}}],"responses":{"200":{"description":"Agent relations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/principal-agent":{"get":{"tags":["Reference data"],"summary":"Principal agent information","description":"Interface T180.","parameters":[{"name":"tin","in":"query","required":true,"description":"Principal agent TIN.","schema":{"type":"string"}},{"name":"branchId","in":"query","required":true,"description":"Branch id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Principal agent information","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/frequent-contacts":{"get":{"tags":["Reference data"],"summary":"Saved buyer contacts","description":"Interface T182.","parameters":[{"name":"buyerTin","in":"query","required":false,"description":"Filter by TIN.","schema":{"type":"string"}},{"name":"buyerLegalName","in":"query","required":false,"description":"Filter by name.","schema":{"type":"string"}}],"responses":{"200":{"description":"Saved buyer contacts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/upload-frequent-contact":{"post":{"tags":["Reference data"],"summary":"Add, change or remove a buyer contact","description":"Interface T181. operationType: 101 add, 102 modify, 103 delete. Modify and delete both need the contact id.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"operationType":"101","buyerType":"0","buyerTin":"1000000002","buyerLegalName":"Kampala Wholesalers Ltd"}}}},"responses":{"200":{"description":"Add, change or remove a buyer contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/update-buyer-details":{"post":{"tags":["Reference data"],"summary":"Amend the buyer on an issued invoice","description":"Interface T166. buyerType \"0\" requires a TIN.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"invoiceNo":"","buyerType":"0","buyerTin":"","buyerLegalName":""}}}},"responses":{"200":{"description":"Amend the buyer on an issued invoice","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/fuel-types":{"get":{"tags":["Fuel stations"],"summary":"Fuel type code list","description":"Interface T162.","responses":{"200":{"description":"Fuel type code list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/fuel-shifts":{"post":{"tags":["Fuel stations"],"summary":"Upload an attendant shift","description":"Interface T163.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"shiftNo":"SH-2026-0821-A","startVolume":"10450.00","endVolume":"12300.50","fuelType":"Petrol","goodsCode":"PMS-01","invoiceAmount":"9252500","invoiceNumber":"184","nozzleNo":"1","pumpNo":"1","tankNo":"1","userName":"A. Attendant","userCode":"ATT-01","startTime":"2026-08-21 06:00:00","endTime":"2026-08-21 14:00:00"}}}},"responses":{"200":{"description":"Upload an attendant shift","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/edc-disconnections":{"post":{"tags":["Fuel stations"],"summary":"Report EDC disconnections","description":"Interface T164. disconnectedType: 101 controller disconnection, 102 abnormal transaction.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":[{"deviceNumber":"","disconnectedType":"101","disconnectedTime":"2026-08-21 09:15:00"}]}}},"responses":{"200":{"description":"Report EDC disconnections","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/edc-invoices":{"get":{"tags":["Fuel stations"],"summary":"EDC invoices and receipts","description":"Interface T167.","parameters":[{"name":"page","in":"query","required":false,"description":"Page number, counting from 1.","schema":{"type":"string","example":"1"}},{"name":"pageSize","in":"query","required":false,"description":"Records per page. URA caps this at 100.","schema":{"type":"string","example":"10"}},{"name":"queryType","in":"query","required":false,"description":"1 unmodified, 2 modified contact, 3 all.","schema":{"type":"string","example":"3"}},{"name":"fuelType","in":"query","required":false,"description":"Filter by fuel type.","schema":{"type":"string"}},{"name":"startDate","in":"query","required":false,"description":"yyyy-MM-dd HH:mm:ss","schema":{"type":"string"}},{"name":"endDate","in":"query","required":false,"description":"yyyy-MM-dd HH:mm:ss","schema":{"type":"string"}}],"responses":{"200":{"description":"EDC invoices and receipts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/fuel-pump-versions":{"get":{"tags":["Fuel stations"],"summary":"Registered pump versions","description":"Interface T168.","responses":{"200":{"description":"Registered pump versions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/fuel-pump-details":{"get":{"tags":["Fuel stations"],"summary":"One pump in full","description":"Interface T169.","parameters":[{"name":"id","in":"query","required":true,"description":"Pump id.","schema":{"type":"string"}}],"responses":{"200":{"description":"One pump in full","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/fuel-nozzle-status":{"post":{"tags":["Fuel stations"],"summary":"Report a nozzle status","description":"Interface T172. Status: 1 available, 2 card plugged in, 3 lifted, 4 fuelling, 5 hung, 6 settling, 7 locked, 10 offline.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"nozzleId":"","nozzleNo":"1","status":"1"}}}},"responses":{"200":{"description":"Report a nozzle status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/edc-device-versions":{"get":{"tags":["Fuel stations"],"summary":"Registered device versions","description":"Interface T173.","responses":{"200":{"description":"Registered device versions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/edc-uom-exchange-rates":{"get":{"tags":["Fuel stations"],"summary":"Unit exchange rates","description":"Interface T171.","responses":{"200":{"description":"Unit exchange rates","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/efd-location":{"get":{"tags":["Fuel stations"],"summary":"EFD location history","description":"Interface T170. Only the most recent entries are returned, capped by a URA setting.","parameters":[{"name":"deviceNumber","in":"query","required":true,"description":"Device number.","schema":{"type":"string"}},{"name":"startDate","in":"query","required":false,"description":"yyyy-MM-dd","schema":{"type":"string"}},{"name":"endDate","in":"query","required":false,"description":"yyyy-MM-dd","schema":{"type":"string"}}],"responses":{"200":{"description":"EFD location history","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/client-initialization":{"get":{"tags":["Device"],"summary":"Client initialisation","description":"Interface T102.","parameters":[{"name":"otp","in":"query","required":false,"description":"One-time password issued for the device.","schema":{"type":"string"}}],"responses":{"200":{"description":"Client initialisation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/registration-details":{"get":{"tags":["Device"],"summary":"Taxpayer registration record","description":"Interface T103. The record URA holds, as returned during the session handshake.","responses":{"200":{"description":"Taxpayer registration record","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/tcs-latest-version":{"get":{"tags":["Device"],"summary":"Latest published TCS version","description":"Interface T135.","responses":{"200":{"description":"Latest published TCS version","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/tcs-upgrade-files":{"get":{"tags":["Device"],"summary":"TCS upgrade files","description":"Interface T133.","parameters":[{"name":"tcsVersion","in":"query","required":true,"description":"The version held locally.","schema":{"type":"string","example":"1"}},{"name":"osType","in":"query","required":false,"description":"0 Linux, 1 Windows.","schema":{"type":"string","example":"1"}}],"responses":{"200":{"description":"TCS upgrade files","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/device-issuing-status":{"post":{"tags":["Device"],"summary":"Report a device issuing status","description":"Interface T176. 101 ready, 102 issuing, 103 printing.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"deviceNo":"","deviceIssuingStatus":"101"}}}},"responses":{"200":{"description":"Report a device issuing status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/efd-transfer":{"post":{"tags":["Device"],"summary":"Move the EFD to another branch","description":"Interface T178.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"destinationBranchId":"","remarks":""}}}},"responses":{"200":{"description":"Move the EFD to another branch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/certificate-public-key":{"post":{"tags":["Device"],"summary":"Upload a certificate public key","description":"Interface T136. verifyString is the file name encrypted under a key derived from the TIN and the date.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"fileName":"client.cer","verifyString":"","fileContent":""}}}},"responses":{"200":{"description":"Upload a certificate public key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/ussd-taxpayer-account":{"post":{"tags":["Device"],"summary":"Create a USSD account","description":"Interface T175.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"tin":"","mobileNumber":""}}}},"responses":{"200":{"description":"Create a USSD account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/exception-logs":{"post":{"tags":["Device"],"summary":"Upload exception logs","description":"Interface T132.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"logs":[{"interruptionTypeCode":"101","description":"Login failed","errorDetail":"Connection timed out","interruptionTime":"2026-08-21 09:15:00"}]}}}},"responses":{"200":{"description":"Upload exception logs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/forgot-password":{"post":{"tags":["Device"],"summary":"Request an enterprise password reset","description":"Interface T105. URA emails the account details to the enterprise user.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"userName":"","changedPassword":""}}}},"responses":{"200":{"description":"Request an enterprise password reset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/submit-invoice":{"post":{"tags":["Invoices"],"summary":"Fiscalise an invoice","description":"Submits an invoice to URA and returns the fiscal document number, verification\ncode and QR code, along with the lines and totals as URA recorded them.\n\nIf URA reports the document reference as already used, the invoice is resubmitted\nunder a unique reference rather than being refused — a real sale is never left\nunfiscalised. The reference that was accepted is returned as `invoiceNumber`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceRequest"}}}},"responses":{"200":{"description":"The invoice was fiscalised.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceResponse"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/invoices":{"get":{"tags":["Invoices"],"summary":"Search issued invoices","parameters":[{"name":"page","in":"query","required":false,"description":"Page number, from 1.","schema":{"type":"string"}},{"name":"pageSize","in":"query","required":false,"description":"Records per page, at most 100.","schema":{"type":"string"}},{"name":"startDate","in":"query","required":false,"description":"Earliest issue date, as yyyy-MM-dd.","schema":{"type":"string"}},{"name":"endDate","in":"query","required":false,"description":"Latest issue date, as yyyy-MM-dd.","schema":{"type":"string"}},{"name":"buyerLegalName","in":"query","required":false,"description":"Filter by buyer name.","schema":{"type":"string"}},{"name":"invoiceNo","in":"query","required":false,"description":"Filter by fiscal document number.","schema":{"type":"string"}}],"responses":{"200":{"description":"Matching invoices.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/invoice/{invoiceNumber}":{"get":{"tags":["Invoices"],"summary":"Retrieve one invoice","parameters":[{"name":"invoiceNumber","in":"path","required":true,"description":"The fiscal document number assigned by URA.","schema":{"type":"string"}}],"responses":{"200":{"description":"The invoice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/submit-credit-note":{"post":{"tags":["Credit notes"],"summary":"Raise a credit note application","description":"Lodges an application to reverse part or all of an invoice. URA issues the credit\nnote once the application is accepted, so a successful response here means the\napplication was lodged — track it with the `referenceNo` it returns.\n\nAmounts are sent as positive values and negated for you.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditNoteRequest"}}}},"responses":{"200":{"description":"The application was lodged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/creditable-invoices":{"get":{"tags":["Credit notes"],"summary":"List invoices eligible for a credit note","parameters":[{"name":"page","in":"query","required":false,"description":"Page number, from 1.","schema":{"type":"string"}},{"name":"pageSize","in":"query","required":false,"description":"Records per page.","schema":{"type":"string"}},{"name":"invoiceNo","in":"query","required":false,"description":"Filter by fiscal document number.","schema":{"type":"string"}},{"name":"startDate","in":"query","required":false,"description":"Earliest issue date.","schema":{"type":"string"}},{"name":"endDate","in":"query","required":false,"description":"Latest issue date.","schema":{"type":"string"}}],"responses":{"200":{"description":"Eligible invoices.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/credit-notes":{"get":{"tags":["Credit notes"],"summary":"Search credit note applications","parameters":[{"name":"page","in":"query","required":false,"description":"Page number, from 1.","schema":{"type":"string"}},{"name":"pageSize","in":"query","required":false,"description":"Records per page.","schema":{"type":"string"}},{"name":"referenceNo","in":"query","required":false,"description":"Filter by application reference.","schema":{"type":"string"}},{"name":"oriInvoiceNo","in":"query","required":false,"description":"Filter by the original invoice.","schema":{"type":"string"}}],"responses":{"200":{"description":"Matching applications.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/register-product":{"post":{"tags":["Products"],"summary":"Register a product","description":"A product must exist in URA's catalogue before it can be invoiced. Send `operationType` \"102\" to update one.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductRequest"}}}},"responses":{"200":{"description":"The product was registered.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/register-products":{"post":{"tags":["Products"],"summary":"Register several products","description":"URA reports success per item, so inspect the response body rather than the status alone.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/ProductRequest"}}}}}}},"responses":{"200":{"description":"The batch was submitted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/goods":{"get":{"tags":["Products"],"summary":"List registered products","parameters":[{"name":"page","in":"query","required":false,"description":"Page number, from 1.","schema":{"type":"string"}},{"name":"pageSize","in":"query","required":false,"description":"Records per page.","schema":{"type":"string"}},{"name":"goodsCode","in":"query","required":false,"description":"Filter by product code.","schema":{"type":"string"}},{"name":"goodsName","in":"query","required":false,"description":"Filter by product name.","schema":{"type":"string"}}],"responses":{"200":{"description":"Registered products.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/stock-increase":{"post":{"tags":["Stock"],"summary":"Record stock received","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockRequest"}}}},"responses":{"200":{"description":"The movement was recorded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/stock-decrease":{"post":{"tags":["Stock"],"summary":"Record stock written down","description":"Requires `adjustType` on the header, which states why the stock was removed.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockRequest"}}}},"responses":{"200":{"description":"The movement was recorded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/stock-transfer":{"post":{"tags":["Stock"],"summary":"Move stock between branches","description":"Branch ids come from the branches endpoint, not from your own numbering.","responses":{"200":{"description":"The transfer was recorded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/branches":{"get":{"tags":["Reference data"],"summary":"List the taxpayer's branches","responses":{"200":{"description":"Registered branches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/commodity-categories":{"get":{"tags":["Reference data"],"summary":"List commodity categories","parameters":[{"name":"page","in":"query","required":false,"description":"Page number.","schema":{"type":"string"}},{"name":"pageSize","in":"query","required":false,"description":"Records per page.","schema":{"type":"string"}}],"responses":{"200":{"description":"Commodity categories.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/excise-duty":{"get":{"tags":["Reference data"],"summary":"List excise duty codes and rates","parameters":[{"name":"code","in":"query","required":false,"description":"Filter by excise duty code.","schema":{"type":"string"}},{"name":"name","in":"query","required":false,"description":"Filter by name.","schema":{"type":"string"}}],"responses":{"200":{"description":"Excise duties.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/exchange-rate":{"get":{"tags":["Reference data"],"summary":"Get a currency rate against UGX","parameters":[{"name":"currency","in":"query","required":true,"description":"Three-letter currency code.","schema":{"type":"string","example":"USD"}},{"name":"issueDate","in":"query","required":false,"description":"Rate date, as yyyy-MM-dd.","schema":{"type":"string"}}],"responses":{"200":{"description":"The exchange rate.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/taxpayer/{tin}":{"get":{"tags":["Reference data"],"summary":"Look up a taxpayer by TIN","parameters":[{"name":"tin","in":"path","required":true,"schema":{"type":"string"}},{"name":"ninBrn","in":"query","required":false,"description":"National identification or business registration number.","schema":{"type":"string"}}],"responses":{"200":{"description":"The taxpayer record.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/system-dictionary":{"get":{"tags":["Reference data"],"summary":"Get the EFRIS code lists","description":"Currencies, units of measure, excise rate types and the other dictionaries.","responses":{"200":{"description":"The code lists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/server-time":{"get":{"tags":["Diagnostics"],"summary":"Get URA's server time","description":"The lightest way to confirm the connection and certificate are working.","responses":{"200":{"description":"The server time.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/efris/diagnostics":{"get":{"tags":["Diagnostics"],"summary":"Check this account's configuration and connectivity","description":"Reports what the gateway holds for the taxpayer and whether a live handshake succeeds. Answers with a body even when the handshake fails.","responses":{"200":{"description":"The diagnostic report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/efris/passthrough/{interfaceCode}":{"post":{"tags":["Diagnostics"],"summary":"Call any EFRIS interface directly","description":"Sends a body of your own to any interface code, for interfaces URA has added since\nthis gateway was last updated. Nothing is validated beyond the encryption mode.","parameters":[{"name":"interfaceCode","in":"path","required":true,"schema":{"type":"string","example":"T109"}},{"name":"encryptCode","in":"query","required":false,"description":"Request encryption: 0 none, 1 signed, 2 encrypted. Defaults to 1.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"URA's decoded response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Acknowledgement"}}}},"400":{"$ref":"#/components/responses/Rejected"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/Upstream"}}}}}}