Đối soát COD API

Đối soát file COD của GHN, GHTK, SPX, J&T, Viettel Post, Ninja Van (XLSX / CSV) với đơn của shop: thiếu tiền, thiếu đơn, đơn trùng, phí, thực nhận.

POSThttps://apibox.io.vn/v1/vn-cod-reconcile

Dữ liệu & JSON▶ Dùng thử online

Tải lên bảng đối soát COD của hãng vận chuyển bằng multipart statement (XLSX hoặc CSV; được gửi nhiều file) hoặc gửi statement_rows dạng JSON, cùng danh sách đơn của shop trong orders (file hoặc mảng JSON có mã đơn và / hoặc mã vận đơn và tiền COD dự kiến). Cột được nhận diện theo tên tiêu đề tiếng Việt hoặc tiếng Anh, không phân biệt dấu ("Mã vận đơn", "Mã đơn shop", "Tiền thu hộ", "Phí vận chuyển", "Phí hoàn", "Thực nhận", "Waybill No.", "COD Amount"…), dòng tiêu đề nằm ở bất kỳ đâu trong 40 dòng đầu, dòng tổng được bỏ qua. Hãng vận chuyển được nhận diện từ tiêu đề / tên file hoặc từ định dạng mã vận đơn (tracking-detect).

Kết quả gồm số tổng (COD, phí vận chuyển, phí thu hộ, phí hoàn, bảo hiểm, phí khác, thực nhận dự kiến = COD − phí, thực nhận theo file), kiểm tra từng dòng (thực nhận ≠ COD − phí, đơn hoàn chưa có phí hoàn), đơn trùng, và khi có orders: đơn khớp, đơn lệch tiền (cod_short, cod_over, đơn hoàn vẫn có COD, phí ship khác báo giá của bạn), đơn có trong danh sách shop nhưng thiếu trên file đối soát và ngược lại. bank_amount so khoản chuyển khoản ngân hàng với tổng thực nhận; tolerance cho phép chênh lệch làm tròn.

Mẫu file của các hãng có thể thay đổi: cột nhận diện được trả về trong columns, và statement_rows cho phép bạn tự đặt tên cột. File chỉ xử lý trong bộ nhớ, không lưu lại.

Tham số

Tên	Vị trí	Kiểu	Bắt buộc	Mặc định
`statement`	body	file	có		Bảng đối soát COD của hãng (XLSX / CSV); statement2… cho các file khác. Hoặc `statement_rows` (mảng JSON các dòng).
`orders`	body	file	không		Đơn của shop: file (XLSX / CSV) hoặc mảng JSON {order_code, tracking, cod, shipping_fee}.
`carrier`	body	string	không		Chỉ định hãng: ghn, ghtk, spx, jt, viettelpost, ninjavan.
`bank_amount`	body	number	không		Số tiền nhận qua ngân hàng, để so với tổng thực nhận.
`tolerance`	body	number	không	`0`	Chênh lệch cho phép (VND).
`include_matched`	body	boolean	không	`false`	Liệt kê cả các đơn đã khớp.

Ví dụ

curl -X POST "https://apibox.io.vn/v1/vn-cod-reconcile" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"carrier":"ghn","statement_rows":[{"Mã đơn GHN":"GAB12CD3","Mã đơn shop":"DH001","Tiền thu hộ":350000,"Phí vận chuyển":22000,"Thực nhận":328000},{"Mã đơn GHN":"GAB12CD4","Mã đơn shop":"DH002","Tiền thu hộ":199000,"Phí vận chuyển":22000,"Thực nhận":177000}],"orders":[{"order_code":"DH001","cod":350000},{"order_code":"DH002","cod":250000},{"order_code":"DH003","cod":120000}]}'

const res = await fetch('https://apibox.io.vn/v1/vn-cod-reconcile', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "carrier": "ghn",
    "statement_rows": [
      {
        "Mã đơn GHN": "GAB12CD3",
        "Mã đơn shop": "DH001",
        "Tiền thu hộ": 350000,
        "Phí vận chuyển": 22000,
        "Thực nhận": 328000
      },
      {
        "Mã đơn GHN": "GAB12CD4",
        "Mã đơn shop": "DH002",
        "Tiền thu hộ": 199000,
        "Phí vận chuyển": 22000,
        "Thực nhận": 177000
      }
    ],
    "orders": [
      {
        "order_code": "DH001",
        "cod": 350000
      },
      {
        "order_code": "DH002",
        "cod": 250000
      },
      {
        "order_code": "DH003",
        "cod": 120000
      }
    ]
  }),
});
const data = await res.json();
console.log(data);

import requests

