Skip to content

Thêm API document Partner cho TaxCDS #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Hienluong0201 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Thêm API document Partner cho TaxCDS #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 12 additions & 2 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@
a { color: #0b63ce; text-decoration: none; }
a:hover { text-decoration: underline; }
ul { margin: 0; padding-left: 18px; }
li { margin-bottom: 12px; }
.note { font-size: 14px; color: #4b5563; }
</style>
</head>
Expand All @@ -31,6 +32,12 @@ <h2>Danh sách module API</h2>
<a href="./modules/Order/index.html">Mở module Order (HTML)</a><br/>
<a href="./modules/Order/index.md">Mở module Order (MD)</a>
</li>

<li>
<strong>TaxCDS</strong><br/>
<a href="./modules/TaxCDS/index.html">Mở module TaxCDS (HTML)</a><br/>
<a href="./modules/TaxCDS/index.md">Mở module TaxCDS (MD)</a>
</li>
</ul>
</div>

Expand Down Expand Up @@ -64,10 +71,13 @@ <h2>Callback / Webhooks</h2>
<h2>Data test tham chiếu</h2>
<ul>
<li>clientId: TESTCLIENT</li>
<li>apiKey: 07e73e61-0dce-4b39-8ecf-06ef70b35c08</li>
<li>apiKey Order: 07e73e61-0dce-4b39-8ecf-06ef70b35c08</li>
<li>apikey TaxCDS: 911abff6-137a-4aa3-a836-555a1d30359b</li>
<li>taxCode TaxCDS mẫu: 8173748371</li>
<li>citizenIdentityNumber TaxCDS mẫu: 079183000002</li>
</ul>
<p class="note">Lưu ý: chỉ dùng để test/integration, cần thay bằng dữ liệu môi trường thật trước production.</p>
</div>
</div>
</body>
</html>
</html>
13 changes: 12 additions & 1 deletion index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,10 @@ Tài liệu này là trang chủ cho toàn bộ API dành cho đối tác.
- Module index HTML: ./modules/Order/index.html
- Module index MD: ./modules/Order/index.md

2. TaxCDS
- Module index HTML: ./modules/TaxCDS/index.html
- Module index MD: ./modules/TaxCDS/index.md

## Callback / Webhooks

1. Lịch hẹn
Expand Down Expand Up @@ -38,4 +42,11 @@ Tài liệu này là trang chủ cho toàn bộ API dành cho đối tác.
- clientId: TESTCLIENT
- apiKey: 07e73e61-0dce-4b39-8ecf-06ef70b35c08

Developer cần thay lại credential và dữ liệu order theo môi trường thật trước khi UAT/production.
## Data test đang dùng cho TaxCDS

- apikey: 911abff6-137a-4aa3-a836-555a1d30359b
- taxCode: 8173748371
- citizenIdentityNumber: 079183000002
- taxpayerName: Nguyễn Văn A

Developer cần thay lại credential và dữ liệu theo môi trường thật trước khi UAT/production.
171 changes: 171 additions & 0 deletions modules/TaxCDS/TaxCDSDeclarationStatusLookup_LookupDeclarationStatus.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,171 @@
<!doctype html>
<html lang="vi">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Tra cứu tình trạng nộp tờ khai</title>
<style>
body { font-family: Arial, sans-serif; margin: 0; background: #f5f7fb; color: #1f2937; }
.wrap { max-width: 1100px; margin: 24px auto; padding: 0 16px; }
.card { background: #fff; border: 1px solid #dbe3ef; border-radius: 12px; padding: 18px; margin-bottom: 14px; }
h1, h2 { margin-top: 0; }
table { width: 100%; border-collapse: collapse; }
th, td { border: 1px solid #dbe3ef; padding: 8px; text-align: left; vertical-align: top; }
th { background: #eef3fb; }
pre { background: #0f172a; color: #e5ecf6; padding: 12px; border-radius: 10px; overflow-x: auto; }
a { color: #0b63ce; text-decoration: none; }
a:hover { text-decoration: underline; }
code { background: #eef3fb; padding: 2px 5px; border-radius: 4px; }
button { background: #0b63ce; color: white; border: none; border-radius: 8px; padding: 8px 12px; cursor: pointer; margin-right: 8px; }
#toast { position: fixed; bottom: 32px; left: 50%; transform: translateX(-50%); background: #1f2937; color: #fff; padding: 10px 22px; border-radius: 8px; font-size: 0.95em; opacity: 0; pointer-events: none; transition: opacity 0.25s; z-index: 9999; }
#toast.show { opacity: 1; }
</style>
</head>
<body>
<div class="wrap">
<div class="card">
<h1>Partner API - Tra cứu tình trạng nộp tờ khai</h1>
<p>Tra cứu tình trạng nộp tờ khai theo mã số thuế, CCCD/CMND hoặc tên người nộp thuế.</p>
<p><a href="./index.html">Về module TaxCDS</a></p>
</div>

<div class="card">
<h2>Endpoint</h2>
<table>
<tr><th>URL</th><td>/TaxCDSDeclarationStatusLookup/partner/lookupDeclarationStatus</td></tr>
<tr><th>Method</th><td>POST</td></tr>
</table>
</div>

<div class="card">
<h2>Headers schema</h2>
<table>
<tr><th>Header</th><th>Required</th><th>Mô tả</th></tr>
<tr><td>apikey</td><td>Yes</td><td>Khóa xác thực API của đối tác</td></tr>
</table>
</div>

<div class="card">
<h2>Body schema</h2>
<table>
<tr><th>Field</th><th>Type</th><th>Required</th><th>Rule</th><th>Mô tả</th></tr>
<tr><td>filter</td><td>object</td><td>Yes</td><td>Bắt buộc</td><td>Nhóm điều kiện tra cứu.</td></tr>
<tr><td>filter.taxCode</td><td>string</td><td>No</td><td>Có thể rỗng</td><td>Mã số thuế cần tra cứu.</td></tr>
<tr><td>filter.citizenIdentityNumber</td><td>string</td><td>No</td><td>Có thể rỗng</td><td>Số CCCD/CMND cần tra cứu.</td></tr>
<tr><td>filter.taxpayerName</td><td>string</td><td>No</td><td>Có thể rỗng, hỗ trợ tìm gần đúng</td><td>Tên người nộp thuế cần tra cứu.</td></tr>
<tr><td>filter.declarationStatus</td><td>string</td><td>No</td><td>Có thể rỗng</td><td>Trạng thái nộp tờ khai.</td></tr>
<tr><td>filter.declarationPeriod</td><td>string</td><td>No</td><td>Có thể rỗng</td><td>Kỳ kê khai.</td></tr>
<tr><td>filter.declarationType</td><td>string</td><td>No</td><td>Có thể rỗng</td><td>Loại tờ khai.</td></tr>
<tr><td>skip</td><td>number</td><td>No</td><td>Mặc định 0, nhỏ nhất 0</td><td>Số bản ghi bỏ qua.</td></tr>
<tr><td>limit</td><td>number</td><td>No</td><td>Mặc định 20, lớn nhất 100</td><td>Số bản ghi tối đa trả về.</td></tr>
<tr><td>startDate</td><td>string</td><td>No</td><td>Chuỗi ngày tháng</td><td>Lọc bản ghi tạo từ ngày.</td></tr>
<tr><td>endDate</td><td>string</td><td>No</td><td>Chuỗi ngày tháng</td><td>Lọc bản ghi tạo đến ngày.</td></tr>
<tr><td>order.key</td><td>string</td><td>No</td><td>Mặc định createdAt</td><td>Tên trường dùng để sắp xếp.</td></tr>
<tr><td>order.value</td><td>string</td><td>No</td><td>asc hoặc desc, mặc định desc</td><td>Chiều sắp xếp.</td></tr>
</table>
<p>Cần truyền ít nhất một điều kiện tra cứu trong <code>filter</code>: <code>taxCode</code>, <code>citizenIdentityNumber</code> hoặc <code>taxpayerName</code>.</p>
</div>

<div class="card">
<h2 style="display:flex;align-items:center;gap:8px;">
Sample Request
<button id="copySampleBtn" title="Copy sang clipboard" style="background:none;border:1px solid #dbe3ef;border-radius:6px;padding:4px 8px;cursor:pointer;display:inline-flex;align-items:center;">
<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="#0b63ce" viewBox="0 0 16 16">
<path d="M4 1.5H3a2 2 0 0 0-2 2V14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V3.5a2 2 0 0 0-2-2h-1v1h1a1 1 0 0 1 1 1V14a1 1 0 0 1-1 1H3a1 1 0 0 1-1-1V3.5a1 1 0 0 1 1-1h1v-1z"/>
<path d="M9.5 1a.5.5 0 0 1 .5.5v1a.5.5 0 0 1-.5.5h-3a.5.5 0 0 1-.5-.5v-1a.5.5 0 0 1 .5-.5h3zm-3-1A1.5 1.5 0 0 0 5 1.5v1A1.5 1.5 0 0 0 6.5 4h3A1.5 1.5 0 0 0 11 2.5v-1A1.5 1.5 0 0 0 9.5 0h-3z"/>
</svg>
</button>
</h2>
<pre id="curlText">curl --location 'http://localhost:4001/TaxCDSDeclarationStatusLookup/partner/lookupDeclarationStatus' \
--header 'Content-Type: application/json' \
--header 'apikey: 911abff6-137a-4aa3-a836-555a1d30359b' \
--data '{
"filter": {
"taxCode": "8173748371"
},
"skip": 0,
"limit": 10
}'</pre>
</div>

<div class="card">
<h2>Success response</h2>
<pre>{
"statusCode": 200,
"error": null,
"message": "Success",
"data": {
"data": [
{
"taxCDSDeclStatusLookupId": 1,
"taxCode": "8173748371",
"citizenIdentityNumber": "079183000002",
"taxpayerName": "Nguyễn Văn A",
"taxDepartment": "Chi cục Thuế khu vực",
"declarationStatus": "OVERDUE",
"statusTitle": "Quá hạn nộp tờ khai",
"statusDescription": "Đã quá hạn nộp tờ khai.",
"submitDate": "15/01/2026",
"declarationPeriod": "01/2026",
"declarationType": "Tờ khai thuế",
"declarationCode": "TK-001",
"receivedDate": "",
"processedDate": "",
"rejectedReason": "",
"additionalRequest": "",
"note": "",
"updatedAt": "2026-05-27T04:11:56.000Z",
"createdAt": "2026-05-27T04:11:56.000Z",
"isHidden": 0,
"isDeleted": 0
}
],
"totalNextPage": 0
}
}</pre>
</div>

<div class="card">
<h2>Mã lỗi</h2>
<table>
<tr><th style="width:100px">HTTP</th><th style="width:35%">Mã lỗi</th><th>Mô tả</th></tr>
<tr><td>400</td><td><em>Validation Error</em></td><td>Payload không đúng schema, thiếu field bắt buộc, sai kiểu hoặc vượt giới hạn.</td></tr>
<tr><td>429</td><td><code>QUOTA_EXCEEDED</code></td><td>apikey không hợp lệ hoặc vượt quota.</td></tr>
<tr><td>500</td><td><code>MISSING_LOOKUP_FIELD</code></td><td>Thiếu điều kiện tra cứu: cần ít nhất một trong các trường MST, CCCD/CMND hoặc tên người nộp thuế.</td></tr>
<tr><td>500</td><td><code>UNKNOWN_ERROR</code></td><td>Lỗi không xác định.</td></tr>
</table>
</div>

<div class="card">
<h2>Tham khảo</h2>
<ul>
<li><a href="../../Common.html#common-error">Quy chuẩn chung → Common Error</a> — danh sách mã lỗi hệ thống trả về trong trường <code>error</code>.</li>
</ul>
</div>

<div class="card">
<h2>Data test cho developer</h2>
<ul>
<li>apikey: 911abff6-137a-4aa3-a836-555a1d30359b</li>
<li>taxCode: 8173748371</li>
<li>citizenIdentityNumber: 079183000002</li>
<li>taxpayerName: Nguyễn Văn A</li>
</ul>
<p>Cần thay bằng dữ liệu môi trường thật khi tích hợp.</p>
</div>
</div>

<script>
const copySampleBtn = document.getElementById('copySampleBtn');
const curlText = document.getElementById('curlText').textContent;

copySampleBtn.addEventListener('click', async () => {
await navigator.clipboard.writeText(curlText);
const toast = document.getElementById('toast');
toast.classList.add('show');
setTimeout(() => toast.classList.remove('show'), 2000);
});
</script>
<div id="toast">Sao chép thành công</div>
</body>
</html>
128 changes: 128 additions & 0 deletions modules/TaxCDS/TaxCDSDeclarationStatusLookup_LookupDeclarationStatus.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,128 @@
# Partner API - Tra cứu tình trạng nộp tờ khai

Tra cứu tình trạng nộp tờ khai theo mã số thuế, CCCD/CMND hoặc tên người nộp thuế.

[Về module TaxCDS](./index.html)

---

## Endpoint

| | |
|---|---|
| URL | `/TaxCDSDeclarationStatusLookup/partner/lookupDeclarationStatus` |
| Method | `POST` |

---

## Headers schema

| Header | Required | Mô tả |
|---|---|---|
| apikey | Yes | Khóa xác thực API của đối tác |
---

## Body schema

| Field | Type | Required | Rule | Mô tả |
|---|---|---|---|---|
| filter | object | Yes | Bắt buộc | Nhóm điều kiện tra cứu. |
| filter.taxCode | string | No | Có thể rỗng | Mã số thuế cần tra cứu. |
| filter.citizenIdentityNumber | string | No | Có thể rỗng | Số CCCD/CMND cần tra cứu. |
| filter.taxpayerName | string | No | Có thể rỗng, hỗ trợ tìm gần đúng | Tên người nộp thuế cần tra cứu. |
| filter.declarationStatus | string | No | Có thể rỗng | Trạng thái nộp tờ khai. |
| filter.declarationPeriod | string | No | Có thể rỗng | Kỳ kê khai. |
| filter.declarationType | string | No | Có thể rỗng | Loại tờ khai. |
| skip | number | No | Mặc định 0, nhỏ nhất 0 | Số bản ghi bỏ qua. |
| limit | number | No | Mặc định 20, lớn nhất 100 | Số bản ghi tối đa trả về. |
| startDate | string | No | Chuỗi ngày tháng | Lọc bản ghi tạo từ ngày. |
| endDate | string | No | Chuỗi ngày tháng | Lọc bản ghi tạo đến ngày. |
| order.key | string | No | Mặc định createdAt | Tên trường dùng để sắp xếp. |
| order.value | string | No | asc hoặc desc, mặc định desc | Chiều sắp xếp. |

Cần truyền ít nhất một điều kiện tra cứu trong `filter`: `taxCode`, `citizenIdentityNumber` hoặc `taxpayerName`.

---

## Sample Request

```bash
curl --location 'http://localhost:4001/TaxCDSDeclarationStatusLookup/partner/lookupDeclarationStatus' \
--header 'Content-Type: application/json' \
--header 'apikey: 911abff6-137a-4aa3-a836-555a1d30359b' \
--data '{
"filter": {
"taxCode": "8173748371"
},
"skip": 0,
"limit": 10
}'
```

---

## Success response

```json
{
"statusCode": 200,
"error": null,
"message": "Success",
"data": {
"data": [
{
"taxCDSDeclStatusLookupId": 1,
"taxCode": "8173748371",
"citizenIdentityNumber": "079183000002",
"taxpayerName": "Nguyễn Văn A",
"taxDepartment": "Chi cục Thuế khu vực",
"declarationStatus": "OVERDUE",
"statusTitle": "Quá hạn nộp tờ khai",
"statusDescription": "Đã quá hạn nộp tờ khai.",
"submitDate": "15/01/2026",
"declarationPeriod": "01/2026",
"declarationType": "Tờ khai thuế",
"declarationCode": "TK-001",
"receivedDate": "",
"processedDate": "",
"rejectedReason": "",
"additionalRequest": "",
"note": "",
"updatedAt": "2026-05-27T04:11:56.000Z",
"createdAt": "2026-05-27T04:11:56.000Z",
"isHidden": 0,
"isDeleted": 0
}
],
"totalNextPage": 0
}
}
```

---

## Mã lỗi

| HTTP | Mã lỗi | Mô tả |
|---|---|---|
| 400 | _Validation Error_ | Payload không đúng schema, thiếu field bắt buộc, sai kiểu hoặc vượt giới hạn. |
| 429 | `QUOTA_EXCEEDED` | apikey không hợp lệ hoặc vượt quota. |
| 500 | `MISSING_LOOKUP_FIELD` | Thiếu điều kiện tra cứu: cần ít nhất một trong các trường MST, CCCD/CMND hoặc tên người nộp thuế. |
| 500 | `UNKNOWN_ERROR` | Lỗi không xác định. |

---

## Tham khảo

- [Quy chuẩn chung → Common Error](../../Common.html#common-error) — danh sách mã lỗi hệ thống trả về trong trường `error`.

---

## Data test cho developer

- apikey: 911abff6-137a-4aa3-a836-555a1d30359b
- taxCode: 8173748371
- citizenIdentityNumber: 079183000002
- taxpayerName: Nguyễn Văn A

Cần thay bằng dữ liệu môi trường thật khi tích hợp.
Loading