Vietnam Invoices (MISA meInvoice create, publish & query)

Official3 toolsLive

by junter1989k-ai · JavaScript

Vietnam MISA meInvoice: AI agents create, publish and query e-invoices, stateless BYO.

Topics

ai-agentclaudee-invoiceeinvoiceinvoicemcpmcp-servertaptaxvatvietnamwishpoolmeinvoice

Captured live from the server via tools/list.

create_invoice

STEP 1 of the MISA meInvoice flow: create a Vietnamese e-invoice (hóa đơn điện tử) draft on MISA — the POST /itg/invoicepublishing/createinvoice call. You supply seller, buyer and line items; this server computes the Vietnamese VAT (thuế GTGT) math locally in VND (integer đồng — no decimals) and forwards the payload. MISA returns a transaction_id, ref_id and invoice_data (an UNSIGNED invoice XML). This server does NOT sign: you then sign invoice_data MERCHANT-SIDE with your own digital signature / USB Token (chữ ký số) using the MISA local signing service, and pass the signed XML to publish_invoice (STEP 3). VAT rates: 10 (standard), 8 (temporary reduced), 5 (essentials), 0 (exports). Set withCode=true if you issue invoices WITH a tax-authority code (hóa đơn có mã); default false (không mã). Result accepted=true when MISA created the draft with no per-document error (check error_code). Required credential headers (set once in your MCP client, per-request, never stored): x-meinvoice-token (your MISA meInvoice access token) + x-meinvoice-taxcode (your company tax code / MST, sent as CompanyTaxCode). Optional header x-meinvoice-env: test (default = sandbox testapi.meinvoice.vn, no fiscal effect) | prod (production api.meinvoice.vn, real fiscal effect). Optional owner-policy headers x-agentpay-max-amount / x-agentpay-approval-above / x-agentpay-allowed-tools. All amounts are in VND (đồng, whole numbers — no decimals).

Parameters12

seller	object	required	The seller (người bán) = your company. Requires legalName + taxCode.
buyer	object	optional	The buyer (người mua). Use legalName+taxCode for a company (B2B) or fullName for an individual consumer.
lines	array	required	Invoice line items. Each: { name, unit?, quantity, unitPrice, taxRate? }. taxRate is a VAT percentage (10 default / 8 / 5 / 0). unitPrice is in whole VND.
invSeries	string	required	Invoice series / ký hiệu (e.g. "1C25MYT") — assigned when you register the invoice template with the tax authority. REQUIRED.
refId	string	optional	Your own reference id for this invoice (RefID). Optional — a UUID is generated if omitted. Reusing a RefID triggers InvoiceDuplicated.
invoiceName	string	optional	Invoice type name, default "Hóa đơn giá trị gia tăng" (VAT invoice).
invDate	string	optional	Invoice date (ngày hóa đơn), ISO datetime. Default: now.
currencyCode	string	optional	Currency, default VND. VND is a 0-decimal currency; non-VND requires exchangeRate.
exchangeRate	number	optional	Exchange rate to VND (default 1 for VND).
paymentMethodName	string	optional	Payment method, default "TM/CK" (cash/bank transfer).
amountInWords	string	optional	Optional total amount spelled out in Vietnamese (số tiền bằng chữ).
withCode	boolean	optional	true = invoice WITH tax-authority code (có mã, uses /code/itg path); false (default) = without code (không mã).

Raw schema

