---
title: "Bắt đầu"
url: "https://oapi-poc.hdbank.work/bat-dau"
image: "https://oapi-poc.hdbank.work/_og/d/c_Ocean.takumi,title_~QuG6r3QgxJHhuqd1,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMwMDAwRjUifX19,p_Ii9iYXQtZGF1Ig,s_PNWTpN0-XMQ_KLCl.png"
---

Sovico Open API · Developer Portal

# Bắt đầu với Sovico Open API

Đăng ký, lấy thông tin xác thực và gọi API đầu tiên trong môi trường sandbox. Dữ liệu 100% giả lập, không chạm hệ thống thật.

[Đăng ký tài khoản](https://oapi-poc.hdbank.work/register)[Xem danh mục API](https://oapi-poc.hdbank.work/apis)

## [Bắt đầu chỉ trong 3 bước](#bắt-đầu-chỉ-trong-3-bước)

1

### [Tạo tài khoản và ứng dụng](#tạo-tài-khoản-và-ứng-dụng)

Đăng ký bằng email và thông tin đơn vị, vào **My Apps** và chọn **New App**. Ứng dụng sandbox được duyệt tự động; INS-02 mở cho mọi nhà phát triển, IDN-01 và PAY-03 chỉ dành cho team được cấp quyền.

2

### [Lấy khóa API sandbox](#lấy-khóa-api-sandbox)

Khóa API xuất hiện ngay sau khi tạo ứng dụng và được gửi trong header `apikey`. Cất khóa an toàn, không đưa lên kho mã hay kênh chung.

3

### [Gọi API đầu tiên](#gọi-api-đầu-tiên)

Dùng curl hoặc Postman gọi `POST /quotes`. Thêm header `X-Mock-Scenario` với giá trị 400, 403, 409, 429 hoặc 503 để thử các mã lỗi.

## [Tiếp tục với hướng dẫn](#tiếp-tục-với-hướng-dẫn)

Hạn mức

### [Gói dịch vụ và hạn mức](#gói-dịch-vụ-và-hạn-mức)

Bốn bậc Public, Partner, Premium, Strategic với tốc độ, hạn mức ngày và cách xử lý khi nhận 429.

[Xem các gói](https://oapi-poc.hdbank.work/goi-dich-vu)

OAuth2

### [Production mô phỏng](#production-mô-phỏng)

Đăng ký ứng dụng, chờ duyệt, lấy token bằng client credentials và gọi API production mô phỏng.

[Đọc hướng dẫn](#production-mo-phong)

Hỗ trợ

### [Điều khoản và hỗ trợ](#điều-khoản-và-hỗ-trợ)

Quy định sử dụng, thời hạn khóa và cách báo sự cố kèm `X-Correlation-ID`.

[Liên hệ hỗ trợ](https://oapi-poc.hdbank.work/ho-tro)

## [Gọi thử bằng curl](#gọi-thử-bằng-curl)

```bash
export SANDBOX=https://apis-dev.hdbank.work
curl -s -H "apikey: $KEY" -H "X-Correlation-ID: $(uuidgen)" \
  -X POST $SANDBOX/quotes -d '{"product":"motor","sum_insured":500000000}'
```

**Header chuẩn:** `X-Correlation-ID` (tự sinh nếu thiếu), `X-Tenant-ID`, `Idempotency-Key` (bắt buộc với PAY-03), `X-Consent-ID` (bắt buộc với IDN-01). Lỗi trả về dạng `application/problem+json` (RFC 9457).

## [Giới hạn và phiên bản](#giới-hạn-và-phiên-bản)

Ứng dụng mới thuộc bậc Public: 2 request/giây, 100 request/ngày. Vượt ngưỡng trả `429` kèm `Retry-After` và `RateLimit-*`. INS-02 v1 đã deprecated (phản hồi có `Deprecation: true`, `Sunset: 31/12/2026`); dùng v2 tại `/v2/quotes`.

## [Production mô phỏng (OAuth2, cần duyệt)](#production-mo-phong)

Dành cho ứng dụng cần OAuth2 thay vì khóa API (API **INS-02 Insurance Quotes (production simulation)**).

1.  Tạo ứng dụng và chọn API production mô phỏng. Yêu cầu chờ API owner **duyệt tay**.
2.  Sau khi được duyệt, portal cấp `client_id` và `client_secret` (Keycloak realm `devportal-demo`).
3.  Lấy token. **Gửi `client_secret` qua HTTP Basic**; gửi trong body form sẽ bị `unauthorized_client`.

```bash
TOKEN=$(curl -s -u "$CLIENT_ID:$CLIENT_SECRET" -d grant_type=client_credentials -d scope=scope-ins \
  https://sso.hdbank.work/realms/devportal-demo/protocol/openid-connect/token | jq -r .access_token)
curl -s -H "Authorization: Bearer $TOKEN" $PROD/prod/quotes/qt-1
```

Khóa và token sandbox **không** dùng được ở production mô phỏng (401).