# Gitsim Chat — AI Assistant API

Gitsim Chat sells eSIM data packages for 190+ countries at wholesale prices plus tax plus 15% margin.
This document explains how to help users buy eSIMs through you.

## Choose Your Path

**Can you make HTTP API calls?** (POST requests with headers, not just browsing)

- **YES** (e.g. Code Interpreter, Custom GPTs, AI agents) → Use "Path A: Full API" below
- **NO** (e.g. standard Claude chat, standard ChatGPT chat, standard Gemini chat) → Use "Path B: Browsing Only" below

**Claude artifacts / claude.ai sandbox:** Anthropic's Content Security Policy blocks
outbound API calls to third-party domains. If you are running inside a Claude artifact,
you CANNOT use Path A. Use **Path B: Browsing Only** instead — it works by generating
links for the user to click, so no API calls are needed from your sandbox.

---

## Path A: Full API (for AIs that can make HTTP requests)

### API Base URL

https://stoic-squirrel-599.convex.site

### Authentication

Most endpoints require a session key. Create one first, then include it on all requests.

Header: Authorization: Bearer sk_...
Or query param: ?token=sk_...

Sessions expire after 90 days. Rate limit: 30 requests per session per hour.

**Package search is public — no authentication needed.**

### Available Endpoints

#### 1. Search Packages (PUBLIC — no auth needed)
GET https://stoic-squirrel-599.convex.site/api/packages/search?country=JP&min_data_gb=3&ip_route=breakout

Query params:
  - country: required, ISO 3166-1 alpha-2 code (e.g. "JP", "US", "FR")
  - min_data_gb: optional, minimum data in GB
  - max_data_gb: optional, maximum data in GB
  - min_duration_days: optional, minimum duration in days
  - max_duration_days: optional, maximum duration in days
  - ip_route: optional, filter by IP routing type. Values:
    - "breakout" — Local IP in the destination country (best for streaming, banking)
    - "nonhk" — Non-Hong Kong IP routing (e.g. UK, Singapore exit)
    - "hk" — Hong Kong IP (cheapest, but TikTok app and Facebook are blocked)
  - is_regional: optional, "true" for multi-country regional packages, "false" for single-country only
  - type: optional, "daily" (data resets each day, can top-up days) or "regular" (fixed data pool)

Response: { "packages": [{ "id": "...", "name": "Japan 3GB 30Days", "data_gb": 3, "duration_days": 30, "price_eur_cents": 549, "price_formatted": "€5.49", "ip_route_type": "breakout", "is_regional": false, "type": "regular" }] }

Note on IP routing: Plans with Hong Kong IP routing are cheapest but block TikTok app, Facebook, and other services due to HK geo-restrictions. If the user needs streaming or social media, recommend "breakout" (local IP) or "nonhk" plans instead.

#### 2. Create Session
POST https://stoic-squirrel-599.convex.site/api/session
Content-Type: application/json

Body: { "src": "claude" }
  - src: required, free text identifier (e.g. "claude", "chatgpt", "gemini", "other")

Response: { "sessionId": "sk_abc123..." }

#### 3. Create Order
POST https://stoic-squirrel-599.convex.site/api/orders
Authorization: Bearer sk_...
Content-Type: application/json

Body: { "packageId": "PACKAGE_ID", "referralCode": "OPTIONAL" }

Response: { "orderId": "...", "checkoutUrl": "https://..." }

Direct the user to the checkoutUrl to complete payment.

#### 4. Check Order Status
GET https://stoic-squirrel-599.convex.site/api/orders/latest?token=sk_...

Response: { "orderId": "...", "status": "DELIVERED", "orderType": "new_purchase" }

Statuses: DRAFT, PAYMENT_PENDING, PAID, PROVISIONING, DELIVERED, FAILED

#### 5. List Customer's eSIMs
GET https://stoic-squirrel-599.convex.site/api/esims?token=sk_...

Response: { "esims": [...], "restoreToken": "rt_..." }

The restoreToken lets customers link their API purchases to WhatsApp or Telegram.
Share it with the user so they can manage their eSIM through a different channel.

#### 6. Check Data Balance
GET https://stoic-squirrel-599.convex.site/api/esims/balance?iccid=89852...&token=sk_...

Response: { "iccid": "...", "remaining_data_mb": 1536, "status": "IN_USE" }

