Introduction

Welcome to Slime Document’s documentation! (aka. Slime Docuception)
The document contains two parts.

Guides, this part, discuss tutorials and high-level stuff.
References where we dive into the consumption details of each API.

Each one serves different purposes during your journey; pick wisely.

Hello World

Lets get your hand dirty. This tutorial will guides you through calling your first API, Hello API.

Running the code example

Follow these steps to test the project on your machine and ensure the runtime environment is set up correctly.

Clone the example code into the directory of your choice.

git clone

CLONE_TO=slime-document-examples; \
git clone https://github.com/slime-systems/slime-document--support.git $CLONE_TO && \
cd "$CLONE_TO/examples/hello"

Assuming Node.js and npm are already installed, proceed to run the code.

run command

npm install && npm start

If you encounter an error similar to the following JSON response, congratulations, you are now successfully connected to the API.

API response

{
  "exception": {
    "code": "JWT::KeyNotFound"
  }
}

Setting Up the API Credentials

The config section

const projectId = 123456;
const keyId = 'k1234';
const secret = 'Bl9j0NXcWz70VMqxzk3Psk1ZAwQ6Pa5xlT9EHucd';

Examine index.js and locate the config section; you will notice that three variables need to be set.

ProjectID
KeyID
Secret

The next objective is to set up the values of these variables.

KeyID and Secret can be generated under the Keys section of your project.
ProjectID, as the name suggested, is the unique identifier for your project.
If you do not have an existing project, use the New Project button to create one.
You will find the New Project button once logged in.

Once you have finished editing index.js, try rerunning the code.

If everything is done correctly, you’ll be greeted back.

{
  "data": {
    "hello": "Sekai"
  }
}

If the code runs without errors, congratulations! You have successfully authenticated with the API.

Understanding API Authentication

To implement authentication in your preferred programming language, it is crucial to grasp the example provided. Fortunately, the process is straightforward.

High-level Overview

The flow involves the client sending a command along with its parameters to the API endpoint and receiving the corresponding response.

Communication Medium

How the command was sent over the HTTP.

const response = await axios.post(apiEndpoint, {
  request: jwt,
});

The encoded payload is transmitted to the designated API endpoint via POST-method HTTP requests. The payload is encapsulated within a POST parameter named request.

Payload Encoding

JWT (JSON Web Token), an industry-standard, simplifies command encoding for robust API authentication. It has broad support across various programming language communities.

Encoding the command into a token is as simple as choosing your preferred JWT library and passing in the parameters.

In the provided code example, we started the implementation by reviewing the API documentation.

According to the document, the “hello” command corresponds to the test/hello API subject.
The command accepts name as the required parameter.

Base payload construction with sub and data claims.

new SignJWT({
  sub: 'test/hello',
  data: {
    name: 'Sekai',
  },
});

Begin the encoding by creating the base payload.

The data claim is a custom claim; it is not backed by the JWT standard.

Setting the required claims.

jwtBuilder.setIssuedAt().setAudience('thai-document.slime.systems')

We now have the base payload; the next step is to set iat (Issued At) and aud (Audience), the required claims, for the token.

The iat and aud claims make the token more secure against advisories; if you are curious, you may Google for the details later.

The aud (Audience) claim must be thai-document.slime.systems, or the token will be rejected.

Set headers

jwtBuilder.setProtectedHeader({
  typ: 'JWT',
  alg: 'HS256',
  kid: keyId,
})

With the payload completed, move on to constructing the header.

Sign

const jwt = jwtBuilder.sign(secret);

Then, sign the token using the shared secret.

This process elucidates the steps involved in encoding the payload. Should you have any queries or concerns, feel free to reach out to us. We are here to assist you.

Implement it your way

The gist remains consistent across various programming languages, albeit with different syntax. The provided example is in JavaScript, chosen for its accessibility and ease of experimentation.

After reading this Hello World section, we hope you will understand the details behind our example code, enabling you to call the API from your language of choice.

Base Integration

This section details the recommended default for integrating with Slime Document. It serves as the foundation upon which you can add further customizations to tailor the integration to your specific needs.

Flow

Customers order
Your customers place orders for products or services through your application or website.
Order fulfillment
You fulfill the orders, ensuring the products are in stock or the services can be delivered.
Tax Invoice Issuance
Call our API to generate a tax invoice after the order has been successfully fulfilled.
Deliver the document
Deliver the generated tax invoice to your customers via the application or website.

APIs

Your system will interact with Slime Document in steps 3 and 4 of the flow through two APIs:

Simple Transaction ⇨ Initiate with Abbreviated Tax Invoice
- Nickname: issuance API
- Involved In: Step 3, Tax Invoice Issuance.
Trading Transaction ⇨ Latest PDF
- Nickname: PDF API
- Involved In: Step 4, Deliver the document.

Document Delivery

User-facing interface

Following a successful issuance API call, a link to the document can be displayed on your website. It’s recommended to include the target="_blank" attribute to open the link in a new tab.
Clicking the link triggers your backend to call the PDF API and redirect your customer to the destination URL.

Handling the PDF Request

The PDF API will be used to get the destination URL.
- The API requires transaction_id used in the issuance API.

Transaction info calling

{
  "sub": "trading-transaction/show",
  "data": {
    "transaction_id": "<your transaction id>",
    "deferrable": true
  }
}

Upon clicking the download link, your backend should have the transaction_id corresponding to the transaction involved. It then calls the PDF API with the deferrable = true parameter to delegate the timing-related handling to Slime Document.

Response

{
  "data": {
    "location": "https://temporary.example.com/thai-document/temporary-path-that-expires-in-1-minute"
  }
}

Then, redirect your customer to the retrieved URL using a 303 See Other status code.

Remember, this section serves as a guide for the fundamental integration scenario. We understand that every use case is unique, and a cookie-cutter approach may not be suitable for all.

If you need customizations that haven’t been covered yet, let’s discuss.

Bearer Tax Invoice

Similar to a Bearer Cheque, which can be cashed or deposited by anyone holding it, a Bearer Tax Invoice allows anyone holding it to be named on the full tax invoice.

Integration

A Bearer Tax Invoice is essentially an abbreviated tax invoice featuring a theme displaying a QR code or a link to our service page.

To implement this, follow the base integration guide and ensure the chosen theme supports the Bearer Tax Invoice feature.

In fact, the retail-hatsu theme used in the base integration example already supports this feature, effectively making the example a practical demonstration of Bearer Tax Invoices.

Hybrid Tax Invoice

The Hybrid Tax Invoice offers a convenient solution, combining the benefits of both physical and electronic documents.

Provides immediate, paper-based abbreviated tax invoices for customers at the point of sale.
Offers the self-service option to reissue a full tax invoice electronically later.

Flow

Order & Fulfillment
The customer completes their purchase, and you fulfill the order.
Tax Invoice Issuance
- The Point-of-Sale (POS) system is ready to print an abbreviated tax invoice on thermal paper.
- But, just before printing, the POS system retrieves a unique URL from Slime Document via API and appends it as a QR code to the printing tax invoice.
Document Delivery
The printed physical tax invoice with the embedded QR code can now be handed to the customer. The QR code enables the customer to issue a full tax invoice afterward.

APIs

