Bappy Bundle SIM Reseller Platform

This document describes the Bappy Reseller Platform: what it is, who it is for, and what it can do. It is intended for partners, resellers, and integrators as public documentation.

---

1. What is Bappy?

Bappy is a multi-tenant API platform that lets resellers and partners sell and manage eSIM and physical SIM data plans through a unified concept called Links. A Link represents a single card — whether eSIM or physical SIM — identified by a UUID or ICCID. Partners integrate via a single REST API to:

• Create new Links (activate eSIMs or physical SIMs)
• Top up existing Links with additional data plans
• Check Link status, usage, and network info
• View Link transaction history
• Send SMS to Links
• Manage plans, coverage, and regions
• View organization balance, transactions, and analytics

The platform handles authentication, billing (wallet/balance), provisioning with the mobile operator, and exposes a unified, provider-agnostic API. Partners do not need to integrate directly with the underlying operator; Bappy abstracts that.

---

2. Who is it for?

• Resellers — Sell eSIM or physical SIM plans to end customers (travel, M2M, etc.).
• Integrators — Embed Link creation and topup into your app, portal, or booking flow.
• M2M / IoT — Create and manage Links programmatically (machine-to-machine tokens supported).

Each partner is an organization (tenant). All data — Links, activations, topups, balance, transactions — is scoped to that organization. Access is controlled via OmaxTelecom ID (identity provider): OAuth 2.0 Client Credentials.

---

3. Core concept: Links

A Link is the central resource in Bappy. It represents a single card (eSIM or physical SIM) and all its associated data.

Property	Description
UUID	Unique identifier assigned on creation
ICCID	SIM card identifier (assigned by provider)
Identifier	All Link endpoints accept either UUID or ICCID as {identifier}
Status	active, suspended, or inactive
Activations	One or more plans attached to the Link (each with its own usage, expiry, coverage)

Examples:

• GET /links/550e8400-e29b-41d4-a716-446655440000 (by UUID)
• GET /links/8901010000000000001 (by ICCID)

---

4. Platform capabilities (what you can do)

4.1 Create a Link

• Create Link — POST /links with plan_id (and optional name). Balance is debited; the eSIM is provisioned. Returns Link UUID, ICCID, MSISDN, LPA profile, activation URL, and amount charged.

Flow:

