Version: 1.2.1 (Latest)

Tạo hóa đơn nháp

API này cho phép tạo hóa đơn nháp (draft/preview) và trả về file PDF Base64 của hóa đơn vừa tạo.

POST

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

Tạo hóa đơn nháp (draft/preview) và trả về file PDF Base64.

Header Request

Header	Bắt buộc	Mô tả
`Content-Type`	✓	`application/json`
`x-client-id`	✓	Mã định danh của đối tác do TINGEE cung cấp.
`x-signature`	✓	Chữ ký xác thực HMAC SHA512. Xem thêm tại Cách sinh chữ ký.
`x-request-timestamp`	✓	Thời gian gửi request (format: `yyyyMMddHHmmssSSS`, múi giờ UTC+7)

Body Parameter

Trường	Kiểu	Bắt buộc	Mô tả
`merchantId`	number	✕	Mã Merchant. (Bắt buộc nếu kết nối bằng tài khoản Master Merchant).
`accountId`	number	✕	ID cấu hình tài khoản (nếu để trống sẽ lấy tài khoản mặc định).
`invoicePattern`	string	✓	Mẫu số hóa đơn. Xem Lấy mẫu hóa đơn.
`invoiceSeries`	string	✓	Ký hiệu hóa đơn. Xem Lấy mẫu hóa đơn.
`invoiceCode`	string	✓	Mã hóa đơn (unique key).
`invoiceDate`	date	✓	Ngày lập hóa đơn (format: `YYYY-MM-DD`, ví dụ: `2025-12-09`).
`invoiceType`	string	✕	Loại hóa đơn (provider-specific).
`buyerTaxCode`	string	✕	Mã số thuế người mua.
`buyerName`	string	✕	Tên người mua. (Bắt buộc nếu sử dụng SInvoice).
`buyerLegalName`	string	✕	Tên đơn vị mua.
`buyerAddress`	string	✕	Địa chỉ người mua.
`buyerPhone`	string	✕	Số điện thoại người mua.
`buyerEmail`	string	✕	Email người mua.
`buyerBankAccount`	string	✕	Số tài khoản ngân hàng người mua.
`buyerBankName`	string	✕	Tên ngân hàng người mua.
`paymentMethod`	number	✕	Phương thức thanh toán: `1`=TM, `2`=CK, `3`=TM/CK.
`paymentMethodName`	string	✕	Tên phương thức thanh toán.
`currency`	string	✕	Mã tiền tệ (Mặc định: `VND`).
`exchangeRate`	string	✕	Tỷ giá ngoại tệ.
`amountInWords`	string	✕	Số tiền bằng chữ (tự sinh nếu không truyền).
`note`	string	✕	Ghi chú hóa đơn.
`items`	array	✓	Danh sách hàng hóa/dịch vụ (xem bảng bên dưới).
`totalDiscount`	string	✕	Tổng tiền chiết khấu (hệ thống tự tính nếu không truyền).
`totalBeforeTax`	string	✕	Tổng tiền trước thuế (hệ thống tự tính nếu không truyền).
`totalTax`	string	✕	Tổng tiền thuế (hệ thống tự tính nếu không truyền).
`totalAfterTax`	string	✕	Tổng tiền sau thuế (hệ thống tự tính nếu không truyền).
`taxRateSummaries`	array	✕	Tổng hợp thuế suất (hệ thống tự tính nếu không truyền, xem bảng bên dưới).

`items[]` — Chi tiết hàng hóa / dịch vụ

Trường	Kiểu	Bắt buộc	Mô tả
`itemCode`	string	✕	Mã hàng hóa.
`itemName`	string	✓	Tên hàng hóa / dịch vụ.
`unitName`	string	✕	Đơn vị tính.
`quantity`	string	✓	Số lượng.
`unitPrice`	string	✓	Đơn giá.
`discount`	string	✕	Phần trăm chiết khấu.
`discountAmount`	string	✕	Số tiền chiết khấu.
`totalBeforeTax`	string	✕	Tổng tiền trước thuế (hệ thống tự tính nếu không truyền).
`taxRateCode`	string	✓	Mã thuế suất: `0`, `5`, `8`, `10`, `-1` (KCT), `-2` (KKKNT).
`taxAmount`	string	✕	Tiền thuế (hệ thống tự tính nếu không truyền).
`totalAfterTax`	string	✕	Tổng tiền sau thuế (hệ thống tự tính nếu không truyền).
`itemType`	number	✕	Loại dòng: `1`=hàng hóa, `2`=khuyến mại, `3`=chiết khấu, `4`=ghi chú.
`adjustmentType`	number	✕	Điều chỉnh tăng/giảm (cho hóa đơn điều chỉnh).

