Налоговые консультации (tbank.tax_consult)

Обработка заявок на налоговые консультации со стороны партнёра-исполнителя: карточка заявки, чат с клиентом, вложения и переходы воркфлоу (взять в работу, запросить уточнение, выставить оплату, отметить готовой и т.д.).

  • Хост: secured-openapi.tbank.ru, требуется mTLS-сертификат (cert).

  • Воркфлоу использует оптимистичную блокировку: передавайте cas_version из карточки заявки — он уходит в заголовок If-Match и защищает от гонок.

  • Вложения: загрузка — octet-stream + заголовки имени/типа файла, скачивание — «сырые» байты.

  • Клиенты: tbank.tax_consult.TaxConsultClient (async) и tbank.tax_consult.sync.TaxConsultClient (sync).

Заявка, чат и воркфлоу

from tbank.tax_consult import TaxConsultClient
from tbank.tax_consult.models import SendMessageRequest

client = TaxConsultClient(
    token="business-token",
    cert=("client.pem", "client-key.pem"),
)

req = await client.get_request(tax_request_id)     # статус, версия, флаг непрочитанных
print(req.status, req.cas_version)

# взять в работу и переписываться с клиентом
state = await client.start_review(tax_request_id, req.cas_version)
state = await client.start_work(tax_request_id, state.cas_version)

chat = await client.get_chat(tax_request_id, limit=50, offset=0)
await client.send_message(tax_request_id, SendMessageRequest(text="Уточните ИНН"))

# выставить оплату, подтвердить и завершить
state = await client.set_pending_payment(tax_request_id, state.cas_version)
state = await client.confirm_payment(tax_request_id, state.cas_version)
state = await client.mark_ready(tax_request_id, state.cas_version)

Прочие переходы: request_clarification, decline, cancel.

Вложения

uploaded = await client.upload_attachment(
    tax_request_id, content=pdf_bytes, file_name="answer.pdf", file_type="application/pdf",
)
data = await client.download_attachment(tax_request_id, uploaded.attachment_id)  # bytes

Клиент

class tbank.tax_consult.aio.TaxConsultClient(token, *, base_url=None, sandbox=False, cert=None, verify=True, retry=None, transport=None)[исходный код]

Базовые классы: BaseAsyncClient

Асинхронный клиент налоговых консультаций: карточка заявки, чат с менеджером, вложения и переходы воркфлоу заявки.

Весь домен работает на secured-хосте и требует mTLS-сертификата (cert). Переходы воркфлоу используют оптимистичную блокировку: передайте cas_version из карточки заявки (уходит в заголовок If-Match). Провод — camelCase.

Параметры:
async get_request(tax_request_id)[исходный код]

Карточка заявки: тип, статус, версия, непрочитанные сообщения.

Параметры:

tax_request_id (str)

Тип результата:

ConsultRequest

async get_chat(tax_request_id, *, limit, offset)[исходный код]

Сообщения чата заявки (постранично).

Параметры:

  • tax_request_id (str)

  • limit (int)

  • offset (int)

Тип результата:

ChatPage

async send_message(tax_request_id, request)[исходный код]

Отправить сообщение в чат заявки.

Параметры:
Тип результата:

None

async download_attachment(tax_request_id, attachment_id)[исходный код]

Скачать вложение заявки (бинарное содержимое).

Параметры:

  • tax_request_id (str)

  • attachment_id (str)

Тип результата:

bytes

async upload_attachment(tax_request_id, content, *, file_name, file_type, idempotency_key=None)[исходный код]

Загрузить вложение к заявке (octet-stream).

Параметры:

  • tax_request_id (str)

  • content (bytes)

  • file_name (str)

  • file_type (str)

  • idempotency_key (str | None)

Тип результата:

UploadAttachmentResult

async start_review(tax_request_id, cas_version)[исходный код]

Взять заявку на рассмотрение.

Параметры:

  • tax_request_id (str)

  • cas_version (int)

Тип результата:

WorkflowState

async start_work(tax_request_id, cas_version)[исходный код]

Начать работу по заявке.

Параметры:

  • tax_request_id (str)

  • cas_version (int)

Тип результата:

WorkflowState

async request_clarification(tax_request_id, cas_version)[исходный код]

Запросить уточнение у клиента.

Параметры:

  • tax_request_id (str)

  • cas_version (int)

Тип результата:

WorkflowState

async decline(tax_request_id, cas_version)[исходный код]

Отклонить заявку.

Параметры:

  • tax_request_id (str)

  • cas_version (int)

Тип результата:

WorkflowState

async cancel(tax_request_id, cas_version)[исходный код]

Отменить заявку.

Параметры:

  • tax_request_id (str)

  • cas_version (int)

Тип результата:

