Pre-release · 2026

API Твойшаг: для бухгалтеров, маркетплейсов и интеграторов

REST + JSON, OAuth 2.0, серверы в РФ. Подключаем самозанятого к вашей системе: чеки, договоры, документы, налоговый календарь в одном кабинете.

API в проработке. Сроков запуска нет: партнёрское API планируем после public beta самого кабинета. Публикуем roadmap, технические решения и форму ранних запросов. Никакой Swagger пока нет: лучше честно сказать «нет», чем дать ссылку на endpoint, которого ещё не существует.

Кому пригодится

📊
Бухгалтерским сервисам
Подтянуть чеки и расходы самозанятых клиентов в свою отчётность. Меньше ручного ввода, быстрее закрытие месяца.
🛒
Маркетплейсам и платформам
Соблюсти 289-ФЗ: автоматическая выписка чеков продавцам-самозанятым, мониторинг лимита 2,4 млн, защита от штрафов.

Сценарии для юридических агентств и массовая проверка заказчиков — часть B2B-направления, которое отложено; сроков и решения о запуске нет.

Технические решения

Базовый URL
https://api.tvoyshag.ru/v1/
Протокол
REST + JSON. Content-Type: application/json; charset=utf-8
Аутентификация
OAuth 2.0 (Authorization Code + PKCE для web, Client Credentials для server-to-server)
Версионирование
Версия в URL: /v1/. Сроки поддержки прежней версии объявим до выхода следующей
Rate limits
60 req/min на токен (basic), 600 req/min (business). Headers X-RateLimit-*
Хранение данных
Персональные данные хранятся на серверах в РФ (152-ФЗ); какие данные и кому передаются — по пунктам в политике конфиденциальности
Webhooks
Подписка на события (новый чек, превышение лимита, ответ ФНС). Retry с экспоненциальным backoff
Идемпотентность
Для POST поддерживается Idempotency-Key header (как у Stripe)
Pagination
Cursor-based: ?cursor=...&limit=50. Без offset (стабильно при росте данных)
SDK
Spec OpenAPI 3.1 для генерации клиентов; готовые SDK — по запросам партнёров

Планируемые ресурсы

/receipts Доходы и расходы: запись операций, импорт банковской выписки, оценка налога НПД за месяц. v1 · без срока
/clients CRM-контрагенты: ФИО/наименование, ИНН, контакты, история сделок. v1 · без срока
/contracts Генерация договоров по ИНН клиента и светофор риска по критериям приказов Минтруда. v1 · без срока
/limit Текущий статус лимита 2,4 млн ₽: использовано, осталось, прогноз даты упирания. v1 · без срока
/documents Акты и счета с платёжным QR. PDF по запросу. v1.1 · без срока
/tax-calendar Календарь налоговых событий с напоминаниями и автоплатежами. v1.1 · без срока
/ip-migration Заявление Р21001, выбор УСН/патента, отслеживание статуса в ФНС. v1.2 · без срока
/webhooks Регистрация callback-эндпоинтов на события сервиса. v1.2 · без срока

Пример типичного запроса

Получить остаток лимита самозанятого (эскиз: внутри кабинета лимит, доля использования и прогноз даты исчерпания уже считаются, формат публичного ответа не зафиксирован):

# GET текущего статуса лимита curl "https://api.tvoyshag.ru/v1/limit" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Accept: application/json" # Ответ 200 OK { "year": 2026, "limit_total": 2400000, "earned": 1820000, "left": 580000, "used_pct": 75.83, "status": "amber", "forecast": { "monthly_avg": 280000, "months_until_limit": 2.07, "projected_date": "2026-07-22" }, "actions": [ { "code": "prepare_ip", "title": "Подготовить переход на ИП", "urgency": "recommended" } ] }

Roadmap

Этап 1
Закрытое тестирование с партнёрами OAuth flow, /receipts и /clients. 10–15 интеграторов по приглашению.
Этап 2
Public beta API (после public beta кабинета) /receipts, /clients, /contracts, /limit. Публикация OpenAPI-спеки; SDK — по запросам партнёров.
Этап 3
v1.1: /documents, /tax-calendar Полный документооборот. Налоговый календарь с автоплатежами.
Этап 4
v1.2: /ip-migration, /webhooks Автоматизация перехода на ИП. Подписка на события через webhooks.
Этап 5
v2 (планируется) GraphQL endpoint, расширенная аналитика, real-time подписки на лимит.

Чего пока не будет

  • Без статуса production-ready. До конца public beta API считается preview, возможны breaking changes.
  • Без SLA на uptime. Гарантий доступности сейчас нет ни на одном тарифе: для API действуют тот же целевой уровень и те же условия, что в п. 8 Пользовательского соглашения.
  • Без массовой регистрации. Доступ по заявке, чтобы выдержать стабильность во время beta.
  • Без публичной OpenAPI до выхода API. Сейчас спека пишется и меняется, публиковать черновики нет смысла.
Запросить ранний доступ к API Напишите кто вы (бухгалтерский сервис / маркетплейс / агентство) и что хотите интегрировать — ответим на почту в рабочие дни.
Написать