List purchase invoices

Use this API to get the list of the business's purchase invoices (input invoices) synced from the General Department of Taxation, with filtering by seller, issue date, approval date, received date and status.

POST

URLhttps://open-api.tingee.vn/v1/e-invoice/input/list

Get the list of purchase invoices with pagination and filters.

Header Request

Header	Required	Description
Content-Type	✓	application/json
x-client-id	✓	Partner identifier issued by TINGEE.
x-signature	✓	HMAC SHA512 authentication signature. See How to generate the signature.
x-request-timestamp	✓	Time the request is sent (format: yyyyMMddHHmmssSSS, UTC+7)

Body Parameter

Field	Type	Required	Description
merchantId	number	~	Merchant ID (Required if you connect with a Master Merchant account).
accountId	number	✕	E-invoice account ID (from List accounts). Leave empty to use the default account.
page	number	✕	Page to retrieve, starting from 0. Default 0.
size	number	✕	Number of records per page (minimum 1). Default 50.
pageSize, current	number	✕	Additional pagination parameters, passed as-is to the provider. We recommend using page and size.
sellerTaxCode	string	✕	Filter by seller tax code.
buyerTaxCode	string	✕	Filter by buyer tax code. Defaults to the business's tax code.
invoiceNo	string	✕	Filter by invoice number.
invoiceFromDate, invoiceToDate	string	✕	Filter by invoice issue date.
approvedFromDate, approvedToDate	string	✕	Filter by approval date.
receivedFromDate, receivedToDate	string	✕	Filter by received date.
invoiceProperty	number	✕	Invoice nature: 1 Original, 2 Replacement, 3 Adjustment, 4 Replaced, 5 Adjusted, 6 Deleted/cancelled.
approvalStatus	number	✕	Approval status: 1 Pending approval, 2 Approved, 3 Rejected, 4 Cancelled, 5 Processed.
label	string	✕	Filter by label.

note

Date filter fields use the yyyy-MM-dd HH:mm:ss.SSS format (e.g. 2026-10-01 00:00:00.000). You can also pass yyyy-MM-dd or ISO 8601 (e.g. 2026-10-01), and the system converts it to the format above; do not use dd/MM/yyyy as in the Sync API. For each date pair, the "from" value must be less than or equal to the "to" value.

Code samples

cURL

curl --location --request POST 'https://open-api.tingee.vn/v1/e-invoice/input/list' \
--header 'accept: application/json' \
--header 'x-client-id: YOUR_CLIENT_ID' \
--header 'x-request-timestamp: 20240509154004003' \
--header 'x-signature: YOUR_SIGNATURE' \
--header 'Content-Type: application/json' \
--data '{
  "page": 0,
  "size": 50,
  "invoiceFromDate": "2026-10-01 00:00:00.000",
  "invoiceToDate": "2026-10-10 23:59:59.999"
}'

NestJS

import axios from "axios";
import { createHmac } from "crypto";

const CLIENT_ID = "YOUR_CLIENT_ID";
const SECRET_KEY = "YOUR_SECRET_KEY";

// Timestamp in UTC+7, format yyyyMMddHHmmssSSS
function getTimestamp() {
    return new Date(Date.now() + 7 * 60 * 60 * 1000)
        .toISOString()
        .replace(/[-:TZ.]/g, "")
        .slice(0, 17);
}

async function eInvoiceInputList() {
    const body = {
        page: 0,
        size: 50,
        invoiceFromDate: "2026-10-01 00:00:00.000",
        invoiceToDate: "2026-10-10 23:59:59.999",
    };

    const bodyJson = JSON.stringify(body);
    const timestamp = getTimestamp();
    const signature = createHmac("sha512", SECRET_KEY)
        .update(`${timestamp}:${bodyJson}`)
        .digest("hex");

    const res = await axios.request({
        method: "POST",
        url: "https://open-api.tingee.vn/v1/e-invoice/input/list",
        data: bodyJson,
        headers: {
            accept: "application/json",
            "Content-Type": "application/json",
            "x-client-id": CLIENT_ID,
            "x-request-timestamp": timestamp,
            "x-signature": signature,
        },
    });

    console.log(res.data);
}