WorkflowState

async set_pending_payment(tax_request_id, cas_version)[исходный код]

Перевести заявку в ожидание оплаты.

Параметры:

  • tax_request_id (str)

  • cas_version (int)

Тип результата:

WorkflowState

async confirm_payment(tax_request_id, cas_version)[исходный код]

Подтвердить оплату заявки.

Параметры:

  • tax_request_id (str)

  • cas_version (int)

Тип результата:

WorkflowState

async mark_ready(tax_request_id, cas_version)[исходный код]

Отметить заявку готовой (ответ предоставлен).

Параметры:

  • tax_request_id (str)

  • cas_version (int)

Тип результата:

WorkflowState

Модели

class tbank.tax_consult.models.TaxConsultModel[исходный код]

Базовые классы: BaseModel

Базовая модель домена: snake_case в Python, camelCase на проводе.

model_config = {'alias_generator': <function to_camel>, 'extra': 'ignore', 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class tbank.tax_consult.models.ConsultRequest(*, clientId, clientFullName, requestType, status, hasUnreadMessages, casVersion, createdAt)[исходный код]

Базовые классы: TaxConsultModel

Карточка заявки на консультацию.

Параметры:
model_config = {'alias_generator': <function to_camel>, 'extra': 'ignore', 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class tbank.tax_consult.models.WorkflowState(*, status, casVersion)[исходный код]

Базовые классы: TaxConsultModel

Состояние заявки после перехода воркфлоу.

Параметры:
model_config = {'alias_generator': <function to_camel>, 'extra': 'ignore', 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class tbank.tax_consult.models.ChatAttachment(*, id, name, mime, size, createdAt)[исходный код]

Базовые классы: TaxConsultModel

Параметры:
model_config = {'alias_generator': <function to_camel>, 'extra': 'ignore', 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class tbank.tax_consult.models.ChatMessage(*, id, authorType, createdAt, text=None, attachments=None)[исходный код]

Базовые классы: TaxConsultModel

Параметры:
model_config = {'alias_generator': <function to_camel>, 'extra': 'ignore', 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class tbank.tax_consult.models.ChatMeta(*, offset, count, total)[исходный код]

Базовые классы: TaxConsultModel

Параметры:
model_config = {'alias_generator': <function to_camel>, 'extra': 'ignore', 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class tbank.tax_consult.models.ChatPage(*, meta, values=<factory>)[исходный код]

Базовые классы: TaxConsultModel

Страница сообщений чата заявки.

Параметры:
model_config = {'alias_generator': <function to_camel>, 'extra': 'ignore', 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class tbank.tax_consult.models.SendMessageRequest(*, text=None, attachments=None)[исходный код]

Базовые классы: TaxConsultModel

Параметры:

  • text (str | None)

  • attachments (List[str] | None)

model_config = {'alias_generator': <function to_camel>, 'extra': 'ignore', 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class tbank.tax_consult.models.UploadAttachmentResult(*, attachmentId)[исходный код]

Базовые классы: TaxConsultModel

Параметры:

attachmentId (str)

model_config = {'alias_generator': <function to_camel>, 'extra': 'ignore', 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Перечисления

class tbank.tax_consult.enums.RequestType(*values)[исходный код]

Базовые классы: str, Enum

Тип заявки на налоговую консультацию.

COMMENT = 'Comment'
DECLARATION = 'Declaration'
class tbank.tax_consult.enums.RequestStatus(*values)[исходный код]

Базовые классы: str, Enum

Статус заявки на налоговую консультацию.

ASSIGNED = 'Assigned'
IN_PROGRESS = 'InProgress'
ANSWERED = 'Answered'
SEEN_BY_CLIENT = 'SeenByClient'
NEEDS_CLARIFICATION = 'NeedsClarification'
CLOSED = 'Closed'
SENT_TO_PARTNER = 'SentToPartner'
DRAFT = 'Draft'
NEW = 'New'
PREPROCESS = 'Preprocess'
PARTNER_GENERATING_REPORT_DATA = 'PartnerGeneratingReportData'
PARTNER_IN_PROGRESS = 'PartnerInProgress'
PENDING_PASSPORT = 'PendingPassport'
PENDING_PAYMENT = 'PendingPayment'
PAYMENT_DONE = 'PaymentDone'
READY = 'Ready'
PARTNER_READY = 'PartnerReady'
ACKNOWLEDGE = 'Acknowledge'
CANCELLED = 'Cancelled'
DECLINED = 'Declined'
CLARIFICATION = 'Clarification'
class tbank.tax_consult.enums.ChatAuthorType(*values)[исходный код]

Базовые классы: str, Enum

Тип автора сообщения в чате.

MANAGER = 'Manager'
CLIENT = 'Client'