e-Tax Invoice & e-Receipt API Gateway

คู่มือการเชื่อมต่อ REST API

เชื่อมต่อระบบธุรกิจของคุณ (ERP, POS, E-commerce, Billing Software) เข้ากับเกตเวย์ของ e-TAXAPP เพื่อออกใบกำกับภาษีอิเล็กทรอนิกส์และใบรับเงินอิเล็กทรอนิกส์ พร้อมประทับรับรองเวลา (Time Stamp) และดาวน์โหลดเอกสาร PDF/XML อัตโนมัติแบบ Real-time

// ข้อมูลสรุป Gateway
Base URL: https://th.e-taxapp.com
Data Format: JSON (UTF-8)
Security: API Key + Secret
Standard: ETDA / RD Compliant

1. ภาพรวมระบบ (System Overview)

e-TAXAPP REST API ถูกออกแบบมาเพื่ออำนวยความสะดวกแก่นักพัฒนาซอฟต์แวร์ในการเชื่อมต่อระบบหลังบ้าน (Backend Server) เช่น ระบบ ERP (SAP, Express, Odoo), ระบบ POS หน้าร้าน, ระบบ E-commerce (WooCommerce, Magento, Shopify) หรือระบบ Billing ของธุรกิจ เข้ากับระบบออกใบกำกับภาษีอิเล็กทรอนิกส์แบบอัตโนมัติ 100%

Real-time Issue

ออกเอกสารใบกำกับภาษีทันทีที่ลูกค้ายืนยันการสั่งซื้อหรือชำระเงิน

Time Stamp อัตโนมัติ

ประทับรับรองเวลาตามมาตรฐาน ETDA และกรมสรรพากรทันที

PDF/A-3 & XML

รับ URL ลิงก์ดาวน์โหลดไฟล์ PDF และโครงสร้าง XML ไปส่งต่อให้ลูกค้าได้ทันที

2. การยืนยันสิทธิ์เข้าใช้งาน (Authentication)

ระบบออกใบกำกับภาษีอิเล็กทรอนิกส์ใช้การยืนยันสิทธิ์ความปลอดภัยผ่าน HTTP Header โดยคุณต้องแนบคู่รหัสที่ได้รับจากเมนูตั้งค่าระบบหลังบ้าน (REST API Keys) ในทุกคำขอ (Request) ที่ส่งเข้ามา:

HTTP Header Key คำอธิบาย ตัวอย่างค่า
Content-Type รูปแบบเนื้อหาข้อมูล ต้องกำหนดเป็น JSON เสมอ application/json
X-API-KEY รหัสสาธารณะ API Key ของคุณที่ผูกกับบัญชีผู้ใช้ etax_a8cd6edec60c...
X-SECRET-KEY รหัสความลับคู่กับ API Key (แนะนำอย่างยิ่งสำหรับการใช้งานจริง) sec_90b4cc2f166b...
ข้อควรระวังด้านความปลอดภัยสูงสุด:
ห้ามเปิดเผย Secret Key หรือฝังค่านี้ไว้ในโค้ดฝั่งหน้าบ้าน (Client-side / Frontend / Mobile App) โดยเด็ดขาด การเรียกใช้งาน API จะต้องทำผ่านโค้ดฝั่งเซิร์ฟเวอร์หลังบ้าน (Backend Server) เท่านั้น

3. สร้างเอกสาร e-Tax (Create Document)

ใช้สำหรับส่งข้อมูลใบสั่งซื้อ/ยอดขายหลังรับชำระเงินเข้ามาบันทึกในระบบ e-TAXAPP เพื่อสร้างเอกสารทันทีตามประเภทที่กำหนด

POST /api/v1/etax/create

พารามิเตอร์ใน Request Body (JSON)