Your POS system will interact with Slime Document in step 2 of the flow through two APIs:

Simple Transaction ⇨ Initiate with Tax Invoice Stub
- Nickname: stub API
- Involved In: Step 2, Tax Invoice Issuance.
Trading Transaction ⇨ Show
- Nickname: transaction info API
- Involved In: Step 2, Tax Invoice Issuance.

Integration

Use the stub API to generate a service page for your customer.

Transaction info calling

{
  "sub": "trading-transaction/show",
  "data": {
    "transaction_id": "<your transaction id>"
  }
}

Transaction info response

{
  "data": {
    "id": "<transaction id>",
    "service_url": "<service url>",
    "...": "...<ignored>..."
  }
}

Upon successful service page creation (confirmed by the stub API response), utilize the transaction info API to retrieve the service_url.

Convert the retrieved service_url into a QR code and embed it onto the abbreviated tax invoice before printing.

By scanning the QR code using their smartphone, customers can easily access the service page. This service page allows them to issue a full tax invoice electronically.

What if?

I am integrating the API with a non-web application.

The base integration guide assumes you’re integrating Slime Document with a website. However, for different scenarios:

Latest PDF calling

{
  "sub": "trading-transaction/show",
  "data": {
    "transaction_id": "<your transaction id>",
    "deferrable": false
  }
}

The deferrable = true setting (introduced in the base integration) is unsuitable. This is because it displays an intermediate HTML page, which wouldn’t function correctly outside a web browser environment.
So, the deferrable should be set to false to ensure a proper response format for non-website integrations.

Response when PDF is available

{
  "data": {
    "location": "https://temporary.example.com/thai-document/temporary-path-that-expires-in-1-minute"
  }
}

If the PDF is ready for download, the API will return the temporary location of the PDF file. You can then use this location to provide your customer with the download or viewing functionalities.

Response when PDF is not ready

{
  "exception": {
    "code": "DocumentPending"
  }
}

If the document is still being generated, you’ll receive a DocumentPending exception. In this case, it’s recommended to display a user-friendly message informing your customer that the document is on its way and will be available shortly.

I want to use unstructured address format for tax invoices.

There is a specific regulations regarding Thailand addresses on Tax Invoices. Ideally, the address information should be provided in a structured data format according to the official standards.

However, it’s important to note that the revenue department might currently accept invoices with unstructured address data, even though it deviates from the recommended format.

Example quirks flag setting

{
  "sub": "simple-transaction/initiate-with-tax-invoice",
  "data": {
    "document": {
      "buyer_info": {
        "address": {
          "line1": "ดาดฟ้า, อาคารมินัสทิริธ",
          "line2": "แขวงลุมพินี, เขตปทุมวัน, กรุงเทพมหานคร",
          "post_code": "10330",
          "country_id": "TH"
        },
        "...": "...<ignored>..."
      },
      "...": "...<ignored>..."
    },
    "customization": {
      "quirks": {
        "allow_unstructured_address": true
      },
      "...": "...<ignored>..."
    }
  }
}

You can optionally set a flag allowing unstructured Thailand addresses.

Flag Name: allow_unstructured_address
Set In: the quirks section (as shown in the example)
Related API:
- Simple Transaction ⇨ Initiate with Tax Invoice
Acknowledgement:
By setting this flag, you acknowledge that the address information might not adhere to the official standard proposed by ETDA.

API Reference

Data Format

Request

Example Request Payload

{
  "sub": "***API Subject***",
  "data": {
    "param1": "value of param1",
    "param2": "value of param2"
  }
}

The request payload consists of an API Subject and parameters encapsulated as sub and data claims of a JSON Web Token, respectively.

Refer to the guide to understand the format of encoded request payloads.

Success Response

Example Success Response

{
  "data": {
    "hello": "Sekai"
  }
}

The success response returns with the HTTP status code 200 and a JSON body.

Unless otherwise specified, the data value should be a JSON object. The shape of the data object can vary between APIs.

Exception Response

Example Exception Response

{
  "exception": {
    "code": "Document::InvalidSender",
    "message": "This message is your debugging companion.",
    "metadata": {
      "useful": "info"
    }
  }
}

The exception response returns with the HTTP status code of 422 and a JSON body.

Unless otherwise specified, the value of the exception is a JSON object containing the following fields.

code: an exception code conveying meaning to humans and machines alike, suitable for programming consumption.
message: (optional) a short message helping developers pinpoint the issue.
metadata: (optional) additional information suitable for programming consumption.

An exception code is always available in an exception response.

Authentication

This section discusses possible exception codes related to the API authentication.

Exception Codes

As a reminder, an exception response looks like this:

{
  "exception": {
    "code": "JWT::KeyNotFound"
  }
}

JWT::KeyNotFound
- The kid specified in the JWT header is not recognized.
- Also, check the API endpoint; each project has a different API endpoint.
JWT::IATDrift
- The iat claim in the token drifts beyond the acceptable period. The token may be stale, or the time source used to generate the token is inaccurate, thus unusable.
JWT::InvalidSubject
- Unrecognized API subject specified.
JWT::VerificationError
- Invalid signature.
- Please check the secret key and the API endpoint.
JWT::DecodeError
- General JWT decoding-related issues.
- This exception code should be accompanied by a useful message for debugging.
JWT::SchemaViolation
- Some fields do not conform to the agreed format at the JWT level.

Test API

APIs for testing your API connections and authentications.

Hello

Example Payload

{
  "sub": "test/hello",
  "data": {
    "name": "Sekai"
  }
}

Example Response

{
  "data": {
    "hello": "Sekai"
  }
}

API Subject

test/hello

Parameters

name
- Type: String
- Required: true

Simple Transaction API

APIs for a trading transaction that requires a document once it is settled.

Initiate with Abbreviated Tax Invoice

Initiate a transaction and generate an abbreviated tax invoice.

Example Payload

{
  "sub": "simple-transaction/initiate-with-abbreviated-tax-invoice",
  "data": {
    "transaction_id": "TEST-ES-0001",
    "document": {
      "issued_at": "2023-11-30T17:00:00Z",
      "line_items": [
        {
          "name": "ข้าวโพดปิ้ง",
          "unit_price": "15",
          "quantity": "8",
          "vatable": true
        },
        {
          "name": "ไข่ต้ม",
          "unit_price": "6",
          "quantity": "10",
          "vatable": true
        },
        {
          "name": "ข้าวสาร",
          "unit_price": "220",
          "quantity": "1",
          "vatable": false
        }
      ]
    },
    "customization": {
      "theme": {
        "id": "retail-hatsu",
        "color": "#cd0c2b"
      },
      "vat_included": false,
      "vat_rate": "0.07"
    }
  }
}

Example Response

{
  "data": {
    "success": true
  }
}

API Subject

simple-transaction/initiate-with-abbreviated-tax-invoice

Parameters

We must admit we cannot document all rules mentioned in the official standard here unless we try to write another standard.

There is a lot of information surrounding the standard; we believe the best approach is to start with the example and then read the references as needed.
We perform reasonable validations on API inputs to ensure they can be represented in the format specified by the standard.

transaction_id
- Type: String
- Required: true
- Remarks: Client-generated transaction ID
  - Must be unique within the project.
  - Accepted Pattern: /^[-_\/a-zA-Z0-9]+$/
  - Max Length: 30