{
  "type": "object",
  "properties": {
    "seller": {
      "type": "object",
      "description": "The seller (người bán) = your company. Requires legalName + taxCode.",
      "properties": {
        "legalName": {
          "type": "string",
          "description": "Seller organization legal name (tên đơn vị). Required for the seller; for the buyer, use legalName for a company or fullName for an individual."
        },
        "fullName": {
          "type": "string",
          "description": "Seller individual full name (họ tên người mua) — use for a personal/consumer buyer instead of legalName."
        },
        "taxCode": {
          "type": "string",
          "description": "Seller tax code / MST (mã số thuế). Required for the seller; for a B2B buyer include it, omit for an individual consumer."
        },
        "address": {
          "type": "string",
          "description": "Seller address (địa chỉ)."
        },
        "email": {
          "type": "string",
          "description": "Seller email (used for e-invoice delivery)."
        },
        "phone": {
          "type": "string",
          "description": "Seller phone number."
        },
        "bankAccount": {
          "type": "string",
          "description": "Seller bank account number (optional)."
        },
        "bankName": {
          "type": "string",
          "description": "Seller bank name (optional)."
        }
      },
      "required": [
        "legalName",
        "taxCode"
      ]
    },
    "buyer": {
      "type": "object",
      "description": "The buyer (người mua). Use legalName+taxCode for a company (B2B) or fullName for an individual consumer.",
      "properties": {
        "legalName": {
          "type": "string",
          "description": "Buyer organization legal name (tên đơn vị). Required for the seller; for the buyer, use legalName for a company or fullName for an individual."
        },
        "fullName": {
          "type": "string",
          "description": "Buyer individual full name (họ tên người mua) — use for a personal/consumer buyer instead of legalName."
        },
        "taxCode": {
          "type": "string",
          "description": "Buyer tax code / MST (mã số thuế). Required for the seller; for a B2B buyer include it, omit for an individual consumer."
        },
        "address": {
          "type": "string",
          "description": "Buyer address (địa chỉ)."
        },
        "email": {
          "type": "string",
          "description": "Buyer email (used for e-invoice delivery)."
        },
        "phone": {
          "type": "string",
          "description": "Buyer phone number."
        },
        "bankAccount": {
          "type": "string",
          "description": "Buyer bank account number (optional)."
        },
        "bankName": {
          "type": "string",
          "description": "Buyer bank name (optional)."
        }
      }
    },
    "lines": {
      "type": "array",
      "description": "Invoice line items. Each: { name, unit?, quantity, unitPrice, taxRate? }. taxRate is a VAT percentage (10 default / 8 / 5 / 0). unitPrice is in whole VND.",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Goods/service name (tên hàng hóa, dịch vụ)."
          },
          "unit": {
            "type": "string",
            "description": "Unit of measure (đơn vị tính), e.g. \"Cái\", \"Giờ\", \"Kg\"."
          },
          "quantity": {
            "type": "number",
            "description": "Quantity (số lượng)."
          },
          "unitPrice": {
            "type": "number",
            "description": "Unit price in VND (đơn giá), whole number."
          },
          "taxRate": {
            "type": "number",
            "description": "VAT rate percent: 10 (default, standard), 8 (reduced), 5, or 0."
          }
        },
        "required": [
          "name",
          "quantity",
          "unitPrice"
        ]
      }
    },
    "invSeries": {
      "type": "string",
      "description": "Invoice series / ký hiệu (e.g. \"1C25MYT\") — assigned when you register the invoice template with the tax authority. REQUIRED."
    },
    "refId": {
      "type": "string",
      "description": "Your own reference id for this invoice (RefID). Optional — a UUID is generated if omitted. Reusing a RefID triggers InvoiceDuplicated."
    },
    "invoiceName": {
      "type": "string",
      "description": "Invoice type name, default \"Hóa đơn giá trị gia tăng\" (VAT invoice)."
    },
    "invDate": {
      "type": "string",
      "description": "Invoice date (ngày hóa đơn), ISO datetime. Default: now."
    },
    "currencyCode": {
      "type": "string",
      "description": "Currency, default VND. VND is a 0-decimal currency; non-VND requires exchangeRate."
    },
    "exchangeRate": {
      "type": "number",
      "description": "Exchange rate to VND (default 1 for VND)."
    },
    "paymentMethodName": {
      "type": "string",
      "description": "Payment method, default \"TM/CK\" (cash/bank transfer)."
    },
    "amountInWords": {
      "type": "string",
      "description": "Optional total amount spelled out in Vietnamese (số tiền bằng chữ)."
    },
    "withCode": {
      "type": "boolean",
      "description": "true = invoice WITH tax-authority code (có mã, uses /code/itg path); false (default) = without code (không mã)."
    }
  },
  "required": [
    "seller",
    "lines",
    "invSeries"
  ]
}

