EDC Invoice/Receipt Inquiry (T167)

Query Electronic Dispensing Controller (EDC) invoices and receipts with filtering options for fuel type, date range, and modification status. This endpoint provides paginated results with detailed invoice information including pump, nozzle, and fuel type data for gas station operations. Request and response are encrypted.

Endpoint Overview

Property	Value
Interface Code	`T167`
Request Encrypted	✅ Yes
Response Encrypted	✅ Yes
Request Body	`{ "fuelType": "...", "invoiceNo": "...", "startDate": "...", ... }`
Response Format	JSON with pagination

Flow Description

Client submits query with optional filters (fuel type, invoice number, buyer name, date range, branch ID) and pagination parameters.
Server validates the request parameters and filters against EDC invoice records.
Server queries invoices based on queryType (unmodified, modified, or all).
Server returns paginated results with invoice details including EDC-specific fields (pump, nozzle, fuel type).
Client displays records or uses data for reconciliation and reporting.

💡 Tip: Use T167 to query EDC-specific invoices that include pump/nozzle information not available in standard invoice queries (T106). Use queryType to filter by modification status.

PHP
JavaScript / TypeScript
Python

try {
    // Call T167: EDC Invoice/Receipt Inquiry
    $filters = [
        'fuelType' => 'Petrol',                    // Optional: Filter by fuel type
        'invoiceNo' => '321000229045',             // Optional: Specific invoice number
        'buyerLegalName' => 'UGANDA REVENUE AUTHORITY', // Optional: Buyer name
        'startDate' => '2025-02-19',               // Optional: Start date
        'endDate' => '2025-02-19',                 // Optional: End date
        'pageNo' => 1,
        'pageSize' => 10,
        'queryType' => '1',                        // 1=Unmodified, 2=Modified, 3=All
        'branchId' => '2020090132456'              // Optional: Branch ID
    ];
    
    $response = $client->edcInvoiceQuery($filters);
    $content = $response['data']['content'] ?? $response;
    $records = $content['records'] ?? [];
    $page = $content['page'] ?? [];
    
    if (!empty($records)) {
        echo "✅ Retrieved " . count($records) . " EDC invoice(s)\n";
        echo "   Page: {$page['pageNo']}/{$page['pageCount']} (Total: {$page['totalSize']})\n";
        
        foreach ($records as $invoice) {
            echo "   • Invoice: {$invoice['invoiceNo']}\n";
            echo "     Buyer: {$invoice['buyerLegalName']}\n";
            echo "     Fuel Type: {$invoice['fuelType']}\n";
            echo "     Pump: {$invoice['pumpNo']}, Nozzle: {$invoice['nozzleNo']}\n";
            echo "     Amount: {$invoice['grossAmount']} {$invoice['currency']}\n";
            echo "     Date: {$invoice['issuedDate']}\n";
            echo "     Update Times: {$invoice['updateTimes']}\n";
            echo "\n";
        }
    } else {
        echo "⚠️  No EDC invoices found for provided criteria\n";
    }
    
} catch (\UraEfrisSdk\Exceptions\APIException $e) {
    echo "❌ Query failed: " . $e->getMessage() . "\n";
    echo "   Return Code: " . $e->getReturnCode() . "\n";
}

