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

## Telkor API

This document describes the **Telkor API**: what it is, who it is for, and what it can do. It is intended for MVNOs, enterprise IoT teams, and M2M integrators as public documentation.

<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/telkor">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>.
      </p>
    </CardContent>
  </Card>
</div>

---

## 1. What is Telkor?

**Telkor** is a **multi-tenant API platform** for managing **SIM inventory**, **coverage zones**, **data plans**, and **links** (active service endpoints). Partners integrate via a REST API to:

- Define **coverages** — groups of mobile operators available for your plans
- Browse and monitor **SIMs** — physical SIMs and eSIMs in your organisation
- Create and configure **plans** — data packages with throttle, validity, and usage notifications
- Manage **links** — provision, activate, suspend, and configure service endpoints bound to SIMs
- Run **bulk operations** — async jobs for mass link/SIM management, tracked via tasks
- View **organisation** profile, balance, and monthly cost snapshots
- Retrieve **eSIM installation** details (LPA profile, QR code, deep links)

The platform handles authentication, upstream synchronisation, and exposes a **unified, provider-agnostic** API. All data is scoped to your organisation (tenant).

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

---

## 2. Who is it for?

- **MVNOs** — Manage SIM inventory, coverage, and plan catalogues programmatically.
- **Enterprise IoT** — Monitor fleets of SIMs, refresh upstream data, and configure data plans.
- **M2M integrators** — Automate coverage and plan management with machine-to-machine tokens.

Each partner is an **organisation** (tenant). All coverages, SIMs, and plans are scoped to that organisation. Access is controlled via **OmaxTelecom ID**: OAuth 2.0 Client Credentials.

---

## 3. Core concepts

### 3.1 Coverages

A **coverage** is a named group of mobile **operators** that defines where a plan can be used. Coverages are the foundation for plan configuration.

| Property | Description |
|----------|-------------|
| **id** | UUID — internal coverage identifier |
| **name** | Display name (e.g. "EU + UK") — not required to be unique |
| **operators** | List of operators included in this coverage |
| **compatibility_zones** | Provider ecosystems spanned by the operators (e.g. `magenta`, `cyan`) |

All operators in a coverage must belong to the same compatibility zone family. Mixed-provider coverages are rejected.

### 3.2 Operators

**Operators** are mobile network operators available in your catalogue. They are referenced when building coverages and filtered when listing plans.

| Property | Description |
|----------|-------------|
| **id** | UUID — operator identifier |
| **name** | Operator display name |
| **country** | ISO 3166-1 alpha-3 country code |
| **tadig** | TADIG code |
| **compatibility_zone** | Zone identifier (`magenta`, `cyan`, `brown`, `amber`, `violet`, `coral`, `teal`, `slate`, `ivory`) |
| **network_types** | Supported RAT types (`2g`, `3g`, `4g`, `5g`) |

Use `GET /coverages/operators` to browse operators available for coverage configuration.

### 3.3 SIMs

A **SIM** represents a physical SIM or eSIM in your organisation's inventory.

| Property | Description |
|----------|-------------|
| **id** | UUID — internal SIM identifier |
| **iccid** | ICCID — the SIM's printed serial number |
| **msisdn** | Phone number assigned to the SIM, if any |
| **status** | `available`, `active`, `suspended`, or `inventory` |
| **sim_type** | `physical` or `esim` |
| **link** | The Link this SIM is bound to (see below), if any |
| **esim_profile_status** | eSIM profile state (`available`, `installed`, `disabled`, `deleted`) — null for physical SIMs |

### 3.4 Links

A **Link** is the central service endpoint — the binding between a SIM and an active data plan in the upstream system. Links support full lifecycle management: create, update, suspend, resume, delete, and bulk operations.

