COD Reconciliation (Vietnam) API

Reconcile COD statements of GHN, GHTK, SPX, J&T, Viettel Post, Ninja Van (XLSX / CSV) with your orders: short COD, missing orders, duplicates, fees.

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

Data & JSON▶ Try it online

Upload the carrier's COD statement (bảng đối soát) as multipart statement (XLSX or CSV; several files allowed) or send statement_rows as JSON, plus your order list as orders (file or JSON array with an order code and / or tracking number and the expected COD). Columns are recognised from their header names in Vietnamese or English, accents ignored ("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"…), with the header row found anywhere in the first 40 rows and total rows skipped. The carrier is recognised from the header / file name or from the tracking-number formats of tracking-detect.

The response gives totals (COD, shipping fee, COD fee, return fee, insurance, other fees, expected payout = COD − fees, stated payout), per-row checks (payout ≠ COD − fees, returned orders without a return fee), duplicates, and with orders: matched orders, amount mismatches (cod_short, cod_over, COD on a returned order, a shipping fee that differs from yours), orders missing from the statement and statement rows missing from your orders. bank_amount compares the bank transfer with the statement payout; tolerance allows small rounding differences.

Carrier export layouts change: unknown headers are reported in columns, and statement_rows lets you map columns yourself. Files are processed in memory and not stored.

Parameters

Name	In	Type	Required	Default
`statement`	body	file	yes		Carrier COD statement (XLSX / CSV); statement2… for more files. Or `statement_rows` (JSON array of row objects).
`orders`	body	file	no		Your orders: file (XLSX / CSV) or JSON array of {order_code, tracking, cod, shipping_fee}.
`carrier`	body	string	no		Force the carrier: ghn, ghtk, spx, jt, viettelpost, ninjavan.
`bank_amount`	body	number	no		Amount received by bank transfer, compared with the statement payout.
`tolerance`	body	number	no	`0`	Allowed difference in VND.
`include_matched`	body	boolean	no	`false`	Also list matched orders.

Example

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));

Response

{
  "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."
}

Use cases

Find orders where the carrier paid less COD than expected
Check that every delivered order appears on the weekly statement
Total shipping, COD and return fees per statement
Match the bank transfer from the carrier with its statement

FAQ

Which carriers are supported?

Any statement with a tracking or order code column and COD / fee / payout columns. Headers used by GHN, GHTK, SPX (Shopee Express), J&T, Viettel Post and Ninja Van are recognised, in Vietnamese or English.

How are orders matched?

By tracking number first, then by your order code (either column may hold either code). Each order is matched once; repeats are listed as duplicates.

Is my data stored?

No. Files are read in memory for the request and discarded.

Related APIs

{✓}

COD Reconciliation (Vietnam) API

Parameters

Example

Response

Use cases

FAQ

Related APIs

JSON Validator

JSON Formatter

CSV to JSON