import {
  Card,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
} from "zudoku/ui/Card";
import { Button } from "zudoku/ui/Button";

## Phone Numbers API

The **Phone Numbers API** lets you search, purchase, and manage phone numbers, configure voice/SMS routing endpoints, send and receive SMS, and submit KYC. All phone numbers must be in **E.164** format (for example `+447700900001`).

<div className="not-prose my-4">
  <Card>
    <CardContent className="pt-6">
      <div className="flex flex-wrap items-center gap-3">
        <Button asChild>
          <a href="/api/phone-numbers">View API Documentation →</a>
        </Button>
        <span className="text-sm text-muted-foreground">
          Interactive reference, request/response schemas, and examples
        </span>
      </div>
      <p className="mt-3 text-sm text-muted-foreground">
        Use the <strong>Interactive Playground</strong> on the API reference page to test endpoints with your Console <code>client_id</code> and <code>client_secret</code>. Download the Postman collection and environment from the same page.
      </p>
    </CardContent>
  </Card>
</div>

**Base URL:** `https://api.omaxtelecom.com/numbers`

---

## What can you do?

| Capability | Endpoint | Description |
|------------|----------|-------------|
| **Verify context** | `GET /me` | Verify token and organization context |
| **Health** | `GET /health` | Check service availability (no auth) |
| **Search catalog** | `GET /available` | Search available numbers to purchase |
| **Preview cost** | `POST /preview` | Get a purchase quote for catalog number IDs |
| **Purchase** | `POST /` | Purchase one or more numbers |
| **List owned** | `GET /` | List numbers owned by your organisation |
| **Get / release** | `GET/DELETE /{phoneNumberId}` | View or release a number |
| **Routing** | `GET/PUT /{phoneNumberId}/routing` | Configure voice/SMS routing |
| **Per-number KYC** | `GET/POST /{phoneNumberId}/kyc` | View or submit number KYC |
| **Endpoints** | `GET/POST /endpoints` | Manage voice/SMS routing endpoints |
| **SMS pricing** | `GET /sms/pricing` | Get outbound SMS pricing |
| **Send SMS** | `POST /sms/send` | Send outbound SMS from an owned number |
| **Inbound SMS** | `GET /sms/messages` | List inbound SMS messages |
| **Partner webhook** | `GET/PUT /sms/webhook` | Configure inbound SMS webhook |
| **Org KYC** | `GET/POST /kyc/organization` | Organisation-level KYC |

---

## Authentication

All endpoints except `/health` require OAuth 2.0 Client Credentials via **OmaxTelecom ID**:

```http
Authorization: Bearer <access_token>
```

Obtain a token from the shared OmaxTelecom API auth endpoint. This is **not** under the Phone Numbers base URL — see the [Auth API reference](/api/auth):

```
POST https://api.omaxtelecom.com/auth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id={client_id}&client_secret={client_secret}
```