try {
    // Call T167: EDC Invoice/Receipt Inquiry
    const filters = {
        fuelType: 'Petrol',                       // Optional: Filter by fuel type
        invoiceNo: '321000229045',                // Optional: Specific invoice number
        buyerLegalName: 'UGANDA REVENUE AUTHORITY', // Optional: Buyer name
        startDate: '2025-02-19',                  // Optional: Start date
        endDate: '2025-02-19',                    // Optional: End date
        pageNo: 1,
        pageSize: 10,
        queryType: '1',                           // 1=Unmodified, 2=Modified, 3=All
        branchId: '2020090132456'                 // Optional: Branch ID
    };
    
    const response = await client.edcInvoiceQuery(filters);
    const content = response?.data?.content ?? response;
    const records = content?.records ?? [];
    const page = content?.page ?? {};
    
    if (records.length > 0) {
        console.log(`✅ Retrieved ${records.length} EDC invoice(s)`);
        console.log(`   Page: ${page.pageNo}/${page.pageCount} (Total: ${page.totalSize})`);
        
        for (const invoice of records) {
            console.log(`   • Invoice: ${invoice.invoiceNo}`);
            console.log(`     Buyer: ${invoice.buyerLegalName}`);
            console.log(`     Fuel Type: ${invoice.fuelType}`);
            console.log(`     Pump: ${invoice.pumpNo}, Nozzle: ${invoice.nozzleNo}`);
            console.log(`     Amount: ${invoice.grossAmount} ${invoice.currency}`);
            console.log(`     Date: ${invoice.issuedDate}`);
            console.log(`     Update Times: ${invoice.updateTimes}`);
            console.log('');
        }
        
        return content;
    } else {
        console.warn('⚠️  No EDC invoices found for provided criteria');
        return { records: [], page };
    }
    
} catch (error: any) {
    console.error(`❌ Query failed: ${error.message}`);
    if (error.returnCode) {
        console.error(`   Return Code: ${error.returnCode}`);
    }
    throw error;
}

try:
    # Call T167: EDC Invoice/Receipt Inquiry
    filters = {
        "fuelType": "Petrol",                      # Optional: Filter by fuel type
        "invoiceNo": "321000229045",               # Optional: Specific invoice number
        "buyerLegalName": "UGANDA REVENUE AUTHORITY", # Optional: Buyer name
        "startDate": "2025-02-19",                 # Optional: Start date
        "endDate": "2025-02-19",                   # Optional: End date
        "pageNo": 1,
        "pageSize": 10,
        "queryType": "1",                          # 1=Unmodified, 2=Modified, 3=All
        "branchId": "2020090132456"                # Optional: Branch ID
    }
    
    response = client.edc_invoice_query(filters)
    content = response.get("data", {}).get("content", response)
    records = content.get("records", [])
    page = content.get("page", {})
    
    if records:
        print(f"✅ Retrieved {len(records)} EDC invoice(s)")
        print(f"   Page: {page.get('pageNo')}/{page.get('pageCount')} (Total: {page.get('totalSize')})")
        
        for invoice in records:
            print(f"   • Invoice: {invoice['invoiceNo']}")
            print(f"     Buyer: {invoice['buyerLegalName']}")
            print(f"     Fuel Type: {invoice['fuelType']}")
            print(f"     Pump: {invoice['pumpNo']}, Nozzle: {invoice['nozzleNo']}")
            print(f"     Amount: {invoice['grossAmount']} {invoice['currency']}")
            print(f"     Date: {invoice['issuedDate']}")
            print(f"     Update Times: {invoice['updateTimes']}")
            print()
        
    else:
        print("⚠️  No EDC invoices found for provided criteria")
    
except Exception as e:
    print(f"❌ Query failed: {e}")
    if hasattr(e, "return_code"):
        print(f"   Return Code: {e.return_code}")
    raise

Request Structure

{
  "data": {
    "content": "BASE64_ENCRYPTED_PAYLOAD",
    "signature": "JKQWJK34K32JJEK2JQWJ5678",
    "dataDescription": {
      "codeType": "1",
      "encryptCode": "2",
      "zipCode": "0"
    }
  },
  "globalInfo": {
    "interfaceCode": "T167",
    "appId": "AP04",
    "version": "1.1.20191201",
    "tin": "1000029771",
    "deviceNo": "TCS9e0df01728335239",
    "taxpayerID": "1"
  }
}

Request Fields (Encrypted Payload)

Field	Required	Type	Length	Description
`fuelType`	❌ No	String	≤200	Fuel type filter (e.g., "Petrol", "Diesel", "Naphtha")
`invoiceNo`	❌ No	String	≤20	Specific invoice number to query
`buyerLegalName`	❌ No	String	≤256	Buyer legal name filter
`startDate`	❌ No	Date	-	Start date for filtering (yyyy-MM-dd HH:mm:ss)
`endDate`	❌ No	Date	-	End date for filtering (yyyy-MM-dd HH:mm:ss)
`pageNo`	✅ Yes	Number	≤10	Current page number (starts from 1)
`pageSize`	✅ Yes	Number	≤3	Records per page; cannot exceed 100
`queryType`	✅ Yes	String (1)	1	1=Unmodified invoices, 2=Modified invoices, 3=All invoices
`branchId`	❌ No	String	≤18	Branch identifier for filtering