| Property | Description |
|----------|-------------|
| **id** | UUID — Link identifier |
| **name** | Customer-assigned name (optional) |
| **status** | `active`, `suspended`, `hold`, or `removed` |
| **sim** | Bound SIM (ICCID, status, type) |
| **network_status** | Live connectivity: operator, country, RAT (`2g_3g`, `4g`, `5g`), policy status |
| **activations** | Data plans currently attached to the link |

**Activations** are plan instances on a link. Each activation tracks usage, expiry, and status. Add activations via `POST /links/{link_id}/activations` or bulk endpoints.

**Link controls:**
- **Network bars** — restrict connectivity to specific networks
- **IMEI lock** — bind the link to a specific device IMEI
- **SMS** — send SMS to the link's MSISDN

### 3.5 Plans

A **plan** is a data package configuration that references a coverage and defines usage rules.

| Property | Description |
|----------|-------------|
| **name** | Customer-assigned plan name |
| **coverage** | Coverage this plan applies to |
| **included_data_mb** | Bundled data in MB |
| **validity_days** | Plan validity from activation, in days |
| **base_throttle** | Max speed (`unlimited`, `128kbps` … `20mbps`) |
| **data_cap** | Optional in-plan soft cap with threshold and throttle action |
| **activation_type** | `immediate` or `on_first_data_usage` |
| **reactivation_trigger** | Renewal trigger (e.g. `on_expiration`) |
| **notifications** | Usage alert SMS notifications |

### 3.6 Plan notifications

**Notifications** are SMS alerts sent to the Link when usage thresholds are reached or lifecycle events occur.

| Type | Description |
|------|-------------|
| `plan_activation` | Sent when the plan activates |
| `plan_expiration` | Sent when the plan expires |
| `data_consumption_absolute` | Sent when data usage reaches a threshold in MB |
| `data_consumption_relative` | Sent when data usage reaches a percentage (50–100%) |

Notifications are managed via the `/plans/{plan_id}/notifications` sub-resource.

### 3.7 Bulk tasks

**Bulk operations** (mass link provisioning, suspend, delete, etc.) run asynchronously. Each bulk request returns a **task** with status counters. Poll task progress via:

- `GET /tasks` — list all bulk tasks
- `GET /tasks/{task_id}` — task header (status, success/failure counts)
- `GET /tasks/{task_id}/items` — per-item results

### 3.8 Organization

Your **organisation** (tenant) is resolved from the JWT. Customer-facing org endpoints:

| Endpoint | Description |
|----------|-------------|
| `GET /org` | Organisation profile (id, name) |
| `GET /org/balance` | Latest main-account balance snapshot |
| `GET /org/cost?year=&month=` | Latest monthly cost snapshot with usage breakdown |

Balance and cost data are collected by background workers (~every 3 hours). Returns **404** until the first snapshot exists.

---

## 4. Platform capabilities

### 4.1 Coverages

- **List coverages** — `GET /coverages` with pagination, sorting, and filters (`operator_ids`, `countries`, `compatibility_zones`, `search`).
- **Create coverage** — `POST /coverages` with `name` and `operator_ids`.
- **List operators** — `GET /coverages/operators` to browse operators for coverage configuration.
- **Get coverage** — `GET /coverages/{coverage_id}`.
- **Rename coverage** — `PATCH /coverages/{coverage_id}` with a new `name`.
- **Delete coverage** — `DELETE /coverages/{coverage_id}` (soft-delete, returns 204).
- **Add operators** — `POST /coverages/{coverage_id}/operators` (idempotent).
- **Remove operators** — `POST /coverages/{coverage_id}/operators/remove` (idempotent).

### 4.2 SIMs

- **List SIMs** — `GET /sims` with pagination, sorting, and filters (`status`, `sim_type`, `compatibility_zones`, `search`, `is_attached`, etc.).
- **Bulk provision** — `POST /sims/bulk-provision` creates links for multiple SIMs asynchronously (returns a task).
- **Get SIM** — `GET /sims/{sim_id}` returns full SIM details including Link summary.
- **eSIM installation** — `GET /sims/{sim_id}/installation` returns LPA activation code, Apple/Android deep links, and QR SVG.
- **Refresh SIM** — `POST /sims/{sim_id}/refresh` pulls the latest data from the upstream system.

