Receipts

Receipts are POS-style documents. A SHORT receipt can be issued immediately at point-of-sale. If the buyer provides tax identification, it can later be converted to a FULL receipt (which generates a full tax invoice).

Receipt Types and Statuses

Type	Statuses	Description
`SHORT`	`SHORT_ACTIVE`, `SHORT_CANCELLED`	Issued at POS without buyer tax ID
`FULL`	`FULL_PENDING` → `FULL_SUBMITTING` → `FULL_ACKNOWLEDGED` / `FULL_FAILED`	Full tax receipt with buyer info

POST /api/v1/receipts

Create a new receipt (SHORT or FULL).

POST /api/v1/receipts

Headers

Header	Required	Description
`X-API-Key`	✓	Your API key
`X-Idempotency-Key`	✓	Unique key per request
`Content-Type`	✓	`application/json`

Request Body

Field	Type	Required	Notes
`sourceId`	string	✓	Your source code
`receiptType`	enum	✓	`SHORT` or `FULL`
`receiptDate`	string	✓	`YYYY-MM-DD`
`receiptNo`	string	—	Auto-generated if omitted
`seller`	object	✓	See Seller fields
`buyer`	object	FULL only	Required when `receiptType=FULL`
`amountExVat`	number	✓	Amount excluding VAT
`vatAmount`	number	✓	VAT amount
`totalAmount`	number	✓	Must equal `amountExVat + vatAmount + shippingCost - discountAmount`
`discountAmount`	number	—	Default: `0`
`shippingCost`	number	—	Default: `0`
`items`	array	—	Line items (name, quantity, unitPrice, lineTotal)
`paymentReceived`	number	—	Amount tendered
`changeAmount`	number	—	Must equal `paymentReceived - totalAmount`
`metadata`	object	—	Free-form key-value

Seller fields: taxId (13-digit), name, branchCode (5-digit), address, phone?, email?

Buyer fields (FULL): taxId (13-digit), name, branchCode (5-digit), address

Example — SHORT Receipt

curl -X POST https://dev-etax.siamprop.app/api/v1/receipts \
  -H "X-API-Key: sk_etax_your_key" \
  -H "X-Idempotency-Key: idem-rcpt-2026-001" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceId": "TESTSRC",
    "receiptType": "SHORT",
    "receiptDate": "2026-03-09",
    "seller": {
      "taxId": "0101234567890",
      "name": "ACME Co., Ltd.",
      "branchCode": "00000",
      "address": "99 Sukhumvit Rd, Bangkok 10110"
    },
    "amountExVat": 1000,
    "vatAmount": 70,
    "totalAmount": 1070,
    "items": [
      { "name": "Product A", "quantity": 1, "unitPrice": 1000, "lineTotal": 1000 }
    ]
  }'

Response — 201 Created

{
  "id": "01KK9PJC7M9QZJF4X5R2Y59MSM",
  "receiptType": "SHORT",
  "receiptNo": "RCPT-20260309-0001",
  "status": "SHORT_ACTIVE"
}

GET /api/v1/receipts/:id

GET /api/v1/receipts/{receiptId}?sourceId=TESTSRC

Query Parameters

Parameter	Required	Description
`sourceId`	✓	Your source code

Example

curl "https://dev-etax.siamprop.app/api/v1/receipts/01KK9PJC7M9QZJF4X5R2Y59MSM?sourceId=TESTSRC" \
  -H "X-API-Key: sk_etax_your_key"

GET /api/v1/receipts

List receipts.

GET /api/v1/receipts?sourceId=TESTSRC&page=1&limit=20

Parameter	Required	Default	Description
`sourceId`	✓	—	Your source code
`receiptType`	—	all	`SHORT` or `FULL`
`status`	—	all	Filter by status
`receiptNo`	—	—	Filter by receipt number
`fromDate`	—	—	`YYYY-MM-DD`
`toDate`	—	—	`YYYY-MM-DD`
`page`	—	`1`	—
`limit`	—	`20`	Max 100

POST /api/v1/receipts/:id/convert-to-full

Convert a SHORT receipt to a FULL receipt by providing buyer tax information.

POST /api/v1/receipts/{receiptId}/convert-to-full

Request Body

Field	Type	Required	Notes
`sourceId`	string	✓	Your source code
`buyer`	object	—	Buyer tax info (`taxId`, `name`, `branchCode`, `address`). `buyer.taxId` is required to generate a full tax invoice.
`fullReceiptDate`	string	—	Override receipt date (`YYYY-MM-DD`)

Example

curl -X POST "https://dev-etax.siamprop.app/api/v1/receipts/01KK9PJC7M9QZJF4X5R2Y59MSM/convert-to-full" \
  -H "X-API-Key: sk_etax_your_key" \
  -H "X-Idempotency-Key: idem-conv-2026-001" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceId": "TESTSRC",
    "fullReceiptDate": "2026-03-09",
    "buyer": {
      "taxId": "0109876543210",
      "name": "Beta Corp Co., Ltd.",
      "branchCode": "00001",
      "address": "55 Silom Rd, Bangkok 10500"
    }
  }'

Error Cases

errorCode	HTTP	Cause
`RECEIPT_NOT_SHORT`	422	Receipt is not in `SHORT_ACTIVE` status
`RECEIPT_ALREADY_CONVERTED`	422	Already converted to full
`RECEIPT_BUYER_TAX_INFO_REQUIRED`	422	Buyer tax ID required
`DUPLICATE_RECEIPT`	409	Idempotency key conflict