publish_invoice

STEP 3 of the MISA meInvoice flow: publish an ALREADY-SIGNED e-invoice — the POST /itg/invoicepublishing call. After create_invoice returns invoice_data (unsigned XML) and you sign it MERCHANT-SIDE with your USB Token (chữ ký số) via the MISA local signing service, pass the signed XML back here with its transaction_id and ref_id. MISA submits it to the tax authority (Tổng cục Thuế) and returns the official inv_no (số hóa đơn), inv_code (mã cơ quan thuế, for coded invoices) and inv_series. This server does NOT sign — it only forwards the signed document. Set withCode to match how the invoice was created. Result accepted=true when MISA published with no per-document error (check error_code); common errors: SignatureEmpty, InvalidSignature, InvoiceNumberNotContinuous, InvoiceDuplicated. Required credential headers (set once in your MCP client, per-request, never stored): x-meinvoice-token (your MISA meInvoice access token) + x-meinvoice-taxcode (your company tax code / MST, sent as CompanyTaxCode). Optional header x-meinvoice-env: test (default = sandbox testapi.meinvoice.vn, no fiscal effect) | prod (production api.meinvoice.vn, real fiscal effect). Optional owner-policy headers x-agentpay-max-amount / x-agentpay-approval-above / x-agentpay-allowed-tools. All amounts are in VND (đồng, whole numbers — no decimals).

Parameters7

refId	string	optional	The RefID of the invoice (from create_invoice ref_id).
transactionId	string	required	The TransactionID returned by create_invoice.
invoiceData	string	required	The SIGNED invoice XML — the invoice_data from create_invoice after you signed it merchant-side with your USB Token / digital signature. This server forwards it untouched.
isSendEmail	boolean	optional	Whether MISA emails the e-invoice to the buyer (default false).
receiverEmail	string	optional	Recipient email (when isSendEmail=true).
receiverName	string	optional	Recipient name (when isSendEmail=true).
withCode	boolean	optional	true = có mã (/code/itg path); false (default) = không mã. Match how create_invoice was called.

Raw schema

{
  "type": "object",
  "properties": {
    "refId": {
      "type": "string",
      "description": "The RefID of the invoice (from create_invoice ref_id)."
    },
    "transactionId": {
      "type": "string",
      "description": "The TransactionID returned by create_invoice."
    },
    "invoiceData": {
      "type": "string",
      "description": "The SIGNED invoice XML — the invoice_data from create_invoice after you signed it merchant-side with your USB Token / digital signature. This server forwards it untouched."
    },
    "isSendEmail": {
      "type": "boolean",
      "description": "Whether MISA emails the e-invoice to the buyer (default false)."
    },
    "receiverEmail": {
      "type": "string",
      "description": "Recipient email (when isSendEmail=true)."
    },
    "receiverName": {
      "type": "string",
      "description": "Recipient name (when isSendEmail=true)."
    },
    "withCode": {
      "type": "boolean",
      "description": "true = có mã (/code/itg path); false (default) = không mã. Match how create_invoice was called."
    }
  },
  "required": [
    "transactionId",
    "invoiceData"
  ]
}

query_invoice

Look up the status of one or more published e-invoices — the POST /itg/invoicepublished/invoicestatus call (read-only). Pass the transaction_id(s) returned by create_invoice/publish_invoice. Result per invoice: publish_status (MISA SaveInvoiceStatus int — draft/published state), send_tax_status + send_tax_status_label = the tax-authority (cơ quan thuế) submission status. For invoices WITHOUT a code (không mã): 0=not sent, 1=sent, 2=accepted, 3=rejected, 4=send error. For invoices WITH a code (có mã, withCode=true): 0=awaiting code, 1=send error, 2=code issued, 3=code rejected. Also returns invoice_code, reference_type (0=original, 1=replacement, 2=adjustment), is_deleted and received_status (0=not received, 1=received). Set withCode to match the invoice type. Required credential headers (set once in your MCP client, per-request, never stored): x-meinvoice-token (your MISA meInvoice access token) + x-meinvoice-taxcode (your company tax code / MST, sent as CompanyTaxCode). Optional header x-meinvoice-env: test (default = sandbox testapi.meinvoice.vn, no fiscal effect) | prod (production api.meinvoice.vn, real fiscal effect). Optional owner-policy headers x-agentpay-max-amount / x-agentpay-approval-above / x-agentpay-allowed-tools. All amounts are in VND (đồng, whole numbers — no decimals).

