Tra cứu Thông điệp Hóa đơn

Truy vấn các thông điệp xử lý hóa đơn điện tử mà một nhà cung cấp T-VAN đang lưu cho một hóa đơn.

Không xác minh tính xác thực

Khả năng duy nhất của T-VAN về hóa đơn là liệt kê thông điệp hóa đơn. Nó không xác minh tính xác thực của hóa đơn với CQT, và không có thao tác validateInvoice.

Tổng quan

Tính năng	Mô tả
Service	TVanService.queryInvoiceMessages()
Nguồn Dữ liệu	Nhà cung cấp T-VAN (ví dụ VNPAY)
Trường hợp Sử dụng	Kiểm tra trạng thái/thông điệp xử lý hóa đơn

Trường hợp Sử dụng

• Lấy các thông điệp xử lý trả về cho một hóa đơn đã gửi
• Kiểm tra mã trạng thái của nhà cung cấp/CQT và ghi chú lý do theo từng thông điệp
• Phân trang qua các tập thông điệp lớn

Tra cứu Thông điệp Hóa đơn

import { TVanService } from '@nx/t-van';

async listInvoiceMessages() {
  const response = await this.tvanService.queryInvoiceMessages({
    provider: 'vnpay',
    params: {
      messageTypeCode: 200,
      messageCode: 'V0102182292A68308EFF92148B0A26',
      taxPayerTaxCode: '1801545696-999',
      invoiceNumberSymbol: '1',
      invoiceSymbol: 'C22THC',
      invoiceNumber: 13,
      invoiceIssuerTaxCode: '0101352495',
      fromDate: '2022-04-25T14:00:00',
      toDate: '2022-04-26T14:00:00',
      page: 0,
      size: 10,
    },
    options: { fetchAll: false },
  });

  return response.messages;
}

Cấu trúc Phản hồi

{
  "messages": [
    {
      "id": 3,
      "invoiceNumberSymbol": "1",
      "invoiceSymbol": "C22TPP",
      "messageTypeCode": 200,
      "messageCode": "V03123038035DE0AA1AC6C34EBAA03F54BD026AA35B",
      "responseMessageCode": "V03123038035DE0AA1AC6C34EBAA03F54BD026AA35B",
      "invoiceIssuerTaxCode": "0101352495",
      "invoiceNumber": 262,
      "taxPayerTaxCode": "0102182292-998",
      "taxDepartmentCode": "-1",
      "invoiceCreatedAt": "2024-01-01T00:00:00",
      "status": 5,
      "information": "Nhận thông tin lỗi từ tổng cục thuế",
      "reason": "02-CTS không phải do nhà CA cung cấp",
      "createdAt": "2024-01-01T00:00:00"
    }
  ],
  "currentPage": 0,
  "pageSize": 10,
  "totalPages": 5,
  "totalItems": 50
}

Trường status là mã số do nhà cung cấp định nghĩa; hãy diễn giải theo tài liệu của nhà cung cấp.

Lấy Toàn bộ Trang

Truyền options.fetchAll = true để tự động gộp mọi trang vào một mảng messages duy nhất (service tự duyệt totalPages):

const response = await this.tvanService.queryInvoiceMessages({
  provider: 'vnpay',
  params,
  options: { fetchAll: true },
});

Luồng Truy vấn

REST API

GET /t-van/invoices?provider=vnpay&messageTypeCode=200&messageCode=V0102182292A68308EFF92148B0A26&taxPayerTaxCode=1801545696-999&invoiceNumberSymbol=1&invoiceSymbol=C22THC&invoiceNumber=13&invoiceIssuerTaxCode=0101352495&fromDate=2022-04-25T14:00:00&toDate=2022-04-26T14:00:00&page=0&size=10

Xử lý Lỗi

Lỗi được trả về từ response của nhà cung cấp (HTTP status + payload lỗi). Hãy kiểm tra response của nhà cung cấp và log service:

try {
  const response = await this.tvanService.queryInvoiceMessages({ provider: 'vnpay', params });
  return response.messages;
} catch (error) {
  this.logger.error('[listInvoiceMessages] T-VAN query failed: %s', error);
  throw error;
}

Liên quan

• Tra cứu Thuế
• Tài liệu tham khảo API
• Tuân thủ