inquireInvoice

Overview

The inquireInvoice command retrieves information about previously generated invoices from the EZcount system. This command allows merchants to fetch invoice data, download links, and status information for invoices created through the platform.

Polling Endpoint: This is essentially a polling endpoint that checks the status of invoice generation. Use it to monitor the progress of invoice creation, especially when invoices are generated asynchronously. It functions as a long-poll endpoint for tracking invoice completion status.

Use cases

Use inquireInvoice when you need to:

Retrieve the download link for a previously generated invoice
Check the status of an invoice created through addCgInvoice
Access invoice metadata such as invoice number and generation date
Obtain a merchant copy of the original customer invoice
Verify invoice details for reconciliation purposes

Request structure

For general API request structure and authentication, see API Request & Response General Structure.

The inquireInvoice command uses the following endpoint:

POST https://your-hyp-environment-url/xpo/Relay

HTTP request format

The request must be sent as a POST request with application/x-www-form-urlencoded content type, containing three required body parameters:

Parameter

Type

Description

user

string

Your merchant username for API authentication

password

string

Your merchant password for API authentication

int_in

string

XML payload containing the command and parameters (see structure below)

XML request structure

<ashrait>
    <request>
        <version>2000</version>
        <language>ENG</language>
        <command>inquireInvoice</command>
        <terminalNumber>{{terminal}}</terminalNumber>
        <inquireInvoice>
            <invoice>
                <invoiceAtranId>119427572</invoiceAtranId>
            </invoice>
        </inquireInvoice>
    </request>
</ashrait>

Required parameters

terminalNumber - string

The terminal number associated with your merchant account.

invoiceAtranId - string

The unique transaction ID returned when the invoice was created. This is the preferred and most reliable method for invoice identification.

Example: 119427572

Response structure

Success response example

<?xml version='1.0'?>
<ashrait>
    <response>
        <command>inquireInvoice</command>
        <dateTime>2025-08-27 09:15</dateTime>
        <requestId />
        <tranId>119717831</tranId>
        <result>000</result>
        <message>Permitted transaction</message>
        <userMessage>Permitted transaction</userMessage>
        <additionalInfo />
        <version>2000</version>
        <language>Eng</language>
        <inquireInvoice>
            <status>000</status>
            <statusText>Permitted transaction</statusText>
            <originalInvoice>
                <invoiceCreationMethod>wait</invoiceCreationMethod>
                <invoiceResponseCode>100</invoiceResponseCode>
                <invoiceResponseName>Proper Invoice Request</invoiceResponseName>
                <invoiceDocNumber>146655</invoiceDocNumber>
                <invoiceDocUrl>https://demo.ezcount.co.il/front/documents/get/b765564e-9ad7-4b5a-95b3-d79a9dbd9f21/copy_en</invoiceDocUrl>
                <invoiceAtranId>119717805</invoiceAtranId>
                <invoiceCreationDate>2025-08-27 09:15:07</invoiceCreationDate>
                <mailTo>[email protected]</mailTo>
                <invoiceCreationCode>000</invoiceCreationCode>
                <cancelTransaction>0</cancelTransaction>
            </originalInvoice>
        </inquireInvoice>
    </response>
</ashrait>

Key Fields in Success Response:

invoiceResponseCode: 100 indicates successful invoice retrieval
invoiceResponseName: "Proper Invoice Request" confirms success
invoiceDocNumber: The invoice number in the EZcount system
invoiceDocUrl: Direct download link for the invoice PDF
invoiceCreationCode: 000 indicates no errors during creation
invoiceCreationDate: When the invoice was generated

Error response example

<?xml version='1.0'?>
<ashrait>
    <response>
        <command>inquireInvoice</command>
        <dateTime>2025-08-27 09:16</dateTime>
        <requestId />
        <tranId>119717840</tranId>
        <result>000</result>
        <message>Permitted transaction</message>
        <userMessage>Permitted transaction</userMessage>
        <additionalInfo />
        <version>2000</version>
        <language>Eng</language>
        <inquireInvoice>
            <status>000</status>
            <statusText>Permitted transaction</statusText>
            <originalInvoice>
                <invoiceCreationMethod />
                <invoiceResponseCode />
                <invoiceResponseName>Invoice not found</invoiceResponseName>
                <invoiceDocNumber />
                <invoiceDocUrl />
                <invoiceAtranId>119712205</invoiceAtranId>
                <invoiceCreationDate />
                <mailTo />
                <invoiceCreationCode>671</invoiceCreationCode>
                <cancelTransaction />
            </originalInvoice>
        </inquireInvoice>
    </response>
</ashrait>

Key Fields in Error Response:

Note that result is still 000 (API call succeeded)
The actual error is in the invoice-specific fields:
- invoiceResponseName: "Invoice not found" describes the error
- invoiceCreationCode: 671 is the specific invoice error code
- Most fields are empty when the invoice is not found

