Skip to main content
Version: Next

Open API Introduction​

TConnect Open API is an open API suite that lets partners integrate TConnect services into their own systems. All APIs share a single authentication mechanism via the API Gateway and follow the common conventions below.

API catalog​

API groupDescriptionDocumentation
Input invoice lookupRetrieve a business's input (purchase) invoices from the tax portal (General Department of Taxation): account registration, sync, retrieval, reconciliation.View details →
Tax code lookupLook up business information by tax code (name, address, tax office, legal representative, etc.). No encryption required; billed per request.View details →

Authentication​

TConnect Open API uses a single shared authentication mechanism for all API groups: a JWT Bearer token issued by Keycloak (same as the Payment API).

  1. Call POST /openapi/v1/auth/login (header Partner-Code, AES-256-CBC-encrypted body containing username/password/client_id/client_secret) → receive an access_token.
  2. Add to every request:
Authorization: Bearer <access_token>
Partner-Code: <Merchant code issued by TConnect>

For the mechanism and AES encryption details, see Authentication (AES Encryption). When the token expires, call /openapi/v1/auth/refresh-token to get a new one.

Environment​

EnvironmentBase URL
Staginghttps://sme-open-api-sandbox.tconnect.vn
ProductionProvided after testing is completed

Conventions​

  • Resource identifiers (e.g. accountId, invoiceId) are UUIDs.
  • Dates use Vietnam time (UTC+7), in YYYY-MM-DD format.
  • Errors follow standard HTTP codes: 400 (invalid data / wrong format), 404 (not found), 401/403 (authentication / no permission).
  • Bodies are JSON (Content-Type: application/json).