document
- Type: JSON Object
- Required: true
- Remarks: The data of the abbreviated tax invoice to be generated
document.ref
- Type: String
- Required: false
- Remarks: Client-generated document reference
  - Must be unique within the transaction.
  - This will be used as an idempotency key.
  - You should not send the value unless the idempotency is required.
document.line_items
- Type: Array<JSON Object>
- Required: true
- Remarks: List of items involved in the trading transactions.
  - Min Size: 1
  - Max Size: 1,000
document.line_items[].product_id
- Type: String
- Required: false
- Remarks:
  - Accepted Pattern: /^[-_/a-zA-Z0-9]+$/
  - Max Length: 35
document.line_items[].name
- Type: String
- Required: true
- Remarks:
  - Max Length: 256
document.line_items[].description
- Type: String
- Required: false
- Remarks:
  - Max Length: 256
document.line_items[].unit_price
- Type: Decimal as String
- Required: true
- Remarks:
  - The price will be displayed on the document as is.
  - The value can be either VAT-inclusive or exclusive.
  - You can specify if this price includes VAT or not by the customization.vat_included parameter.
  - Do not sent float via JSON; it is a lossy format and won’t preserve decimal places.
document.line_items[].quantity
- Type: Decimal as String
- Required: true
- Remarks: Do not sent float via JSON
  - It is a lossy format and won’t preserve decimal places.
document.line_items[].unit_code
- Type: String
- Required: false
- Remarks: Do not sent float via JSON
  - Unit code listed in UN/CEFACT Recommendation No. 20
document.line_items[].vatable
- Type: Boolean
- Required: true
- Remarks:
  - Some goods are exempted from VAT; this flag specifies if the product or service is VATable or not.
document.issued_at
- Type: String
- Required: true
- Remarks: ISO-8601-formatted timestamp of the time when the trading transaction was settled.
  - It can be in the past or present, but it wouldn’t make much sense to be in the future.
document.theme_parameters
- Type: JSON Object
- Required: conditional
- Remarks: Theme-specific parameters
  - Should not be sent unless specified by the theme you are using.
customization
- Type: JSON Object
- Required: true
- Remarks: Customization for the trading transaction
  - It is required because, at least, you must pick a theme (skin) for the documents.
customization.theme
- Type: JSON Object
- Required: true
customization.theme.id
- Type: String
- Required: true
- Remarks: Customization for the trading transaction
  - Recommended Theme: retail-hatsu
  - Custom Theme Development: Contact Us
customization.seller_branch_id
- Type: String
- Required: false
- Remarks: The branch id that sell products or services.
  - Accepted Pattern: /^\d{5}$/
customization.vat_included
- Type: Boolean
- Required: true
- Remarks: Weather we should list price as
customization.vat_rate
- Type: Decimal as String
- Required: true
- Remarks: For 7% VAT, please inputs “0.07”
tags
- Type: Array<String>
- Required: false
- Remarks: The transaction can be tagged.
  - Similar to hashtags, transactions can be filtered by a tag.
  - Min Size: 0
  - Max Size: 2
  - Max String Length: 100

Exception Codes

SchemaViolation
Certificate::NotReady
Fund::InsufficientBalance
- Please top up your account
Trade::Initiated
- The trading transaction with the supplied transaction_id already existed.
Seller::NotConfigured
- Seller info not ready
LineItems::InvalidUnitCode
Theme::NotFound
Theme::UnsupportedDocumentType
- The theme selected does not support this document type (abbreviated tax invoice).
Theme::UnsupportedLanguage
- The theme selected does not support the language you configured

Initiate with Tax Invoice Stub

Initiate a transaction and preparing a service page for tax invoices without generating a document. Please refer to the Hybrid Tax Invoice guide for its application.

Example Payload

{
  "sub": "simple-transaction/initiate-with-tax-invoice-stub",
  "data": {
    "transaction_id": "TEST-ES-0002",
    "document": {
      "issued_at": "2023-11-30T17:00:00Z",
      "line_items": [
        {
          "name": "ข้าวโพดปิ้ง",
          "unit_price": "15",
          "quantity": "8",
          "vatable": true
        },
        {
          "name": "ไข่ต้ม",
          "unit_price": "6",
          "quantity": "10",
          "vatable": true
        },
        {
          "name": "ข้าวสาร",
          "unit_price": "220",
          "quantity": "1",
          "vatable": false
        }
      ]
    },
    "customization": {
      "theme": {
        "id": "retail-hatsu",
        "color": "#cd0c2b"
      },
      "vat_included": false,
      "vat_rate": "0.07"
    }
  }
}

Example Response

{
  "data": {
    "success": true
  }
}

API Subject

simple-transaction/initiate-with-tax-invoice-stub

Parameters

We must admit we cannot document all rules mentioned in the official standard here unless we try to write another standard.

There is a lot of information surrounding the standard; we believe the best approach is to start with the example and then read the references as needed.
We perform reasonable validations on API inputs to ensure they can be represented in the format specified by the standard.

transaction_id
- Type: String
- Required: true
- Remarks: Client-generated transaction ID
  - Must be unique within the project.
  - Accepted Pattern: /^[-_\/a-zA-Z0-9]+$/
  - Max Length: 30
document
- Type: JSON Object
- Required: true
- Remarks: The data of the tax invoice to be generated
document.ref
- Type: String
- Required: false
- Remarks: Client-generated document reference
  - Must be unique within the transaction.
  - This will be used as an idempotency key.
  - You should not send the value unless the idempotency is required.
document.line_items
- Type: Array<JSON Object>
- Required: true
- Remarks: List of items involved in the trading transactions.
  - Min Size: 1
  - Max Size: 1,000
document.line_items[].product_id
- Type: String
- Required: false
- Remarks:
  - Accepted Pattern: /^[-_/a-zA-Z0-9]+$/
  - Max Length: 35
document.line_items[].name
- Type: String
- Required: true
- Remarks:
  - Max Length: 256
document.line_items[].description
- Type: String
- Required: false
- Remarks:
  - Max Length: 256
document.line_items[].unit_price
- Type: Decimal as String
- Required: true
- Remarks:
  - The price will be displayed on the document as is.
  - The value can be either VAT-inclusive or exclusive.
  - You can specify if this price includes VAT or not by the customization.vat_included parameter.
  - Do not sent float via JSON; it is a lossy format and won’t preserve decimal places.
document.line_items[].quantity
- Type: Decimal as String
- Required: true
- Remarks: Do not sent float via JSON
  - It is a lossy format and won’t preserve decimal places.
document.line_items[].unit_code
- Type: String
- Required: false
- Remarks: Do not sent float via JSON
  - Unit code listed in UN/CEFACT Recommendation No. 20
document.line_items[].vatable
- Type: Boolean
- Required: true
- Remarks:
  - Some goods are exempted from VAT; this flag specifies if the product or service is VATable or not.
document.issued_at
- Type: String
- Required: true
- Remarks: ISO-8601-formatted timestamp of the time when the trading transaction was settled.
  - It can be in the past or present, but it wouldn’t make much sense to be in the future.