Get your `client_id` and `client_secret` from [OmaxTelecom Console](https://console.omaxtelecom.com).

For M2M clients without an `organization` claim in the token, include:

```http
X-Organization-Id: <organization_id>
```

Verify your token and organisation context with `GET /me`.

---

## Billing

Number purchases, inbound SMS, and outbound SMS may be charged via the Console Wallet API depending on configured sell rates.

| HTTP status | Error code | Meaning |
|-------------|------------|---------|
| `402` | `INSUFFICIENT_BALANCE` | Wallet balance too low |
| `403` | `PHONE_NUMBERS_DISABLED` | Phone numbers not enabled for your organisation |
| `403` | `BILLING_NOT_CONFIGURED` | Billing is not configured |
| `403` | `ORGANIZATION_NOT_FOUND` | Organisation not registered |
| `403` | `KYC_REQUIRED` | Organisation KYC approval required before purchasing |
| `403` | `TRAFFIC_RESTRICTED` | Outbound SMS not permitted |
| `404` | `OFFERING_NOT_FOUND` | No offering found for the requested country/type |
| `422` | `VALIDATION_ERROR` | Invalid request body or phone number format |
| `502` | `OUTBOUND_SMS_FAILED` | Outbound SMS failed at supplier |

---

## Response envelope

Successful responses:

```json
{
  "success": true,
  "data": { ... }
}
```

Error responses:

```json
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message"
  }
}
```

---

## Purchase workflow

1. **Search** — `GET /available` returns catalog number IDs (opaque UUIDs with a short TTL)
2. **Preview** — `POST /preview` returns a cost quote and optional `quote_token`
3. **Purchase** — `POST /` using the catalog number ID(s) from step 1 or 2

---

## Examples

### Search available numbers

```bash
curl "https://api.omaxtelecom.com/numbers/available?country_iso=GB&number_type=mobile&limit=20" \
  -H "Authorization: Bearer <access_token>"
```

**Response `200 OK`:**

```json
{
  "success": true,
  "data": {
    "numbers": [
      {
        "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "e164": "+447700900123",
        "phone_number": "+447700900123",
        "national_format": "07700 900123",
        "country_iso": "GB",
        "number_type": "mobile",
        "connection_fee": "5.000000",
        "monthly_fee": "2.000000",
        "total_fee": "7.000000",
        "billing_period": "monthly",
        "currency": "EUR",
        "value_tier": "standard"
      }
    ],
    "total_available": 42
  }
}
```

### Preview purchase cost

```bash
curl -X POST "https://api.omaxtelecom.com/numbers/preview" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"number_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"]}'
```

**Response `200 OK`:**

```json
{
  "success": true,
  "data": {
    "numbers": [
      {
        "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "e164": "+447700900123",
        "phone_number": "+447700900123",
        "national_format": "07700 900123",
        "country_iso": "GB",
        "number_type": "mobile",
        "connection_fee": "5.000000",
        "monthly_fee": "2.000000",
        "total_fee": "7.000000",
        "billing_period": "monthly",
        "currency": "EUR",
        "value_tier": "standard"
      }
    ],
    "quote": {
      "connection_cost": 5,
      "monthly_cost": 2,
      "total_cost": 7,
      "currency": "EUR",
      "quote_token": "qt_abc123xyz",
      "expected_total_cost_minor": 700,
      "first_billing_date": "2026-09-17",
      "next_billing_date": "2026-10-17"
    }
  }
}
```

### Purchase a number

```bash
curl -X POST "https://api.omaxtelecom.com/numbers" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: purchase-2026-09-17-001" \
  -d '{"number_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"}'
```

**Response `201 Created`:**

```json
{
  "success": true,
  "data": {
    "order_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
    "phone_numbers": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "e164": "+447700900001",
        "phone_number": "+447700900001",
        "national_format": "07700 900001",
        "country_iso": "GB",
        "number_type": "local",
        "connection_fee": "5.000000",
        "monthly_fee": "2.000000",
        "total_fee": "7.000000",
        "status": "provisioning",
        "kyc_status": "approved",
        "traffic_direction": "inbound_and_outbound",
        "voice_endpoint_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "sms_endpoint_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
        "next_billing_date": "2026-10-01",
        "billing_period": "monthly",
        "currency": "EUR"
      }
    ]
  }
}
```

### List owned numbers

```bash
curl "https://api.omaxtelecom.com/numbers?page=1&per_page=20" \
  -H "Authorization: Bearer <access_token>"
```

**Response `200 OK`:**

```json
{
  "success": true,
  "data": {
    "phone_numbers": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "e164": "+447700900001",
        "phone_number": "+447700900001",
        "national_format": "07700 900001",
        "country_iso": "GB",
        "number_type": "local",
        "connection_fee": "5.000000",
        "monthly_fee": "2.000000",
        "total_fee": "7.000000",
        "status": "active",
        "kyc_status": "approved",
        "traffic_direction": "inbound_and_outbound",
        "voice_endpoint_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "sms_endpoint_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
        "next_billing_date": "2026-10-01",
        "billing_period": "monthly",
        "currency": "EUR"
      }
    ],
    "page": 1,
    "per_page": 20,
    "total": 1
  }
}
```

### Send outbound SMS

```bash
curl -X POST "https://api.omaxtelecom.com/numbers/sms/send" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+447700900001",
    "to": "+447911123456",
    "body": "Your verification code is 123456"
  }'
```

**Response `201 Created`:**

```json
{
  "success": true,
  "data": {
    "id": "f6a7b8c9-d0e1-2345-fabc-456789012345",
    "phone_number_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "from": "+447700900001",
    "to": "+447911123456",
    "body": "Your verification code is 123456",
    "segments": 1,
    "status": "sent",
    "sent_at": "2026-09-17T09:20:00+00:00",
    "delivered_at": null
  }
}
```

### Configure inbound SMS webhook

```bash
curl -X PUT "https://api.omaxtelecom.com/numbers/sms/webhook" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/webhooks/inbound-sms",
    "secret": "my-webhook-secret-16chars",
    "enabled": true
  }'
```

**Response `200 OK`:**

```json
{
  "success": true,
  "data": {
    "url": "https://api.example.com/webhooks/inbound-sms",
    "enabled": true,
    "has_secret": true
  }
}
```

### Health check

```bash
curl "https://api.omaxtelecom.com/numbers/health"
```

**Response `200 OK`:**

```json
{
  "ok": true,
  "timestamp": "2026-09-17T12:00:00+00:00"
}
```

---

## Getting started

1. Enable phone numbers for your organisation in [OmaxTelecom Console](https://console.omaxtelecom.com).
2. Obtain an access token via **OmaxTelecom ID** using your `client_id` and `client_secret`.
3. Call `GET /health` to confirm the service is reachable.
4. Verify context with `GET /me`.
5. Search available numbers with `GET /available`, preview cost, then purchase.
6. Configure routing endpoints and inbound SMS webhook as needed.

## API Documentation

<div className="not-prose my-6">
  <Card>
    <CardHeader>
      <CardTitle>Complete API Reference</CardTitle>
      <CardDescription>
        Explore all endpoints with interactive examples, schemas, authentication details, and Postman downloads.
      </CardDescription>
    </CardHeader>
    <CardContent>
      <Button asChild>
        <a href="/api/phone-numbers">View API Documentation →</a>
      </Button>
    </CardContent>
  </Card>
</div>

## Need Help?

Contact [support@omaxtelecom.com](mailto:support@omaxtelecom.com) for integration support.