{
  "openapi": "3.1.0",
  "info": {
    "title": "hddt.dev API",
    "version": "1.0.0",
    "description": "Hợp đồng các endpoint đã có trang trên /docs. Endpoint chưa có trang tài liệu không nằm trong file này. Sandbox: https://sandbox.api.hddt.dev. Live: https://api.hddt.dev."
  },
  "servers": [
    {
      "url": "https://sandbox.api.hddt.dev",
      "description": "Sandbox"
    },
    {
      "url": "https://api.hddt.dev",
      "description": "Live"
    }
  ],
  "tags": [
    {
      "name": "Ứng dụng"
    },
    {
      "name": "Hoá đơn"
    },
    {
      "name": "Tra cứu"
    },
    {
      "name": "Webhook"
    }
  ],
  "paths": {
    "/v1/apps/{app_id}": {
      "get": {
        "tags": [
          "Ứng dụng"
        ],
        "operationId": "getApp",
        "summary": "Thông tin ứng dụng",
        "description": "Đọc hồ sơ ứng dụng đã tạo trong trang quản trị: tên, trạng thái, mã số thuế và hạn mức của môi trường gắn với API key.\n\nAPI này trả thông tin một ứng dụng bạn đã tạo trong trang quản trị. Dùng khi cần đối chiếu App ID, tên đơn vị, trạng thái hoạt động hoặc số hoá đơn còn lại trước khi phát hành.\n\nXác thực bằng API key trong header api_key. Key quyết định môi trường được trả về: key hddt_test_ đọc sandbox, key Live đọc production. Endpoint không dùng token hoá đơn và không trừ hạn mức phát hành.\n\nGửi GET với App ID trên đường dẫn. Host phải cùng môi trường với API key. Sandbox: https://sandbox.api.hddt.dev. Live: https://api.hddt.dev.\n\nAPI key phải thuộc đúng ứng dụng có app_id đó. Phản hồi không chứa API key, bí mật webhook hay danh sách IP cho phép.\n\nMarkdown: /docs/apps.md\n\n```bash\ncurl https://sandbox.api.hddt.dev/v1/apps/f47ac10b-58cc-4372-a567-0e02b2c3d479 \\\n  -H \"api_key: $HDDT_API_KEY\"\n```",
        "responses": {
          "200": {
            "description": "Thành công.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "App ID, trùng giá trị trên đường dẫn."
                    },
                    "object": {
                      "type": "string",
                      "description": "Luôn là app.",
                      "enum": [
                        "app"
                      ]
                    },
                    "name": {
                      "type": "string",
                      "description": "Tên ứng dụng trong trang quản trị."
                    },
                    "description": {
                      "type": "string",
                      "description": "Mô tả ngắn. Chuỗi rỗng nếu chưa nhập."
                    },
                    "status": {
                      "type": "string",
                      "description": "active khi ứng dụng đang chạy, paused khi đang tạm dừng."
                    },
                    "tax_code": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Mã số thuế đơn vị phát hành. null nếu chưa khai báo."
                    },
                    "company_name": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Tên đơn vị phát hành. null nếu chưa khai báo."
                    },
                    "environment": {
                      "type": "string",
                      "description": "sandbox hoặc live, theo API key của request.",
                      "enum": [
                        "sandbox",
                        "live"
                      ]
                    },
                    "base_url": {
                      "type": "string",
                      "description": "Host gốc của môi trường đó, gồm tiền tố /v1."
                    },
                    "rate_limit": {
                      "type": "integer",
                      "description": "Số request tối đa mỗi phút của môi trường này."
                    },
                    "created_at": {
                      "type": "string",
                      "description": "Thời điểm tạo ứng dụng, ISO 8601, múi giờ +07:00."
                    },
                    "quota": {
                      "type": "object",
                      "description": "Object quota theo môi trường của API key. Đây là tổng số hoá đơn được dùng, không làm mới theo tháng.",
                      "properties": {
                        "invoices_used": {
                          "type": "integer",
                          "description": "Tổng số hoá đơn đã phát hành trong môi trường này."
                        },
                        "invoices_remaining": {
                          "type": "integer",
                          "description": "Tổng số hoá đơn còn lại của môi trường. Không làm mới theo tháng. Khi về 0, API phát hành trả 402."
                        }
                      },
                      "required": [
                        "invoices_used",
                        "invoices_remaining"
                      ]
                    }
                  },
                  "required": [
                    "id",
                    "object",
                    "name",
                    "description",
                    "status",
                    "environment",
                    "base_url",
                    "rate_limit",
                    "created_at",
                    "quota"
                  ]
                },
                "example": {
                  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
                  "object": "app",
                  "name": "Shop ABC",
                  "description": "Website bán hàng, xuất hoá đơn tự động khi đơn hàng hoàn tất.",
                  "status": "active",
                  "tax_code": "0312345678",
                  "company_name": "Công ty TNHH Thương mại ABC",
                  "environment": "sandbox",
                  "base_url": "https://sandbox.api.hddt.dev/v1",
                  "rate_limit": 30,
                  "quota": {
                    "invoices_used": 342,
                    "invoices_remaining": 658
                  },
                  "created_at": "2026-03-12T09:00:00+07:00"
                }
              }
            }
          },
          "401": {
            "description": "unauthorized — Thiếu header api_key, API key sai hoặc đã bị thu hồi.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "forbidden — API key không thuộc app_id này, hoặc gửi key của môi trường khác (key hddt_live_ tới host Sandbox, key hddt_test_ tới host Live).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "not_found — Không có ứng dụng nào khớp app_id.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "validation_error — app_id không phải UUID.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "appApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "app_id",
            "in": "path",
            "required": true,
            "description": "Định danh ứng dụng (UUID) sao chép từ trang quản trị. Ví dụ f47ac10b-58cc-4372-a567-0e02b2c3d479.",
            "schema": {
              "type": "string",
              "description": "Định danh ứng dụng (UUID) sao chép từ trang quản trị. Ví dụ f47ac10b-58cc-4372-a567-0e02b2c3d479."
            }
          }
        ]
      },
      "patch": {
        "tags": [
          "Ứng dụng"
        ],
        "operationId": "updateApp",
        "summary": "Cập nhật ứng dụng",
        "description": "Sửa một phần hồ sơ ứng dụng: tên, mô tả, mã số thuế, tên đơn vị hoặc trạng thái. Trường không gửi giữ nguyên.\n\nAPI này sửa hồ sơ ứng dụng: tên, mô tả, mã số thuế, tên đơn vị và trạng thái chạy hoặc tạm dừng. Hạn mức, API key, webhook và danh sách IP không đổi qua endpoint này.\n\nSandbox và Live là hai hệ thống tách biệt. Gọi trên Live sẽ sửa hồ sơ chính thức, và console hiển thị đúng hồ sơ này. Gọi trên Sandbox chỉ sửa bản dùng để thử. Lần tới khi bạn sửa ứng dụng trên console, bản Sandbox sẽ bị ghi đè theo hồ sơ chính thức.\n\nChỉ gửi những trường cần sửa. Trường bỏ qua giữ giá trị hiện tại. Xác thực bằng API key của ứng dụng đó, không dùng token hoá đơn và không trừ hạn mức phát hành.\n\nGửi PATCH tới cùng đường dẫn với API đọc thông tin ứng dụng. Host phải cùng môi trường với API key. Sandbox: https://sandbox.api.hddt.dev. Live: https://api.hddt.dev.\n\nBody là JSON. Cần ít nhất một trường. API key phải thuộc đúng app_id trên đường dẫn.\n\nMarkdown: /docs/apps/update.md\n\n```bash\ncurl -X PATCH https://sandbox.api.hddt.dev/v1/apps/f47ac10b-58cc-4372-a567-0e02b2c3d479 \\\n  -H \"api_key: $HDDT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"tax_code\": \"0312345678\",\n    \"company_name\": \"Công ty TNHH Thương mại ABC\"\n  }'\n```",
        "responses": {
          "200": {
            "description": "Thành công.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "object": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "description": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string"
                    },
                    "tax_code": {
                      "type": "string"
                    },
                    "company_name": {
                      "type": "string"
                    },
                    "environment": {
                      "type": "string"
                    },
                    "base_url": {
                      "type": "string"
                    },
                    "rate_limit": {
                      "type": "integer"
                    },
                    "quota": {
                      "type": "object",
                      "properties": {
                        "invoices_used": {
                          "type": "integer"
                        },
                        "invoices_remaining": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "invoices_used",
                        "invoices_remaining"
                      ]
                    },
                    "created_at": {
                      "type": "string",
                      "format": "date-time"
                    }
                  },
                  "required": [
                    "id",
                    "object",
                    "name",
                    "description",
                    "status",
                    "tax_code",
                    "company_name",
                    "environment",
                    "base_url",
                    "rate_limit",
                    "quota",
                    "created_at"
                  ]
                },
                "example": {
                  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
                  "object": "app",
                  "name": "Shop ABC",
                  "description": "Website bán hàng, xuất hoá đơn tự động khi đơn hàng hoàn tất.",
                  "status": "active",
                  "tax_code": "0312345678",
                  "company_name": "Công ty TNHH Thương mại ABC",
                  "environment": "sandbox",
                  "base_url": "https://sandbox.api.hddt.dev/v1",
                  "rate_limit": 30,
                  "quota": {
                    "invoices_used": 342,
                    "invoices_remaining": 658
                  },
                  "created_at": "2026-03-12T09:00:00+07:00"
                }
              }
            }
          },
          "401": {
            "description": "unauthorized — Thiếu header api_key, API key sai hoặc đã bị thu hồi.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "forbidden — API key không thuộc app_id này, hoặc gửi key của môi trường khác (key hddt_live_ tới host Sandbox, key hddt_test_ tới host Live).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "not_found — Không có ứng dụng nào khớp app_id.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "validation_error — Body rỗng, app_id không phải UUID, tên ngoài 3–50 ký tự, mô tả dài hơn 160 ký tự, mã số thuế sai định dạng, status lạ, hoặc xoá mã số thuế / tên đơn vị khi Live đã bật.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "appApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "app_id",
            "in": "path",
            "required": true,
            "description": "Định danh ứng dụng (UUID) sao chép từ trang quản trị. Ví dụ f47ac10b-58cc-4372-a567-0e02b2c3d479.",
            "schema": {
              "type": "string",
              "description": "Định danh ứng dụng (UUID) sao chép từ trang quản trị. Ví dụ f47ac10b-58cc-4372-a567-0e02b2c3d479."
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Tên ứng dụng sau khi bỏ khoảng trắng hai đầu. Từ 3 đến 50 ký tự."
                  },
                  "description": {
                    "type": "string",
                    "description": "Mô tả ngắn, tối đa 160 ký tự. Chuỗi rỗng để xoá mô tả."
                  },
                  "tax_code": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Mã số thuế 10 số, hoặc chi nhánh dạng 0302712571-999. 13 số liền cũng được chấp nhận và được lưu thành dạng có dấu gạch. Chuỗi rỗng hoặc null để xoá. Khi Live đã bật, không được để trống."
                  },
                  "company_name": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Tên đơn vị phát hành. Chuỗi rỗng hoặc null để xoá. Khi Live đã bật, không được để trống."
                  },
                  "status": {
                    "type": "string",
                    "description": "active hoặc paused.",
                    "enum": [
                      "active",
                      "paused"
                    ]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/invoices/token": {
      "post": {
        "tags": [
          "Hoá đơn"
        ],
        "operationId": "createInvoiceToken",
        "summary": "Lấy token",
        "description": "Gửi App ID trên header để lấy token ngắn hạn dùng cho các API hoá đơn. Hệ thống tự lấy mã số thuế và tài khoản nhà cung cấp đã gắn với ứng dụng.\n\nTrước khi gọi các API hoá đơn, gửi App ID trên header để lấy một token ngắn hạn. App ID chọn đúng ứng dụng đã tạo trong trang quản trị.\n\nLấy App ID cạnh tên ứng dụng trên trang chi tiết (tab Kết nối & bảo mật). Không gửi body. Không gửi username hay password nhà cung cấp trong request. Hệ thống tự lấy mã số thuế và tài khoản nhà cung cấp đã gắn với ứng dụng (đội hỗ trợ cấu hình trên trang quản trị). Gửi API key và App ID trên header. Key sandbox có tiền tố hddt_test_. Token sandbox không gọi được host Live và ngược lại.\n\nToken có thời hạn. Hết hạn hoặc khi API hoá đơn trả 401, gọi lại endpoint này để lấy token mới.\n\nGửi POST tới host của môi trường đang dùng. Sandbox: https://sandbox.api.hddt.dev. Live: https://api.hddt.dev.\n\nĐặt API key vào header api_key và App ID vào header app_id. Không có body. API key phải thuộc đúng ứng dụng có App ID đó.\n\nMarkdown: /docs/invoices.md\n\n```bash\ncurl -X POST https://sandbox.api.hddt.dev/v1/invoices/token \\\n  -H \"api_key: $HDDT_API_KEY\" \\\n  -H \"app_id: $HDDT_APP_ID\"\n```",
        "responses": {
          "200": {
            "description": "Thành công.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "token": {
                      "type": "string",
                      "description": "Chuỗi dùng trong header Authorization của các API hoá đơn. Gửi kèm header api_key và app_id. Không ghi token ra log."
                    },
                    "token_type": {
                      "type": "string",
                      "description": "Luôn là Bearer.",
                      "enum": [
                        "Bearer"
                      ]
                    },
                    "expires_in": {
                      "type": "integer",
                      "description": "Số giây token còn hiệu lực, tính từ lúc phản hồi. Mặc định 3600 (1 giờ)."
                    },
                    "expires_at": {
                      "type": "string",
                      "description": "Thời điểm hết hạn, ISO 8601, múi giờ +07:00."
                    }
                  },
                  "required": [
                    "token",
                    "token_type",
                    "expires_in",
                    "expires_at"
                  ]
                },
                "example": {
                  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.xxxxxxx",
                  "token_type": "Bearer",
                  "expires_in": 3600,
                  "expires_at": "2026-10-27T15:09:00+07:00"
                }
              }
            }
          },
          "401": {
            "description": "unauthorized — Thiếu header api_key hoặc app_id; API key sai, đã thu hồi, hoặc không thuộc App ID; hoặc ứng dụng chưa có mã số thuế / tài khoản nhà cung cấp.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "forbidden — Ứng dụng đang tạm dừng, hoặc môi trường Live của app chưa được bật.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "not_found — Không có ứng dụng nào khớp app_id.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "appApiKey": [],
            "appId": []
          }
        ]
      }
    },
    "/v1/invoices/templates": {
      "get": {
        "tags": [
          "Hoá đơn"
        ],
        "operationId": "listInvoiceTemplates",
        "summary": "Lấy mẫu hoá đơn",
        "description": "Danh sách mẫu số và ký hiệu hoá đơn đã đăng ký theo năm, để chọn template_id khi tạo hoá đơn.\n\nAPI trả các mẫu hoá đơn doanh nghiệp đã đăng ký và còn dùng trong một năm. Khi tạo hoá đơn, gửi id của mẫu vào template_id.\n\nGọi endpoint này sau khi đã lấy token. Header Authorization dùng token đó. Gửi thêm API key trong header api_key và App ID trong header app_id. Các giá trị phải cùng ứng dụng, cùng môi trường. Endpoint không trừ hạn mức phát hành.\n\nMuốn xem sổ mẫu kèm số lượng đã dùng, tạo / duyệt / xoá mẫu trên trang quản lý, dùng các API trong nhóm mẫu hoá đơn ngay sau mục này. Các API đó giữ cùng cách gọi (token + api_key + app_id); hệ thống tự dùng tài khoản trang quản lý đã gắn với ứng dụng, không gửi username hay password trang quản lý trong request.\n\nGửi GET kèm năm trên query string. Host phải cùng môi trường với token. Sandbox: https://sandbox.api.hddt.dev. Live: https://api.hddt.dev.\n\nKhông có mẫu nào trong năm đó vẫn trả 200 với data là mảng rỗng.\n\nMarkdown: /docs/invoices/templates.md\n\n```bash\ncurl \"https://sandbox.api.hddt.dev/v1/invoices/templates?year=2026\" \\\n  -H \"Authorization: Bearer $HDDT_TOKEN\" \\\n  -H \"api_key: $HDDT_API_KEY\" \\\n  -H \"app_id: $HDDT_APP_ID\"\n```",
        "responses": {
          "200": {
            "description": "Thành công.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "type": "string",
                      "enum": [
                        "list"
                      ]
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "Giá trị gửi vào template_id khi tạo hoá đơn. Ghép ký hiệu mẫu số và ký hiệu hoá đơn, ví dụ 1C26TAA."
                          },
                          "object": {
                            "type": "string",
                            "description": "Luôn là invoice_template.",
                            "enum": [
                              "invoice_template"
                            ]
                          },
                          "form": {
                            "type": "string",
                            "description": "Ký hiệu mẫu số hoá đơn, ví dụ 1."
                          },
                          "serial": {
                            "type": "string",
                            "description": "Ký hiệu hoá đơn, 6 ký tự, ví dụ C26TAA. Xem mục Ký hiệu."
                          },
                          "year": {
                            "type": "integer",
                            "description": "Năm của mẫu, trùng năm đã gửi trên query."
                          },
                          "has_tax_authority_code": {
                            "type": "boolean",
                            "description": "true khi ký tự đầu của serial là C (có mã cơ quan thuế).\nfalse khi là K (không mã)."
                          },
                          "invoice_type": {
                            "type": "string",
                            "description": "Ký tự loại hoá đơn, ký tự thứ tư của serial. Một trong T, D, L, M, N, B, G, H.",
                            "enum": [
                              "T",
                              "D",
                              "L",
                              "M",
                              "N",
                              "B",
                              "G",
                              "H"
                            ]
                          }
                        },
                        "required": [
                          "id",
                          "object",
                          "form",
                          "serial",
                          "year",
                          "has_tax_authority_code",
                          "invoice_type"
                        ]
                      }
                    }
                  },
                  "required": [
                    "object",
                    "data"
                  ]
                },
                "example": {
                  "object": "list",
                  "data": [
                    {
                      "id": "1C26TAA",
                      "object": "invoice_template",
                      "form": "1",
                      "serial": "C26TAA",
                      "year": 2026,
                      "has_tax_authority_code": true,
                      "invoice_type": "T"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "unauthorized — Thiếu token hoặc header api_key, token sai hoặc hết hạn, API key đã thu hồi, hoặc key không cùng ứng dụng và môi trường với token. Gọi lại API Lấy token nếu token hết hạn.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "validation_error — Thiếu year hoặc year không phải năm dương lịch 4 chữ số.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "invoiceToken": [],
            "appApiKey": [],
            "appId": []
          }
        ],
        "parameters": [
          {
            "name": "year",
            "in": "query",
            "required": true,
            "description": "Năm dương lịch của mẫu đã đăng ký, 4 chữ số. Ví dụ 2026.",
            "schema": {
              "type": "integer",
              "description": "Năm dương lịch của mẫu đã đăng ký, 4 chữ số. Ví dụ 2026."
            }
          }
        ]
      },
      "post": {
        "tags": [
          "Hoá đơn"
        ],
        "operationId": "createInvoiceTemplate",
        "summary": "Tạo mẫu hoá đơn",
        "description": "Tạo mẫu số–ký hiệu mới. Gửi ký hiệu mẫu, năm lập, loại hoá đơn thường hoặc máy tính tiền, và hai ký tự cuối do người bán tự đặt. Bỏ trống ô có mã thì hiểu là có mã cơ quan thuế.\n\nAPI tạo một mẫu hoá đơn mới trên trang quản lý. Gửi ký hiệu mẫu, năm lập, chọn hoá đơn điện tử bình thường hoặc hoá đơn máy tính tiền, và hai ký tự cuối để phân biệt mẫu. Có mã cơ quan thuế hay không là tuỳ chọn; bỏ trống thì là có mã. Hệ thống ghép ký hiệu và tự chọn thiết kế mẫu.\n\nGọi endpoint này sau khi đã lấy token. Header Authorization dùng token đó. Gửi thêm API key trong header api_key và App ID trong header app_id. Các giá trị phải cùng ứng dụng, cùng môi trường.\n\nKhông gửi username hay password trang quản lý hoá đơn trong request. Hệ thống dùng tài khoản đã gắn với ứng dụng trên trang quản trị để đăng nhập và xử lý phần mẫu hoá đơn.\n\nSau khi tạo, mẫu thường chưa duyệt. Dùng Duyệt số lượng hoá đơn để cấp số lượng, hoặc Xoá mẫu chưa duyệt nếu tạo nhầm.\n\nGửi POST với body JSON. Host phải cùng môi trường với token. Sandbox: https://sandbox.api.hddt.dev. Live: https://api.hddt.dev.\n\nPath trùng với GET Lấy mẫu hoá đơn theo năm; method POST dùng để tạo mẫu mới.\n\nMarkdown: /docs/invoices/templates/create.md\n\n```bash\ncurl -X POST https://sandbox.api.hddt.dev/v1/invoices/templates \\\n  -H \"Authorization: Bearer $HDDT_TOKEN\" \\\n  -H \"api_key: $HDDT_API_KEY\" \\\n  -H \"app_id: $HDDT_APP_ID\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"form\": \"1\",\n    \"year\": 2026,\n    \"cash_register\": \"0\",\n    \"suffix\": \"TV\"\n  }'\n```",
        "responses": {
          "200": {
            "description": "Thành công.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "Định danh mẫu vừa tạo trên trang quản lý."
                    },
                    "object": {
                      "type": "string",
                      "description": "Luôn là invoice_template_registration.",
                      "enum": [
                        "invoice_template_registration"
                      ]
                    },
                    "template_id": {
                      "type": "string",
                      "description": "Ghép form và serial vừa tạo, ví dụ 1C26TTV."
                    },
                    "form": {
                      "type": "string",
                      "description": "Mẫu số vừa tạo."
                    },
                    "serial": {
                      "type": "string",
                      "description": "Ký hiệu vừa ghép. Ví dụ C26TTV khi có mã, năm 2026, hoá đơn điện tử bình thường và suffix TV."
                    },
                    "published": {
                      "type": "boolean",
                      "description": "false ngay sau khi tạo, cho đến khi mẫu được duyệt."
                    }
                  },
                  "required": [
                    "id",
                    "object",
                    "template_id",
                    "form",
                    "serial",
                    "published"
                  ]
                },
                "example": {
                  "id": "15899",
                  "object": "invoice_template_registration",
                  "template_id": "1C26TTV",
                  "form": "1",
                  "serial": "C26TTV",
                  "published": false
                }
              }
            }
          },
          "401": {
            "description": "unauthorized — Thiếu token hoặc header api_key, token sai hoặc hết hạn, API key đã thu hồi, hoặc key không cùng ứng dụng và môi trường với token. Gọi lại API Lấy token nếu token hết hạn.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "conflict — Cặp form và serial đã tồn tại.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "validation_error — Thiếu form, year, cash_register hoặc suffix; form không phải 1 hoặc 2; year không phải năm 4 chữ số; cash_register không phải 0 hoặc 1; suffix không phải đúng 2 chữ cái; hoặc has_tax_authority_code không phải true hoặc false.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "bad_gateway — Ứng dụng chưa được gắn tài khoản trang quản lý hoá đơn, hoặc hệ thống không đăng nhập được bằng tài khoản đó.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "invoiceToken": [],
            "appApiKey": [],
            "appId": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "form": {
                    "type": "string",
                    "description": "Ký hiệu mẫu số.\n1: Hoá đơn giá trị gia tăng.\n2: Hoá đơn bán hàng."
                  },
                  "has_tax_authority_code": {
                    "type": "boolean",
                    "description": "Hoá đơn có mã của cơ quan thuế hay không. Bỏ trống thì là có mã.\ntrue khi có mã. Ký tự 1 của serial là C.\nfalse khi không có mã. Ký tự 1 của serial là K."
                  },
                  "year": {
                    "type": "integer",
                    "description": "Năm lập hoá đơn, 4 chữ số. Hai số cuối thành ký tự 2–3 của serial. Năm 2026 ghi thành 26."
                  },
                  "cash_register": {
                    "type": "string",
                    "description": "Cách lập hoá đơn.\n0: Hoá đơn điện tử bình thường. Ký tự 4 của serial là T.\n1: Hoá đơn máy tính tiền. Ký tự 4 của serial là M."
                  },
                  "suffix": {
                    "type": "string",
                    "description": "Hai ký tự cuối của serial, do người bán tự đặt để phân biệt các mẫu cùng loại. Đúng 2 chữ cái, ví dụ TV."
                  }
                },
                "required": [
                  "form",
                  "year",
                  "cash_register",
                  "suffix"
                ]
              }
            }
          }
        }
      }
    },
    "/v1/invoices/templates/registered": {
      "get": {
        "tags": [
          "Hoá đơn"
        ],
        "operationId": "listRegisteredInvoiceTemplates",
        "summary": "Danh sách mẫu đã đăng ký",
        "description": "Danh sách mẫu số và ký hiệu hoá đơn đã tạo trên trang quản lý, kèm số lượng đã dùng và còn lại của từng mẫu.\n\nAPI trả các mẫu hoá đơn doanh nghiệp đã tạo trên trang quản lý, gồm mẫu số, ký hiệu, số lượng đã cấp, đã dùng và còn lại. Dùng để đối chiếu hạn mức từng mẫu hoặc lấy id mẫu chưa duyệt trước khi xoá / duyệt số lượng.\n\nGọi endpoint này sau khi đã lấy token. Header Authorization dùng token đó. Gửi thêm API key trong header api_key và App ID trong header app_id. Các giá trị phải cùng ứng dụng, cùng môi trường.\n\nKhông gửi username hay password trang quản lý hoá đơn trong request. Hệ thống dùng tài khoản đã gắn với ứng dụng trên trang quản trị để đăng nhập và xử lý phần mẫu hoá đơn.\n\nKhác với API Lấy mẫu hoá đơn theo năm: endpoint đó dùng khi chọn template_id lúc tạo hoá đơn; endpoint này đọc sổ mẫu đã đăng ký kèm số lượng.\n\nGửi GET không có query. Host phải cùng môi trường với token. Sandbox: https://sandbox.api.hddt.dev. Live: https://api.hddt.dev.\n\nChưa có mẫu nào vẫn trả 200 với data là mảng rỗng.\n\nMarkdown: /docs/invoices/templates/registered.md\n\n```bash\ncurl https://sandbox.api.hddt.dev/v1/invoices/templates/registered \\\n  -H \"Authorization: Bearer $HDDT_TOKEN\" \\\n  -H \"api_key: $HDDT_API_KEY\" \\\n  -H \"app_id: $HDDT_APP_ID\"\n```",
        "responses": {
          "200": {
            "description": "Thành công.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "type": "string",
                      "enum": [
                        "list"
                      ]
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "Định danh mẫu đã đăng ký trên trang quản lý. Dùng khi duyệt số lượng hoặc xoá mẫu chưa duyệt."
                          },
                          "object": {
                            "type": "string",
                            "description": "Luôn là invoice_template_registration.",
                            "enum": [
                              "invoice_template_registration"
                            ]
                          },
                          "template_id": {
                            "type": "string",
                            "description": "Ghép mẫu số và ký hiệu, ví dụ 1C26TTV. Có thể dùng tương ứng template_id khi tạo hoá đơn."
                          },
                          "form": {
                            "type": "string",
                            "description": "Ký hiệu mẫu số hoá đơn, ví dụ 1."
                          },
                          "serial": {
                            "type": "string",
                            "description": "Ký hiệu hoá đơn, 6 ký tự, ví dụ C26TTV."
                          },
                          "year": {
                            "type": "integer",
                            "description": "Năm suy từ hai số trong serial."
                          },
                          "quantity": {
                            "type": "integer",
                            "description": "Số lượng hoá đơn đã cấp cho mẫu."
                          },
                          "used": {
                            "type": "integer",
                            "description": "Số lượng đã dùng."
                          },
                          "remaining": {
                            "type": "integer",
                            "description": "Số lượng còn lại."
                          },
                          "invoice_category_name": {
                            "type": "string",
                            "description": "Tên loại hoá đơn, ví dụ Hóa đơn giá trị gia tăng."
                          },
                          "published": {
                            "type": "boolean",
                            "description": "true khi mẫu đã được duyệt.\nfalse khi mẫu còn chưa duyệt."
                          }
                        },
                        "required": [
                          "id",
                          "object",
                          "template_id",
                          "form",
                          "serial",
                          "year",
                          "quantity",
                          "used",
                          "remaining",
                          "published"
                        ]
                      }
                    }
                  },
                  "required": [
                    "object",
                    "data"
                  ]
                },
                "example": {
                  "object": "list",
                  "data": [
                    {
                      "id": "13362",
                      "object": "invoice_template_registration",
                      "template_id": "1C26TDV",
                      "form": "1",
                      "serial": "C26TDV",
                      "year": 2026,
                      "quantity": 10,
                      "used": 0,
                      "remaining": 10,
                      "invoice_category_name": "Hóa đơn giá trị gia tăng",
                      "published": true
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "unauthorized — Thiếu token hoặc header api_key, token sai hoặc hết hạn, API key đã thu hồi, hoặc key không cùng ứng dụng và môi trường với token. Gọi lại API Lấy token nếu token hết hạn.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "bad_gateway — Ứng dụng chưa được gắn tài khoản trang quản lý hoá đơn, hoặc hệ thống không đăng nhập được bằng tài khoản đó.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "invoiceToken": [],
            "appApiKey": [],
            "appId": []
          }
        ]
      }
    },
    "/v1/invoices/quota": {
      "get": {
        "tags": [
          "Hoá đơn"
        ],
        "operationId": "getInvoiceQuota",
        "summary": "Hạn mức hoá đơn",
        "description": "Xem ngân sách hoá đơn của doanh nghiệp trên trang quản lý: tổng số đã có và số còn lại để phát hành.\n\nAPI trả ngân sách hoá đơn của doanh nghiệp trên trang quản lý: total là tổng số hoá đơn trong hạn mức, remaining là số còn lại có thể dùng để phát hành.\n\nDùng khi cần biết còn bao nhiêu hoá đơn trước khi tạo hoá đơn hoặc duyệt thêm số lượng cho mẫu. Đây là hạn mức tổng của tài khoản, không phải số lượng gắn từng mẫu số–ký hiệu.\n\nGọi endpoint này sau khi đã lấy token. Header Authorization dùng token đó. Gửi thêm API key trong header api_key và App ID trong header app_id. Các giá trị phải cùng ứng dụng, cùng môi trường.\n\nKhông gửi username hay password trang quản lý hoá đơn trong request. Hệ thống dùng tài khoản đã gắn với ứng dụng trên trang quản trị để đăng nhập và xử lý phần mẫu hoá đơn.\n\nGửi GET không có query. Host phải cùng môi trường với token. Sandbox: https://sandbox.api.hddt.dev. Live: https://api.hddt.dev.\n\nMarkdown: /docs/invoices/quota.md\n\n```bash\ncurl https://sandbox.api.hddt.dev/v1/invoices/quota \\\n  -H \"Authorization: Bearer $HDDT_TOKEN\" \\\n  -H \"api_key: $HDDT_API_KEY\" \\\n  -H \"app_id: $HDDT_APP_ID\"\n```",
        "responses": {
          "200": {
            "description": "Thành công.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "type": "string",
                      "description": "Luôn là invoice_quota.",
                      "enum": [
                        "invoice_quota"
                      ]
                    },
                    "total": {
                      "type": "integer",
                      "description": "Tổng số hoá đơn trong ngân sách / hạn mức của tài khoản."
                    },
                    "remaining": {
                      "type": "integer",
                      "description": "Số hoá đơn còn lại có thể dùng để phát hành."
                    }
                  },
                  "required": [
                    "object",
                    "total",
                    "remaining"
                  ]
                },
                "example": {
                  "object": "invoice_quota",
                  "total": 1000,
                  "remaining": 850
                }
              }
            }
          },
          "401": {
            "description": "unauthorized — Thiếu token hoặc header api_key, token sai hoặc hết hạn, API key đã thu hồi, hoặc key không cùng ứng dụng và môi trường với token. Gọi lại API Lấy token nếu token hết hạn.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "bad_gateway — Ứng dụng chưa được gắn tài khoản trang quản lý hoá đơn, hoặc hệ thống không đăng nhập được bằng tài khoản đó.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "invoiceToken": [],
            "appApiKey": [],
            "appId": []
          }
        ]
      }
    },
    "/v1/invoices/templates/approve-quantity": {
      "post": {
        "tags": [
          "Hoá đơn"
        ],
        "operationId": "approveInvoiceTemplateQuantity",
        "summary": "Duyệt số lượng hoá đơn",
        "description": "Cấp hoặc cập nhật số lượng hoá đơn cho một hoặc nhiều mẫu đã đăng ký trên trang quản lý.\n\nAPI duyệt số lượng cho từng mẫu đã đăng ký. Mỗi dòng chỉ cần id mẫu, số lượng muốn cấp và số lượng trước đó.\n\nGọi endpoint này sau khi đã lấy token. Header Authorization dùng token đó. Gửi thêm API key trong header api_key và App ID trong header app_id. Các giá trị phải cùng ứng dụng, cùng môi trường.\n\nKhông gửi username hay password trang quản lý hoá đơn trong request. Hệ thống dùng tài khoản đã gắn với ứng dụng trên trang quản trị để đăng nhập và xử lý phần mẫu hoá đơn.\n\nGửi POST với body JSON. Host phải cùng môi trường với token. Sandbox: https://sandbox.api.hddt.dev. Live: https://api.hddt.dev.\n\nMarkdown: /docs/invoices/templates/approve-quantity.md\n\n```bash\ncurl -X POST https://sandbox.api.hddt.dev/v1/invoices/templates/approve-quantity \\\n  -H \"Authorization: Bearer $HDDT_TOKEN\" \\\n  -H \"api_key: $HDDT_API_KEY\" \\\n  -H \"app_id: $HDDT_APP_ID\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"items\": [\n      {\n        \"id\": 13362,\n        \"quantity\": 10,\n        \"quantity_previous\": 10\n      }\n    ]\n  }'\n```",
        "responses": {
          "200": {
            "description": "Thành công.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "type": "string",
                      "description": "Luôn là invoice_template_approve_quantity.",
                      "enum": [
                        "invoice_template_approve_quantity"
                      ]
                    },
                    "approved": {
                      "type": "integer",
                      "description": "Số dòng mẫu đã duyệt trong request."
                    }
                  },
                  "required": [
                    "object",
                    "approved"
                  ]
                },
                "example": {
                  "object": "invoice_template_approve_quantity",
                  "approved": 1
                }
              }
            }
          },
          "401": {
            "description": "unauthorized — Thiếu token hoặc header api_key, token sai hoặc hết hạn, API key đã thu hồi, hoặc key không cùng ứng dụng và môi trường với token. Gọi lại API Lấy token nếu token hết hạn.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "validation_error — Thiếu items, mảng rỗng, hoặc một dòng thiếu id, quantity hoặc quantity_previous.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "bad_gateway — Ứng dụng chưa được gắn tài khoản trang quản lý hoá đơn, hoặc hệ thống không đăng nhập được bằng tài khoản đó.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "invoiceToken": [],
            "appApiKey": [],
            "appId": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "items": {
                    "type": "array",
                    "description": "Danh sách mẫu cần duyệt số lượng. Không được để mảng rỗng.",
                    "items": {}
                  },
                  "items[].id": {
                    "type": "integer",
                    "description": "Id mẫu đã đăng ký (trường id trên Danh sách mẫu đã đăng ký)."
                  },
                  "items[].quantity": {
                    "type": "integer",
                    "description": "Số lượng muốn cấp sau khi duyệt."
                  },
                  "items[].quantity_previous": {
                    "type": "integer",
                    "description": "Số lượng trước khi duyệt, lấy từ quantity hiện tại của mẫu."
                  }
                },
                "required": [
                  "items",
                  "items[].id",
                  "items[].quantity",
                  "items[].quantity_previous"
                ]
              }
            }
          }
        }
      }
    },
    "/v1/invoices/templates/{id}": {
      "delete": {
        "tags": [
          "Hoá đơn"
        ],
        "operationId": "deleteInvoiceTemplate",
        "summary": "Xoá mẫu chưa duyệt",
        "description": "Xoá một mẫu hoá đơn đã tạo nhưng chưa được duyệt số lượng trên trang quản lý.\n\nAPI xoá mẫu đã tạo khi mẫu chưa được duyệt số lượng. Mẫu đã có số lượng sẽ bị từ chối.\n\nGọi endpoint này sau khi đã lấy token. Header Authorization dùng token đó. Gửi thêm API key trong header api_key và App ID trong header app_id. Các giá trị phải cùng ứng dụng, cùng môi trường.\n\nKhông gửi username hay password trang quản lý hoá đơn trong request. Hệ thống dùng tài khoản đã gắn với ứng dụng trên trang quản trị để đăng nhập và xử lý phần mẫu hoá đơn.\n\nGửi DELETE với id mẫu trên đường dẫn. Host phải cùng môi trường với token. Sandbox: https://sandbox.api.hddt.dev. Live: https://api.hddt.dev.\n\nMarkdown: /docs/invoices/templates/delete.md\n\n```bash\ncurl -X DELETE https://sandbox.api.hddt.dev/v1/invoices/templates/15899 \\\n  -H \"Authorization: Bearer $HDDT_TOKEN\" \\\n  -H \"api_key: $HDDT_API_KEY\" \\\n  -H \"app_id: $HDDT_APP_ID\"\n```",
        "responses": {
          "200": {
            "description": "Thành công.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "Id mẫu vừa xoá."
                    },
                    "object": {
                      "type": "string",
                      "description": "Luôn là invoice_template_registration.",
                      "enum": [
                        "invoice_template_registration"
                      ]
                    },
                    "deleted": {
                      "type": "boolean",
                      "description": "Luôn là true.",
                      "enum": [
                        "true"
                      ]
                    }
                  },
                  "required": [
                    "id",
                    "object",
                    "deleted"
                  ]
                },
                "example": {
                  "id": "15899",
                  "object": "invoice_template_registration",
                  "deleted": true
                }
              }
            }
          },
          "401": {
            "description": "unauthorized — Thiếu token hoặc header api_key, token sai hoặc hết hạn, API key đã thu hồi, hoặc key không cùng ứng dụng và môi trường với token. Gọi lại API Lấy token nếu token hết hạn.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "not_found — Không có mẫu khớp id.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "conflict — Mẫu đã được duyệt số lượng. Chỉ xoá được mẫu có số lượng còn trống.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "bad_gateway — Ứng dụng chưa được gắn tài khoản trang quản lý hoá đơn, hoặc hệ thống không đăng nhập được bằng tài khoản đó.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "invoiceToken": [],
            "appApiKey": [],
            "appId": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Định danh mẫu đã đăng ký. Ví dụ 15899.",
            "schema": {
              "type": "string",
              "description": "Định danh mẫu đã đăng ký. Ví dụ 15899."
            }
          }
        ]
      }
    },
    "/v1/invoices": {
      "post": {
        "tags": [
          "Hoá đơn"
        ],
        "operationId": "createInvoice",
        "summary": "Tạo hoá đơn",
        "description": "Tạo một hoá đơn nháp hoặc phát hành hoá đơn điện tử. Tên trường là tiếng Anh. Mỗi lần phát hành thành công trừ một hoá đơn khỏi hạn mức của app.\n\nAPI tạo một hoá đơn. issue_mode bằng 0 thì lưu nháp, bằng 1 thì tạo và phát hành. Trường này không bắt buộc. Hoá đơn có mã hay không mã của cơ quan thuế phụ thuộc mẫu đã chọn.\n\nGửi template_id lấy từ API Lấy mẫu hoá đơn. Khi thay thế hoặc điều chỉnh, gửi related_invoice_id bằng id (UUID) của hoá đơn gốc. Thay thế hoặc điều chỉnh chỉ tạo được khi ứng dụng đang dùng đúng nhà cung cấp đã phát hành hoá đơn gốc.\n\nreference luôn duy nhất trong ứng dụng. Bỏ trống reference_duplicate_policy, hoặc gửi 0 hoặc 1, thì trùng mã tham chiếu sẽ bị từ chối. lookup_code không có ràng buộc unique trong database; bỏ trống lookup_code_duplicate_policy thì không kiểm tra trùng mã tra cứu.\n\nChưa hỗ trợ vé xe, hàng hoá đặc trưng và các trường mở rộng. Trên sandbox, hoá đơn không được gửi tới cơ quan thuế. Thử trên host sandbox.api.hddt.dev với token, API key tiền tố hddt_test_ và App ID. Phát hành thật trên api.hddt.dev với token và API key Live.\n\nGửi POST với JSON. Sandbox: https://sandbox.api.hddt.dev. Live: https://api.hddt.dev.\n\nMarkdown: /docs/invoices/create.md\n\n```bash\ncurl -X POST https://api.hddt.dev/v1/invoices \\\n  -H \"Authorization: Bearer $HDDT_TOKEN\" \\\n  -H \"api_key: $HDDT_API_KEY\" \\\n  -H \"app_id: $HDDT_APP_ID\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: 7c1d6c3e-2f4b-4a8e\" \\\n  -d '{\n    \"invoice_type\": 0,\n    \"template_id\": \"1C26TAA\",\n    \"lookup_code\": \"7B164DE808\",\n    \"lookup_code_duplicate_policy\": 0,\n    \"reference\": \"DH-1001\",\n    \"reference_duplicate_policy\": 1,\n    \"seller_store_code\": \"CH01\",\n    \"seller_store_name\": \"Cửa hàng Quận 1\",\n    \"currency\": \"VND\",\n    \"exchange_rate\": 1,\n    \"buyer\": {\n      \"name\": \"Công ty TNHH ABC\",\n      \"tax_code\": \"0312345678\",\n      \"address\": \"123 Nguyễn Huệ, Quận 1, TP. Hồ Chí Minh\",\n      \"email\": \"ketoan@abc.vn\"\n    },\n    \"items\": [\n      {\n        \"item_type\": 1,\n        \"line_number\": 1,\n        \"name\": \"Gói phần mềm\",\n        \"unit\": \"Gói\",\n        \"quantity\": 1,\n        \"unit_price\": 5000000,\n        \"amount_before_discount\": 5000000,\n        \"discount_rate\": 0,\n        \"discount_amount\": 0,\n        \"amount\": 5000000,\n        \"vat_rate\": 10,\n        \"tax_amount\": 500000,\n        \"line_total\": 5500000\n      }\n    ],\n    \"subtotal\": 5000000,\n    \"trade_discount\": 0,\n    \"other_deduction\": 0,\n    \"tax_total\": 500000,\n    \"total\": 5500000,\n    \"total_in_words\": \"Năm triệu năm trăm nghìn đồng\"\n  }'\n```",
        "responses": {
          "200": {
            "description": "Thành công.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "description": "true khi tạo được hoá đơn, false khi thất bại."
                    },
                    "data": {
                      "type": "object",
                      "description": "Kết quả tạo hoá đơn. Khi thành công có id (UUID), number và lookup_code. Khi có mã số thuế người mua thì thêm pdf_url. xml_url chỉ có khi phát hành."
                    },
                    "error_code": {
                      "type": "string",
                      "description": "Trống khi thành công. Khi thất bại là mã lỗi nghiệp vụ."
                    },
                    "message": {
                      "type": "string",
                      "description": "Thông báo thành công hoặc thất bại."
                    },
                    "id": {
                      "type": "string",
                      "description": "UUID của hoá đơn nằm trong data. Gửi lại vào related_invoice_id khi thay thế hoặc điều chỉnh."
                    },
                    "number": {
                      "type": "integer",
                      "description": "Số hoá đơn nằm trong data khi tạo thành công. Tối đa 8 chữ số."
                    },
                    "lookup_code": {
                      "type": "string",
                      "description": "Mã tra cứu nằm trong data khi tạo thành công. Tối đa 100 ký tự."
                    },
                    "pdf_url": {
                      "type": "string",
                      "description": "Có khi tạo thành công, kể cả nháp, và hoá đơn có mã số thuế người mua. Mở bản thể hiện: https://hddt.dev/tra-cuu/hoa-don?token=...&type=pdf."
                    },
                    "xml_url": {
                      "type": "string",
                      "description": "Chỉ có khi phát hành, không có ở hoá đơn nháp. Cùng token với pdf_url. Tải file XML: https://hddt.dev/tra-cuu/hoa-don?token=...&type=xml."
                    }
                  },
                  "required": [
                    "success",
                    "data",
                    "error_code",
                    "message"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "bad_request — Request sai định dạng hoặc thiếu tham số bắt buộc.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "unauthorized — Thiếu token hoặc header api_key, token hết hạn, API key đã thu hồi, hoặc key không cùng ứng dụng và môi trường với token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Hết hạn mức hoá đơn của môi trường đang gọi.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "not_found — Không tìm thấy template_id hoặc related_invoice_id.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "conflict — Trùng Idempotency-Key với request khác nội dung, mã tra cứu đã tồn tại theo chính sách, hoặc reference đã tồn tại trong ứng dụng.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "validation_error — Dữ liệu không hợp lệ: thiếu trường bắt buộc, thuế suất vat_rate ngoài danh mục, hoặc related_invoice_id thuộc nhà cung cấp khác với nhà cung cấp đang dùng.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "rate_limited — Vượt giới hạn số request cho phép.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "invoiceToken": [],
            "appApiKey": [],
            "appId": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Chuỗi duy nhất cho mỗi lần phát hành. Cùng key và cùng nội dung trả lại kết quả đã tạo. Cùng key nhưng nội dung khác trả 409.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "issue_mode": {
                    "type": "integer",
                    "description": "Cách tạo.\n0: lưu nháp.\n1: tạo và phát hành.\nTối đa 10 chữ số."
                  },
                  "invoice_type": {
                    "type": "integer",
                    "description": "Tính chất hoá đơn.\n0: hoá đơn mới.\n1: thay thế.\n2: điều chỉnh tăng.\n3: điều chỉnh giảm.\n4: điều chỉnh thông tin.\n5: điều chỉnh tăng và giảm.\nTối đa 5 chữ số."
                  },
                  "template_id": {
                    "type": "string",
                    "description": "Mã mẫu từ API Lấy mẫu hoá đơn, ví dụ 1C26TAA."
                  },
                  "issued_at": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Ngày lập hoá đơn."
                  },
                  "currency": {
                    "type": "string",
                    "description": "Mã tiền tệ ISO 4217.\nVND: Việt Nam đồng.\nUSD: đô la Mỹ.\nCAD: đô la Canada.\nHệ thống tự map sang mã của từng nhà cung cấp khi gọi nền tảng."
                  },
                  "exchange_rate": {
                    "type": "number",
                    "description": "Tỷ giá. Với VND gửi 1. Tối đa 7 chữ số, 2 chữ số thập phân."
                  },
                  "payment_method": {
                    "type": "string",
                    "description": "Hình thức thanh toán."
                  },
                  "lookup_code": {
                    "type": "string",
                    "description": "Mã tra cứu. Tối đa 100 ký tự."
                  },
                  "lookup_code_duplicate_policy": {
                    "type": "integer",
                    "description": "Cách xử lý khi lookup_code trùng.\n0: trùng thì không tạo.\n1: trùng thì xoá hoá đơn chưa phát hành, hoá đơn đã phát hành thì không tạo.\nBỏ trống thì không kiểm tra."
                  },
                  "reference": {
                    "type": "string",
                    "description": "Mã tham chiếu của hoá đơn trên hệ thống của bạn. Duy nhất trong ứng dụng. Tối đa 20 ký tự."
                  },
                  "reference_duplicate_policy": {
                    "type": "integer",
                    "description": "Cách xử lý khi reference trùng.\n0: giữ để tương thích, trùng thì từ chối.\n1: trùng thì từ chối.\n2: trùng thì xoá hoá đơn chưa phát hành; hoá đơn đã phát hành thì từ chối.\nBỏ trống: trùng thì từ chối."
                  },
                  "note": {
                    "type": "string",
                    "description": "Ghi chú. Tối đa 255 ký tự."
                  },
                  "related_invoice_id": {
                    "type": "string",
                    "description": "UUID của hoá đơn gốc, lấy từ id của hoá đơn đó. Dùng khi invoice_type là thay thế hoặc điều chỉnh."
                  },
                  "subtotal": {
                    "type": "number",
                    "description": "Tổng tiền trước thuế. Tối đa 21 chữ số, 6 chữ số thập phân."
                  },
                  "trade_discount": {
                    "type": "number",
                    "description": "Tổng tiền chiết khấu thương mại. Gửi 0 nếu không chiết khấu. Tối đa 21 chữ số, 6 chữ số thập phân."
                  },
                  "other_deduction": {
                    "type": "number",
                    "description": "Tổng giảm trừ khác. Gửi 0 nếu không giảm trừ. Tối đa 21 chữ số, 6 chữ số thập phân."
                  },
                  "tax_total": {
                    "type": "number",
                    "description": "Tổng tiền thuế. Tối đa 21 chữ số, 6 chữ số thập phân."
                  },
                  "total": {
                    "type": "number",
                    "description": "Tổng tiền thanh toán bằng số. Tối đa 21 chữ số, 6 chữ số thập phân."
                  },
                  "total_in_words": {
                    "type": "string",
                    "description": "Tổng tiền thanh toán bằng chữ. Tối đa 255 ký tự."
                  },
                  "buyer": {
                    "type": "object",
                    "description": "Người mua. Xem mục Người mua.",
                    "properties": {
                      "name": {
                        "type": "string",
                        "description": "Tên đơn vị hoặc tên khách hàng. Tối đa 100 ký tự."
                      },
                      "tax_code": {
                        "type": "string",
                        "description": "Mã số thuế người mua. Tối đa 14 ký tự."
                      },
                      "address": {
                        "type": "string",
                        "description": "Địa chỉ. Tối đa 400 ký tự."
                      },
                      "code": {
                        "type": "string",
                        "description": "Mã khách hàng trên hệ thống của bạn. Tối đa 100 ký tự."
                      },
                      "phone": {
                        "type": "string",
                        "description": "Số điện thoại. Tối đa 20 ký tự."
                      },
                      "email": {
                        "type": "string",
                        "description": "Email. Tối đa 50 ký tự."
                      },
                      "contact_name": {
                        "type": "string",
                        "description": "Họ và tên người mua hàng. Tối đa 100 ký tự."
                      },
                      "bank_account": {
                        "type": "string",
                        "description": "Số tài khoản ngân hàng."
                      },
                      "bank_name": {
                        "type": "string",
                        "description": "Tên ngân hàng."
                      },
                      "citizen_id": {
                        "type": "string",
                        "description": "Số định danh cá nhân (CCCD). Tối đa 12 ký tự."
                      },
                      "budget_unit_code": {
                        "type": "string",
                        "description": "Mã đơn vị quan hệ ngân sách. Tối đa 7 ký tự."
                      },
                      "passport": {
                        "type": "string",
                        "description": "Số hộ chiếu hoặc giấy tờ nhập xuất cảnh. Tối đa 20 ký tự."
                      }
                    }
                  },
                  "items": {
                    "type": "array",
                    "description": "Danh sách hàng hoá, dịch vụ. Xem mục Dòng hàng.",
                    "items": {
                      "type": "object",
                      "properties": {
                        "item_type": {
                          "type": "integer",
                          "description": "Tính chất dòng.\n1: hàng hoá, dịch vụ.\n2: khuyến mãi.\n3: chiết khấu.\n4: ghi chú."
                        },
                        "line_number": {
                          "type": "integer",
                          "description": "Số thứ tự dòng. Tối đa 4 chữ số."
                        },
                        "code": {
                          "type": "string",
                          "description": "Mã hàng hoá, dịch vụ. Tối đa 50 ký tự."
                        },
                        "name": {
                          "type": "string",
                          "description": "Tên hàng hoá, dịch vụ. Tối đa 500 ký tự."
                        },
                        "unit": {
                          "type": "string",
                          "description": "Đơn vị tính. Tối đa 50 ký tự."
                        },
                        "quantity": {
                          "type": "number",
                          "description": "Số lượng. Tối đa 21 chữ số, 6 chữ số thập phân."
                        },
                        "unit_price": {
                          "type": "number",
                          "description": "Đơn giá. Tối đa 21 chữ số, 6 chữ số thập phân."
                        },
                        "amount_before_discount": {
                          "type": "number",
                          "description": "Thành tiền trước thuế, trước chiết khấu. Tối đa 21 chữ số, 6 chữ số thập phân."
                        },
                        "discount_rate": {
                          "type": "number",
                          "description": "Tỷ lệ chiết khấu, đơn vị phần trăm. Gửi 0 nếu không chiết khấu. Tối đa 6 chữ số, 4 chữ số thập phân."
                        },
                        "discount_amount": {
                          "type": "number",
                          "description": "Số tiền chiết khấu. Gửi 0 nếu không chiết khấu. Tối đa 21 chữ số, 6 chữ số thập phân."
                        },
                        "amount": {
                          "type": "number",
                          "description": "Thành tiền trước thuế, sau chiết khấu. Tối đa 21 chữ số, 6 chữ số thập phân."
                        },
                        "vat_rate": {
                          "type": "number",
                          "description": "Thuế suất.\n-2: không kê khai, không nộp thuế.\n-1: không chịu thuế.\n0: 0%.\n5: 5%.\n8: 8%.\n10: 10%.\n3.5: thuế suất khác."
                        },
                        "tax_amount": {
                          "type": "number",
                          "description": "Tiền thuế của dòng. Tối đa 21 chữ số, 6 chữ số thập phân."
                        },
                        "line_total": {
                          "type": "number",
                          "description": "Tiền sau thuế của dòng. Tối đa 21 chữ số, 6 chữ số thập phân."
                        }
                      },
                      "required": [
                        "item_type",
                        "line_number",
                        "name",
                        "quantity",
                        "unit_price",
                        "amount_before_discount",
                        "discount_rate",
                        "discount_amount",
                        "amount",
                        "vat_rate",
                        "tax_amount",
                        "line_total"
                      ]
                    }
                  },
                  "fees": {
                    "type": "array",
                    "description": "Danh sách phí, lệ phí. Xem mục Loại phí.",
                    "items": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string",
                          "description": "Tên loại phí. Tối đa 100 ký tự."
                        },
                        "amount": {
                          "type": "number",
                          "description": "Tiền phí. Tối đa 21 chữ số, 6 chữ số thập phân."
                        }
                      }
                    }
                  },
                  "seller_store_code": {
                    "type": "string",
                    "description": "Mã cửa hàng, điểm bán. Tối đa 50 ký tự."
                  },
                  "seller_store_name": {
                    "type": "string",
                    "description": "Tên cửa hàng, điểm bán. Tối đa 400 ký tự."
                  }
                },
                "required": [
                  "invoice_type",
                  "currency",
                  "exchange_rate",
                  "subtotal",
                  "trade_discount",
                  "other_deduction",
                  "tax_total",
                  "total",
                  "items"
                ]
              }
            }
          }
        }
      },
      "get": {
        "tags": [
          "Hoá đơn"
        ],
        "operationId": "get_invoices_list",
        "summary": "Danh sách hoá đơn",
        "description": "Lấy danh sách chi tiết hoá đơn theo bộ lọc. Tên trường là tiếng Anh, cùng key với API Tạo hoá đơn.\n\nAPI trả danh sách chi tiết hoá đơn đã tạo trong ứng dụng. Mỗi phần tử trong data dùng cùng tên trường với body của API Tạo hoá đơn, kèm invoice_code (UUID, cùng data.id lúc tạo), number, lookup_code và status.\n\nBắt buộc gửi template_id. Các bộ lọc còn lại tuỳ chọn. Khi gửi cả issued_from và issued_to, khoảng tìm kiếm tối đa 10 ngày, tính cả hai đầu mút. Endpoint không trừ hạn mức phát hành.\n\nThử trên host sandbox.api.hddt.dev với token, API key tiền tố hddt_test_ và App ID. Dữ liệu Live trên api.hddt.dev với token và API key Live.\n\nGửi GET với bộ lọc trên query string. Host phải cùng môi trường với token. Sandbox: https://sandbox.api.hddt.dev. Live: https://api.hddt.dev.\n\nKhông có hoá đơn khớp bộ lọc vẫn trả success true và data là mảng rỗng.\n\nMarkdown: /docs/invoices/list.md\n\n```bash\ncurl \"https://sandbox.api.hddt.dev/v1/invoices?template_id=1C26TAA&issued_from=2026-04-01&issued_to=2026-04-10&status=4\" \\\n  -H \"Authorization: Bearer $HDDT_TOKEN\" \\\n  -H \"api_key: $HDDT_API_KEY\" \\\n  -H \"app_id: $HDDT_APP_ID\"\n```",
        "responses": {
          "200": {
            "description": "Thành công.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "description": "true khi lấy được danh sách, false khi thất bại."
                    },
                    "data": {
                      "type": "array",
                      "description": "Danh sách hoá đơn. Mảng rỗng khi không có hoá đơn khớp bộ lọc.",
                      "items": {}
                    },
                    "error_code": {
                      "type": "string",
                      "description": "Trống khi thành công. Khi thất bại là mã lỗi nghiệp vụ."
                    },
                    "message": {
                      "type": "string",
                      "description": "Thông báo thành công hoặc thất bại."
                    },
                    "invoice_code": {
                      "type": "string",
                      "description": "UUID của hoá đơn. Gửi lại vào related_invoice_id khi thay thế hoặc điều chỉnh."
                    },
                    "number": {
                      "type": "integer",
                      "description": "Số hoá đơn. Tối đa 8 chữ số."
                    },
                    "lookup_code": {
                      "type": "string",
                      "description": "Mã tra cứu. Tối đa 100 ký tự."
                    },
                    "status": {
                      "type": "integer",
                      "description": "Trạng thái hoá đơn.\n1: nháp.\n2: lỗi ký.\n3: chưa gửi cơ quan thuế.\n4: đã cấp mã hoặc đã tiếp nhận.\n5: cơ quan thuế chưa phản hồi.\n6: không đủ điều kiện cấp mã hoặc tiếp nhận."
                    },
                    "issue_mode": {
                      "type": "integer",
                      "description": "Cách tạo.\n0: lưu nháp.\n1: tạo và phát hành.\nTối đa 10 chữ số."
                    },
                    "invoice_type": {
                      "type": "integer",
                      "description": "Tính chất hoá đơn.\n0: hoá đơn mới.\n1: thay thế.\n2: điều chỉnh tăng.\n3: điều chỉnh giảm.\n4: điều chỉnh thông tin.\n5: điều chỉnh tăng và giảm.\nTối đa 5 chữ số."
                    },
                    "template_id": {
                      "type": "string",
                      "description": "Mã mẫu, ví dụ 1C26TAA."
                    },
                    "issued_at": {
                      "type": "string",
                      "format": "date-time",
                      "description": "Ngày lập hoá đơn."
                    },
                    "currency": {
                      "type": "string",
                      "description": "Mã tiền tệ ISO 4217.\nVND: Việt Nam đồng.\nUSD: đô la Mỹ.\nCAD: đô la Canada.\nHệ thống tự map sang mã của từng nhà cung cấp khi gọi nền tảng."
                    },
                    "exchange_rate": {
                      "type": "number",
                      "description": "Tỷ giá. Với VND là 1. Tối đa 7 chữ số, 2 chữ số thập phân."
                    },
                    "payment_method": {
                      "type": "string",
                      "description": "Hình thức thanh toán."
                    },
                    "reference": {
                      "type": "string",
                      "description": "Mã tham chiếu của hoá đơn trên hệ thống của bạn. Tối đa 20 ký tự."
                    },
                    "note": {
                      "type": "string",
                      "description": "Ghi chú. Tối đa 255 ký tự."
                    },
                    "related_invoice_id": {
                      "type": "string",
                      "description": "UUID của hoá đơn gốc, lấy từ id của hoá đơn đó, khi invoice_type là thay thế hoặc điều chỉnh."
                    },
                    "seller_store_code": {
                      "type": "string",
                      "description": "Mã cửa hàng, điểm bán. Xem mục Người bán. Tối đa 50 ký tự."
                    },
                    "seller_store_name": {
                      "type": "string",
                      "description": "Tên cửa hàng, điểm bán. Xem mục Người bán. Tối đa 400 ký tự."
                    },
                    "buyer": {
                      "type": "object",
                      "description": "Người mua. Xem mục Người mua."
                    },
                    "items": {
                      "type": "array",
                      "description": "Danh sách hàng hoá, dịch vụ. Xem mục Dòng hàng.",
                      "items": {}
                    },
                    "fees": {
                      "type": "array",
                      "description": "Danh sách phí, lệ phí. Xem mục Loại phí.",
                      "items": {}
                    },
                    "subtotal": {
                      "type": "number",
                      "description": "Tổng tiền trước thuế. Tối đa 21 chữ số, 6 chữ số thập phân."
                    },
                    "trade_discount": {
                      "type": "number",
                      "description": "Tổng tiền chiết khấu thương mại. Tối đa 21 chữ số, 6 chữ số thập phân."
                    },
                    "other_deduction": {
                      "type": "number",
                      "description": "Tổng giảm trừ khác. Tối đa 21 chữ số, 6 chữ số thập phân."
                    },
                    "tax_total": {
                      "type": "number",
                      "description": "Tổng tiền thuế. Tối đa 21 chữ số, 6 chữ số thập phân."
                    },
                    "total": {
                      "type": "number",
                      "description": "Tổng tiền thanh toán bằng số. Tối đa 21 chữ số, 6 chữ số thập phân."
                    },
                    "total_in_words": {
                      "type": "string",
                      "description": "Tổng tiền thanh toán bằng chữ. Tối đa 255 ký tự."
                    }
                  },
                  "required": [
                    "success",
                    "data",
                    "error_code",
                    "message",
                    "invoice_code",
                    "status",
                    "invoice_type",
                    "currency",
                    "exchange_rate",
                    "items",
                    "subtotal",
                    "trade_discount",
                    "other_deduction",
                    "tax_total",
                    "total"
                  ]
                },
                "example": {
                  "success": true,
                  "data": [
                    {
                      "invoice_code": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
                      "number": 125,
                      "lookup_code": "7B164DE808",
                      "status": 4,
                      "issue_mode": 1,
                      "invoice_type": 0,
                      "template_id": "1C26TAA",
                      "issued_at": "2026-04-11T06:46:41.850Z",
                      "currency": "VND",
                      "exchange_rate": 1,
                      "payment_method": "TM/CK",
                      "reference": "DH-1001",
                      "seller_store_code": "CH01",
                      "seller_store_name": "Cửa hàng Quận 1",
                      "buyer": {
                        "name": "Công ty TNHH ABC",
                        "tax_code": "0312345678",
                        "address": "123 Nguyễn Huệ, Quận 1, TP. Hồ Chí Minh",
                        "email": "ketoan@abc.vn"
                      },
                      "items": [
                        {
                          "item_type": 1,
                          "line_number": 1,
                          "name": "Gói phần mềm",
                          "unit": "Gói",
                          "quantity": 1,
                          "unit_price": 5000000,
                          "amount_before_discount": 5000000,
                          "discount_rate": 0,
                          "discount_amount": 0,
                          "amount": 5000000,
                          "vat_rate": 10,
                          "tax_amount": 500000,
                          "line_total": 5500000
                        }
                      ],
                      "subtotal": 5000000,
                      "trade_discount": 0,
                      "other_deduction": 0,
                      "tax_total": 500000,
                      "total": 5500000,
                      "total_in_words": "Năm triệu năm trăm nghìn đồng"
                    }
                  ],
                  "error_code": "",
                  "message": "Thành công"
                }
              }
            }
          },
          "400": {
            "description": "bad_request — Request sai định dạng.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "unauthorized — Thiếu token hoặc header api_key, token hết hạn, API key đã thu hồi, hoặc key không cùng ứng dụng và môi trường với token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "validation_error — Thiếu template_id, template_id không đúng ký hiệu mẫu số và ký hiệu hoá đơn, ngày không đúng yyyy-MM-dd, hoặc invoice_kind, status ngoài danh mục.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "rate_limited — Vượt giới hạn số request cho phép.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "invoiceToken": [],
            "appApiKey": [],
            "appId": []
          }
        ],
        "parameters": [
          {
            "name": "template_id",
            "in": "query",
            "required": true,
            "description": "Mã mẫu từ API Lấy mẫu hoá đơn, ví dụ 1C26TAA. Gồm ký hiệu mẫu số và ký hiệu hoá đơn.",
            "schema": {
              "type": "string",
              "description": "Mã mẫu từ API Lấy mẫu hoá đơn, ví dụ 1C26TAA. Gồm ký hiệu mẫu số và ký hiệu hoá đơn."
            }
          },
          {
            "name": "issued_from",
            "in": "query",
            "required": false,
            "description": "Ngày lập bắt đầu, lọc theo issued_at. Gồm cả ngày này. Định dạng yyyy-MM-dd. Cùng issued_to thì khoảng tối đa 10 ngày.",
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Ngày lập bắt đầu, lọc theo issued_at. Gồm cả ngày này. Định dạng yyyy-MM-dd. Cùng issued_to thì khoảng tối đa 10 ngày."
            }
          },
          {
            "name": "issued_to",
            "in": "query",
            "required": false,
            "description": "Ngày lập kết thúc, lọc theo issued_at. Gồm cả ngày này. Định dạng yyyy-MM-dd. Cùng issued_from thì khoảng tối đa 10 ngày.",
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Ngày lập kết thúc, lọc theo issued_at. Gồm cả ngày này. Định dạng yyyy-MM-dd. Cùng issued_from thì khoảng tối đa 10 ngày."
            }
          },
          {
            "name": "number",
            "in": "query",
            "required": false,
            "description": "Số hoá đơn. Tối đa 8 chữ số.",
            "schema": {
              "type": "integer",
              "description": "Số hoá đơn. Tối đa 8 chữ số."
            }
          },
          {
            "name": "invoice_code",
            "in": "query",
            "required": false,
            "description": "UUID của hoá đơn, cùng data.id trả về khi tạo.",
            "schema": {
              "type": "string",
              "description": "UUID của hoá đơn, cùng data.id trả về khi tạo."
            }
          },
          {
            "name": "invoice_kind",
            "in": "query",
            "required": false,
            "description": "Loại hoá đơn cần lấy.\n-1: tất cả, gồm hoá đơn nháp.\n0: tất cả, không gồm hoá đơn nháp.\n1: nháp.\n2: hoá đơn mới.\n3: hoá đơn xoá bỏ.\n4: hoá đơn thay thế.\n5: hoá đơn bị thay thế.\n6: hoá đơn điều chỉnh tăng.\n7: hoá đơn điều chỉnh giảm.\n8: hoá đơn điều chỉnh thông tin.\n9: hoá đơn điều chỉnh tăng và giảm.\n10: hoá đơn bị điều chỉnh.\nTối đa 2 chữ số.",
            "schema": {
              "type": "integer",
              "description": "Loại hoá đơn cần lấy.\n-1: tất cả, gồm hoá đơn nháp.\n0: tất cả, không gồm hoá đơn nháp.\n1: nháp.\n2: hoá đơn mới.\n3: hoá đơn xoá bỏ.\n4: hoá đơn thay thế.\n5: hoá đơn bị thay thế.\n6: hoá đơn điều chỉnh tăng.\n7: hoá đơn điều chỉnh giảm.\n8: hoá đơn điều chỉnh thông tin.\n9: hoá đơn điều chỉnh tăng và giảm.\n10: hoá đơn bị điều chỉnh.\nTối đa 2 chữ số."
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Trạng thái hoá đơn.\n-1: tất cả, gồm hoá đơn nháp.\n0: tất cả, không gồm hoá đơn nháp.\n1: nháp.\n2: lỗi ký.\n3: chưa gửi cơ quan thuế.\n4: đã cấp mã hoặc đã tiếp nhận.\n5: cơ quan thuế chưa phản hồi.\n6: không đủ điều kiện cấp mã hoặc tiếp nhận.\nTối đa 2 chữ số.",
            "schema": {
              "type": "integer",
              "description": "Trạng thái hoá đơn.\n-1: tất cả, gồm hoá đơn nháp.\n0: tất cả, không gồm hoá đơn nháp.\n1: nháp.\n2: lỗi ký.\n3: chưa gửi cơ quan thuế.\n4: đã cấp mã hoặc đã tiếp nhận.\n5: cơ quan thuế chưa phản hồi.\n6: không đủ điều kiện cấp mã hoặc tiếp nhận.\nTối đa 2 chữ số."
            }
          },
          {
            "name": "customer",
            "in": "query",
            "required": false,
            "description": "Tìm theo thông tin khách hàng. Khớp một trong buyer.name, buyer.tax_code, buyer.contact_name, reference. Tối đa 200 ký tự.",
            "schema": {
              "type": "string",
              "description": "Tìm theo thông tin khách hàng. Khớp một trong buyer.name, buyer.tax_code, buyer.contact_name, reference. Tối đa 200 ký tự."
            }
          }
        ]
      }
    },
    "/v1/invoices/sign": {
      "post": {
        "tags": [
          "Hoá đơn"
        ],
        "operationId": "signDraftInvoice",
        "summary": "Ký hoá đơn nháp",
        "description": "Ký một hoá đơn đã lưu nháp. Gửi invoice_code là UUID lấy từ data.id của API Tạo hoá đơn.\n\nAPI ký một hoá đơn đang ở trạng thái nháp. Tạo nháp bằng API Tạo hoá đơn với issue_mode bằng 0, rồi gửi UUID trong data.id vào invoice_code của API này.\n\nHoá đơn đã phát hành không ký lại bằng API này. Trên sandbox, hoá đơn không được gửi tới cơ quan thuế.\n\nGửi POST với JSON. Sandbox: https://sandbox.api.hddt.dev. Live: https://api.hddt.dev.\n\nMarkdown: /docs/invoices/sign.md\n\n```bash\ncurl -X POST https://sandbox.api.hddt.dev/v1/invoices/sign \\\n  -H \"Authorization: Bearer $HDDT_TOKEN\" \\\n  -H \"api_key: $HDDT_API_KEY\" \\\n  -H \"app_id: $HDDT_APP_ID\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"invoice_code\": \"7c9e6679-7425-40de-944b-e07fc1f90ae7\"\n  }'\n```",
        "responses": {
          "200": {
            "description": "Thành công.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "description": "true khi ký được hoá đơn, false khi thất bại."
                    },
                    "data": {
                      "type": "object",
                      "description": "Dữ liệu trả về khi ký thành công. Khi thất bại có thể trống."
                    },
                    "error_code": {
                      "type": "string",
                      "description": "Trống khi thành công. Khi thất bại là mã lỗi nghiệp vụ."
                    },
                    "message": {
                      "type": "string",
                      "description": "Thông báo thành công hoặc thất bại."
                    }
                  },
                  "required": [
                    "success",
                    "data",
                    "error_code",
                    "message"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "unauthorized — Thiếu token hoặc header api_key, token sai hoặc hết hạn, API key đã thu hồi, hoặc key không cùng ứng dụng và môi trường với token. Gọi lại API Lấy token nếu token hết hạn.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "validation_error — Thiếu invoice_code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "invoiceToken": [],
            "appApiKey": [],
            "appId": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "invoice_code": {
                    "type": "string",
                    "description": "UUID của hoá đơn nháp, lấy từ data.id của API Tạo hoá đơn."
                  }
                },
                "required": [
                  "invoice_code"
                ]
              }
            }
          }
        }
      }
    },
    "/v1/invoices/{id}": {
      "delete": {
        "tags": [
          "Hoá đơn"
        ],
        "operationId": "deleteDraftInvoice",
        "summary": "Xoá hoá đơn nháp",
        "description": "Xoá một hoá đơn đang lưu nháp. Hoá đơn đã phát hành không xoá bằng API này.\n\nAPI xoá một hoá đơn đang lưu nháp. Tạo nháp bằng API Tạo hoá đơn với issue_mode bằng 0, rồi gửi UUID trong data.id lên đường dẫn của API này.\n\nHoá đơn đã phát hành không xoá được. Muốn bỏ một hoá đơn đã phát hành thì dùng quy trình thông báo sai sót, không dùng API này. Thao tác không hoàn tác được.\n\nGửi DELETE với UUID của hoá đơn nháp trên đường dẫn. Sandbox: https://sandbox.api.hddt.dev. Live: https://api.hddt.dev.\n\nMarkdown: /docs/invoices/cancel.md\n\n```bash\ncurl -X DELETE https://sandbox.api.hddt.dev/v1/invoices/7c9e6679-7425-40de-944b-e07fc1f90ae7 \\\n  -H \"Authorization: Bearer $HDDT_TOKEN\" \\\n  -H \"api_key: $HDDT_API_KEY\" \\\n  -H \"app_id: $HDDT_APP_ID\"\n```",
        "responses": {
          "200": {
            "description": "Thành công.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "description": "true khi xoá được hoá đơn nháp, false khi thất bại."
                    },
                    "data": {
                      "type": "object",
                      "description": "Kết quả xoá. Khi thành công có id và deleted."
                    },
                    "error_code": {
                      "type": "string",
                      "description": "Trống khi thành công. Khi thất bại là mã lỗi nghiệp vụ."
                    },
                    "message": {
                      "type": "string",
                      "description": "Thông báo thành công hoặc thất bại."
                    },
                    "id": {
                      "type": "string",
                      "description": "UUID của hoá đơn nháp vừa xoá, nằm trong data."
                    },
                    "deleted": {
                      "type": "boolean",
                      "description": "Luôn là true khi xoá thành công, nằm trong data.",
                      "enum": [
                        "true"
                      ]
                    }
                  },
                  "required": [
                    "success",
                    "data",
                    "error_code",
                    "message",
                    "id",
                    "deleted"
                  ]
                },
                "example": {
                  "success": true,
                  "data": {
                    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
                    "deleted": true
                  },
                  "error_code": "",
                  "message": "Thành công"
                }
              }
            }
          },
          "401": {
            "description": "unauthorized — Thiếu token hoặc header api_key, token sai hoặc hết hạn, API key đã thu hồi, hoặc key không cùng ứng dụng và môi trường với token. Gọi lại API Lấy token nếu token hết hạn.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "not_found — Không có hoá đơn nháp với id này trong ứng dụng, hoặc hoá đơn đã được xoá.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "validation_error — id không phải UUID, hoặc hoá đơn không còn là nháp (đã ký hoặc đã phát hành).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "invoiceToken": [],
            "appApiKey": [],
            "appId": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "UUID của hoá đơn nháp, lấy từ data.id của API Tạo hoá đơn.",
            "schema": {
              "type": "string",
              "description": "UUID của hoá đơn nháp, lấy từ data.id của API Tạo hoá đơn."
            }
          }
        ]
      }
    },
    "/v1/tax-codes/{mst}": {
      "get": {
        "tags": [
          "Tra cứu"
        ],
        "operationId": "getTaxCode",
        "summary": "Tra cứu mã số thuế",
        "description": "Lấy tên đơn vị, địa chỉ và trạng thái hoạt động từ mã số thuế (MST) để tự điền thông tin người mua khi lập hoá đơn.\n\nGọi API này khi người dùng nhập mã số thuế trên form bán hàng. Kết quả có tên, địa chỉ và trạng thái để điền người mua trước khi tạo hoá đơn.\n\nTrên sandbox, 0312345678 và 0109876543 luôn trả dữ liệu mẫu để thử.\n\nGửi GET với MST trên đường dẫn. MST 10 số chỉ khớp đúng đơn vị đó, không kèm chi nhánh. Muốn tra chi nhánh thì gửi đủ 13 số.\n\nMọi request cần API key trong header api_key và App ID trong header app_id. API key phải thuộc đúng ứng dụng đó. Không dùng Authorization. Endpoint không trừ hạn mức phát hành hoá đơn, nhưng vẫn tính vào giới hạn số request.\n\nMarkdown: /docs/tax-codes.md\n\n```bash\ncurl https://sandbox.api.hddt.dev/v1/tax-codes/0312345678 \\\n  -H \"api_key: $HDDT_API_KEY\" \\\n  -H \"app_id: $HDDT_APP_ID\"\n```",
        "responses": {
          "200": {
            "description": "Thành công.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "type": "string",
                      "description": "Luôn là tax_code.",
                      "enum": [
                        "tax_code"
                      ]
                    },
                    "id": {
                      "type": "string",
                      "description": "Trùng tax_code."
                    },
                    "tax_code": {
                      "type": "string",
                      "description": "MST đã chuẩn hoá. 10 số, hoặc chi nhánh dạng 0312345678-001."
                    },
                    "name": {
                      "type": "string",
                      "description": "Tên đơn vị trên hồ sơ thuế."
                    },
                    "name_international": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Tên giao dịch quốc tế. null khi không có."
                    },
                    "address": {
                      "type": "string",
                      "description": "Địa chỉ trên hồ sơ thuế."
                    },
                    "status": {
                      "type": "string",
                      "description": "Mã trạng thái. Xem mục Trạng thái. Chỉ active là đang hoạt động."
                    },
                    "status_label": {
                      "type": "string",
                      "description": "Câu tiếng Việt cùng nghĩa với status, dùng để hiện trên form."
                    },
                    "tax_office": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Cơ quan thuế quản lý. null khi không có."
                    },
                    "representative": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Người đại diện. null khi không có."
                    },
                    "updated_at": {
                      "type": "string",
                      "description": "Thời điểm cập nhật thông tin, ISO 8601, múi giờ +07:00."
                    }
                  },
                  "required": [
                    "object",
                    "id",
                    "tax_code",
                    "name",
                    "name_international",
                    "address",
                    "status",
                    "status_label",
                    "tax_office",
                    "representative",
                    "updated_at"
                  ]
                },
                "example": {
                  "object": "tax_code",
                  "id": "0312345678",
                  "tax_code": "0312345678",
                  "name": "Công ty TNHH ABC",
                  "name_international": null,
                  "address": "123 Nguyễn Huệ, Phường Bến Nghé, Quận 1, TP. Hồ Chí Minh",
                  "status": "active",
                  "status_label": "Đang hoạt động",
                  "tax_office": "Cục Thuế TP. Hồ Chí Minh",
                  "representative": "Nguyễn Văn A",
                  "updated_at": "2026-10-20T08:00:00+07:00"
                }
              }
            }
          },
          "401": {
            "description": "unauthorized — Thiếu header api_key hoặc app_id, API key sai hoặc đã thu hồi, hoặc API key không thuộc App ID.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "not_found — Không có đơn vị nào khớp MST đã nhập.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "validation_error — MST sai định dạng (độ dài, ký tự không hợp lệ).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "rate_limited — Vượt giới hạn số request tra cứu trong khoảng thời gian cho phép.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "provider_unavailable — Không tra cứu được mã số thuế lúc này. Thử lại sau.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "appApiKey": [],
            "appId": []
          }
        ],
        "parameters": [
          {
            "name": "mst",
            "in": "path",
            "required": true,
            "description": "Mã số thuế cần tra cứu. Chấp nhận 10 chữ số hoặc 13 chữ số (MST chi nhánh, dạng XXXXXXXXXX-XXX hoặc 13 số liền không dấu gạch). Chỉ gồm chữ số và dấu gạch ngang nếu có.",
            "schema": {
              "type": "string",
              "description": "Mã số thuế cần tra cứu. Chấp nhận 10 chữ số hoặc 13 chữ số (MST chi nhánh, dạng XXXXXXXXXX-XXX hoặc 13 số liền không dấu gạch). Chỉ gồm chữ số và dấu gạch ngang nếu có."
            }
          }
        ]
      }
    },
    "/v1/webhooks": {
      "get": {
        "tags": [
          "Webhook"
        ],
        "operationId": "listWebhooks",
        "summary": "Danh sách webhook",
        "description": "Lấy các webhook của ứng dụng xác định bởi app_id: URL, trạng thái bật và sự kiện đã đăng ký.\n\nAPI trả các webhook đã thêm cho ứng dụng. Header app_id là UUID dùng để tìm ứng dụng. Header api_key phải là key đang hiệu lực của đúng ứng dụng đó. Key có thể được tạo lại, nên không dùng key để định danh ứng dụng. Key hddt_test_ chỉ gọi Sandbox, key Live chỉ gọi Live. Sandbox và Live là hai danh sách riêng.\n\nDanh sách không trả secret dùng để ký thông báo. Secret chỉ có trong phản hồi của API Thêm webhook. Endpoint không dùng token hoá đơn và không trừ hạn mức phát hành.\n\nGửi GET. Host phải cùng môi trường với API key. Sandbox: https://sandbox.api.hddt.dev. Live: https://api.hddt.dev.\n\nChưa có webhook vẫn trả 200 và data là mảng rỗng.\n\nMarkdown: /docs/webhooks.md\n\n```bash\ncurl https://sandbox.api.hddt.dev/v1/webhooks \\\n  -H \"app_id: $HDDT_APP_ID\" \\\n  -H \"api_key: $HDDT_API_KEY\"\n```",
        "responses": {
          "200": {
            "description": "Thành công.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "type": "string",
                      "description": "Luôn là list.",
                      "enum": [
                        "list"
                      ]
                    },
                    "data": {
                      "type": "array",
                      "description": "Danh sách webhook. Mảng rỗng khi chưa thêm webhook nào. Xem mục Webhook.",
                      "items": {}
                    }
                  },
                  "required": [
                    "object",
                    "data"
                  ]
                },
                "example": {
                  "object": "list",
                  "data": [
                    {
                      "id": "wh_8f2a1c9d",
                      "object": "webhook",
                      "url": "https://api.cua-ban.vn/webhooks/hddt",
                      "enabled": true,
                      "events": [
                        "invoice_issued",
                        "tax_authority_response"
                      ]
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "unauthorized — Thiếu header app_id hoặc api_key; API key sai, đã thu hồi, hoặc không thuộc app_id.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "forbidden — Gửi key của môi trường khác (key hddt_live_ tới host Sandbox, key hddt_test_ tới host Live).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "not_found — Không có ứng dụng nào khớp app_id.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "validation_error — app_id không phải UUID.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "appApiKey": [],
            "appId": []
          }
        ]
      },
      "post": {
        "tags": [
          "Webhook"
        ],
        "operationId": "createWebhook",
        "summary": "Thêm webhook",
        "description": "Đăng ký URL nhận thông báo theo sự kiện mẫu hoá đơn và hoá đơn. Secret chỉ trả một lần trong phản hồi này.\n\nAPI thêm một webhook cho ứng dụng tìm theo header app_id. API key phải thuộc ứng dụng đó. Key hddt_test_ thêm vào sandbox. Key Live thêm vào production.\n\nPhản hồi có secret dạng whsec_. Lưu lại ngay. Các lần gọi API Danh sách webhook sau không trả secret này. Dùng secret để kiểm tra chữ ký trên header X-HDDT-Signature.\n\nGửi POST với JSON. Sandbox: https://sandbox.api.hddt.dev. Live: https://api.hddt.dev.\n\nMarkdown: /docs/webhooks/create.md\n\n```bash\ncurl -X POST https://sandbox.api.hddt.dev/v1/webhooks \\\n  -H \"app_id: $HDDT_APP_ID\" \\\n  -H \"api_key: $HDDT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"url\": \"https://api.cua-ban.vn/webhooks/hddt\",\n    \"events\": [\"invoice_issued\", \"tax_authority_response\"]\n  }'\n```",
        "responses": {
          "201": {
            "description": "Thành công.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "Định danh webhook, ví dụ wh_8f2a1c9d."
                    },
                    "object": {
                      "type": "string",
                      "description": "Luôn là webhook.",
                      "enum": [
                        "webhook"
                      ]
                    },
                    "url": {
                      "type": "string",
                      "description": "URL HTTPS nhận thông báo."
                    },
                    "enabled": {
                      "type": "boolean",
                      "description": "true khi webhook đang nhận thông báo, false khi đang tắt."
                    },
                    "events": {
                      "type": "string",
                      "description": "Các mã trong bảng Sự kiện đang đăng ký."
                    },
                    "secret": {
                      "type": "string",
                      "description": "Bí mật ký thông báo, tiền tố whsec_. Chỉ trả khi vừa thêm webhook."
                    }
                  },
                  "required": [
                    "id",
                    "object",
                    "url",
                    "enabled",
                    "events",
                    "secret"
                  ]
                },
                "example": {
                  "id": "wh_8f2a1c9d",
                  "object": "webhook",
                  "url": "https://api.cua-ban.vn/webhooks/hddt",
                  "enabled": true,
                  "events": [
                    "invoice_issued",
                    "tax_authority_response"
                  ],
                  "secret": "whsec_4f8c2a91b7e64d0c"
                }
              }
            }
          },
          "401": {
            "description": "unauthorized — Thiếu header app_id hoặc api_key; API key sai, đã thu hồi, hoặc không thuộc app_id.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "forbidden — Gửi key của môi trường khác (key hddt_live_ tới host Sandbox, key hddt_test_ tới host Live).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "not_found — Không có ứng dụng nào khớp app_id.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "validation_error — app_id không phải UUID, thiếu url hoặc events, url không phải HTTPS, events rỗng, hoặc có giá trị ngoài all, template_created, template_quantity_approved, template_deleted, invoice_draft_created, invoice_issued, invoice_signed, tax_authority_response, invoice_draft_deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "appApiKey": [],
            "appId": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "description": "URL HTTPS nhận POST khi có sự kiện. Ví dụ https://api.cua-ban.vn/webhooks/hddt."
                  },
                  "events": {
                    "type": "string",
                    "description": "Sự kiện cần nhận. Gửi ít nhất một mã trong bảng Sự kiện đang đăng ký."
                  },
                  "enabled": {
                    "type": "boolean",
                    "description": "Bật nhận thông báo ngay khi tạo.\ntrue: bật.\nfalse: tạo nhưng chưa gửi.\nBỏ trống thì hệ thống dùng true."
                  }
                },
                "required": [
                  "url",
                  "events"
                ]
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key Bearer cho hoá đơn đầu vào. Tra cứu MST không dùng header này."
      },
      "invoiceToken": {
        "type": "http",
        "scheme": "bearer",
        "description": "Token ngắn hạn từ POST /v1/invoices/token. Header: Authorization: Bearer <token>. Dùng cho API hoá đơn cùng với header api_key."
      },
      "appApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "api_key",
        "description": "API key của ứng dụng. Dùng cho API ứng dụng, Lấy token, và các API hoá đơn (cùng token). Key phải đang hiệu lực; với API hoá đơn phải cùng ứng dụng và môi trường với token."
      },
      "appId": {
        "type": "apiKey",
        "in": "header",
        "name": "app_id",
        "description": "Định danh ứng dụng (UUID). Bắt buộc trên webhook và các API hoá đơn. Webhook dùng app_id để tìm ứng dụng. Sao chép App ID trên trang chi tiết ứng dụng (tab Kết nối & bảo mật)."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "description": "Thân lỗi có error.code và error.message, như trang Tạo hoá đơn mô tả.",
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}
