# Netcell API v1

## Base URL

```text
https://api.example.com/api/v1
```

Replace the hostname with your production domain.

## Authentication

Create an API key in the customer dashboard. The full key is shown only once.
Send it from your backend with:

```http
Authorization: Bearer nc_live_xxxxxxxxx
```

Never put keys in URLs, frontend JavaScript, Git, or mobile apps.

## Endpoints

```text
GET  /services?country=187&featured=1&limit=30
GET  /orders?limit=50
GET  /orders/{id}
POST /orders
POST /orders/{id}/check
POST /orders/{id}/cancel
GET  /transactions
```

Create orders with a unique idempotency key:

```http
POST /orders
Authorization: Bearer nc_live_xxx
Idempotency-Key: your-system-order-123
Content-Type: application/json
```

```json
{"service":"wa","country":"187"}
```

Response (`201`):

```json
{"order_id":123,"support_id":"NC-20260831-000123"}
```

Poll `POST /orders/{id}/check` every 5–10 seconds. Cancel only while status is
`waiting`. Statuses are `waiting`, `received`, `cancelled`, `failed`, `error`.

Order responses contain customer data only; provider IDs and internal cost are
never exposed.

## Errors

```json
{"error":"Số dư khả dụng không đủ"}
```

`400` invalid input/balance, `401` missing or invalid key, `404` unavailable or
not owned, `409` state conflict, `429` rate limited, `502` provider unavailable.
Do not retry an order with a new idempotency key unless you intend a new order.

## cURL

```bash
BASE_URL="https://api.example.com/api/v1"
API_KEY="nc_live_replace_me"
curl "$BASE_URL/services?country=187&featured=1" -H "Authorization: Bearer $API_KEY"
curl -X POST "$BASE_URL/orders" -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" -H "Idempotency-Key: my-order-123" -d '{"service":"wa","country":"187"}'
curl -X POST "$BASE_URL/orders/123/check" -H "Authorization: Bearer $API_KEY"
```

## Python

```python
import requests
base = "https://api.example.com/api/v1"
headers = {"Authorization": "Bearer nc_live_replace_me", "Idempotency-Key": "my-order-123"}
response = requests.post(base + "/orders", headers=headers, json={"service": "wa", "country": "187"})
response.raise_for_status()
print(response.json())
```

Use HTTPS, one key per integration/environment, periodic rotation, exponential
backoff for `429`, and redact `Authorization` from logs.