Parameters3

transactionIds	array	optional	One or more TransactionID lookup codes to query.
transactionId	string	optional	A single TransactionID (convenience alternative to transactionIds).
withCode	boolean	optional	true = có mã (/code/itg path); false (default) = không mã. Match the invoice type.

Raw schema

{
  "type": "object",
  "properties": {
    "transactionIds": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "One or more TransactionID lookup codes to query."
    },
    "transactionId": {
      "type": "string",
      "description": "A single TransactionID (convenience alternative to transactionIds)."
    },
    "withCode": {
      "type": "boolean",
      "description": "true = có mã (/code/itg path); false (default) = không mã. Match the invoice type."
    }
  }
}

README.md7 KBView on GitHub

🇻🇳 Vietnam Invoice MCP — MISA meInvoice (hóa đơn điện tử)

Use it in 60 seconds

Paste this into your MCP client config (Claude Desktop, Cursor, Windsurf, or any MCP-capable agent):

json

{
  "mcpServers": {
    "vietnam-invoice": {
      "type": "http",
      "url": "https://inv-vn.wishpool.app/mcp"
    }
  }
}

Nothing to install. Credentials, when you need them, travel as HTTP headers on each request and are never stored — see the threat model.

Or run it yourself

Would you rather not send production credentials to a server you do not control? Deploy this identical code to your own account and point your agent at your own URL:

bash

git clone https://github.com/junter1989k-ai/vietnam-invoice-mcp && cd vietnam-invoice-mcp && npx vercel --prod

MIT-licensed. Self-hosting removes us from the picture entirely, at no cost and with no loss of function.

A remote MCP server that lets any AI agent create, publish and query Vietnamese e-invoices (hóa đơn điện tử) through MISA meInvoice, a Tax-Department-connected e-invoicing provider. Electronic invoices have been mandatory nationwide since 1 July 2022 (connected to the General Department of Taxation / Tổng cục Thuế).

Endpoint: https://inv-vn.wishpool.app/mcp
Stateless · bring-your-own MISA token · stores nothing
We only wrap the API calls — the digital signature stays merchant-side

What this server is (and is not)

Vietnamese e-invoices are signed with the merchant's own digital signature (chữ ký số) on a USB Token (or HSM), applied by the MISA local signing service. This server never signs and never holds a certificate/USB Token. It is a thin, stateless translation layer that:

create_invoice — builds the invoice, computes the VAT (thuế GTGT) in VND locally, and POSTs to MISA's createinvoice endpoint. MISA returns an unsigned invoice XML (invoice_data) + a transaction_id.
You sign invoice_data merchant-side with your USB Token (MISA local signing service) — this step never touches this server.
publish_invoice — forwards the signed XML to MISA's invoicepublishing endpoint; MISA issues the official inv_no / inv_code.
query_invoice — read-only tax-authority + publish status.

This mirrors the "we only wrap the submission" honesty of the sister servers (Saudi ZATCA, Malaysia MyInvois): the cryptographic signing never leaves the merchant.

Connect

json

{
  "mcpServers": {
    "vietnam-invoice": {
      "type": "http",
      "url": "https://inv-vn.wishpool.app/mcp",
      "headers": {
        "x-meinvoice-token": "your-misa-meinvoice-token",
        "x-meinvoice-taxcode": "your-company-tax-code",
        "x-meinvoice-env": "prod"
      }
    }
  }
}

