Закрывающие документы

УПД, акт сверки и подключение ЭДО для аккаунта, который платит по счёту от организации.

Адрес

Авторизация

Ключ управления с правами billing:read, billing:write

УПД формируется в начале каждого месяца на сумму, израсходованную за прошлый месяц, по одному на организацию-плательщика, и отправляется через ЭДО. Организации — те, что сохранены в счетах и организациях; их id — строка UUID — стоит в путях /documents/companies/{id}/….

Методы

Метод	Право	Что делает
`GET /documents`	`billing:read`	Закрывающие документы (УПД), новые первыми
`GET /documents/{id}/pdf`	`billing:read`	Один УПД в PDF
`GET /documents/companies/{id}/reconciliation`	`billing:read`	Акт сверки с организацией за период
`GET /documents/companies/{id}/reconciliation/pdf`	`billing:read`	Тот же акт сверки в PDF
`POST /documents/companies/{id}/edo`	`billing:write`	Подключить организацию к нам в ЭДО или проверить подключение

Список документов

curl https://api.aitunnel.ru/v1/aitunnel/documents \
  -H "Authorization: Bearer sk-aitunnel-mgmt-xxx"

JSON

{
  "enabled": true,
  "data": [
    {
      "id": 412,
      "period": "2026-10",
      "date": "2026-10-31",
      "payer_name": "ООО «Ромашка»",
      "payer_inn": "7707083893",
      "payer_kpp": "773601001",
      "amount": 1600.49,
      "status": "signed",
      "created_at": "2026-11-01T03:00:05.000Z"
    }
  ]
}

Поле	Смысл
`enabled`	`true`, если документы сейчас отправляются через ЭДО
`id`	Номер документа, для `/documents/{id}/pdf`
`period`	Месяц, за который документ: `YYYY-MM`
`date`	Дата на документе: `YYYY-MM-DD`
`payer_name`, `payer_inn`, `payer_kpp`	Организация-покупатель. `payer_kpp` — `null` у предпринимателя
`amount`	Сумма документа, ₽
`status`	Где документ сейчас, см. ниже
`created_at`	Когда документ создан

status	Смысл
`pending`	Сумма определена, документ ещё не создан в ЭДО
`draft`	Черновик готов и ждёт нашей подписи
`sent`	Подписан и отправлен, покупатель ещё не ответил
`signed`	Покупатель подписал
`rejected`	Покупатель отказался подписать
`no_edo`	Покупатель пока недоступен в ЭДО. Проверяется ежедневно; документ уйдёт, когда организация подключится
`error`	ЭДО не принял документ. Отправка повторяется

УПД в PDF

GET /documents/{id}/pdf отдаёт документ файлом: Content-Type: application/pdf.

cURL

curl -o upd.pdf https://api.aitunnel.ru/v1/aitunnel/documents/412/pdf \
  -H "Authorization: Bearer sk-aitunnel-mgmt-xxx"

Акт сверки

GET /documents/companies/{id}/reconciliation считает взаиморасчёты с одной организацией за период. {id} — id сохранённой организации, строка UUID.

curl "https://api.aitunnel.ru/v1/aitunnel/documents/companies/3f9c2a71-5b8e-4d0a-9c6f-1e2d7b4a8c05/reconciliation?from=2026-10-01&to=2026-10-31" \
  -H "Authorization: Bearer sk-aitunnel-mgmt-xxx"

JSON

{
  "from": "2026-10-01",
  "to": "2026-10-31",
  "seller": {
    "name": "Индивидуальный предприниматель Агафонов Никита Андреевич",
    "short_name": "ИП Агафонов Н. А.",
    "inn": "692499040700",
    "signer_position": "Индивидуальный предприниматель"
  },
  "buyer": { "name": "ООО «Ромашка»", "inn": "7707083893", "kpp": "773601001" },
  "opening_balance": 0,
  "rows": [
    {
      "date": "2026-10-04",
      "title": "Оплата (п/п № 512 от 04.10.2026)",
      "debit": 0,
      "credit": 10000
    },
    {
      "date": "2026-10-31",
      "title": "Реализация (УПД № 412 от 31.10.2026)",
      "debit": 1600.49,
      "credit": 0
    }
  ],
  "totals": { "debit": 1600.49, "credit": 10000 },
  "closing_balance": -8399.51
}

Поле	Смысл
`from`, `to`	Период, даты `YYYY-MM-DD`. Оба параметра обязательны, `from` не позже `to`
`seller`	Мы: полное и краткое название, ИНН, должность подписанта
`buyer`	Организация: название, ИНН, КПП (`null` у предпринимателя)
`opening_balance`	Сальдо на начало периода, ₽: больше нуля — организация должна нам, меньше — мы организации
`rows`	Операции периода по дате: `debit` — оказанные услуги (УПД) и возвращённые деньги, `credit` — полученные оплаты
`totals`	Обороты за период: суммы `debit` и `credit`
`closing_balance`	Сальдо на конец периода, ₽, по тому же правилу знака

Тот же акт файлом — GET /documents/companies/{id}/reconciliation/pdf с теми же from и to.

Подключение ЭДО

Чтобы УПД доходили, организация должна быть нашим контрагентом в ЭДО. POST /documents/companies/{id}/edo с оператором организации запрашивает подключение: мы отправляем приглашение.

curl -X POST https://api.aitunnel.ru/v1/aitunnel/documents/companies/3f9c2a71-5b8e-4d0a-9c6f-1e2d7b4a8c05/edo \
  -H "Authorization: Bearer sk-aitunnel-mgmt-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "operator": "diadoc"
  }'

JSON

{
  "id": "3f9c2a71-5b8e-4d0a-9c6f-1e2d7b4a8c05",
  "edo_status": "invited",
  "edo_operator": "diadoc",
  "edo_requested_at": "2026-11-14T13:16:00.000Z",
  "edo_invited_at": "2026-11-14T13:16:01.000Z"
}

operator	Смысл
`diadoc`	Контур.Диадок
`sbis`	Saby (СБИС)
`taxcom`	Такском
`astral`	Астрал
`1c`	1С-ЭДО
`other`	Другой оператор
`none`	ЭДО у организации нет

edo_status	Смысл
`unknown`	Подключение не запрашивали или статус ещё не получен
`invited`	Приглашение отправлено, ждём, когда организация его примет
`connected`	Организация подключена: документы доходят
`rejected`	Организация отклонила приглашение
`not_found`	Организация в ЭДО не найдена
`roaming`	Нужен роуминг между операторами: его настраивает наша поддержка, после этого приглашение уйдёт само

Тот же метод без operator проверяет подключение и возвращает текущий статус. Чаще раза в минуту статус заново не запрашивается.
Вызов метода отправляет приглашение повторно, даже если прошлое организация отклонила.
edo_requested_at — когда подключение запросили, edo_invited_at — когда отправлено приглашение.
Когда организация подключилась, документы, ждавшие в статусе no_edo, отправляются сразу.

Ссылки для бухгалтера — доступ к документам одной организации без входа в аккаунт — выдаются только в кабинете.

Ошибки

Статус	Смысл
`400`	`invalid_request` — неверный период акта сверки или неизвестный `operator`. В `error.metadata.fields` — каждое поле с объяснением
`401`	`authentication_failed` — ключа нет, он неверный, отозван или истёк
`403`	`permission_denied` — у ключа нет нужного права, IP не в списке разрешённых или метод вызван API-ключом
`404`	`not_found` — «УПД не найден» или «Организация не найдена» (в том числе когда `{id}` организации — не UUID)