### 4.3 Plans

- **List plans** — `GET /plans` with extensive filters (coverage, operators, compatibility zones, data/validity ranges, throttle, `search`, `for_link_id`).
- **Create plan** — `POST /plans` with coverage, data allowance, validity, throttle, and optional caps/notifications.
- **Get plan** — `GET /plans/{plan_id}`.
- **Update plan** — `PATCH /plans/{plan_id}` (partial update).
- **Delete plan** — `DELETE /plans/{plan_id}` (soft-delete, returns 204).
- **Add notification** — `POST /plans/{plan_id}/notifications`.
- **Update notification** — `PATCH /plans/{plan_id}/notifications/{notification_id}`.
- **Remove notification** — `DELETE /plans/{plan_id}/notifications/{notification_id}` (returns 204).

### 4.4 Links

- **List links** — `GET /links` with filters (`status`, `compatibility_zones`, `countries`, `search`).
- **Create link** — `POST /links` provisions a new link (optionally bound to a SIM and plan).
- **Get link** — `GET /links/{link_id}` (refreshes live network status for active links).
- **Update link** — `PATCH /links/{link_id}` (rename, etc.).
- **Delete link** — `DELETE /links/{link_id}` (soft-delete, returns 204).
- **Bind SIM** — `POST /links/{link_id}/sim` / `POST /links/{link_id}/sim/remove`.
- **Network bars** — `POST /links/{link_id}/network-bars` / `POST .../network-bars/remove`.
- **IMEI lock** — `POST /links/{link_id}/imei-lock` / `POST .../imei-lock/remove`.
- **SMS** — `GET /links/{link_id}/sms` (list), `POST /links/{link_id}/sms` (send).
- **Suspend / resume** — `POST /links/{link_id}/suspend`, `POST /links/{link_id}/resume`.
- **Activations** — `GET /links/{link_id}/activations`, `POST /links/{link_id}/activations`, `DELETE /links/{link_id}/activations/{activation_id}`.

**Bulk link operations** (all return a task id):

| Endpoint | Action |
|----------|--------|
| `POST /links/bulk-delink-sim` | Detach SIM from multiple links |
| `POST /links/bulk-delete` | Soft-delete multiple links |
| `POST /links/bulk-suspend` | Suspend multiple links |
| `POST /links/bulk-resume` | Resume multiple links |
| `POST /links/bulk-add-activation` | Add plan activation to multiple links |
| `POST /links/bulk-delete-activation` | Remove activation from multiple links |

### 4.5 Tasks

- **List tasks** — `GET /tasks` with filters (`type`, `status`).
- **Get task** — `GET /tasks/{task_id}` (status + counters).
- **List task items** — `GET /tasks/{task_id}/items` (per-item success/failure details).

### 4.6 Organization

- **Profile** — `GET /org` returns your organisation id and name.
- **Balance** — `GET /org/balance` returns the latest collected balance snapshot.
- **Cost** — `GET /org/cost?year=2026&month=6` returns the latest monthly cost breakdown.

---

## 5. Technical specifications

### 5.1 API

- **Style:** REST, JSON request/response.
- **Base URL:** `https://api.omaxtelecom.com/telkor`
- **Authentication:** OAuth 2.0 Client Credentials via **OmaxTelecom ID**. Send `Authorization: Bearer <access_token>`.

### 5.2 Authentication

Obtain a token from the OmaxTelecom API auth endpoint:

