---
title: Go Server SDK
---

# Go Server SDK

SDK phía máy chủ chính thức cho Go — `github.com/Captcha-La/captchala-go`.

Ba việc SDK xử lý giúp bạn:

1. **Xác minh** — kiểm tra pass token `pt_` từ SDK trình duyệt.
2. **Phát hành** — tạo một server token `sct_` dùng một lần để gắn thử thách sắp tới với một hành động / IP / UID cụ thể.
3. **Kiểm duyệt** — kiểm duyệt nội dung đa phương thức (văn bản + hình ảnh) qua cùng pipeline tương thích OpenAI mà bảng điều khiển sử dụng.

## Cài đặt

```bash
go get github.com/Captcha-La/captchala-go
```

Chỉ dùng thư viện chuẩn. Không có phụ thuộc bên ngoài.

## Xác minh (token `pt_`)

Hãy truyền IP của người dùng cuối (lấy từ `CF-Connecting-IP` / `X-Forwarded-For`,
dự phòng bằng `RemoteAddr`). Tùy chọn, nhưng **nên truyền** — nó được dùng cho
các kiểm tra rủi ro bổ sung.

```go
import captchala "github.com/Captcha-La/captchala-go"

client := captchala.NewClient(appKey, appSecret)

func handler(w http.ResponseWriter, r *http.Request) {
    token := r.FormValue("captcha_token")

    result, err := client.ValidateWithClientIP(token, false, clientIP(r))
    if err != nil || !result.Valid {
        http.Error(w, result.Error, http.StatusBadRequest)
        return
    }
    // Verification passed; proceed with the request.
    // result.CaptchaArgs has Platform / UserIP / Referer / Pkg / SolvedAt / RiskScore
}

// Real end-user IP behind a CDN / proxy
func clientIP(r *http.Request) string {
    if ip := r.Header.Get("CF-Connecting-IP"); ip != "" {
        return ip
    }
    if xff := r.Header.Get("X-Forwarded-For"); xff != "" {
        return strings.TrimSpace(strings.Split(xff, ",")[0])
    }
    host, _, _ := net.SplitHostPort(r.RemoteAddr)
    return host
}
```

Không có sẵn IP? Dùng `client.Validate(token)` — việc xác minh vẫn hoạt động,
chỉ là thiếu tín hiệu rủi ro bổ sung dựa trên IP.

Nếu `server_token` ban đầu được phát hành với `bind_uid`, hãy so sánh:

```go
if result.UID != expectedUserID {
    http.Error(w, "user mismatch", http.StatusBadRequest)
    return
}
```

Ngữ cảnh tại thời điểm giải thử thách cũng được trả về trong
`result.CaptchaArgs` để bạn tham khảo:

```go
ip := result.CaptchaArgs.UserIP   // visitor IP recorded at solve time
```

## Phát hành server token

Khuyến nghị cho các luồng quan trọng (đăng nhập, đăng ký, thanh toán): backend phát hành một
token `sct_` dùng một lần, trao cho trình duyệt, trình duyệt sử dụng nó làm prop
`serverToken`. Dùng một lần, giới hạn theo hành động, có thể tùy chọn gắn IP/UID.

```go
issue, err := client.IssueServerTokenWithOptions("login", captchala.IssueOptions{
    BindingIP: userIP,    // backend từ chối token nếu IP khác sử dụng
    TTL:       300,       // giây
    MaxUses:   5,         // ngân sách thử lại của SDK
    BindUID:   userID,    // ghép với ValidateResult.UID khi xác minh
})
if err != nil || !issue.OK {
    http.Error(w, issue.Error, http.StatusBadRequest)
    return
}
// trao issue.Token cho trình duyệt
```

Cách rút gọn chỉ dùng giá trị mặc định:

```go
issue, err := client.IssueServerToken("login")
```

## Kiểm duyệt nội dung

Đa phương thức — nhận một slice `ModerationItem` (text và/hoặc image_url ở
định dạng tương thích OpenAI):

```go
result, err := client.ModerationCheck([]captchala.ModerationItem{
    captchala.TextItem(userComment),
    captchala.ImageURLItem(uploadedImageURL),
}, userID)

if err != nil || !result.OK {
    http.Error(w, result.Error, http.StatusBadRequest)
    return
}

if result.Flagged {
    if result.HasCategory("violence", "csam") {
        // chặn cứng
    }
}
```

Cách rút gọn cho văn bản thuần:

```go
result, err := client.ModerationText("user comment here", userID)
```

Danh mục do model định nghĩa; hãy lặp qua `result.Categories` một cách phòng vệ thay vì
gán cứng một tập cố định.

## Kiểu dữ liệu

| Kiểu | Trường |
|---|---|
| `ValidateResult` | `Valid`, `Error`, `UID`, `ChallengeID`, `Action`, `Offline`, `ClientOnly`, `Warning`, `CaptchaArgs` |
| `CaptchaArgs` (tham khảo) | `Platform`, `UserIP`, `Referer`, `Pkg`, `SolvedAt`, `RiskScore` |
| `IssueResult` | `OK`, `Token`, `ExpiresIn`, `IssuedAt`, `Error`, `Message` |
| `IssueOptions` | `BindingIP`, `TTL`, `MaxUses`, `BindUID` |
| `ModerationItem` | `Type`, `Text`, `ImageURL` (dùng helper `TextItem()` / `ImageURLItem()`) |
| `ModerationResult` | `OK`, `Flagged`, `Categories`, `ContentType`, `Raw`, `Error`, `Message`; phương thức `HasCategory(...names)` |

## Liên kết

- [pkg.go.dev](https://pkg.go.dev/github.com/Captcha-La/captchala-go) · [GitHub](https://github.com/Captcha-La/captchala-go)
- [Tổng quan Web SDK](/vi/web-sdk) · [Tài liệu API](/vi/api-reference)