Code examples

#!/bin/bash

# Invoice inquiry by invoiceAtranId
curl -X POST https://your-hyp-environment-url/xpo/Relay \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "user=your_username" \
  --data-urlencode "password=your_password" \
  --data-urlencode "int_in=<ashrait>
    <request>
        <command>inquireInvoice</command>
        <terminalNumber>1234567</terminalNumber>
        <inquireInvoice>
            <invoice>
                <invoiceAtranId>119427572</invoiceAtranId>
            </invoice>
        </inquireInvoice>
    </request>
</ashrait>"

import requests
import xml.etree.ElementTree as ET

def inquire_invoice(username, password, terminal, invoice_atran_id):
    """
    Retrieve invoice information from EZcount system
    """
    # Build XML request
    ashrait = ET.Element("ashrait")
    request = ET.SubElement(ashrait, "request")
    
    ET.SubElement(request, "command").text = "inquireInvoice"
    ET.SubElement(request, "terminalNumber").text = terminal
    
    # Add inquireInvoice section with invoice details
    inquire_invoice = ET.SubElement(request, "inquireInvoice")
    invoice = ET.SubElement(inquire_invoice, "invoice")
    ET.SubElement(invoice, "invoiceAtranId").text = invoice_atran_id
    
    xml_string = ET.tostring(ashrait, encoding='unicode')
    
    # Send request with user/password as separate parameters
    response = requests.post(
        "https://your-hyp-environment-url/xpo/Relay",
        data={
            "user": username,
            "password": password,
            "int_in": xml_string
        },
        headers={
            "Content-Type": "application/x-www-form-urlencoded"
        }
    )
    
    if response.status_code == 200:
        # Parse response
        root = ET.fromstring(response.text)
        result = root.find(".//result").text
        
        if result == "000":
            # Check for invoice-specific errors
            invoice_creation_code = root.find(".//invoiceCreationCode").text
            invoice_response_name = root.find(".//invoiceResponseName").text
            
            if invoice_creation_code in ["000", "100"]:
                invoice_url = root.find(".//invoiceDocUrl").text
                invoice_number = root.find(".//invoiceDocNumber").text
                print(f"Invoice found: {invoice_number}")
                print(f"Download URL: {invoice_url}")
                return {
                    "success": True, 
                    "invoice_url": invoice_url,
                    "invoice_number": invoice_number
                }
            else:
                print(f"Invoice error: {invoice_response_name} (Code: {invoice_creation_code})")
                return {
                    "success": False, 
                    "error": invoice_response_name,
                    "error_code": invoice_creation_code
                }
        else:
            message = root.find(".//message").text
            print(f"Error: {message}")
            return {"success": False, "error": message}
    else:
        return {"success": False, "error": f"HTTP {response.status_code}"}

# Example usage
result = inquire_invoice(
    username="your_username",
    password="your_password", 
    terminal="1234567",
    invoice_atran_id="119427572"
)

import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.net.URLEncoder;
import javax.xml.parsers.DocumentBuilder;
import javax.xml.parsers.DocumentBuilderFactory;
import org.w3c.dom.*;

public class InvoiceInquiry {
    
    public static class InvoiceResult {
        public boolean success;
        public String invoiceUrl;
        public String invoiceNumber;
        public String error;
        
        public InvoiceResult(boolean success, String invoiceUrl, String invoiceNumber, String error) {
            this.success = success;
            this.invoiceUrl = invoiceUrl;
            this.invoiceNumber = invoiceNumber;
            this.error = error;
        }
    }
    