ฟิลด์ข้อมูล ประเภท จำเป็น คำอธิบาย
reference_no String จำเป็น เลขที่อ้างอิงบิลจากระบบของคุณ (ต้องไม่ซ้ำกัน เช่น INV-2026-0001)
doc_type String จำเป็น ประเภทเอกสารที่ต้องการสร้าง:
  • tax_receipt: ใบกำกับภาษี/ใบเสร็จรับเงิน
  • tax_invoice: ใบกำกับภาษี
  • receipt: ใบเสร็จรับเงิน
  • abb_receipt: ใบกำกับภาษีอย่างย่อ
  • credit_note: ใบลดหนี้
  • debit_note: ใบเพิ่มหนี้
sales_date String (Date) จำเป็น วันที่ทำรายการ รูปแบบ YYYY-MM-DD
vat_mode String ทางเลือก การคำนวณภาษี: Inclusive (รวมภาษี) หรือ Exclusive (แยกภาษี)
customer Object จำเป็น ข้อมูลลูกค้าผู้รับเอกสาร:
  • tax_number: เลขประจำตัวผู้เสียภาษี 13 หลัก
  • name: ชื่อบริษัทหรือชื่อบุคคล
  • address: ที่อยู่เต็ม
  • email: อีเมลรับไฟล์ e-Tax
  • branch_code: รหัสสาขา (เช่น 00000 สำหรับสำนักงานใหญ่)
items Array[Object] จำเป็น รายการสินค้า (ชื่อสินค้า, จำนวน, ราคาต่อหน่วย, % ภาษี)
Request Payload (JSON)
{
  "reference_no": "ORDER-2026-004-NEW",
  "doc_type": "tax_receipt",
  "sales_date": "2026-08-07",
  "vat_mode": "Inclusive",
  "payment_status": "Paid",
  "customer": {
    "tax_number": "0105558123456",
    "name": "บริษัท ตัวอย่าง เทคโนโลยี จำกัด",
    "address": "123/45 ถนนสุขุมวิท แขวงคลองเตย เขตคลองเตย กรุงเทพมหานคร 10110",
    "email": "accounting@example.com",
    "phone": "021234567",
    "branch_code": "00000",
    "headquarter": 1
  },
  "items": [
    {
      "name": "บริการระบบ e-Tax Invoice รายปี",
      "qty": 1,
      "price": 3990.00,
      "vat_percent": 7,
      "discount": 0
    }
  ],
  "discount_all": 0,
  "shipping_fee": 0
}
Response สำเร็จ (201 Created)
{
  "status": true,
  "message": "สร้างเอกสาร e-Tax เรียบร้อยแล้ว",
  "data": {
    "sales_id": 142,
    "sales_code": "SL0142",
    "reference_no": "ORDER-2026-004-NEW",
    "tax_invoice_code": "TAX-2608-0005",
    "pdf_url": "https://th.e-taxapp.com/pdf_facturx/sales/142",
    "xml_url": "https://th.e-taxapp.com/xml_download/sales/142",
    "created_at": "2026-08-07 14:30:15"
  }
}

4. ตรวจสอบสถานะและลิงก์ PDF (Check Status)

ใช้สำหรับสืบค้นสถานะบิล ดึงเลขที่ใบกำกับภาษี และรับ URL สำหรับดาวน์โหลดเอกสาร PDF (มีตราประทับรับรองเวลา) หรือ XML

GET /api/v1/etax/status/{ID_OR_CODE}

พารามิเตอร์ URL: {ID_OR_CODE} สามารถใช้ค่าใดค่าหนึ่งต่อไปนี้:

  • sales_id: เช่น 142
  • sales_code: รหัสบิลในระบบ e-Tax เช่น SL0142
  • reference_no: เลขที่อ้างอิงจากระบบเดิมของคุณ เช่น ORDER-2026-004-NEW
Response สำเร็จ (200 OK)
{
  "status": true,
  "sales_id": 142,
  "sales_code": "SL0142",
  "reference_no": "ORDER-2026-004-NEW",
  "sales_date": "2026-08-07",
  "grand_total": 3990.00,
  "vat_amount": 261.03,
  "is_tax_invoice_requested": 1,
  "tax_invoice": {
    "invoice_code": "TAX-2608-0005",
    "invoice_type": "Tax Invoice/Receipt",
    "created_date": "2026-08-07"
  },
  "pdf_url": "https://th.e-taxapp.com/pdf_facturx/sales/142",
  "xml_url": "https://th.e-taxapp.com/xml_download/sales/142"
}