1. Checks wallet balance (must cover plan's retail price)
2. Fetches available eSIM ICCID from provider
3. Deducts plan retail price from wallet
4. Creates provider endpoint with the plan
5. Creates Link + activation + transaction records
6. On provider failure: wallet amount is automatically refunded

4.2 View and manage Links

• List Links — GET /links with optional filters: status, search, per_page, page. Returns paginated list of all Links for your organization.
• Get Link — GET /links/{identifier} returns full Link details including: live usage data, eSIM activation URLs (Apple/Android), all activations with per-plan usage, and aggregated coverage data.
• Reactivate Link — PUT /links/{identifier} with {"status": "active"} to reactivate a suspended Link (synchronized with provider).

4.3 Plans and topup

• Available topup plans — GET /links/{identifier}/topup-plans returns plans compatible with a specific Link (filtered by matching sponsor profile). Each plan includes data amount, validity, pricing, and coverage summary.
• Remove plan — PUT /links/{identifier}/plans with {"remove": ["activation-uuid"]} to cancel an activation from a Link. Get the activation UUID from GET /links/{identifier} → activations[].id.

4.4 Link history

• Transaction history — GET /links/{identifier}/history returns a paginated list of all transactions for a Link: activations, topups, refunds, and monthly link fees. Ordered by date (newest first).

4.5 Network status

• Live network status — GET /links/{identifier}/network-status?live=true forces a live check from the provider, bypassing cache.

4.6 eSIM-specific

• LPA profile — Returned on Link creation; used for eSIM activation.
• Apple activation URL — Universal deep link for iOS eSIM installation.
• Android activation URL — Universal deep link for Android eSIM installation.
• Installation instructions — GET /info/instructions returns step-by-step eSIM installation guides for iOS and Android.

4.7 SMS

• Send SMS — POST /sms with link_id (UUID or ICCID) and message (max 80 characters). SMS is queued for async delivery.
• List SMS — GET /sms?link_id={identifier} to list SMS messages for a specific Link.

4.8 Plans (reference data)

• List plans — GET /plans with optional filters: region, coverage_type, sponsor_profile. Returns all available plans with pricing, data amount, validity, and coverage summary.
• Get plan — GET /plans/{plan_id} returns detailed plan information.
• Plan coverage — GET /plans/{plan_id}/coverage returns full coverage details: all countries and their operators with network types.
• Coverage regions — GET /plans/regions returns all available regions (EU, AF, AS, LA, NA, OC) for filtering plans.

4.9 Organization (tenant)

• Profile — GET /organization: name, slug, status, pricing settings (price_per_sms, price_per_link).
• Balance — GET /organization/balance: current wallet balance and currency (used for Link creation and topups).

4.10 Transactions and analytics

• List transactions — GET /transactions with optional link_id filter. For per-Link history, prefer GET /links/{identifier}/history.
• Statistics — GET /transactions/stats with optional from/to date range.
• Analytics — GET /transactions/analytics with optional period_days (e.g. last 30 days).

4.11 Info

• eSIM installation instructions — GET /info/instructions returns step-by-step guides for iOS and Android.
• Mobile operators — GET /info/operators?search={country} searches operators by country name.

---

5. Technical specifications

5.1 API

• Style: REST, JSON request/response.
• Base path: /v1 (e.g. https://api.omaxtelecom.com/bappy/v1).
• Authentication: OAuth 2.0 Client Credentials via OmaxTelecom ID. Send Authorization: Bearer <access_token>. Token is obtained from OmaxTelecom ID token endpoint, not from Bappy.
• Public endpoints (no auth): GET /health, GET /status for availability and dependency checks.

5.2 Link identifiers

All single-resource Link endpoints accept either a Link UUID or an ICCID as the {identifier} path parameter. Use whichever is more convenient for your integration.

5.3 Response format

• Success: { "success": true, "data": { ... }, "meta": { "timestamp", "response_time_ms" } }.
• Paginated: data contains data (array) and meta (current_page, last_page, per_page, total, from, to).
• Error: { "success": false, "error": { "code", "message", "details" }, "meta": { "timestamp" } } with appropriate HTTP status (401, 402, 404, 422, 502, etc.).

5.4 Multi-tenancy

• Every authenticated request is bound to an organization (tenant) derived from the token.
• All Links, transactions, balance, and SMS are scoped to that organization. No cross-tenant access.

5.5 Provider abstraction

• The platform does not expose the underlying mobile operator or provider name in the public API.
• Errors are normalized to generic codes (e.g. PROVISIONING_ERROR, PROVIDER_UNAVAILABLE). Internal provider details are not returned to clients.

5.6 Error codes (summary)

Code	Typical HTTP	Meaning
UNAUTHORIZED	401	Missing or invalid Bearer token
INSUFFICIENT_BALANCE	402	Wallet balance too low
ORG_SUSPENDED	403	Organization is suspended
NOT_FOUND	404	Resource not found
PLAN_NOT_FOUND	404	Plan not found or not enabled for your org
VALIDATION_ERROR	422	Invalid request parameters
INVALID_STATUS_CHANGE	422	Status transition not allowed
INVALID_STATE	422	Resource in invalid state
INVALID_PLAN	422	Plan not available for operation
CONFIG_ERROR	500	Server misconfiguration
PROVISIONING_ERROR	502	Provider API error
PROVISIONING_FAILED	502	Provider returned no result
PROVIDER_ERROR	502	Provider operation failed

---

6. Getting started (high-level)

1. Obtain credentials — Get an organization (tenant) and OmaxTelecom ID credentials (client_id + client_secret).
2. Get a token — Call OmaxTelecom ID token endpoint with Client Credentials grant. Use the returned access_token as Authorization: Bearer <access_token>.
3. Discover plans — GET /plans to see available packages with pricing, data, validity, and coverage.
4. Check balance — GET /organization/balance before creating or topping up Links.
5. Create a Link — POST /links with plan_id to create a new Link (eSIM activation). You'll receive UUID, ICCID, LPA profile, and activation URLs.
6. Manage Links — Use GET /links to list all Links, GET /links/{identifier} for details, and GET /links/{identifier}/topup-plans to find compatible topup plans.
7. Optional: Use transactions and analytics for reporting, and SMS for messaging.

---

7. Summary table

Area	Capability
Links	Central resource: represents eSIM or physical SIM, identified by UUID or ICCID
Create Link	Single eSIM activation with plan
Topup	Per Link with compatible topup plans
Link Details	Full details: usage, activations, eSIM URLs, coverage
History	Per-Link transaction history (activations, topups, refunds, fees)
Network	Live network status per Link
SMS	Send and list SMS per Link
Plans	List, filter by region/coverage/sponsor, view full coverage and operators
Organization	Profile, balance, pricing settings
Transactions	List, statistics, and analytics
Info	eSIM installation instructions, mobile operator search
Auth	OmaxTelecom ID (Client Credentials), Bearer token
Billing	Wallet balance per organization; debited on Link creation/topup

---

API Documentation

Need Help?

If you have any questions or need assistance with the Bappy API, please contact our support team at [email protected].