API Твойшаг — для бухгалтеров, маркетплейсов и интеграторов
REST + JSON, OAuth 2.0, серверы в РФ. Подключаем самозанятого к вашей системе: чеки, договоры, документы, налоговый календарь — единым кабинетом.
API в разработке. Запуск v1 — Q3 2026 вместе с public beta самого сервиса.
Публикуем roadmap, технические решения и форму ранних запросов. Никакой Swagger
пока нет: лучше честно сказать «нет», чем дать ссылку на endpoint, которого ещё не существует.
Кому пригодится
Бухгалтерским сервисам
Подтянуть чеки и расходы самозанятых клиентов в свою отчётность. Меньше ручного ввода — быстрее закрытие месяца.
Маркетплейсам и платформам
Соблюсти 289-ФЗ: автоматическая выписка чеков продавцам-самозанятым, мониторинг лимита 2,4 млн, защита от штрафов.
Юридическим агентствам
Массовая проверка договоров клиентов на 11 признаков переквалификации. Автогенерация претензий по дебиторке.
Технические решения
- Базовый 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/,/v2/. Минимум 12 месяцев поддержки после deprecation - Rate limits
- 60 req/min на токен (basic), 600 req/min (business). Headers
X-RateLimit-* - Хранение данных
- Только серверы в РФ (152-ФЗ). Yandex Cloud, реплики в Москве/СПб/Владимире
- Webhooks
- Подписка на события (новый чек, превышение лимита, ответ ФНС). Retry с экспоненциальным backoff
- Идемпотентность
- Для POST поддерживается
Idempotency-Keyheader (как у Stripe) - Pagination
- Cursor-based:
?cursor=...&limit=50. Без offset (стабильно при росте данных) - SDK
- Python, Node.js, PHP — на старте. Spec OpenAPI 3.1 для генерации остальных
Планируемые ресурсы в v1
/receipts
Создание и получение чеков «Мой налог». Прокси к ФНС API с обработкой ошибок.
v1 (Q3)
/clients
CRM-контрагенты: ФИО/наименование, ИНН, контакты, история сделок.
v1 (Q3)
/contracts
Генерация и проверка договоров. Анализ на 11 признаков переквалификации.
v1 (Q3)
/limit
Текущий статус лимита 2,4 млн ₽: использовано, осталось, прогноз даты упирания.
v1 (Q3)
/documents
Акты, счета, претензии. Подпись через КЭП, отправка через ЭДО.
v1.1 (Q4)
/tax-calendar
Календарь налоговых событий с напоминаниями и автоплатежами.
v1.1 (Q4)
/ip-migration
Заявление Р21001, выбор УСН/патента, отслеживание статуса в ФНС.
v1.2 (Q1.2027)
/webhooks
Регистрация callback-эндпоинтов на события сервиса.
v1.2 (Q1.2027)
Пример типичного запроса
Получить остаток лимита самозанятого (запрос как будет в v1):
# 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
Q2 2026
Закрытое тестирование с партнёрами
OAuth flow, /receipts и /clients. 10–15 интеграторов по приглашению.
Q3 2026
Public beta v1 (вместе с самим сервисом)
/receipts, /clients, /contracts, /limit. OpenAPI спека опубликована. SDK для Python/Node/PHP.
Q4 2026
v1.1: /documents, /tax-calendar
Полный документооборот. Налоговый календарь с автоплатежами.
Q1 2027
v1.2: /ip-migration, /webhooks
Автоматизация перехода на ИП. Подписка на события через webhooks.
Q2 2027
v2 (планируется)
GraphQL endpoint, расширенная аналитика, real-time подписки на лимит.
Чего пока не будет
- Без статуса production-ready. До конца public beta API считается preview — могут быть breaking changes.
- Без SLA на uptime. На production цель — 99.9%, но гарантии — только в платных enterprise-планах после v1.0.
- Без массовой регистрации. Доступ — по заявке, чтобы выдержать стабильность во время beta.
- Без публичной OpenAPI до Q3. Сейчас спека пишется и меняется — публиковать черновики не имеет смысла.
Запросить ранний доступ к API
Напишите кто вы (бухгалтерский сервис / маркетплейс / агентство) и что хотите интегрировать. Ответим в течение 3 рабочих дней.
Написать