> ## Documentation Index
> Fetch the complete documentation index at: https://docs.econtractid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Giới thiệu API

> Tổng quan về econtractid REST API – Base URL, định dạng request/response và các quy ước chung

## Tổng quan

**econtractid API** là API RESTful cho phép tích hợp đầy đủ chức năng ký hợp đồng điện tử vào hệ thống của bạn.

<CardGroup cols={2}>
  <Card title="Base URL Production" icon="server">
    `https://api.econtractid.vn/api`
  </Card>

  <Card title="Base URL Sandbox" icon="flask">
    `https://sandbox-api.econtractid.vn/api`
  </Card>
</CardGroup>

***

## Xác thực

Tất cả API đều yêu cầu xác thực. Có 2 phương thức:

### 1. Bearer Token (JWT)

```http theme={null}
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
```

### 2. API Key

```http theme={null}
X-API-Key: eck_live_xxxxxxxxxxxxxxxxxxxx
```

Xem chi tiết tại [Xác thực & Phân quyền](/technical/xac-thuc).

***

## Định dạng Request

```http theme={null}
Content-Type: application/json
Accept: application/json
```

***

## Định dạng Response

Tất cả response đều có cấu trúc chuẩn:

```json theme={null}
{
  "statusCode": 200,
  "message": "Thành công",
  "data": { ... },
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "totalPages": 5
  }
}
```

| Trường       | Kiểu             | Mô tả                             |
| ------------ | ---------------- | --------------------------------- |
| `statusCode` | `number`         | HTTP status code                  |
| `message`    | `string`         | Thông báo kết quả                 |
| `data`       | `object / array` | Dữ liệu trả về                    |
| `meta`       | `object`         | Phân trang (chỉ có với danh sách) |

***

## Phân trang

Các API danh sách hỗ trợ phân trang qua query params:

```http theme={null}
GET /api/contracts?page=1&limit=20&sortBy=createdAt&order=DESC
```

| Param    | Mặc định    | Mô tả                             |
| -------- | ----------- | --------------------------------- |
| `page`   | `1`         | Số trang                          |
| `limit`  | `20`        | Số bản ghi mỗi trang (tối đa 100) |
| `sortBy` | `createdAt` | Trường sắp xếp                    |
| `order`  | `DESC`      | `ASC` hoặc `DESC`                 |

***

## Rate Limiting

| Loại                 | Giới hạn           |
| -------------------- | ------------------ |
| Xác thực (`/auth/*`) | 10 request / phút  |
| API thông thường     | 100 request / phút |
| Upload file          | 10 request / phút  |

Khi vượt giới hạn, API trả về `429 Too Many Requests`.

***

## Sandbox & Testing

Môi trường sandbox cho phép test toàn bộ luồng mà không ảnh hưởng dữ liệu thật.

<Info>
  Trong sandbox, email thông báo sẽ chỉ gửi tới địa chỉ đã đăng ký trong tài khoản developer — **không** gửi tới email bên ký thực tế.
</Info>

Tạo tài khoản sandbox tại [developer.econtractid.vn](https://developer.econtractid.vn).

***

## SDK & Thư viện

| Ngôn ngữ                | Package                            |
| ----------------------- | ---------------------------------- |
| JavaScript / TypeScript | `npm install @econtractid/sdk`     |
| PHP                     | `composer require econtractid/sdk` |
| Python                  | `pip install econtractid-sdk`      |

```typescript theme={null}
import { econtractidClient } from '@econtractid/sdk';

const client = new econtractidClient({
  apiKey: process.env.econtractid_API_KEY,
  baseUrl: 'https://api.econtractid.vn/api',
});

const contracts = await client.contracts.list({ page: 1, limit: 10 });
```