    public static InvoiceResult inquireInvoice(String username, String password, String terminal, 
                                              String invoiceAtranId) {
        try {
            // Build XML request
            StringBuilder xml = new StringBuilder();
            xml.append("<ashrait>");
            xml.append("<request>");
            xml.append("<command>inquireInvoice</command>");
            xml.append("<terminalNumber>").append(terminal).append("</terminalNumber>");
            xml.append("<inquireInvoice>");
            xml.append("<invoice>");
            xml.append("<invoiceAtranId>").append(invoiceAtranId).append("</invoiceAtranId>");
            xml.append("</invoice>");
            xml.append("</inquireInvoice>");
            xml.append("</request>");
            xml.append("</ashrait>");
            
            // Send HTTP request with user/password as separate parameters
            URL url = new URL("https://your-hyp-environment-url/xpo/Relay");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();
            conn.setRequestMethod("POST");
            conn.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
            conn.setDoOutput(true);
            
            String postData = "user=" + URLEncoder.encode(username, "UTF-8") +
                            "&password=" + URLEncoder.encode(password, "UTF-8") +
                            "&int_in=" + URLEncoder.encode(xml.toString(), "UTF-8");
            
            try (OutputStream os = conn.getOutputStream()) {
                os.write(postData.getBytes("UTF-8"));
            }
            
            // Parse response
            if (conn.getResponseCode() == 200) {
                DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
                DocumentBuilder builder = factory.newDocumentBuilder();
                Document doc = builder.parse(conn.getInputStream());
                
                String result = doc.getElementsByTagName("result").item(0).getTextContent();
                
                if ("000".equals(result)) {
                    // Check for invoice-specific errors
                    String invoiceCreationCode = doc.getElementsByTagName("invoiceCreationCode").item(0).getTextContent();
                    String invoiceResponseName = doc.getElementsByTagName("invoiceResponseName").item(0).getTextContent();
                    
                    if ("000".equals(invoiceCreationCode) || "100".equals(invoiceCreationCode)) {
                        String invoiceUrl = doc.getElementsByTagName("invoiceDocUrl").item(0).getTextContent();
                        String invoiceNumber = doc.getElementsByTagName("invoiceDocNumber").item(0).getTextContent();
                        System.out.println("Invoice found: " + invoiceNumber);
                        System.out.println("Download URL: " + invoiceUrl);
                        return new InvoiceResult(true, invoiceUrl, invoiceNumber, null);
                    } else {
                        System.out.println("Invoice error: " + invoiceResponseName + " (Code: " + invoiceCreationCode + ")");
                        return new InvoiceResult(false, null, null, invoiceResponseName);
                    }
                } else {
                    String message = doc.getElementsByTagName("message").item(0).getTextContent();
                    System.out.println("Error: " + message);
                    return new InvoiceResult(false, null, null, message);
                }
            } else {
                return new InvoiceResult(false, null, null, "HTTP " + conn.getResponseCode());
            }
            
        } catch (Exception e) {
            e.printStackTrace();
            return new InvoiceResult(false, null, null, e.getMessage());
        }
    }
    
    public static void main(String[] args) {
        InvoiceResult result = inquireInvoice(
            "your_username",
            "your_password",
            "1234567",
            "119427572"
        );
        
        if (result.success) {
            System.out.println("Success! Invoice URL: " + result.invoiceUrl);
        } else {
            System.out.println("Failed: " + result.error);
        }
    }
}

const https = require('https');
const querystring = require('querystring');
const { DOMParser } = require('xmldom');

function inquireInvoice(username, password, terminal, invoiceAtranId) {
    return new Promise((resolve, reject) => {
        // Build XML request
        let xml = `<ashrait>
    <request>
        <command>inquireInvoice</command>
        <terminalNumber>${terminal}</terminalNumber>
        <inquireInvoice>
            <invoice>
                <invoiceAtranId>${invoiceAtranId}</invoiceAtranId>
            </invoice>
        </inquireInvoice>
    </request>
</ashrait>`;

        // Prepare POST data with user/password as separate parameters
        const postData = querystring.stringify({
            user: username,
            password: password,
            int_in: xml
        });

        // HTTP request options
        const options = {
            hostname: 'cguat2.creditguard.co.il',
            path: '/xpo/Relay',
            method: 'POST',
            headers: {
                'Content-Type': 'application/x-www-form-urlencoded',
                'Content-Length': Buffer.byteLength(postData)
            }
        };

        // Send request
        const req = https.request(options, (res) => {
            let responseData = '';

            res.on('data', (chunk) => {
                responseData += chunk;
            });

            res.on('end', () => {
                try {
                    // Parse XML response
                    const parser = new DOMParser();
                    const doc = parser.parseFromString(responseData, 'text/xml');
                    
                    const result = doc.getElementsByTagName('result')[0]?.textContent;
                    
                    if (result === '000') {
                        // Check for invoice-specific errors
                        const invoiceCreationCode = doc.getElementsByTagName('invoiceCreationCode')[0]?.textContent;
                        const invoiceResponseName = doc.getElementsByTagName('invoiceResponseName')[0]?.textContent;
                        
                        if (invoiceCreationCode === '000' || invoiceCreationCode === '100') {
                            const invoiceUrl = doc.getElementsByTagName('invoiceDocUrl')[0]?.textContent;
                            const invoiceNumber = doc.getElementsByTagName('invoiceDocNumber')[0]?.textContent;
                            console.log(`Invoice found: ${invoiceNumber}`);
                            console.log(`Download URL: ${invoiceUrl}`);
                            resolve({
                                success: true,
                                invoiceUrl: invoiceUrl,
                                invoiceNumber: invoiceNumber
                            });
                        } else {
                            console.log(`Invoice error: ${invoiceResponseName} (Code: ${invoiceCreationCode})`);
                            resolve({
                                success: false,
                                error: invoiceResponseName,
                                errorCode: invoiceCreationCode
                            });
                        }
                    } else {
                        const message = doc.getElementsByTagName('message')[0]?.textContent;
                        console.log(`Error: ${message}`);
                        resolve({
                            success: false,
                            error: message
                        });
                    }
                } catch (error) {
                    reject(error);
                }
            });
        });

        req.on('error', (error) => {
            reject(error);
        });

        // Send POST data
        req.write(postData);
        req.end();
    });
}