document.theme_parameters
- Type: JSON Object
- Required: conditional
- Remarks: Theme-specific parameters
  - Should not be sent unless specified by the theme you are using.
customization
- Type: JSON Object
- Required: true
- Remarks: Customization for the trading transaction
  - It is required because, at least, you must pick a theme (skin) for the documents.
customization.theme
- Type: JSON Object
- Required: true
customization.theme.id
- Type: String
- Required: true
- Remarks: Customization for the trading transaction
  - Recommended Theme: retail-hatsu
  - Custom Theme Development: Contact Us
customization.seller_branch_id
- Type: String
- Required: false
- Remarks: The branch id that sell products or services.
  - Accepted Pattern: /^\d{5}$/
customization.vat_included
- Type: Boolean
- Required: true
- Remarks: Weather we should list price as
customization.vat_rate
- Type: Decimal as String
- Required: true
- Remarks: For 7% VAT, please inputs “0.07”
tags
- Type: Array<String>
- Required: false
- Remarks: The transaction can be tagged.
  - Similar to hashtags, transactions can be filtered by a tag.
  - Min Size: 0
  - Max Size: 2
  - Max String Length: 100

Exception Codes

SchemaViolation
Certificate::NotReady
Fund::InsufficientBalance
- Please top up your account
Trade::Initiated
- The trading transaction with the supplied transaction_id already existed.
Seller::NotConfigured
- Seller info not ready
LineItems::InvalidUnitCode
Theme::NotFound
Theme::UnsupportedDocumentType
- The theme selected does not support this document type (abbreviated tax invoice).
Theme::UnsupportedLanguage
- The theme selected does not support the language you configured

Initiate with Tax Invoice

Initiate a transaction and generate a tax invoice document corresponding to the transaction.

Example Payload

{
  "sub": "simple-transaction/initiate-with-tax-invoice",
  "data": {
    "transaction_id": "TEST-TAX-INVOICE-0001",
    "document": {
      "issued_at": "2023-11-30T17:00:00Z",
      "buyer_info": {
        "name": "Alabibi",
        "identity": {
          "type": "NIDN",
          "national_id_number": "1111111111119"
        },
        "address": {
          "country_id": "TH",
          "post_code": "20180",
          "changwat_id": "20",
          "amphoe_id": "2009",
          "tambon_id": "200905",
          "street_name": "ถนนข่าวสาร",
          "soi": "ตรอกไดแอกอน",
          "building_number": "123/456"
        }
      },
      "line_items": [
        {
          "name": "ข้าวโพดปิ้ง",
          "unit_price": "15",
          "quantity": "8",
          "vatable": true
        },
        {
          "name": "ไข่ต้ม",
          "unit_price": "6",
          "quantity": "10",
          "vatable": true
        },
        {
          "name": "ข้าวสาร",
          "unit_price": "220",
          "quantity": "1",
          "vatable": false
        }
      ]
    },
    "customization": {
      "theme": {
        "id": "retail-hatsu",
        "color": "#cd0c2b"
      },
      "vat_included": true,
      "vat_rate": "0.07"
    }
  }
}

Example Response

{
  "data": {
    "success": true
  }
}

API Subject

simple-transaction/initiate-with-tax-invoice

Parameters

We must admit we cannot document all rules mentioned in the official standard here unless we try to write another standard.

There is a lot of information surrounding the standard; we believe the best approach is to start with the example and then read the references as needed.
We perform reasonable validations on API inputs to ensure they can be represented in the format specified by the standard.

transaction_id
- Type: String
- Required: true
- Remarks: Client-generated transaction ID
  - Must be unique within the project.
  - Accepted Pattern: /^[-_\/a-zA-Z0-9]+$/
  - Max Length: 30
document
- Type: JSON Object
- Required: true
- Remarks: The data of the tax invoice to be generated
document.ref
- Type: String
- Required: false
- Remarks: Client-generated document reference
  - Must be unique within the transaction.
  - This will be used as an idempotency key.
  - You should not send the value unless the idempotency is required.
document.buyer_info
- Type: JSON Object
- Required: true
document.buyer_info.name
- Type: String
- Required: true
document.buyer_info.identity
- Type: JSON Object
- Required: true
- Remarks: Legal identity of the buyer
document.buyer_info.identity.type
- Type: Enum<String>
- Required: true
- Enums:
  - TXID: Tax ID, for juristic persons
  - NIDN: National ID Number, for Thai Citizen
  - CCPT: Passport Number
document.buyer_info.identity.tax_id
- Type: String
- Required: conditional
- Remarks:
  - Must be present when setting the value of document.buyer_info.identity.type to TXID.
  - Must pass the checksum test, preventing typos.
  - Accepted Pattern: /^\d{13}$/
document.buyer_info.identity.branch_id
- Type: String
- Required: false
- Remarks:
  - Accepted Pattern: /^\d{5}$/
document.buyer_info.identity.national_id_number
- Type: String
- Required: conditional
- Remarks:
  - Must be present when setting the value of document.buyer_info.identity.type to NIDN.
  - Must pass the checksum test, preventing typos.
  - Accepted Pattern: /^\d{13}$/
document.buyer_info.identity.passport_number
- Type: String
- Required: conditional
- Remarks:
  - Must be present when setting the value of document.buyer_info.identity.type to CCPT.
  - Accepted Pattern: /^\d{13}$/
document.buyer_info.identity.other_id
- Type: String
- Required: conditional
- Remarks:
  - Reserved for future uses.
document.buyer_info.email
- Type: String
- Required: false
- Remarks:
  - Accepted Format: e-mail address
document.buyer_info.phone_number
- Type: String
- Required: false
- Remarks:
  - Accepted Format: phone number
document.buyer_info.address
- Type: JSON Object
- Required: conditional
- Remarks:
  - Must be present per the official standard.
  - Please contact us if you want to do things that deviate from the standard. We probably support that, too.
document.buyer_info.address.country_id
- Type: String
- Required: true
- Remarks: ISO 3166-1 alpha-2 country code
document.buyer_info.address.post_code
- Type: String
- Required: true
- Remarks:
  - Accepted Pattern for address within Thailand: /^\d{5}$/
document.buyer_info.address.changwat_id
- Type: String
- Required: conditional
- Remarks: Thailand’s Changwat code
  - As specified by the Department of Provincial Administration, Ministry of Interior.
document.buyer_info.address.amphoe_id
- Type: String
- Required: conditional
- Remarks: Thailand’s Amphoe code
  - As specified by the Department of Provincial Administration, Ministry of Interior.
document.buyer_info.address.tambon_id
- Type: String
- Required: conditional
- Remarks: Thailand’s Tambon code
  - As specified by the Department of Provincial Administration, Ministry of Interior.
document.buyer_info.address.moo
- Type: String
- Required: false
- Remarks: The value will be displayed in the document with prefix
  - Example Values:
    - 10 will be displayed in the document as หมู่ 10 (language: th)
    - 11 will be displayed in the document as Moo 11 (language: en)
document.buyer_info.address.moo_barn
- Type: String
- Required: false
- Remarks: The value will be displayed in the document with prefix
  - Example Values:
    - จักจั่น will be displayed in the document as หมู่บ้านจักจั่น (language: th)
    - Raccoon will be displayed in the document as Moobarn Raccoon (language: en)