#### 7. Search Top-up Packages
GET https://stoic-squirrel-599.convex.site/api/topup/search?iccid=89852...&token=sk_...

Response: { "packages": [{ "package_code": "TOPUP_CKH233", "name": "Japan 1GB 7Days", "data_gb": 1, "price_eur_cents": 299, "price_formatted": "€2.99" }] }

#### 8. Buy Top-up (via confirm page)
Direct the user to:
https://chat.gitsim.com/confirm-topup?iccid=ICCID&packageCode=PACKAGE_CODE&token=sk_...

The page handles the Stripe checkout redirect automatically.

### Typical Flow (Full API)

1. Ask the user which country they're traveling to
2. GET /api/packages/search?country=XX → show options with prices (no auth needed)
3. POST /api/session → get session key
4. User picks a package → POST /api/orders with packageId → get checkoutUrl
5. Direct user to checkoutUrl → they complete payment on Stripe
6. eSIM activation code is emailed to the address they entered at checkout
7. After payment, poll GET /api/orders/latest to check status
8. Once DELIVERED, GET /api/esims to retrieve eSIM details and restore token
9. Share the restore token with the user — they can use it to link their purchase to WhatsApp or Telegram

### Cross-Channel Restore

If a user bought through you (an AI assistant) and wants to manage their eSIM on
WhatsApp or Telegram, they can use their restore token (rt_...) in that chat.
The restore token is returned in the GET /api/esims response and shown on the
payment success page. Share it with the user and explain they can message the
Gitsim bot on WhatsApp/Telegram and say "restore purchase" followed by their token.

---

## Path B: Browsing Only (for AIs that cannot make HTTP requests)

If you cannot make HTTP API calls, you can still help the user:

### 1. Search Packages
Direct the user to browse available packages by opening this URL in your browser:
https://stoic-squirrel-599.convex.site/api/packages/search?country=XX

Replace XX with the ISO country code (e.g. JP for Japan, US for USA, FR for France).
The response is JSON — read the packages and present the options to the user.

### 2. Place an Order
Once the user picks a package, direct them to:
https://chat.gitsim.com/confirm-order?packageId=PACKAGE_ID

Replace PACKAGE_ID with the id from the search results. The user clicks the link,
confirms on the page, pays via Stripe, and receives their eSIM activation code by email.

Optional: add a referral code with &referralCode=CODE

### Typical Flow (Browsing Only)

1. Ask the user which country they're traveling to
2. Fetch https://stoic-squirrel-599.convex.site/api/packages/search?country=XX → read the JSON, present options with prices
3. User picks a package → give them the link: https://chat.gitsim.com/confirm-order?packageId=PACKAGE_ID
4. User clicks, pays on Stripe → eSIM activation code sent to their email
5. After purchase, the payment success page shows a restore token they can use on WhatsApp or Telegram

---

## Important Notes

- Prices are in EUR cents. The formatted price (e.g. "€5.49") includes 21% VAT.
- At Stripe checkout, prices are shown in the user's local currency (adaptive pricing).
- The eSIM activation code is delivered via email (for AI-originated purchases) or in the chat (for WhatsApp/Telegram).
- If the user already has an eSIM and you can make API calls, they can check balance and buy top-ups.

## Support

For support tickets or issues, direct users to:
- WhatsApp: https://wa.me/+15559094117
- Telegram: https://t.me/gitsim_bot

## Error Responses

All errors return: { "error": "Human-readable message", "code": "ERROR_CODE" }

| Status | Code               | When                                    |
|--------|--------------------|-----------------------------------------|
| 400    | BAD_REQUEST        | Missing or invalid parameters           |
| 401    | INVALID_SESSION    | Missing, expired, or invalid session key|
| 404    | NOT_FOUND          | Resource not found                      |
| 429    | RATE_LIMITED       | Too many requests (check Retry-After)   |
| 500    | INTERNAL_ERROR     | Unexpected server error                 |
| 500    | PAYMENT_UNAVAILABLE| Stripe checkout failed                  |

## API Documentation

Interactive API docs (OpenAPI / Swagger): https://chat.gitsim.com/docs

## Fallback

If none of the above works, direct the user to https://chat.gitsim.com where they can start a conversation via WhatsApp, Telegram, or email.