// Example usage
(async () => {
    try {
        const result = await inquireInvoice(
            'your_username',
            'your_password',
            '1234567',
            '119427572'
        );
        
        if (result.success) {
            console.log('Success! Invoice URL:', result.invoiceUrl);
        } else {
            console.log('Failed:', result.error);
        }
    } catch (error) {
        console.error('Error:', error.message);
    }
})();

Error codes

General API error codes

Code

Description

Solution

000

Success

Invoice information retrieved successfully

325

Invalid XML format

Check XML structure and ensure all required fields are present

405

SSL HTTPS customers are not permitted to access the system

Verify username and password are correct

414

An XML field or an INT_IN parameter is too short/long

Check field lengths match API requirements

Invoice module error codes

Note: Invoice-specific errors are returned in the invoiceResponseCode and invoiceResponseName tags.

CG Gateway invoice error codes

Code

Description

Solution

668

Cannot Create Invoice

Invoice creation failed - check request parameters

669

Currency not supported for invoice creation

Only ILS (Israeli Shekel) invoices are supported

670

Invoice Validation Failed

Check invoice data for invalid values

671

Invoice not found

Verify the invoice identifier is correct and exists

Invoice vendor response codes

Code

Description

Meaning

100

Success

Completed successfully

101

UsernameInvalid

Attempted transaction with invalid username

102

CompanyCodeAlreadyExists

Attempted to create a company with an existing company code

103

CompanyCodeDoesNotExist

Company code does not exist

104

CompanyCodeInvalidFormat

Company code format is not numeric

105

DocumentInvalidSubject

Subject line is invalid

106

DocumentDoesNotExit

Document number was not found

107

SendEmailAborted

E-mailing document failed

108

EmailInvalid

Invalid e-mail format

109

CultureInvalid

Invalid culture

110

KeyInvalid

Invalid key

111

AccountExpired

Account has expired

112

DocumentInvalidItemNumber

Multiple items in an invoice are in the wrong format

113

DocumentInvalidQuantity

Quantity format is not numeric

114

DocumentInvalidPrice

Price format is not numeric

116

DocumentDoesNotExistForSpecifiedCompany

The specified document doesn't exist or is incompatible with the company code provided

117

CurrencyConversionServiceNotAvailable

Currency conversion service is out of service

118

InvalidItemCode

Unacceptable item code

119

CurrencyInWrongFormat

Currency is not an integer

120

DocumentMissingItem

Quantity, price, description and code must match

121

DocumentInvalidDateFormatDDMMYY

Date format must be DDMMYY

122

PaymentAmountDoesntMatchInvoice

Total receivables must be positive

123

DocumentAmountInvalid

Amount must be double

124

CashInvalidAmount

Amount must be double

125

CheckInvalidAmount

Amount must be double

126

CCInvalidAmount

Amount must be double

127

TransInvalidAmount

Amount must be double

128

CheckInvalidDateFormatDDMMYY

Date format must be DDMMYY

129

CCInvalidDateFormatDDMMYY

Date format must be DDMMYY

130

TransInvalidDateFormatDDMMYY

Date format must be DDMMYY

131

PaymentTotalMustBeEqualToInvoiceTotal

Payment total must be equal to invoice total

132

TaxRateInTheDocsIsNotEqual

Tax rate in the docs is not equal

133

ClientCompanyNameAlreadyExists

Client company name already exists

134

ClientTicketAlreadyExists

Client ticket already exists

Currency Support: At this time, only ILS (Israeli Shekel) invoices are supported. Other currencies will be processed but no invoices will be created.

Language: Invoice vendor response messages are always returned in English.

addCgInvoice - Create new invoices
refundCgInvoice - Process invoice refunds
doDeal - Process payments with automatic invoice generation

Best practices

Use invoiceAtranId when available - This is the most reliable identifier for invoice queries
Store invoice identifiers - Keep track of invoiceAtranId returned from addCgInvoice for future queries
Handle not found errors gracefully - Invoices may be deleted or expired in the EZcount system
Use for reconciliation - Regular invoice queries help maintain accurate financial records
Monitor invoice status - Check invoice status to ensure proper delivery to customers

PreviousgetSessionId NextrefundCgInvoice

Last updated 3 months ago

Was this helpful?

Good afternoon

Overview

Use cases

Request structure

HTTP request format

XML request structure

Required parameters

Response structure

Success response example

Error response example

Code examples

Error codes

General API error codes

Invoice module error codes

CG Gateway invoice error codes

Invoice vendor response codes

Related commands

Best practices