res = requests.post(
    "https://apibox.io.vn/v1/vn-cod-reconcile",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"carrier": "ghn", "statement_rows": [{"Mã đơn GHN": "GAB12CD3", "Mã đơn shop": "DH001", "Tiền thu hộ": 350000, "Phí vận chuyển": 22000, "Thực nhận": 328000}, {"Mã đơn GHN": "GAB12CD4", "Mã đơn shop": "DH002", "Tiền thu hộ": 199000, "Phí vận chuyển": 22000, "Thực nhận": 177000}], "orders": [{"order_code": "DH001", "cod": 350000}, {"order_code": "DH002", "cod": 250000}, {"order_code": "DH003", "cod": 120000}]},
    timeout=30,
)
print(res.json())

<?php
$ch = curl_init('https://apibox.io.vn/v1/vn-cod-reconcile');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => ['Authorization: Bearer YOUR_API_KEY', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => '{"carrier":"ghn","statement_rows":[{"Mã đơn GHN":"GAB12CD3","Mã đơn shop":"DH001","Tiền thu hộ":350000,"Phí vận chuyển":22000,"Thực nhận":328000},{"Mã đơn GHN":"GAB12CD4","Mã đơn shop":"DH002","Tiền thu hộ":199000,"Phí vận chuyển":22000,"Thực nhận":177000}],"orders":[{"order_code":"DH001","cod":350000},{"order_code":"DH002","cod":250000},{"order_code":"DH003","cod":120000}]}',
]);
$response = curl_exec($ch);
print_r(json_decode($response, true));

Kết quả trả về

{
  "statements": [
    {
      "name": "ghn",
      "carrier": "ghn",
      "carrier_name": "Giao Hàng Nhanh (GHN)",
      "carrier_detected_by": "parameter",
      "header_row": 1,
      "columns": {
        "tracking": "Mã đơn GHN",
        "order_code": "Mã đơn shop",
        "cod": "Tiền thu hộ",
        "shipping_fee": "Phí vận chuyển",
        "payout": "Thực nhận"
      },
      "rows": 2
    }
  ],
  "totals": {
    "rows": 2,
    "delivered": 2,
    "returned": 0,
    "cod": 549000,
    "shipping_fee": 44000,
    "cod_fee": 0,
    "return_fee": 0,
    "insurance_fee": 0,
    "other_fee": 0,
    "total_fees": 44000,
    "expected_payout": 505000,
    "stated_payout": 505000
  },
  "reconciliation": {
    "summary": {
      "orders": 3,
      "statement_rows": 2,
      "matched": 1,
      "amount_mismatch": 1,
      "missing_in_statement": 1,
      "missing_in_orders": 0,
      "duplicates": 0,
      "cod_short_total": 51000
    },
    "amount_mismatch": [
      {
        "tracking": "GAB12CD4",
        "order_code": "DH002",
        "cod_statement": 199000,
        "cod_expected": 250000,
        "fees": 22000,
        "payout": 177000,
        "status": null,
        "issues": [
          "cod_short"
        ],
        "difference": -51000
      }
    ],
    "missing_in_statement": [
      {
        "tracking": null,
        "order_code": "DH003",
        "cod_expected": 120000,
        "status": null,
        "row": 4
      }
    ],
    "missing_in_orders": []
  },
  "privacy": "Files are processed in memory and not stored."
}

Ứng dụng

Tìm đơn hãng trả thiếu tiền COD
Kiểm tra mọi đơn giao thành công đều có trên bảng đối soát tuần
Tổng hợp phí ship, phí thu hộ, phí hoàn theo từng kỳ
Khớp khoản tiền hãng chuyển vào tài khoản với bảng đối soát

Hỏi đáp

Hỗ trợ những hãng nào?

Mọi bảng đối soát có cột mã vận đơn hoặc mã đơn và cột COD / phí / thực nhận. Tiêu đề cột của GHN, GHTK, SPX (Shopee Express), J&T, Viettel Post, Ninja Van được nhận diện, cả tiếng Việt lẫn tiếng Anh.

Đơn được ghép thế nào?

Theo mã vận đơn trước, sau đó theo mã đơn của shop (mỗi cột có thể chứa loại mã kia). Mỗi đơn chỉ ghép một lần; dòng lặp lại được liệt kê là đơn trùng.

Dữ liệu có bị lưu không?

Không. File chỉ được đọc trong bộ nhớ cho request đó rồi bỏ đi.

API liên quan

{✓}

Đối soát COD API

Tham số

Ví dụ

Kết quả trả về

Ứng dụng

Hỏi đáp

API liên quan

Kiểm tra JSON

Định dạng JSON

CSV sang JSON