document.buyer_info.address.street_name
- Type: String
- Required: false
- Remarks: The value will be displayed verbatim in the document
  - Example Values:
    - Silk Road will be displayed in the document as Silk Road
    - Sesame Street will be displayed in the document as Sesame Street
document.buyer_info.address.soi
- Type: String
- Required: false
- Remarks: The value will be displayed verbatim in the document
  - Example Values:
    - Soi YikYik will be displayed in the document as Soi YikYik.
    - Trok Diagon will be displayed in the document as Trok Diagon.
document.buyer_info.address.building_name
- Type: String
- Required: false
- Remarks: The value will be displayed verbatim in the document.
document.buyer_info.address.building_number
- Type: String
- Required: conditional
- Remarks:
  - This value is required when the address is located in Thailand. It is required due to the Revenue Department validation composited with the rules specified by the official standard.
  - The value will be displayed in the document with a prefix.
  - Example Values:
    - 123/456 will be displayed in the document as เลขที่ 123/456 (language: th)
    - 78/9 will be displayed in the document as Building No. 78/9 (language: en)
document.buyer_info.address.floor
- Type: String
- Required: false
- Remarks:
  - This is a non-standard value.
  - The value will be displayed in the document with a prefix.
  - Example Values:
    - G will be displayed in the document as ชั้น G (language: th)
    - 10 will be displayed in the document as floor 10 (language: en)
document.buyer_info.address.room
- Type: String
- Required: false
- Remarks: The value will be displayed verbatim in the document.
  - ห้อง A/1 will be displayed in the document as ห้อง A/1.
  - Grand Suite will be displayed in the document as Grand Suite.
document.buyer_info.address.line1
- Type: String
- Required: conditional
document.buyer_info.address.line2
- Type: String
- Required: false
document.line_items
- Type: Array<JSON Object>
- Required: true
- Remarks: List of items involved in the trading transactions.
  - Min Size: 1
  - Max Size: 1,000
document.line_items[].product_id
- Type: String
- Required: false
- Remarks:
  - Accepted Pattern: /^[-_/a-zA-Z0-9]+$/
  - Max Length: 35
document.line_items[].name
- Type: String
- Required: true
- Remarks:
  - Max Length: 256
document.line_items[].description
- Type: String
- Required: false
- Remarks:
  - Max Length: 256
document.line_items[].unit_price
- Type: Decimal as String
- Required: true
- Remarks:
  - The price will be displayed on the document as is.
  - The value can be either VAT-inclusive or exclusive.
  - You can specify if this price includes VAT or not by the customization.vat_included parameter.
  - Do not sent float via JSON; it is a lossy format and won’t preserve decimal places.
document.line_items[].quantity
- Type: Decimal as String
- Required: true
- Remarks: Do not sent float via JSON
  - It is a lossy format and won’t preserve decimal places.
document.line_items[].unit_code
- Type: String
- Required: false
- Remarks: Do not sent float via JSON
  - Unit code listed in UN/CEFACT Recommendation No. 20
document.line_items[].vatable
- Type: Boolean
- Required: true
- Remarks:
  - Some goods are exempted from VAT; this flag specifies if the product or service is VATable or not.
document.issued_at
- Type: String
- Required: true
- Remarks: ISO-8601-formatted timestamp of the time when the trading transaction was settled.
  - It can be in the past or present, but it wouldn’t make much sense to be in the future.
document.theme_parameters
- Type: JSON Object
- Required: conditional
- Remarks: Theme-specific parameters
  - Should not be sent unless specified by the theme you are using.
customization
- Type: JSON Object
- Required: true
- Remarks: Customization for the trading transaction
  - It is required because, at least, you must pick a theme (skin) for the documents.
customization.theme
- Type: JSON Object
- Required: true
customization.theme.id
- Type: String
- Required: true
- Remarks: Customization for the trading transaction
  - Recommended Theme: retail-hatsu
  - Custom Theme Development: Contact Us
customization.seller_branch_id
- Type: String
- Required: false
- Remarks: The branch id that sell products or services.
  - Accepted Pattern: /^\d{5}$/
customization.vat_included
- Type: Boolean
- Required: true
- Remarks: Weather we should list price as
customization.vat_rate
- Type: Decimal as String
- Required: true
- Remarks: For 7% VAT, please inputs “0.07”
customization.quirks
- Type: JSON Object
- Required: false
- Remarks: Options for customize beyond standards
  - AKA: non-standard customizations
  - Should be left blank in generals but please contact us when you have a challenge you cannot overcome by standard means.
tags
- Type: Array<String>
- Required: false
- Remarks: The transaction can be tagged.
  - Similar to hashtags, transactions can be filtered by a tag.
  - Min Size: 0
  - Max Size: 2
  - Max String Length: 100

Exception Codes

SchemaViolation
Certificate::NotReady
Fund::InsufficientBalance
- Please top up your account
Trade::Initiated
- The trading transaction with the supplied transaction_id already existed.
Seller::NotConfigured
- Seller info not ready
Buyer::CheckDigitFailed
- A checksum mismatch has been detected for the tax or citizen ID.
Buyer::InvalidEmail
Buyer::InvalidPhoneNumber
Buyer::InvalidCountry
Buyer::InvalidPostcode
Buyer::InvalidChangwat
Buyer::InvalidAmphoe
Buyer::InvalidTambon
Buyer::AmphoeNotInChangwat
Buyer::TambonNotInAmphoe
LineItems::InvalidUnitCode
Theme::NotFound
Theme::UnsupportedDocumentType
- The theme selected does not support this document type (receipt)
Theme::UnsupportedLanguage
- The theme selected does not support the language you configured

Initiate with Receipt

Initiate a transaction and generate a receipt document corresponding to the transaction.

Example Payload

{
  "sub": "simple-transaction/initiate-with-receipt",
  "data": {
    "transaction_id": "TEST-RECEIPT-0001",
    "document": {
      "issued_at": "2023-11-30T17:00:00Z",
      "buyer_info": {
        "name": "เมธี วัชรีเมาคลีกระโทก",
        "identity": {
          "type": "NIDN",
          "national_id_number": "1234567851231"
        },
        "address": {
          "country_id": "TH",
          "post_code": "20180",
          "changwat_id": "20",
          "amphoe_id": "2009",
          "tambon_id": "200905",
          "street_name": "ถนนข่าวสาร",
          "soi": "ตรอกไดแอกอน",
          "building_number": "123/456"
        }
      },
      "line_items": [
        {
          "name": "ข้าวโพดปิ้ง",
          "unit_price": "15",
          "quantity": "5"
        }
      ]
    },
    "customization": {
      "theme": {
        "id": "retail-hatsu",
        "color": "#cd0czb"
      }
    }
  }
}

Example Response

{
  "data": {
    "success": true
  }
}

API Subject

simple-transaction/initiate-with-receipt

Parameters

We must admit we cannot document all rules mentioned in the official standard here unless we try to write another standard.

There is a lot of information surrounding the standard; we believe the best approach is to start with the example and then read the references as needed.
We perform reasonable validations on API inputs to ensure they can be represented in the format specified by the standard.