eInvoiceInputList();

C#

using System;
using System.Net.Http;
using System.Security.Cryptography;
using System.Text;
using System.Text.Encodings.Web;
using System.Text.Json;
using System.Threading.Tasks;

public class Program
{
    private const string ClientId = "YOUR_CLIENT_ID";
    private const string SecretKey = "YOUR_SECRET_KEY";
    private static readonly HttpClient Client = new HttpClient();

    public static async Task Main()
    {
        var body = new
        {
            page = 0,
            size = 50,
            invoiceFromDate = "2026-10-01 00:00:00.000",
            invoiceToDate = "2026-10-10 23:59:59.999"
        };

        // Do not escape non-ASCII / special characters so the JSON matches TINGEE's JSON.stringify
        var jsonOptions = new JsonSerializerOptions { Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping };
        var bodyJson = JsonSerializer.Serialize(body, jsonOptions);

        // Timestamp in UTC+7, format yyyyMMddHHmmssSSS
        var timestamp = DateTime.UtcNow.AddHours(7).ToString("yyyyMMddHHmmssfff");
        var signature = HmacSha512(SecretKey, $"{timestamp}:{bodyJson}");

        var request = new HttpRequestMessage(HttpMethod.Post, "https://open-api.tingee.vn/v1/e-invoice/input/list");
        request.Headers.Add("accept", "application/json");
        request.Headers.Add("x-client-id", ClientId);
        request.Headers.Add("x-request-timestamp", timestamp);
        request.Headers.Add("x-signature", signature);
        request.Content = new StringContent(bodyJson, Encoding.UTF8, "application/json");

        var response = await Client.SendAsync(request);
        Console.WriteLine(await response.Content.ReadAsStringAsync());
    }

    private static string HmacSha512(string key, string message)
    {
        using var hmac = new HMACSHA512(Encoding.UTF8.GetBytes(key));
        var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(message));
        return Convert.ToHexString(hash).ToLower();
    }
}

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.time.ZoneId;
import java.time.ZonedDateTime;
import java.time.format.DateTimeFormatter;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public class Main {
    private static final String CLIENT_ID = "YOUR_CLIENT_ID";
    private static final String SECRET_KEY = "YOUR_SECRET_KEY";

    public static void main(String[] args) throws Exception {
        // Minified JSON, same as JSON.stringify()
        String bodyJson = "{\"page\":0,\"size\":50,\"invoiceFromDate\":\"2026-10-01 00:00:00.000\",\"invoiceToDate\":\"2026-10-10 23:59:59.999\"}";

        // Timestamp in UTC+7, format yyyyMMddHHmmssSSS
        String timestamp = ZonedDateTime.now(ZoneId.of("Asia/Ho_Chi_Minh"))
                .format(DateTimeFormatter.ofPattern("yyyyMMddHHmmssSSS"));
        String signature = hmacSha512(SECRET_KEY, timestamp + ":" + bodyJson);

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("https://open-api.tingee.vn/v1/e-invoice/input/list"))
                .header("accept", "application/json")
                .header("Content-Type", "application/json")
                .header("x-client-id", CLIENT_ID)
                .header("x-request-timestamp", timestamp)
                .header("x-signature", signature)
                .method("POST", HttpRequest.BodyPublishers.ofString(bodyJson, StandardCharsets.UTF_8))
                .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
                .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }

    private static String hmacSha512(String key, String data) throws Exception {
        Mac mac = Mac.getInstance("HmacSHA512");
        mac.init(new SecretKeySpec(key.getBytes(StandardCharsets.UTF_8), "HmacSHA512"));
        byte[] hash = mac.doFinal(data.getBytes(StandardCharsets.UTF_8));
        StringBuilder hex = new StringBuilder();
        for (byte b : hash) hex.append(String.format("%02x", b));
        return hex.toString();
    }
}

PHP

<?php
$clientId = "YOUR_CLIENT_ID";
$secretKey = "YOUR_SECRET_KEY";

$body = [
    "page" => 0,
    "size" => 50,
    "invoiceFromDate" => "2026-10-01 00:00:00.000",
    "invoiceToDate" => "2026-10-10 23:59:59.999",
];

