# YFi Net — eSIM Platform API (guide for AI assistants)

> YFi Net is a telecom backend: white-label eSIM storefronts, corporate Team
> eSIMs, and a REST API for programmatic eSIM ordering in 200+ countries.
> This file is written for AI coding assistants (Claude, etc.) helping a
> developer integrate. Everything below is current and self-contained.

## Base URL and authentication

- Base URL: `https://esimyfi.live`
- Every request: `Authorization: Bearer <api_key>`
- Keys: `yf_live_…` (production — real charges, real eSIMs) and
  `yf_test_…` (sandbox — full lifecycle, no charges, no real eSIMs).
- Keys are managed in the dealer console: Console → API keys (generate or
  rotate live and test keys; each shown only once).
- MCP server: `https://esimyfi.live/mcp` (Streamable HTTP). Add to Claude Code:
  `claude mcp add --transport http yfinet https://esimyfi.live/mcp --header "Authorization: Bearer yf_test_YOUR_KEY"`

## Sandbox (test mode) — start here

Use the `yf_test_` key while developing. Behavior:
- Real catalog and real pricing math; identical response shapes to live.
- NO balance charge, NO real eSIM, NO provider mutation — guaranteed server-side.
- Responses carry `test_mode: true` and a synthetic ICCID starting `8999`.
- Sandbox orders work across order detail, lookup, usage, top-ups, cancel.
- A test key can NEVER act on a live order (403 `test_key_live_order`);
  a live key can never act on a sandbox order (400 `live_key_test_order`).
- Live-key orders require a minimum balance of $500 (402
  `minimum_balance_required` below it). Test keys are unaffected.

## Endpoints

### Account
- `GET /v1/balance` — balance, account mode, `live_api_enabled` flag.
- `GET /v1/account` — profile. `PATCH /v1/account` — update webhook_url etc.
- `GET /v1/transactions` — balance ledger.
- `GET /v1/keys` — key prefixes + last rotation. `POST /v1/keys/rotate`
  body `{"mode":"live"|"test"}` — new key returned once as `api_key`.

### Catalog
- `GET /v1/countries` — countries with plan counts.
- `GET /v1/countries/{code}/plans` — plans with dealer pricing applied.
  Plans with `is_daily: true` are priced PER DAY.
- `GET /v1/regions` — regional/global groupings.

### Orders
- `POST /v1/orders` — create an eSIM order. Body:
  - `package_code` (required)
  - `customer_email` (optional — eSIM is emailed with QR + install steps)
  - `customer_label` (optional free text)
  - `dealer_reference` (optional — idempotency key; same reference returns
    the original order with `idempotent_replay: true`)
  - `period_num` (1–60, DAILY PLANS ONLY — number of days; charged =
    per-day price × period_num. On a fixed-duration plan returns 400
    `not_a_daily_plan`.)
  - Success: `order_id`, `iccid`, `activation_code` (LPA string),
    `smdp_address`, `qr_code_url`, `charged_cents`.
- `GET /v1/orders` — list orders. `GET /v1/orders/{id}` — detail.
- `GET /v1/orders/{id}/topup-options` — compatible top-up packages.
- `POST /v1/orders/{id}/topup` — body `{"package_code": "..."}`.
- `POST /v1/orders/{id}/cancel` — cancel/refund where supported.
- `POST /v1/orders/{id}/suspend` / `POST /v1/orders/{id}/unsuspend`.

### eSIMs
- `GET /v1/esims/{iccid}` — lookup by ICCID.
- `GET /v1/esims/{iccid}/usage` — live data usage.

### Webhooks
- Configure `webhook_url` via `PATCH /v1/account`.
- `POST /v1/webhooks/test` — send a signed test delivery.
- `POST /v1/webhooks/rotate-secret` — new signing secret.
- `GET /v1/webhooks/deliveries` — recent delivery log.
- Signature: `X-YFi-Signature: sha256=HMAC_SHA256(secret, raw_body)`.

### System
- `GET /v1/system/status` — platform status.

## Typical integration (sandbox first)

```bash
# 1. Check auth + balance
curl https://esimyfi.live/v1/balance -H "Authorization: Bearer yf_test_KEY"

# 2. Browse plans for Japan
curl https://esimyfi.live/v1/countries/JP/plans -H "Authorization: Bearer yf_test_KEY"

# 3. Order (fixed-duration plan)
curl -X POST https://esimyfi.live/v1/orders \
  -H "Authorization: Bearer yf_test_KEY" -H "Content-Type: application/json" \
  -d '{"package_code":"JP-10GB-30D","customer_email":"traveler@example.com","dealer_reference":"order-123"}'

# 4. Order a daily plan for 7 days (is_daily: true plans only)
curl -X POST https://esimyfi.live/v1/orders \
  -H "Authorization: Bearer yf_test_KEY" -H "Content-Type: application/json" \
  -d '{"package_code":"GL-1GBDAY","period_num":7}'

# 5. Check usage later
curl https://esimyfi.live/v1/esims/8999.../usage -H "Authorization: Bearer yf_test_KEY"
```

Switch `yf_test_` → `yf_live_` when ready for production. Same endpoints,
same shapes; live orders charge the prepaid balance and provision real eSIMs.

## Error model

JSON: `{"error": "machine_code", "message": "human text", "request_id": "req_…"}`.
Common codes: `invalid_api_key_format`, `invalid_api_key`, `dealer_suspended`,
`plan_not_available`, `not_a_daily_plan`, `insufficient_balance`,
`minimum_balance_required`, `test_key_live_order`, `live_key_test_order`,
`bad_json`, `missing_fields`, `unknown_endpoint`.

## Rules for AI assistants

1. Always develop against a `yf_test_` key. Never place live orders unless
   the human explicitly asks for production.
2. Never print or log a full API key; refer to it as `yf_test_…`/`yf_live_…`.
3. Use `dealer_reference` for idempotent order creation in any retry loop.
4. `period_num` only on plans where `is_daily` is true.
5. Treat `8999…` ICCIDs as sandbox artifacts — they are not real eSIMs.
6. Full human docs live in the dealer console → Developer → API documentation.
   Support: contact@yfinet.app · WhatsApp +1 437 849 5612.