transaction_id
- Type: String
- Required: true
- Remarks: Client-generated transaction ID
  - Must be unique within the project.
  - Accepted Pattern: /^[-_\/a-zA-Z0-9]+$/
  - Max Length: 30
document
- Type: JSON Object
- Required: true
- Remarks: The data of the receipt to be generated
document.ref
- Type: String
- Required: false
- Remarks: Client-generated document reference
  - Must be unique within the transaction.
  - This will be used as an idempotency key.
  - You should not send the value unless the idempotency is required.
document.buyer_info
- Type: JSON Object
- Required: true
document.buyer_info.name
- Type: String
- Required: true
document.buyer_info.identity
- Type: JSON Object
- Required: true
- Remarks: Legal identity of the buyer
document.buyer_info.identity.type
- Type: Enum<String>
- Required: true
- Enums:
  - TXID: Tax ID, for juristic persons
  - NIDN: National ID Number, for Thai Citizen
  - CCPT: Passport Number
document.buyer_info.identity.tax_id
- Type: String
- Required: conditional
- Remarks:
  - Must be present when setting the value of document.buyer_info.identity.type to TXID.
  - Must pass the checksum test, preventing typos.
  - Accepted Pattern: /^\d{13}$/
document.buyer_info.identity.branch_id
- Type: String
- Required: false
- Remarks:
  - Accepted Pattern: /^\d{5}$/
document.buyer_info.identity.national_id_number
- Type: String
- Required: conditional
- Remarks:
  - Must be present when setting the value of document.buyer_info.identity.type to NIDN.
  - Must pass the checksum test, preventing typos.
  - Accepted Pattern: /^\d{13}$/
document.buyer_info.identity.passport_number
- Type: String
- Required: conditional
- Remarks:
  - Must be present when setting the value of document.buyer_info.identity.type to CCPT.
  - Accepted Pattern: /^\d{13}$/
document.buyer_info.identity.other_id
- Type: String
- Required: conditional
- Remarks:
  - Reserved for future uses.
document.buyer_info.email
- Type: String
- Required: false
- Remarks:
  - Accepted Format: e-mail address
document.buyer_info.phone_number
- Type: String
- Required: false
- Remarks:
  - Accepted Format: phone number
document.buyer_info.address
- Type: JSON Object
- Required: conditional
- Remarks:
  - Must be present per the official standard.
  - Please contact us if you want to do things that deviate from the standard. We probably support that, too.
document.buyer_info.address.country_id
- Type: String
- Required: true
- Remarks: ISO 3166-1 alpha-2 country code
document.buyer_info.address.post_code
- Type: String
- Required: true
- Remarks:
  - Accepted Pattern for address within Thailand: /^\d{5}$/
document.buyer_info.address.changwat_id
- Type: String
- Required: conditional
- Remarks: Thailand’s Changwat code
  - As specified by the Department of Provincial Administration, Ministry of Interior.
document.buyer_info.address.amphoe_id
- Type: String
- Required: conditional
- Remarks: Thailand’s Amphoe code
  - As specified by the Department of Provincial Administration, Ministry of Interior.
document.buyer_info.address.tambon_id
- Type: String
- Required: conditional
- Remarks: Thailand’s Tambon code
  - As specified by the Department of Provincial Administration, Ministry of Interior.
document.buyer_info.address.moo
- Type: String
- Required: false
- Remarks: The value will be displayed in the document with prefix
  - Example Values:
    - 10 will be displayed in the document as หมู่ 10 (language: th)
    - 11 will be displayed in the document as Moo 11 (language: en)
document.buyer_info.address.moo_barn
- Type: String
- Required: false
- Remarks: The value will be displayed in the document with prefix
  - Example Values:
    - จักจั่น will be displayed in the document as หมู่บ้านจักจั่น (language: th)
    - Raccoon will be displayed in the document as Moobarn Raccoon (language: en)
document.buyer_info.address.street_name
- Type: String
- Required: false
- Remarks: The value will be displayed verbatim in the document
  - Example Values:
    - Silk Road will be displayed in the document as Silk Road
    - Sesame Street will be displayed in the document as Sesame Street
document.buyer_info.address.soi
- Type: String
- Required: false
- Remarks: The value will be displayed verbatim in the document
  - Example Values:
    - Soi YikYik will be displayed in the document as Soi YikYik.
    - Trok Diagon will be displayed in the document as Trok Diagon.
document.buyer_info.address.building_name
- Type: String
- Required: false
- Remarks: The value will be displayed verbatim in the document.
document.buyer_info.address.building_number
- Type: String
- Required: conditional
- Remarks:
  - This value is required when the address is located in Thailand. It is required due to the Revenue Department validation composited with the rules specified by the official standard.
  - The value will be displayed in the document with a prefix.
  - Example Values:
    - 123/456 will be displayed in the document as เลขที่ 123/456 (language: th)
    - 78/9 will be displayed in the document as Building No. 78/9 (language: en)
document.buyer_info.address.floor
- Type: String
- Required: false
- Remarks:
  - This is a non-standard value.
  - The value will be displayed in the document with a prefix.
  - Example Values:
    - G will be displayed in the document as ชั้น G (language: th)
    - 10 will be displayed in the document as floor 10 (language: en)
document.buyer_info.address.room
- Type: String
- Required: false
- Remarks: The value will be displayed verbatim in the document.
  - ห้อง A/1 will be displayed in the document as ห้อง A/1.
  - Grand Suite will be displayed in the document as Grand Suite.
document.buyer_info.address.line1
- Type: String
- Required: conditional
document.buyer_info.address.line2
- Type: String
- Required: false
document.line_items
- Type: Array
- Required: true
- Remarks: List of items involved in the trading transactions
  - Min Size: 1
  - Max Size: 1,000
document.line_items[].product_id
- Type: String
- Required: false
document.line_items[].name
- Type: String
- Required: true
document.line_items[].description
- Type: String
- Required: false
document.line_items[].unit_price
- Type: Decimal as String
- Required: true
- Remarks: Do not sent float via JSON; it is a lossy format
document.line_items[].quantity
- Type: Decimal as String
- Required: true
- Remarks: Do not sent float via JSON; it is a lossy format
document.line_items[].unit_code
- Type: String
- Required: false
- Remarks: Unit code listed in UN/CEFACT Recommendation No. 20
document.issued_at
- Type: String
- Required: false
- Remarks: ISO-8601-formatted timestamp of the time when the trading transaction was settled
  - It can be in the past or present, but it wouldn’t make much sense to be in the future.
document.theme_parameters
- Type: JSON Object
- Required: conditional
- Remarks: Theme-specific parameters
  - You should not sent the parameters unless specified by the theme you are using.
customization
- Type: JSON Object
- Required: true
- Remarks: Customization for the trading transaction
  - It is required because, at least, you must pick a theme (skin) for the documents.
customization.theme
- Type: JSON Object
- Required: true
customization.theme.id
- Type: String
- Required: true
- Remarks: Theme ID”
customization.seller_branch_id
- Type: String
- Required: false
- Remarks: The branch id that sell products or services.
  - Accepted Pattern: /^\d{5}$/
customization.quirks
- Type: JSON Object
- Required: false
- Remarks: Options for customize beyond standards
  - AKA: non-standard customizations
  - Should be left blank in generals but please contact us when you have a challenge you cannot overcome by standard means.