`taxRateSummaries[]` — Tổng hợp thuế suất

Trường	Kiểu	Bắt buộc	Mô tả
`taxRateCode`	string	✓	Mã thuế suất.
`totalTaxableAmount`	string	✕	Tổng tiền chịu thuế.
`taxAmount`	string	✕	Tổng tiền thuế.

Ví dụ mã nguồn

cURL
NestJS
C#
Java
PHP

curl --location --request POST 'https://open-api.tingee.vn/v1/e-invoice/create' \
--header 'x-signature: YOUR_SIGNATURE' \
--header 'x-request-timestamp: 20251209103911111' \
--header 'x-client-id: YOUR_CLIENT_ID' \
--header 'Content-Type: application/json' \
--data '{
"invoicePattern": "1",
"invoiceSeries": "C25TAB",
"invoiceCode": "INV-20251209-001",
"invoiceDate": "2025-12-09",
"buyerName": "Nguyen Van A",
"buyerLegalName": "CONG TY TNHH ABC",
"buyerTaxCode": "0109876543",
"buyerAddress": "123 Nguyen Hue, Quan 1, TP.HCM",
"paymentMethod": 2,
"paymentMethodName": "Chuyển khoản",
"items": [
  {
    "itemName": "Dịch vụ thanh toán",
    "unitName": "Gói",
    "quantity": "1",
    "unitPrice": "1000000",
    "taxRateCode": "10"
  }
]
}'

import axios from "axios";
import { createHmac } from "crypto";
import { format } from 'date-fns';

async function createInvoice() {
const body = {
  invoicePattern: "1",
  invoiceSeries: "C25TAB",
  invoiceCode: "INV-20251209-001",
  invoiceDate: "2025-12-09",
  buyerName: "Nguyen Van A",
  buyerLegalName: "CONG TY TNHH ABC",
  buyerTaxCode: "0109876543",
  buyerAddress: "123 Nguyen Hue, Quan 1, TP.HCM",
  paymentMethod: 2,
  paymentMethodName: "Chuyển khoản",
  items: [
    {
      itemName: "Dịch vụ thanh toán",
      unitName: "Gói",
      quantity: "1",
      unitPrice: "1000000",
      taxRateCode: "10",
    },
  ],
};

const timestamp = format(new Date(), "yyyyMMddHHmmssSSS");
const secretKey = "YOUR_SECRET_KEY";
const message = `${timestamp}:${JSON.stringify(body)}`;
const signature = createHmac('sha512', secretKey).update(message).digest('hex');

const res = await axios.post('https://open-api.tingee.vn/v1/e-invoice/create', body, {
  headers: {
    'x-signature': signature,
    'x-request-timestamp': timestamp,
    'x-client-id': 'YOUR_CLIENT_ID',
    'Content-Type': 'application/json',
  },
});

console.log(res.data);
}

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

public class CreateInvoiceExample
{
  private static readonly HttpClient client = new HttpClient();

  public static async Task Main()
  {
      var body = new {
          invoicePattern = "1",
          invoiceSeries = "C25TAB",
          invoiceCode = "INV-20251209-001",
          invoiceDate = "2025-12-09",
          buyerName = "Nguyen Van A",
          buyerLegalName = "CONG TY TNHH ABC",
          buyerTaxCode = "0109876543",
          buyerAddress = "123 Nguyen Hue, Quan 1, TP.HCM",
          paymentMethod = 2,
          paymentMethodName = "Chuyển khoản",
          items = new[] {
              new {
                  itemName = "Dịch vụ thanh toán",
                  unitName = "Gói",
                  quantity = "1",
                  unitPrice = "1000000",
                  taxRateCode = "10"
              }
          }
      };

      var timestamp = DateTime.Now.ToString("yyyyMMddHHmmssfff");
      var secretKey = "YOUR_SECRET_KEY";
      var bodyJson = JsonSerializer.Serialize(body);
      var message = $"{timestamp}:{bodyJson}";
      var signature = CreateHmacSha512(secretKey, message);

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

      var response = await client.SendAsync(request);
      string result = await response.Content.ReadAsStringAsync();
      Console.WriteLine(result);
  }

  private static string CreateHmacSha512(string key, string message)
  {
      using var hmac = new HMACSHA512(Encoding.UTF8.GetBytes(key));
      var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(message));
      return BitConverter.ToString(hash).Replace("-", "").ToLower();
  }
}

import java.net.http.*;
import java.net.URI;
import java.nio.charset.StandardCharsets;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;