Header	Required	Notes
`x-meinvoice-token`	✅	MISA meInvoice access token → forwarded as `Authorization: Bearer`
`x-meinvoice-taxcode`	✅	Company tax code / MST → forwarded as the `CompanyTaxCode` header
`x-meinvoice-env`	optional	`test` (default, sandbox `testapi.meinvoice.vn`, no fiscal effect) · `prod` (`api.meinvoice.vn`, real fiscal effect)

Owner policy guardrails (set by the human owner in the client config; the agent cannot relax them): x-agentpay-max-amount, x-agentpay-approval-above, x-agentpay-allowed-tools. The cap applies to the invoice grand total (TotalAmount, VND) computed at create time.

Tools

`create_invoice` (step 1)

Build + compute VAT, POST createinvoice. Input: seller{legalName,taxCode,address,…}, buyer{legalName|fullName,taxCode?,address,email?}, lines:[{name,unit?,quantity,unitPrice,taxRate?}], invSeries, optional refId/invDate/currencyCode/withCode. Output: transaction_id, ref_id, invoice_data (unsigned XML — sign it merchant-side), inv_no.

VAT rates: 10 standard · 8 temporary reduced · 5 essentials · 0 exports. You choose the rate per line (tax classification is the merchant's decision).
Currency: VND (đồng) — a 0-decimal integer currency; every amount is a whole number.

`publish_invoice` (step 3)

Forward the merchant-signed XML, POST invoicepublishing. Input: transactionId, refId?, invoiceData (the signed XML), isSendEmail?, receiverEmail?, withCode?. Output: inv_no, inv_code, inv_series. Common errors surfaced verbatim: SignatureEmpty, InvalidSignature, InvoiceNumberNotContinuous, InvoiceDuplicated.

`query_invoice` (read-only)

POST invoicepublished/invoicestatus. Input: transactionIds:[…] (or single transactionId), withCode?. Output per invoice: publish_status, send_tax_status + label.

send_tax_status (không mã / no code): 0 not sent · 1 sent · 2 accepted · 3 rejected · 4 send error. send_tax_status (có mã / with code): 0 awaiting code · 1 send error · 2 code issued · 3 code rejected.

Path convention

MISA v3 splits by invoice type: no-code (không mã) = /itg/…, with-code (có mã) = /code/itg/…. Set withCode per invoice (default false). Base: https://{testapi|api}.meinvoice.vn/api/v3.

Development

bash

npm run dev    # local server on http://localhost:3240
npm test       # e2e: protocol + validation + VAT math + LIVE MISA InvalidTokenCode probe

The e2e suite makes a real call to testapi.meinvoice.vn with a fake token and asserts MISA's native InvalidTokenCode fingerprint — proof the integration line is wired correctly (we never sign, so a real published invoice needs a real merchant token + USB Token).

Honest gaps

The prod host api.meinvoice.vn/api/v3 is taken from MISA's official developer intro (doc.meinvoice.vn/api/); only the test host testapi.meinvoice.vn/api/v3 is live-verified here.
End-to-end publish cannot be verified without a real MISA token and a merchant USB Token to sign the XML — by design, signing is merchant-side. The create/publish/query request shapes follow MISA's InvoicePublishing and GetStatusInvoice docs.

Sister servers

Invoices: Malaysia MyInvois · Saudi ZATCA · Mexico CFDI · Poland KSeF · Chile DTE · Brazil NF-e · Peru CPE · India GST. Local payments in 81 countries: mcp.wishpool.app · Logistics: logi.wishpool.app.

Install

Tools (3)

create_invoicepublish_invoicequery_invoice

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://inv-vn.wishpool.app/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "vietnam-invoice-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://inv-vn.wishpool.app/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.

Topics

create_invoice

publish_invoice

query_invoice

🇻🇳 Vietnam Invoice MCP — MISA meInvoice (hóa đơn điện tử)

Use it in 60 seconds

Or run it yourself

What this server is (and is not)

Connect

Tools

create_invoice (step 1)

publish_invoice (step 3)

query_invoice (read-only)

Path convention

Development

Honest gaps

Sister servers

Install

Remote endpoint

`create_invoice` (step 1)

`publish_invoice` (step 3)

`query_invoice` (read-only)