5. ตัวอย่างโค้ดเชื่อมต่อ (Code Examples)

เลือกภาษาการเขียนโปรแกรมที่คุณใช้งานเพื่อดูตัวอย่างคำขอสร้างเอกสาร e-Tax แบบพร้อมรันได้ทันที:

example_create_etax.php
<?php
$apiUrl    = "https://th.e-taxapp.com/api/v1/etax/create";
$apiKey    = "etax_a8cd6edec60c8e5555b7676675d7bae8";
$secretKey = "sec_90b4cc2f166b295546e3375cff57f8392...";

$payload = [
    "reference_no"   => "INV-2026-" . time(),
    "doc_type"       => "tax_receipt",
    "sales_date"     => date('Y-m-d'),
    "vat_mode"       => "Inclusive",
    "payment_status" => "Paid",
    "customer"       => [
        "tax_number"  => "0105558123456",
        "name"        => "บริษัท ตัวอย่างจำกัด",
        "address"     => "กรุงเทพมหานคร 10110",
        "email"       => "accounting@example.com",
        "branch_code" => "00000"
    ],
    "items" => [
        [
            "name"        => "ค่าสินค้าทดสอบ",
            "qty"         => 2,
            "price"       => 500.00,
            "vat_percent" => 7
        ]
    ]
];

$ch = curl_init($apiUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "X-API-KEY: " . $apiKey,
    "X-SECRET-KEY: " . $secretKey
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);
?>
example_create_etax.js
const axios = require('axios');

const config = {
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'etax_a8cd6edec60c8e5555b7676675d7bae8',
    'X-SECRET-KEY': 'sec_90b4cc2f166b295546e3375cff57f8392...'
  }
};

const payload = {
  reference_no: `INV-${Date.now()}`,
  doc_type: "tax_receipt",
  sales_date: new Date().toISOString().split('T')[0],
  customer: {
    tax_number: "0105558123456",
    name: "บริษัท ตัวอย่างจำกัด",
    address: "กรุงเทพมหานคร 10110",
    email: "accounting@example.com",
    branch_code: "00000"
  },
  items: [
    {
      name: "ค่าบริการระบบ SaaS รายเดือน",
      qty: 1,
      price: 1000.00,
      vat_percent: 7
    }
  ]
};

axios.post('https://th.e-taxapp.com/api/v1/etax/create', payload, config)
  .then(response => {
    console.log('e-Tax Created Successfully:', response.data);
    console.log('PDF URL:', response.data.data.pdf_url);
  })
  .catch(error => {
    console.error('API Error:', error.response ? error.response.data : error.message);
  });
example_create_etax.py
import requests
import json
from datetime import date

url = "https://th.e-taxapp.com/api/v1/etax/create"
headers = {
    "Content-Type": "application/json",
    "X-API-KEY": "etax_a8cd6edec60c8e5555b7676675d7bae8",
    "X-SECRET-KEY": "sec_90b4cc2f166b295546e3375cff57f8392..."
}

payload = {
    "reference_no": "INV-2026-PY001",
    "doc_type": "tax_receipt",
    "sales_date": str(date.today()),
    "customer": {
        "tax_number": "0105558123456",
        "name": "บริษัท ตัวอย่างจำกัด",
        "address": "กรุงเทพมหานคร 10110",
        "email": "accounting@example.com",
        "branch_code": "00000"
    },
    "items": [
        {
            "name": "อุปกรณ์ไอทีไร้สาย",
            "qty": 5,
            "price": 2000.00,
            "vat_percent": 7
        }
    ]
}