// Do not escape "/" or non-ASCII characters so the JSON matches TINGEE's JSON.stringify
$bodyJson = json_encode($body, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);

// Timestamp in UTC+7, format yyyyMMddHHmmssSSS
$now = new DateTime("now", new DateTimeZone("Asia/Ho_Chi_Minh"));
$timestamp = $now->format("YmdHisv");
$signature = hash_hmac("sha512", $timestamp . ":" . $bodyJson, $secretKey);

$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => "https://open-api.tingee.vn/v1/e-invoice/input/list",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => $bodyJson,
    CURLOPT_HTTPHEADER => [
        "Accept: application/json",
        "Content-Type: application/json",
        "x-client-id: " . $clientId,
        "x-request-timestamp: " . $timestamp,
        "x-signature: " . $signature,
    ],
]);

$response = curl_exec($ch);
if ($response === false) {
    echo "cURL Error: " . curl_error($ch);
} else {
    echo $response;
}
curl_close($ch);

Sample Response

{
  "code": "00",
  "message": "Success",
  "data": {
    "totalCount": 1,
    "items": [
      {
        "id": 123456,
        "invoiceCode": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
        "fileHistoryId": "f9e8d7c6-b5a4-4321-9876-543210fedcba",
        "invoiceNo": "0000125",
        "invoicePattern": "1",
        "invoiceSeries": "C26TAA",
        "sellerName": "CÔNG TY TNHH ABC",
        "sellerTaxCode": "0101234567",
        "totalBeforeTax": 1000000,
        "taxAmount": 80000,
        "totalAfterTax": 1080000,
        "invoiceDate": "2026-10-05",
        "receivedDate": "2026-10-06",
        "invoiceStatus": 1,
        "approvalStatus": 1,
        "tctStatus": 1,
        "invoiceType": 1,
        "invoiceProperty": 1,
        "importMethod": 1,
        "orderNo": null,
        "note": null
      }
    ]
  }
}

Field	Type	Description
code	string	Result code (00 = Success).
message	string	Response message.
data.totalCount	number	Total number of invoices matching the conditions.
data.items	array	Purchase invoices on the current page.
data.items[].id	number	Invoice ID at the provider.
data.items[].invoiceCode	string	Invoice identifier, used for the Details and PDF rendition APIs.
data.items[].fileHistoryId	string	Invoice file history ID at the provider.
data.items[].invoiceNo	string	Invoice number.
data.items[].invoicePattern	string	Invoice template number (mẫu số).
data.items[].invoiceSeries	string	Invoice symbol (ký hiệu).
data.items[].sellerName	string	Seller name.
data.items[].sellerTaxCode	string	Seller tax code.
data.items[].totalBeforeTax	number	Total amount before tax.
data.items[].taxAmount	number	Tax amount.
data.items[].totalAfterTax	number	Total payment amount.
data.items[].invoiceDate	string	Invoice issue date.
data.items[].receivedDate	string	Invoice received date.
data.items[].approvalStatus	number	Approval status (see the approvalStatus parameter).
data.items[].invoiceProperty	number	Invoice nature (see the invoiceProperty parameter).
data.items[].invoiceStatus	number	Invoice status (as provided by the provider).
data.items[].tctStatus	number	Invoice status at the tax authority.
data.items[].invoiceType	number	Invoice type (as provided by the provider).
data.items[].importMethod	number	Invoice import method (as provided by the provider).
data.items[].orderNo	string	Order number (if any).
data.items[].note	string	Note (if any).

---

Common error codes

Code	Description	How to handle
2040	Invalid time range	The start date must be less than or equal to the end date.
400	Failed to get the list of purchase invoices	message contains the details.
2036	The account is not registered for the purchase invoice service	Update the account so that services contains input-invoice via the Create/Update account API.
2007	The provider is not supported	Purchase invoices only support x-cyber provider accounts.
2032	No default account is configured	Pass accountId, or set an account as the default.
1057	Account information not found	Check accountId.
1095, 1096	Master Merchant merchantId error	Pass a merchantId belonging to the Master Merchant calling the API.
90, 91, 92, 97	Request authentication error (timestamp, client-id, signature)	See System error codes.
Others	Other errors	See Error codes.