Гайд оператора

Гайд ведёт от пустого сервера до первой продажи, а затем описывает ежедневную работу: заказы, возвраты, баланс, бэкапы, обновления. На настройку заложите час. Большая часть этого часа уходит на ожидание оптового аккаунта и DNS-записи.

Другие документы: обзор · гайд для агентов · онбординг · интеграции · SDK

1. Что вы поднимаете

            https://esim.example.com
                      │
                   Caddy (80, 443, Let's Encrypt)
      ┌───────────────┼──────────────────────────────┐
      │               │                              │
   store          rails (/agents/*)              node (/.well-known/ai-market.json, /ai-market/*)
 покупают люди   покупают агенты по x402        хабы находят ваши предложения
      │               │
      └──── ваш баланс в eSIM Access ────┘     платежи идут на ваши кошельки

• store — сайт: страницы стран, оплата, страница заказа с QR-кодом.
• rails — узел продавца для ИИ-агентов: бесплатные предложения, платные заказы по x402.
• node — это aimarket node. Он сообщает хабам AIMarket, что вы продаёте, чтобы агенты вас нашли. Запускайте его последним, когда всё остальное работает.
• Caddy получает и продлевает HTTPS-сертификат и раздаёт запросы трём сервисам.

store и rails покупают с одного оптового аккаунта. Ни один из них не держит деньги: покупатели платят на ваши адреса, а кит только читает сети, чтобы увидеть поступление.

2. Перед началом

3. Оптовый аккаунт

1. Зарегистрируйтесь на esimaccess.com и подтвердите почту.
2. Пополните баланс (в консоли: баланс, затем пополнение). Минимум — $50. Каждая проданная eSIM оплачивается с этого баланса по оптовой цене, так что это ваш товарный запас, а не комиссия.
3. Откройте раздел разработчика (API) в консоли. Там два значения: AccessCode и SecretKey. Обращайтесь с SecretKey как с паролем.

Песочницы нет: каждый заказ через API настоящий. Два способа проверить дёшево:

• Закажите самый дешёвый тариф (несколько десятков центов) и отмените неиспользованный профиль. Неиспользованные профили возвращаются на баланс.
• До первого пополнения попросите в поддержке небольшой тестовый кредит: Customer Support, затем Submit ticket, тип «Top Up». Объясните, что подключаете API и вам нужно несколько долларов на тестовые заказы.

4. Сервер и домен

1. Создайте A-запись домена на IPv4-адрес сервера. Проверьте со своего компьютера:

dig +short esim.example.com

2. Установите Docker на сервер (docs.docker.com/engine/install) и проверьте, что compose работает:

docker compose version

3. Откройте порты 80 и 443 в файрволе сервера и в панели хостинга. Let's Encrypt проверяет порт 80, прежде чем выдать сертификат.

5. Скачайте кит и настройте его

git clone https://github.com/alexar76/esim-operator-kit.git
cd esim-operator-kit
cp .env.example .env
nano .env

Как считается цена. Цена = опт × (1 + MARGIN_PCT/100), но не меньше опт + MIN_MARGIN_USD. Округление — вверх до цента. С настройками по умолчанию (100 % и $1.00) Франция 1 ГБ на 7 дней стоит $0.70 оптом и продаётся за $1.70. Тариф на 20 ГБ за $9.00 оптом продаётся за $18.00. Розничные eSIM-магазины обычно берут $4–8 за маленькие тарифы, так что запас есть.

Только адреса. Каждый PAY_TO_* — адрес, на который вы принимаете. Киту никогда не нужен приватный ключ или сид-фраза. Если инструкция или человек просит положить их в .env, это ошибка.

6. Положите ключи

Ключи лежат в secrets/, по одному значению в файле. Папка исключена из git и монтируется в контейнеры только для чтения. Введите значения так, чтобы они не попали в историю команд:

cd ~/esim-operator-kit
umask 077
printf 'AccessCode: '; read -rs v; printf %s "$v" > secrets/esimaccess_access_code; echo
printf 'SecretKey: '; read -rs v; printf %s "$v" > secrets/esimaccess_secret_key; echo
unset v

Контейнеры работают от пользователя 1000, поэтому отдайте ему файлы ключей и папки данных:

mkdir -p data/store data/rails data/node data/caddy
sudo chown 1000:1000 secrets/*
sudo chown -R 1000:1000 data/store data/rails data/node
ls -l secrets

Сама папка остаётся вашей, так что файлы можно добавлять и позже. Каждому новому файлу ключа нужны те же sudo chown 1000:1000 и chmod 600.

В secrets/README.md перечислены все необязательные файлы: ключ CDP, ключи tonapi и TronGrid, ключи Stripe.

7. Запуск в демо-режиме

docker compose up -d --build
docker compose ps
docker compose logs --tail 30 store rails

Первая сборка занимает несколько минут. Затем проверьте три вещи:

curl -s https://esim.example.com/agents/healthz
curl -s -X POST https://esim.example.com/agents/quote -H 'content-type: application/json' \
  -d '{"country":"FR","min_gb":3,"min_days":7,"limit":3}'

• Проверка здоровья отвечает "ok":true и показывает число предложений, у eSIM Access их около 1700. "demo":true пока ожидаемо.
• Запрос предложений возвращает настоящие тарифы по вашим ценам.
• https://esim.example.com/ показывает вашу витрину с демо-баннером. Откройте страну и пройдите оплату: каждый шаг оплаты отвечает «Демо-режим: оплата отключена».

Если проверка отвечает "ok":false, оптовые ключи неверны или не читаются. См. раздел 14.

Проверьте цены. Команда печатает баланс и лучшие предложения по любым странам с вашей наценкой, рядом с каждым — оптовая цена:

docker compose exec -T rails node scripts/catalog.mjs FR ES IT US JP TH

Поменяйте MARGIN_PCT или MIN_MARGIN_USD в .env и примените: docker compose up -d.

8. Платежи

Каждый способ включается, когда задан его адрес (и ключ, где он нужен). Включите те, которыми пользуются ваши покупатели. USDT в Tron — самый частый способ платить криптой; за ним идут USDT и USDC в EVM-сетях и USDT в TON.

Отправленный платёж (все способы, кроме Base без газа и карт) ищется в течение 24 часов после создания заказа.

Ключ Coinbase Developer Platform. Он включает USDC в Base без газа для людей и заказы агентов по x402. Без него витрина всё равно принимает USDC в Base обычным переводом, но узел для агентов заказы не принимает.

1. Войдите на portal.cdp.coinbase.com и создайте проект.
2. API Keys: создайте секретный API-ключ и скачайте его JSON-файл.
3. Скопируйте файл в secrets/cdp_api_key.json (в нём id и privateKey), затем выполните sudo chown 1000:1000 secrets/cdp_api_key.json && sudo chmod 600 secrets/cdp_api_key.json и docker compose up -d.

Stripe. В панели Stripe добавьте вебхук https://<ваш домен>/api/stripe/webhook с событиями checkout.session.completed и checkout.session.async_payment_succeeded. Секретный ключ (sk_live_…) положите в secrets/stripe_secret_key, а секрет подписи вебхука (whsec_…) — в secrets/stripe_webhook_secret.

Лимиты запросов. Публичных TronGrid, tonapi и RPC хватает небольшому магазину. Когда продажи станут регулярными, добавьте бесплатный ключ TronGrid и ключ tonapi, а EVM_RPC_<номер> и SOLANA_RPC направьте на своего провайдера.

9. Агенты и федерация

Узел rails уже отвечает агентам по адресу https://<ваш домен>/agents/. Чтобы агенты находили вас поиском на хабе, опишите узел для федерации и анонсируйте его.

1. Сгенерируйте node.toml из живого каталога. Подставьте своё название, домен и PRODUCT_ID:

docker compose exec -T rails node scripts/node-toml.mjs \
  --name "My Travel eSIM" --url https://esim.example.com \
  --product esim-mytravel --upstream http://rails:9490 > node.toml
head -20 node.toml

2. Запустите узел:

docker compose --profile federation up -d --build node
curl -s https://esim.example.com/.well-known/ai-market.json | head -c 400; echo

3. Проверьте его так, как проверит хаб, и анонсируйте:

docker compose exec node aimarket doctor --url https://esim.example.com
docker compose exec node aimarket node knock --config /node/node.toml --hub https://modelmarket.dev

Перед тем как внести вас в каталог, хаб вызывает esim.quote с настоящей страной. После этого агент, который ищет на хабе «eSIM France», получает ваши предложения. Оплата никогда не идёт через хаб: агент платит вашему узлу по x402, прямо на ваш кошелёк.

В data/node/ лежит ключ подписи узла — это его идентичность в федерации. Сделайте бэкап. Повторите пункт 1, когда в каталоге появятся новые страны.

10. Тестовый заказ и запуск продаж

1. В .env поставьте DEMO_MODE=0 и ещё раз сверьте адреса PAY_TO_* символ за символом.
2. Примените:

docker compose up -d
curl -s https://esim.example.com/agents/healthz

Должно быть "demo":false. "paid_orders":true появляется, когда заданы ключ CDP и PAY_TO_EVM.

3. Купите самый дешёвый тариф какой-нибудь страны в своей витрине, своим кошельком, в той сети, которой, по-вашему, чаще всего будут платить покупатели. QR-код должен появиться на странице заказа в течение минуты.
4. Проверьте платёж в кошельке и заказ в консоли eSIM Access.
5. Если eSIM вам не нужна, отмените неиспользованный профиль в консоли eSIM Access. Оптовая цена вернётся на баланс. Ваш платёж всё равно ушёл на ваш же кошелёк.

Повторите для каждой включённой сети. После этого вы в деле.

11. Ежедневная работа

Заказы. Витрина хранит их в data/store/orders.json. Список тех, что требуют вашего внимания:

sudo jq -r '.[] | select(.status=="refund_due" or .status=="underpaid")
  | [.created_at, .id, .status, .method, (.price_cents/100), .payment.ref, (.payment.payer // "-"), (.error // "")] | @tsv' \
  data/store/orders.json

Покупатели пишут на STORE_CONTACT. Просите у них номер заказа из адреса страницы (/o/<номер>). Не просите полную ссылку: в ней их токен.

Баланс. Держите оптовый баланс выше продаж за несколько дней. Когда его не хватает на заказ, оплата пишет «Тариф временно недоступен» и не берёт деньги. Проверить баланс:

docker compose exec -T rails node scripts/catalog.mjs | head -1

Логи.

docker compose logs -f --tail 100 store rails

В логах никогда нет кодов активации и ключей.

Бэкапы. Ежедневно сохраняйте data/ и secrets/ куда-нибудь вне сервера:

• data/store/: заказы. Потеряете их — страницы заказов у покупателей перестанут работать.
• data/rails/: заказы агентов, ключ их статус-токенов и ключ подписи узла.
• data/node/: идентичность в федерации.
• data/caddy/: сертификаты. Их можно выпустить заново, но бэкап избавит от лимитов Let's Encrypt.

Обновления.

git pull
docker compose up -d --build
docker compose --profile federation up -d --build node    # если запускаете узел федерации

Читайте заметки к выпуску, прежде чем обновлять магазин, который продаёт.

12. Заказы агентов

Агенты покупают через POST /agents/order (см. гайд для агентов). Узел проверяет платёж x402, покупает профиль и проводит платёж только после того, как профиль создан. Если проведение не удалось, профиль отменяется, а оптовая цена возвращается на баланс. Заказы агентов записываются в data/rails/orders.json, без кодов активации. USDC приходят на PAY_TO_EVM в сети Base.

13. Законы, налоги и условия

Это не юридическая и не налоговая консультация. Прежде чем продавать, спросите бухгалтера в своей стране.

• Продавец — вы. Покупатели покупают у вас, на ваших условиях. eSIM Access — ваш поставщик. Возвраты, поддержка и налоги — ваши.
• Условия и конфиденциальность. eSIM Access ждёт, что на вашем сайте опубликованы условия продажи и политика конфиденциальности. Задайте STORE_TERMS_URL и STORE_PRIVACY_URL. В условиях опишите возвраты (установленную eSIM обычно вернуть нельзя), совместимость устройства (разблокированный телефон с поддержкой eSIM) и момент начала действия.
• НДС в ЕС. Телекоммуникационные услуги потребителям облагаются в стране покупателя. Единое окно OSS (One-Stop Shop) позволяет декларировать все страны ЕС одной декларацией. Вне ЕС правила другие.
• Крипта. Можно ли принимать криптовалюту и как её учитывать, зависит от вашей страны. Храните записи заказов: у витрины есть сеть, транзакция и сумма каждого платежа.
• Персональные данные. Витрина ничего не спрашивает у покупателей: ни имени, ни почты. Она хранит заказ (тариф, цена, способ) и платёж (транзакция и адрес плательщика). Адрес в блокчейне всё же может считаться персональными данными по GDPR, так что упомяните его в политике конфиденциальности.

14. Решение проблем