response = requests.post(url, data=json.dumps(payload), headers=headers)
print("Status Code:", response.status_code)
print("Result JSON:", response.json())
Terminal / Bash cURL
curl -X POST "https://th.e-taxapp.com/api/v1/etax/create" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: etax_a8cd6edec60c8e5555b7676675d7bae8" \
  -H "X-SECRET-KEY: sec_90b4cc2f166b295546e3375cff57f8392..." \
  -d '{
    "reference_no": "INV-2026-CURL001",
    "doc_type": "tax_receipt",
    "sales_date": "2026-08-07",
    "customer": {
      "tax_number": "0105558123456",
      "name": "บริษัท ตัวอย่างจำกัด",
      "address": "กรุงเทพมหานคร 10110",
      "email": "accounting@example.com"
    },
    "items": [
      {
        "name": "สินค้าตัวอย่าง",
        "qty": 1,
        "price": 1000.00,
        "vat_percent": 7
      }
    ]
  }'

6. ข้อแนะนำสำหรับนักพัฒนา (Best Practices)

เพื่อความเสถียรและความปลอดภัยสูงสุดในการทำงานระดับ Production ขอแนะนำแนวทางปฏิบัติดังนี้:

1. ระบบประมวลผลแบบคิว (Background Job Queue)

แนะนำให้จัดเก็บคำสั่งซื้อลงฐานข้อมูลฝั่งคุณก่อน แล้วให้ Background Worker ทยอยดึงไปเรียก API ของ e-Tax (Asynchronous) เพื่อป้องกันไม่ให้หน้าจอชำระเงินของลูกค้ารอคอยนาน

2. การบันทึกสถานะกลับ (Data Sync & Logging)

เมื่อ API ตอบกลับสถานะสำเร็จ ให้บันทึก sales_id, tax_invoice_code และ pdf_url เก็บไว้ในฐานข้อมูลของคุณ เพื่อนำไปแสดงปุ่มพิมพ์เอกสารให้ลูกค้าดาวน์โหลดซ้ำได้ตลอดเวลา

3. กลไกส่งซ้ำเมื่อเกิดข้อผิดพลาด (Retry Logic)

หากเกิด Network Timeout หรือ Server Error (5xx) ให้ตั้งค่ากลไก Retry แบบเว้นช่วงเวลา (Exponential Backoff) โดยส่งรหัส reference_no เดิมเสมอ ระบบ e-Tax จะป้องกันการออกบิลซ้ำให้อัตโนมัติ

4. การตรวจสอบความถูกต้องก่อนส่ง (Pre-validation)

ควรตรวจสอบรูปแบบข้อมูลเบื้องต้น เช่น ตรวจสอบเลขผู้เสียภาษี 13 หลัก, ตรวจสอบรูปแบบอีเมล (Email Format) และตรวจราคาเป็นจำนวนบวก ก่อนส่งคำขอเข้ามา เพื่อลดข้อผิดพลาด 422 Unprocessable Entity

7. รหัสสถานะการตอบกลับ (HTTP Status Codes)

HTTP Code สถานะ ความหมาย
200 OK Success เรียกดูข้อมูลหรือตรวจสอบสถานะสำเร็จ
201 Created Document Created สร้างเอกสาร e-Tax และบันทึกข้อมูลเรียบร้อย
400 Bad Request Invalid Request ข้อมูล JSON ผิดรูปแบบหรือไม่ตรงตามโครงสร้าง
401 Unauthorized Invalid API Key X-API-KEY หรือ X-SECRET-KEY ไม่ถูกต้องหรือถูกระงับสิทธิ์
404 Not Found Document Not Found ไม่พบข้อมูลเลขที่เอกสารหรือบิลที่ระบุในระบบ
422 Unprocessable Validation Error ข้อมูลไม่ผ่านการตรวจสอบ (เช่น เลขผู้เสียภาษีไม่ครบ 13 หลัก)
500 Server Error Internal Error ระบบประมวลผลเซิร์ฟเวอร์ขัดข้อง กรุณาลองใหม่อีกครั้ง