💡 Tip: All filter fields are optional except pagination (pageNo, pageSize) and queryType. Use specific filters to narrow results for better performance.

Response Structure

{
  "data": {
    "content": {
      "page": {
        "pageNo": "1",
        "pageSize": "10",
        "totalSize": "50",
        "pageCount": "5"
      },
      "records": [
        {
          "id": "159078217852531032",
          "invoiceNo": "00000000001",
          "oriInvoiceId": "00000000003",
          "oriInvoiceNo": "00000000002",
          "issuedDate": "19/02/2025 10:00:00",
          "buyerTin": "1000029771",
          "buyerLegalName": "UGANDA REVENUE AUTHORITY",
          "buyerNinBrn": "00000000001",
          "currency": "UGX",
          "grossAmount": "2000.00",
          "taxAmount": "2000.00",
          "dataSource": "101",
          "isInvalid": "1",
          "isRefund": "1",
          "invoiceType": "1",
          "invoiceKind": "1",
          "invoiceIndustryCode": "102",
          "branchName": "Mr. RAJIV DINESH GANDHI",
          "deviceNo": "121241304906446273",
          "uploadingTime": "19/02/2025 10:00:00",
          "referenceNo": "00000000012",
          "operator": "administrator",
          "userName": "Mr. ANDREW KIIZA",
          "pumpNo": "000001",
          "nozzleNo": "000002",
          "fuelType": "Petrol",
          "updateTimes": "1"
        }
      ]
    }
  },
  "globalInfo": {
    "interfaceCode": "T167",
    "returnStateInfo": {
      "returnCode": "00",
      "returnMessage": "SUCCESS"
    }
  }
}

Response Fields

Pagination Object

Field	Required	Type	Description
`pageNo`	✅ Yes	Number	Current page number
`pageSize`	✅ Yes	Number	Records per page
`totalSize`	✅ Yes	Number	Total number of matching records
`pageCount`	✅ Yes	Number	Total number of pages

Invoice Records Array Items

Field	Required	Type	Length	Description
`id`	✅ Yes	String	≤32	Unique invoice identifier
`invoiceNo`	✅ Yes	String	≤30	Invoice number (FDN)
`oriInvoiceId`	❌ No	String	≤32	Original invoice ID (for credit/debit notes)
`oriInvoiceNo`	❌ No	String	≤30	Original invoice number (for credit/debit notes)
`issuedDate`	✅ Yes	Date	-	Invoice issue date (dd/MM/yyyy HH:mm:ss)
`buyerTin`	❌ No	String	10-20	Buyer's Taxpayer Identification Number
`buyerLegalName`	✅ Yes	String	≤256	Buyer legal name
`buyerNinBrn`	❌ No	String	≤100	Buyer NIN/BRN
`currency`	✅ Yes	String	≤10	Currency code (e.g., UGX)
`grossAmount`	✅ Yes	Number	-	Total invoice amount
`taxAmount`	✅ Yes	Number	-	Total tax amount
`dataSource`	✅ Yes	String (3)	3	101=EFD, 102=Windows Client, 103=WebService API, 104=Mis, 105=Webportal, 106=Offline Mode Enabler
`isInvalid`	✅ Yes	String (1)	1	1=Obsolete, 0=Not obsolete
`isRefund`	❌ No	String (1)	1	0=No credit/debit, 1=Credit issued, 2=Debit issued
`invoiceType`	✅ Yes	String (1)	1	1=Invoice/Receipt, 2=Credit Note With FDN, 3=Credit Note Without FDN, 4=Debit Note
`invoiceKind`	✅ Yes	String (1)	1	1=Invoice, 2=Receipt
`invoiceIndustryCode`	❌ No	String (3)	3	Industry code (e.g., 110=EDC)
`branchName`	❌ No	String	≤500	Branch name
`deviceNo`	✅ Yes	String	≤50	Device serial number
`uploadingTime`	✅ Yes	Date	-	Server upload timestamp
`referenceNo`	❌ No	String	≤50	Seller's reference number
`operator`	❌ No	String	≤100	Operator name
`userName`	❌ No	String	≤500	User name
`pumpNo`	❌ No	String	≤50	Fuel pump number (EDC-specific)
`nozzleNo`	❌ No	String	≤50	Fuel nozzle number (EDC-specific)
`fuelType`	❌ No	String	≤200	Fuel type dispensed (EDC-specific)
`updateTimes`	❌ No	Number	-	Number of times invoice was modified