public class CreateInvoice {
public static void main(String[] args) throws Exception {
  String bodyJson = "{"invoicePattern":"1","invoiceSeries":"C25TAB","invoiceCode":"INV-20251209-001","invoiceDate":"2025-12-09","buyerName":"Nguyen Van A","buyerLegalName":"CONG TY TNHH ABC","buyerTaxCode":"0109876543","buyerAddress":"123 Nguyen Hue, Quan 1, TP.HCM","paymentMethod":2,"paymentMethodName":"Chuyển khoản","items":[{"itemName":"Dịch vụ thanh toán","unitName":"Gói","quantity":"1","unitPrice":"1000000","taxRateCode":"10"}]}";
  String secretKey = "YOUR_SECRET_KEY";
  String timestamp = LocalDateTime.now().format(DateTimeFormatter.ofPattern("yyyyMMddHHmmssSSS"));

  String message = timestamp + ":" + bodyJson;
  String signature = hmacSha512(secretKey, message);

  HttpClient client = HttpClient.newHttpClient();
  HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://open-api.tingee.vn/v1/e-invoice/create"))
      .header("x-signature", signature)
      .header("x-request-timestamp", timestamp)
      .header("x-client-id", "YOUR_CLIENT_ID")
      .header("Content-Type", "application/json")
      .POST(HttpRequest.BodyPublishers.ofString(bodyJson))
      .build();

  HttpResponse<String> response = client.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");
    SecretKeySpec secretKeySpec = new SecretKeySpec(key.getBytes(StandardCharsets.UTF_8), "HmacSHA512");
    mac.init(secretKeySpec);
    byte[] hash = mac.doFinal(data.getBytes(StandardCharsets.UTF_8));
    return toHex(hash);
}

private static String toHex(byte[] bytes) {
    StringBuilder hex = new StringBuilder(bytes.length * 2);
    for (byte b : bytes) {
        hex.append(String.format("%02x", b));
    }
    return hex.toString();
}
}

function createInvoice() {
  $body = [
      "invoicePattern" => "1",
      "invoiceSeries" => "C25TAB",
      "invoiceCode" => "INV-20251209-001",
      "invoiceDate" => "2025-12-09",
      "buyerName" => "Nguyen Van A",
      "buyerLegalName" => "CONG TY TNHH ABC",
      "buyerTaxCode" => "0109876543",
      "buyerAddress" => "123 Nguyen Hue, Quan 1, TP.HCM",
      "paymentMethod" => 2,
      "paymentMethodName" => "Chuyển khoản",
      "items" => [
          [
              "itemName" => "Dịch vụ thanh toán",
              "unitName" => "Gói",
              "quantity" => "1",
              "unitPrice" => "1000000",
              "taxRateCode" => "10"
          ]
      ]
  ];

  $jsonBody = json_encode($body);
  $timestamp = date("YmdHis") . substr((string)microtime(true), -3);
  $secretKey = "YOUR_SECRET_KEY";

  $message = $timestamp . ":" . $jsonBody;
  $signature = hash_hmac("sha512", $message, $secretKey);

  $ch = curl_init();
  curl_setopt_array($ch, [
      CURLOPT_URL => "https://open-api.tingee.vn/v1/e-invoice/create",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_POST => true,
      CURLOPT_POSTFIELDS => $jsonBody,
      CURLOPT_HTTPHEADER => [
          "Content-Type: application/json",
          "x-client-id: YOUR_CLIENT_ID",
          "x-request-timestamp: " . $timestamp,
          "x-signature: " . $signature
      ]
  ]);

  $response = curl_exec($ch);
  curl_close($ch);
  echo $response;
}

Response mẫu

{
  "code": "00",
  "message": "Success",
  "data": {
    "invoiceCode": "INV-20251209-001",
    "pdfBase64": "JVBERi0xLjQKMSAwIG9iago8PA..."
  }
}

Trường	Kiểu	Mô tả
`code`	string	Mã trạng thái.
`message`	string	Thông điệp kết quả.
`data.invoiceCode`	string	Mã hóa đơn.
`data.pdfBase64`	string	Nội dung file PDF dạng Base64.

Mã lỗi thường gặp

Code	Mô tả	Hướng xử lý
`90`	Sai format timestamp	Kiểm tra format `yyyyMMddHHmmssSSS`.
`91`	Request quá hạn	Kiểm tra thời gian gửi request.
`97`	Sai chữ ký	Kiểm tra lại Secret Key và logic tạo Signature.
`Others`	Lỗi khác	Xem Danh sách mã lỗi.

Header Request​

Body Parameter​

items[] — Chi tiết hàng hóa / dịch vụ​

taxRateSummaries[] — Tổng hợp thuế suất​

Ví dụ mã nguồn​

Response mẫu​

Mã lỗi thường gặp​