Tích hợp ThueAPI.VN với PHP / Laravel để tra cứu lịch sử giao dịch ngân hàng

PHP là ngôn ngữ backend phổ biến nhất tại Việt Nam, đặc biệt với framework Laravel. Bài viết này hướng dẫn tích hợp ThueAPI.VN vào dự án PHP/Laravel của bạn.

Hướng dẫn tạo và lấy thông tin API: https://thueapi.vn/blog/huong-dan-su-dung-api-tra-cuu-giao-dich-ngan-hang-thueapivn

1. Gọi API bằng PHP thuần (cURL)

<?php
// Tra cứu danh sách giao dịch
$apiKey = 'YOUR_API_KEY';
$url = 'https://thueapi.vn/api/v1/transactions?page=1&per_page=10';

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
        'Accept: application/json',
    ],
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 200) {
    $data = json_decode($response, true);
    foreach ($data['transactions'] as $tx) {
        echo $tx['bank'] . ' - ' . number_format($tx['amount']) . 'đ - ' . $tx['description'] . "\n";
    }
} else {
    echo "Lỗi: HTTP " . $httpCode;
}

2. Tích hợp Laravel - Service Class

<?php
// app/Services/ThueApiService.php
namespace App\Services;

use Illuminate\Support\Facades\Http;

class ThueApiService
{
    private string $baseUrl = 'https://thueapi.vn/api/v1';
    private string $apiKey;

    public function __construct()
    {
        $this->apiKey = config('services.thueapi.key');
    }

    public function getTransactions(array $params = []): array
    {
        $response = Http::withToken($this->apiKey)
            ->get($this->baseUrl . '/transactions', $params);

        return $response->json();
    }

    public function getBankAccounts(): array
    {
        $response = Http::withToken($this->apiKey)
            ->get($this->baseUrl . '/bank-accounts');

        return $response->json();
    }
}

3. Nhận Webhook trong Laravel

<?php
// routes/api.php
Route::post('/webhook/thueapi', [WebhookController::class, 'handle']);

// app/Http/Controllers/WebhookController.php
namespace App\Http\Controllers;

use Illuminate\Http\Request;

class WebhookController extends Controller
{
    public function handle(Request $request)
    {
        // Xác thực webhook
        $secret = config('services.thueapi.webhook_secret');
        $token = $request->bearerToken();

        if ($token !== $secret) {
            return response()->json(['success' => false], 401);
        }

        // Xử lý giao dịch
        $transactions = $request->input('transactions', []);

        foreach ($transactions as $tx) {
            // Lưu vào database
            \App\Models\Transaction::create([
                'transaction_id' => $tx['transaction_id'],
                'bank'           => $tx['bank'],
                'amount'         => $tx['amount'],
                'description'    => $tx['description'],
                'type'           => $tx['type'],
                'received_at'    => $tx['transaction_date'],
            ]);

            // Xử lý business logic (xác nhận đơn hàng, nạp tiền...)
            $this->processTransaction($tx);
        }

        return response()->json(['success' => true]);
    }

    private function processTransaction(array $tx): void
    {
        // Ví dụ: Xác nhận đơn hàng dựa trên nội dung chuyển khoản
        if (preg_match('/ORDER(\d+)/', $tx['description'], $matches)) {
            $orderId = $matches[1];
            // Cập nhật trạng thái đơn hàng
        }
    }
}

4. Cấu hình Laravel

// config/services.php
'thueapi' => [
    'key' => env('THUEAPI_API_KEY'),
    'webhook_secret' => env('THUEAPI_WEBHOOK_SECRET'),
],

// .env
THUEAPI_API_KEY=your_api_key_here
THUEAPI_WEBHOOK_SECRET=your_webhook_secret

Lưu ý bảo mật

  • Luôn lưu API key trong .env, không hardcode
  • Xác thực webhook bằng secret key trước khi xử lý
  • Sử dụng HTTPS cho webhook endpoint
  • Validate dữ liệu đầu vào trước khi lưu database