tags
- Type: Array
- Required: false
- Remarks: The transaction can be tagged.
  - Similar to hashtags, transactions can be filtered by a tag
  - Min Size: 0
  - Max Size: 2

Exception Codes

SchemaViolation
Certificate::NotReady
Fund::InsufficientBalance
- Please top up your account
Trade::Initiated
- The trading transaction with the supplied transaction_id already existed.
Seller::NotConfigured
- Seller info not ready
Buyer::CheckDigitFailed
- A checksum mismatch has been detected for the tax or citizen ID.
Buyer::InvalidEmail
Buyer::InvalidPhoneNumber
Buyer::InvalidCountry
Buyer::InvalidPostcode
Buyer::InvalidChangwat
Buyer::InvalidAmphoe
Buyer::InvalidTambon
Buyer::AmphoeNotInChangwat
Buyer::TambonNotInAmphoe
LineItems::InvalidUnitCode
Theme::NotFound
Theme::UnsupportedDocumentType
- The theme selected does not support this document type (receipt)
Theme::UnsupportedLanguage
- The theme selected does not support the language you configured

Trading Transaction API

APIs for trading transactions in general.

Show

Retrieve transaction information using the transaction_id.

Example Payload

{
  "sub": "trading-transaction/show",
  "data": {
    "transaction_id": "TEST-TRANSACTION-0001",
    "include_documents": "latest"
  }
}

Example Response

{
  "data": {
    "id": "TEST-TRANSACTION-0001",
    "initiated_at": "2023-11-20T11:38:57Z",
    "trade_value": "90.0",
    "tags": [],
    "system_tags": [
      "NIDN:1234567851234"
    ],
    "storage_used": 120171,
    "service_url": "https://app.thai-document.slime.systems/projects/1234/trading-document-interface/TEST-TRANSACTION-0001/0123456789abcdef0123456789abcdef",
    "documents": [
      {
        "id": "TEST-TRANSACTION-0001D1",
        "sequence": 1,
        "ready": true,
        "xml_size": 12942,
        "pdf_size": 107229
      }
    ]
  }
}

API Subject

trading-transaction/show

Parameters

transaction_id
- Type: String
- Required: true
include_documents
- Type: Enum<String>
- Required: false
- Enums:
  - latest: Include the latest generated document of the transaction. The result can contains either one document or none.
  - readied: Include all documents ready to be viewed or downloaded.
  - all: Include all documents of the transaction. Some of them might not readied yet. (Still generating)
- Remarks:
  - Omit the parameter when you don’t want to include data about the documents for performance improvement.

Exception Codes

NotFound

Latest PDF

Get the latest PDF of the transaction.

Example Payload

{
  "sub": "trading-transaction/latest-pdf",
  "data": {
    "transaction_id": "MY-TRANSACTION-001",
    "deferrable": true
  }
}

Example Response

{
  "data": {
    "location": "https://temporary.example.com/thai-document/temporary-path-that-expires-in-1-minute"
  }
}

API Subject

trading-transaction/latest-pdf

Parameters

transaction_id
- Type: String
- Required: true
deferrable
- Type: Boolean
- Required: false
- Boolean:
  - true: If the document file is generating (not ready), return an intermediate waiting page.
    Once the document is ready, the user will be automatically redirected from the waiting page to the PDF file.
  - false: If the document file is not ready, return the DocumentPending exception.
- Default: false

Exception Codes

NotFound
DocumentPending

Set Tags

Assign tags to the transaction for filtering purposes.

Example Payload

{
  "sub": "trading-transaction/set-tags",
  "data": {
    "transaction_id": "TEST-TRANSACTION-0001",
    "tags": [
      "order_id:314159",
      "customer_id:265358"
    ]
  }
}

Example Response

{
  "data": {
    "success": true
  }
}

Alternatives

Tags can be set during transaction initiation, which is preferred over setting them afterward.
Ditching tags: manage everything your way and associate with us through transaction_id.

API Subject

trading-transaction/set-tags

Parameters

transaction_id
- Type: String
- Required: true
tags
- Type: Array<String>
- Required: true
- Remarks:
  - Minimum Array Length: 0
  - Maximum Array Length: 2
  - Maximum String Length: 100

Exception Codes

NotFound

List By Tag

Retrieve transactions based on a specified tag.
The tag used for filtering can be a user-supplied tag or a system tag.

Example Payload

{
  "sub": "trading-transaction/list-by-tag",
  "data": {
    "tag": "NIDN:1234567851234"
  }
}

Example Response

{
  "data": {
    "transactions": [
      {
        "id": "TEST-TRANSACTION-001",
        "initiated_at": "2023-11-20T11:35:36Z",
        "trade_value": "42.0",
        "tags": [],
        "system_tags": [
          "NIDN:1234567851234"
        ],
        "storage_used": 120099,
        "service_url": "https://app.thai-document.slime.systems/projects/1234/trading-document-interface/TEST-TRANSACTION-001/0123456789abcdef0123456789abcdef"
      },
      {
        "id": "TEST-TRANSACTION-002",
        "initiated_at": "2023-11-20T11:38:57Z",
        "trade_value": "60.0",
        "tags": [],
        "system_tags": [
          "NIDN:1234567851234"
        ],
        "storage_used": 120219,
        "service_url": "https://app.thai-document.slime.systems/projects/1234/trading-document-interface/TEST-TRANSACTION-002/0123456789abcdef0123456789abcdef"
      },
      {
        "id": "TEST-TRANSACTION-003",
        "initiated_at": "2023-11-20T11:41:30Z",
        "trade_value": "120.0",
        "tags": [],
        "system_tags": [
          "NIDN:1234567851234"
        ],
        "storage_used": 120068,
        "service_url": "https://app.thai-document.slime.systems/projects/1234/trading-document-interface/TEST-TRANSACTION-003/0123456789abcdef0123456789abcdef"
      }
    ]
  }
}

Limitation

Only one tag per filtering.
The response is limited to 1,000 transactions, which suffice for common use cases. Otherwise, revise your tagging strategy.

Alternatives

For complex or uncommon requirements, manage everything in your backend and associate with us through transaction_id, ignoring tags-related APIs.

API Subject

trading-transaction/list-by-tag

Parameters

tag
- Type: String
- Required: true
include_documents
- Type: Enum<String>
- Required: false
- Enums:
  - latest: Include the latest generated document of the transaction. The result can contains either one document or none.
  - readied: Include all documents ready to be viewed or downloaded.
  - all: Include all documents of the transaction. Some of them might not readied yet. (Still generating)
- Remarks:
  - Omit the parameter when you don’t want to include data about the documents for performance improvement.

Trading Document API

A trading transaction may consist of one or more documents.
Trading Document APIs facilitate direct interaction with these documents.

Show

Retrieve document information by specifying the document_id.

Example Payload

{
  "sub": "trading-document/show",
  "data": {
    "document_id": "TEST-TRANSACTION-001D1"
  }
}

Example Response

{
  "data": {
    "id": "TEST-TRANSACTION-001D1",
    "transaction_id": "TEST-TRANSACTION-001",
    "sequence": 1,
    "ready": true,
    "readied_at": "2023-11-21T09:26:02Z",
    "xml_size": 12942,
    "pdf_size": 107229
  }
}