💡 Tip: EDC-specific fields (pumpNo, nozzleNo, fuelType, updateTimes) distinguish T167 results from standard invoice queries (T106). Use updateTimes to track buyer detail modifications (T166).

Return Codes

Code	Message	Description
`00`	SUCCESS	EDC invoices retrieved successfully
`99`	Unknown error	Generic server error
`400`	Device does not exist	`deviceNo` not registered for this TIN
`402`	Device key expired	Device credentials expired; re-run T102
`403`	Device status is abnormal	Device blocked or suspended
`1521`	pageNo:cannot be empty!	Missing page number in request
`1522`	pageNo:The byte length cannot be less than 0 and cannot be greater than 20!	Page number format error
`1523`	pageNo:Cannot be greater than -1!	Page number must be positive
`1524`	pageSize:cannot be empty!	Missing page size in request
`1525`	pageSize:The byte length cannot be less than 0 and cannot be greater than 3!	Page size format error
`1526`	pageSize:Cannot be greater than 100!	Page size exceeds maximum (100)
`2916`	fuelType: cannot be empty!	Fuel type required in some contexts
`2917`	fuelType: Byte length cannot be greater than 200!	Fuel type exceeds length limit

💡 Tip: Error codes 1521-1526 are the most common pagination-related errors. Ensure pageNo ≥ 1 and pageSize ≤ 100.

Common Use Cases

EDC Sales Reconciliation
Query EDC invoices to reconcile pump meter readings with issued invoices for shift closing (T163).
Fuel Type Sales Analysis
Filter by fuelType to analyze sales performance by product (Petrol, Diesel, Naphtha, etc.).
Pump/Nozzle Performance Tracking
Use pumpNo and nozzleNo to track sales per dispensing point for maintenance scheduling.
Modified Invoice Audit
Use queryType=2 to query invoices where buyer details were modified (T166) for audit trails.
Branch Sales Reporting
Filter by branchId to generate branch-specific EDC sales reports for multi-station operators.
Date-Range Sales Queries
Generate daily, weekly, or monthly EDC sales reports using startDate and endDate filters.
Buyer Transaction History
Filter by buyerLegalName or buyerTin to track specific customer fuel purchase history.

Integration Checklist

✅ Ensure pageNo ≥ 1 and pageSize ≤ 100 before submitting request
✅ Handle empty records array gracefully (no matching invoices found)
✅ Implement pagination logic using pageCount and totalSize from response
✅ Validate date format is yyyy-MM-dd HH:mm:ss for startDate and endDate
✅ Use queryType appropriately (1=unmodified, 2=modified, 3=all) based on use case
✅ Cache frequently-queried EDC invoices to reduce API calls
✅ Log query parameters for audit trail compliance
✅ Cross-reference pumpNo/nozzleNo with T169 pump configuration data
✅ Use updateTimes to identify invoices with buyer detail modifications
✅ Filter by invoiceIndustryCode=110 (EDC) to ensure EDC-specific invoices only

Endpoint Overview​

Flow Description​

Request Structure​

Request Fields (Encrypted Payload)​

Response Structure​

Response Fields​

Pagination Object​

Invoice Records Array Items​

Return Codes​

Common Use Cases​

Integration Checklist​