```
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). The token has a limited lifetime — request a new one when it expires. There are no refresh tokens in the Client Credentials flow.

### 5.3 Pagination

List endpoints (`/coverages`, `/coverages/operators`, `/sims`, `/plans`, `/links`, `/tasks`) return paginated results:

```json
{
  "items": [...],
  "total": 42,
  "page": 1,
  "page_size": 25,
  "total_pages": 2
}
```

Query parameters: `page` (1-based, default 1), `page_size` (default 25, max 500).

### 5.4 Filtering and sorting

- Filters combine with **AND** semantics.
- Repeatable filters (`operator_ids`, `countries`, `compatibility_zones`) match **any** of the provided values.
- `search` performs a case-insensitive substring match.
- Use `sort_by` and `sort_order` (`asc` / `desc`) on list endpoints.

### 5.5 Error format

```json
{
  "message": "Entity not found: id=...",
  "code": "entity_not_found",
  "details": { ... }
}
```

### 5.6 Error codes

| Code | HTTP | Meaning |
|------|------|---------|
| `unauthorized` | 401 | Missing or invalid Bearer token |
| `forbidden` | 403 | Authenticated but lacks required role |
| `entity_not_found` | 404 | Resource not found |
| `entity_deleted` | 410 | Resource has been soft-deleted |
| `duplicate_entity` | 409 | Entity already exists |
| `validation_error` | 422 | Business rule violation |
| `request_validation_error` | 422 | Request input failed schema validation |
| `upstream_unavailable` | 502 | Upstream dependency error |

### 5.7 Multi-tenancy

Every authenticated request is bound to an **organisation** derived from the token. All coverages, SIMs, plans, links, and tasks are scoped to that organisation. No cross-tenant access.

---

## 6. Getting started

1. **Obtain credentials** — Get `client_id` and `client_secret` from [OmaxTelecom Console](https://console.omaxtelecom.com).
2. **Get a token** — Call the OmaxTelecom ID token endpoint with Client Credentials grant. Use the returned `access_token` as `Authorization: Bearer <access_token>`.
3. **Confirm tenant** — `GET /org` to verify which organisation your token is bound to.
4. **Browse operators** — `GET /coverages/operators` to see available operators.
5. **Create a coverage** — `POST /coverages` with a name and operator IDs.
6. **Create a plan** — `POST /plans` referencing your coverage, with data allowance and validity.
7. **List SIMs** — `GET /sims` to view your SIM inventory.
8. **Create a link** — `POST /links` to provision a service endpoint, or `POST /sims/bulk-provision` for multiple SIMs.
9. **Monitor bulk jobs** — `GET /tasks/{task_id}` to track async bulk operation progress.
10. **Optional:** Configure plan notifications, check balance (`GET /org/balance`), and refresh SIM data.

---

## 7. Summary table

| Area | Capability |
|------|------------|
| **Coverages** | Define operator groups for plan coverage |
| **Operators** | Browse mobile operators in your catalogue |
| **SIMs** | List, view, bulk-provision, refresh SIM inventory |
| **eSIM install** | LPA profile, QR code, Apple/Android deep links |
| **Plans** | Create and manage data plans with throttle and caps |
| **Notifications** | SMS usage alerts on plans |
| **Links** | Full lifecycle: create, activate, suspend, SMS, network bars, IMEI lock |
| **Bulk ops** | Mass link/SIM operations via async tasks |
| **Tasks** | Track bulk job progress and per-item results |
| **Organization** | Profile, balance snapshot, monthly cost breakdown |
| **Auth** | OmaxTelecom ID (Client Credentials), Bearer token |

---

## API Documentation

<div className="not-prose my-6">
  <Card>
    <CardHeader>
      <CardTitle>Complete API Reference</CardTitle>
      <CardDescription>
        Explore the full API documentation with interactive examples, request/response schemas, and authentication details.
      </CardDescription>
    </CardHeader>
    <CardContent>
      <Button asChild>
        <a href="/api/telkor">View API Documentation →</a>
      </Button>
    </CardContent>
  </Card>
</div>

## Need Help?

If you have any questions or need assistance with the Telkor API, please contact our support team at [support@omaxtelecom.com](mailto:support@omaxtelecom.com).