API Subject

trading-document/show

Parameters

document_id
- Type: String
- Required: true

Exception Codes

NotFound

List by Transaction

Retrieve a list of documents in a specific transaction.

Example Payload

{
  "sub": "trading-document/list-by-transaction",
  "data": {
    "transaction_id": "TEST-TRANSACTION-001"
  }
}

Example Response

{
  "data": {
    "documents": [
      {
        "id": "TEST-TRANSACTION-001D1",
        "transaction_id": "TEST-TRANSACTION-001",
        "sequence": 1,
        "ready": true,
        "readied_at": "2023-11-21T09:26:02Z",
        "xml_size": 12942,
        "pdf_size": 107229
      }
    ]
  }
}

API Subject

trading-document/list-by-transaction

Parameters

transaction_id
- Type: String
- Required: true

Download PDF

Obtain an ephemeral document URL to download the PDF file.

Please ensure to initiate the download promptly, as the URL expires in one minute.
There is also an option to redirect to the target location instead of receiving a JSON response.

Example Payload

{
  "sub": "trading-document/download-pdf",
  "data": {
    "document_id": "TEST-TRANSACTION-001D1",
    "redirect": false
  }
}

Example Response

{
  "data": {
    "location": "https://temporary.example.com/thai-document/temporary-path-that-expires-in-1-minute"
  }
}

API Subject

trading-document/download-pdf

Parameters

document_id
- Type: String
- Required: true
redirect
- Type: Boolean
- Required: false
- Boolean:
  - true: The server will redirect to the document location instead of returning JSON data.
  - false: Returning the result as JSON, as shown in the example.
- Default: false

Exception Codes

NotFound
NotReady
- The document is not yet ready to be downloaded.

Download XML

Obtain an ephemeral document URL to download the XML file.

Please ensure to initiate the download promptly, as the URL expires in one minute.
There is also an option to redirect to the target location instead of receiving a JSON response.

Example Payload

{
  "sub": "trading-document/download-xml",
  "data": {
    "document_id": "TEST-TRANSACTION-001D1",
    "redirect": false
  }
}

Example Response

{
  "data": {
    "location": "https://temporary.example.com/thai-document/temporary-path-that-expires-in-1-minute"
  }
}

API Subject

trading-document/download-xml

Parameters

document_id
- Type: String
- Required: true
redirect
- Type: Boolean
- Required: false
- Boolean:
  - true: The server will redirect to the document location instead of returning JSON data.
  - false: Returning the result as JSON, as shown in the example.
- Default: false

Exception Codes

NotFound
NotReady
- The document is not yet ready to be downloaded.

Stream Generated

This API enables the streaming of document information upon generation.
To initiate the streaming process, polling for updates. The API offers fault tolerance through indefinite stream replayability.

Example Payload (start the stream)

{
  "sub": "trading-document/stream-generated",
  "data": {
    "from": "2024-08-20T18:10:42Z",
    "limit": 200
  }
}

Example Payload (continue the stream)

{
  "sub": "trading-document/stream-generated",
  "data": {
    "continuation_token": "eyJhbGciOiJkaXIi...<opaque token>...j1agfeeQ24ipLR-A",
    "limit": 200
  }
}

Example Response

{
  "data": {
    "documents": [
      {
        "id": "TEST-TRANSACTION-001D1",
        "transaction_id": "TEST-TRANSACTION-001",
        "sequence": 1,
        "ready": true,
        "readied_at": "2023-11-21T09:26:02Z",
        "xml_size": 12942,
        "pdf_size": 107229
      }
    ],
    "continuation_token": "eyJhbGciOiJkaXIi...<opaque token>...39Jh0eEkWaDj_4hA"
  }
}

Example Use Cases

Sending the generated PDF to your customer via email.
Sending push notifications to your app to alert your customer when the document is ready for download.

API Subject

trading-document/stream-generated

Parameters

from
- Type: String
- Required: conditional
  - Either from or continuation_token must be present.
- Remarks: ISO-8601-formatted timestamp of the time you want to start streaming from.
continuation_token
- Type: String
- Required: conditional
  - Either from or continuation_token must be present.
- Remarks: The token returned from the previous call.
  - It is a streaming cursor to continue for the next items.
limit
- Type: Integer
- Required: false
- Remarks: The limit of returned items.
  - The value can be in between 1 and 1,000 inclusively.
- Default: 100

Exception Codes

AmbiguousInstruction
- Occurs when you set both from and continuation_token in the same call.
InvalidContinuationToken

Themes

`retail-hatsu`

Example Payload for Abbreviated Tax Invoices

{
  "sub": "simple-transaction/initiate-with-abbreviated-tax-invoice",
  "data": {
    "...":  "...<ignored>...",
    "customization": {
      "theme": {
        "id": "retail-hatsu",
        "color": "#cd0c2b"
      },
      "...":  "...<ignored>..."
    }
  }
}

Supported Features

Tax Invoice
Abbreviated Tax Invoice
Receipt
Bearer Tax Invoice
Hybrid Tax Invoice

Supported Languages

eng
tha

Parameters

id
- Type: String
- Required: true
- Value: retail-hatsu
color
- Type: String
- Required: true
- Remarks: The theme color of the documents; choose one that matches your brand.
  - Accepted Pattern: /^#[0-9a-fA-F]{6}$/
  - Example: #cd0c2b

Guides
Introduction
Hello World
Base Integration
Bearer Tax Invoice
- Integration
Hybrid Tax Invoice
- Flow
- APIs
- Integration
What if?
- I am integrating the API with a non-web application.
- I want to use unstructured address format for tax invoices.
References
API Reference
- Data Format
- Authentication
Test API
- Hello
Simple Transaction API
Trading Transaction API
- Show
- Latest PDF
- Set Tags
- List By Tag
Trading Document API
Themes
- retail-hatsu

NAV

Introduction

Hello World

Running the code example

Setting Up the API Credentials

Understanding API Authentication

High-level Overview

Communication Medium

Payload Encoding

Implement it your way

Base Integration

Flow

APIs

Document Delivery

User-facing interface

Handling the PDF Request

Bearer Tax Invoice

Integration

Hybrid Tax Invoice

Flow

APIs

Integration

What if?

I am integrating the API with a non-web application.

I want to use unstructured address format for tax invoices.

API Reference

Data Format

Request

Success Response

Exception Response

Authentication

Exception Codes

Test API

Hello

API Subject

Parameters

Simple Transaction API

Initiate with Abbreviated Tax Invoice

API Subject

Parameters

Exception Codes

Initiate with Tax Invoice Stub

API Subject

Parameters

Exception Codes

Initiate with Tax Invoice

See Also

API Subject

Parameters

Exception Codes

Initiate with Receipt

API Subject

Parameters

Exception Codes

Trading Transaction API

Show

API Subject

Parameters

Exception Codes

Latest PDF

See Also

API Subject

Parameters

Exception Codes

Set Tags

Alternatives

See Also

API Subject

Parameters

Exception Codes

List By Tag

Limitation

Alternatives

See Also

API Subject

Parameters

Trading Document API

Show

API Subject

Parameters

Exception Codes

`retail-hatsu`