API tải hóa đơn điện tử

Tải file hóa đơn điện tử dạng PDF hoặc XML theo mã tracking qua SePay E-Invoice API. Trả về nội dung file dạng base64 để lưu trữ hoặc in ấn.

||

API Endpoint

GET
https://einvoice-api.sepay.vn/v1/invoices/{tracking_code}/download

API Request

tracking_codestringrequired

Mã tracking của hóa đơn

typeenumrequired

Loại file cần tải (pdf hoặc xml)

API Response

Response thành công (200)
{
  "success": true,
  "data": {
    "file_type": "pdf",
    "file_name": "HD_0000589_20251215.pdf",
    "content": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlL1hPYmplY3Q..."
  }
}
successboolean
dataobject

Xử lý lỗi

400Bad Request

Tham số type không hợp lệ (không phải pdf hoặc xml).

401Unauthorized

Thiếu hoặc sai Bearer token.

404Not Found

Không tìm thấy hóa đơn theo tracking_code.

Lưu ý

Lưu ý
  • API trả về nội dung file dạng base64. Bạn cần decode base64 để lưu thành file PDF hoặc XML.
  • Tham số type chỉ chấp nhận hai giá trị: pdf hoặc xml.
  • Đảm bảo hóa đơn đã được phát hành thành công trước khi tải file.

Xử lý Base64 thành File

Sau khi gọi API thành công, bạn cần decode nội dung base64 và lưu thành file. Dưới đây là ví dụ với PHP:

PHPDecode Base64 và lưu file
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
<?php
// Giả sử $response là kết quả từ API
$response = json_decode($apiResult, true);
 
if ($response['success']) {
  // Lấy nội dung base64 từ response
  $base64Content = $response['data']['content'];
  $fileName = $response['data']['file_name'];
 
  // Decode base64 thành binary
  $binaryContent = base64_decode($base64Content);
 
  // Kiểm tra decode thành công
  if ($binaryContent === false) {
      throw new Exception('Lỗi decode base64');
  }
 
  // Lưu file
  $bytesWritten = file_put_contents($fileName, $binaryContent);
 
  if ($bytesWritten === false) {
      throw new Exception('Lỗi ghi file');
  }
 
  echo "Đã lưu file: {$fileName} ({$bytesWritten} bytes)";
}

Các bước xử lý:

  1. Parse JSON response - Chuyển đổi response thành mảng PHP
  2. Lấy nội dung base64 - Truy cập $response['data']['content']
  3. Decode base64 - Sử dụng base64_decode() để chuyển thành binary
  4. Lưu file - Sử dụng file_put_contents() để ghi ra file
Lưu ý quan trọng
  • Luôn kiểm tra kết quả base64_decode() vì có thể trả về false nếu chuỗi base64 không hợp lệ.
  • Đảm bảo thư mục lưu file có quyền ghi (write permission).
  • Với file PDF, có thể kiểm tra header %PDF sau khi decode để xác nhận file hợp lệ.

Code mẫu

>
>
>
curl --request GET \
  --url 'https://einvoice-api.sepay.vn/v1/invoices/084e179d-d95a-11f0-aef4-52c7e9b4f41b/download?type=pdf' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Bước tiếp theo

Sau khi tải hóa đơn thành công:

  1. Kiểm tra hạn ngạch — Kiểm tra số lượng hóa đơn còn lại trong gói dịch vụ để tránh gián đoạn khi xuất hóa đơn tiếp theo
  2. Xuất hóa đơn điện tử — Bắt đầu chu trình mới để xuất hóa đơn cho giao dịch tiếp theo
Trước
—
Tiếp theo
—