Skip to content

feat(accruals-gateway): DOMA-12591 added accruals gateway doc #7021

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
vovaaxeapolla merged 4 commits into from
Dec 29, 2025
Merged

feat(accruals-gateway): DOMA-12591 added accruals gateway doc #7021

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
6194b36
feat(accruals-gateway): DOMA-12591 added accruals gateway docs
vovaaxeapolla Dec 10, 2025
bc1aa59
feat(accruals-gateway): DOMA-12591 added accruals gateway docs
vovaaxeapolla Dec 10, 2025
b932877
feat(accruals-gateway): DOMA-12591 fix doc
vovaaxeapolla Dec 15, 2025
52428d1
feat(accruals-gateway): DOMA-12591 fix doc
vovaaxeapolla Dec 15, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion apps/dev-portal-web/docs/_meta.en.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,5 +9,6 @@
},
"ui": "Condo UI",
"bridge": "Condo Bridge",
"api": "Condo API"
"api": "Condo API",
"accruals-gateway": "Accruals gateway"
}
1 change: 1 addition & 0 deletions apps/dev-portal-web/docs/_meta.ru.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@
"ui": "Condo UI",
"bridge": "Condo Bridge",
"api": "Condo API",
"accruals-gateway": "Шлюз начислений",
"g-doc-link": {
"title": "Старая документация",
"href": "https://docs.google.com/document/d/1pTMq0Qi9307uUIfHK4eGi6T1xtUvrK4Asz9j5Eoo8bI/edit?usp=sharing"
Expand Down
6 changes: 6 additions & 0 deletions apps/dev-portal-web/docs/accruals-gateway/_meta.en.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
{
"auth": "Authentication",
"search": "Search organizations",
"check": "Get accruals",
"pay": "Register payment"
}
6 changes: 6 additions & 0 deletions apps/dev-portal-web/docs/accruals-gateway/_meta.ru.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
{
"auth": "Авторизация",
"search": "Поиск организаций",
"check": "Получение начислений",
"pay": "Регистрация оплаты"
}
35 changes: 35 additions & 0 deletions apps/dev-portal-web/docs/accruals-gateway/auth.en.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
## Basic Authentication
All API requests require Basic Authentication and must be executed **only from IP addresses registered in the agent**.

<Alert type={'warning'}>
**For operation, ensure that:**
- Your IP addresses are registered in the system
- You have valid `username` and `password` credentials
</Alert>

## Mandatory Requirements

### 1. IP Addresses
Requests must originate only from pre-registered IP addresses. Otherwise, access will be blocked.

### 2. Basic Authentication
Client credentials must be passed in the `Authorization` header:
```
Authorization: Basic <base64_encoded_credentials>
```

### Example
```bash
curl -X GET "https://accruals-gateway.doma.ai/api/search?search=Столичный" \
-H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ="
```

## Authorization Errors

| Error Code | HTTP Status | Message | Cause |
|------------------------|--------------|--------------------------|-------------------------------------------------------|
| AGENT_NOT_FOUND | 404 | Agent is not found | The provided `username` does not match any registered agent |
| AGENT_DISABLED | 403 | Agent is disabled | The agent exists but is disabled in the system |
| IP_NOT_ALLOWED | 403 | IP address not allowed | Request was made from an unregistered IP address |
| INVALID_HEADERS | 403 | Invalid headers provided | Invalid headers are present |
| AUTHORIZATION_REQUIRED | 403 | Authorization required | Missing `Authorization` header or invalid credentials |
35 changes: 35 additions & 0 deletions apps/dev-portal-web/docs/accruals-gateway/auth.ru.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
## Basic Authentication
Все запросы к API требуют Basic Authentication и должны выполняться **только с IP-адресов, зарегистрированных в агенте**.

<Alert type={'warning'}>
**Для работы убедитесь, что:**
- Ваши IP-адреса зарегистрированы в системе
- У вас есть корректные учетные данные `username` и `password`
</Alert>

## Обязательные требования

### 1. IP-адреса
Запросы должны поступать только с предварительно зарегистрированных IP-адресов. В противном случае доступ будет заблокирован.

### 2. Basic Authentication
Необходимо передавать учетные данные клиента в заголовке `Authorization`:
```
Authorization: Basic <base64_encoded_credentials>
```

### Пример
```bash
curl -X GET "https://accruals-gateway.doma.ai/api/search?search=Столичный" \
-H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ="
```

## Ошибки авторизации

| Код ошибки | HTTP статус | Сообщение | Причина |
|------------------------|--------------|--------------------------|-----------------------------------------------------------------------------|
| AGENT_NOT_FOUND | 404 | Agent is not found | Переданный `username` не соответствует ни одному зарегистрированному агенту |
| AGENT_DISABLED | 403 | Agent is disabled | Агент существует, но отключен в системе |
| IP_NOT_ALLOWED | 403 | IP address not allowed | Запрос выполнен с незарегистрированного IP-адреса |
| INVALID_HEADERS | 403 | Invalid headers provided | Присутствуют некорректные загловки |
| AUTHORIZATION_REQUIRED | 403 | Authorization required | Отсутствует заголовок `Authorization` или неверные учетные данные |
70 changes: 70 additions & 0 deletions apps/dev-portal-web/docs/accruals-gateway/check.en.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
`GET /api/check`

Returns a list of accruals by organization TIN and personal account. The response is always an array if accruals are found, otherwise a 404 error is returned..

## 🔐Authentication

[View authentication documentation →](/docs/accruals-gateway/auth)

## Query parameters

| Parameter | Type/Format | Required | Description | Example |
|-----------|-------------------------------|----------|-------------------------|-----------------|
| tin | string\<10 to 12 characters\> | ✅ | Organization TIN | `7712345678` |
| account | string\<1 to 100 characters\> | ✅ | Personal account number | `ЛС-1234567890` |

## Request example

```
GET /api/check?tin=9731062087&account=ЛС-1234567890
```

## Response

| Parameter | Type/Format | Required | Description | Example |
|----------------|----------------------|----------|-------------------------------------------------|----------------------------------------------------------------|
| id | string\<uuid\> | ✅ | Unique accrual identifier | `75b12bb4-a87b-4c5d-8e4d-900802c67ed3` |
| category | string | ✅ | Accrual category | `Квартплата`, `Электроэнергия` |
| account | string | ✅ | Payer's personal account | `ЛС-1234567890` |
| toPay | string | ✅ | Amount to pay | `15620.50` |
| period | string\<YYYY-MM-01\> | ✅ | Accrual period | `2025-08-01` |
| address | string | ✅ | Property address | `г Москва, ул Тверская, д 15, кв 42` |
| organization | string | ✅ | Recipient organization name | `ООО УК "Столичный дом"` |
| tin | string | ✅ | Organization TIN | `7712345678` |
| iec | string | ❌ | Organization IEC (Tax Registration Reason Code) | `770101001` |
| routingNumber | string | ✅ | Recipient bank BIC (Bank Identification Code) | `044525555` |
| bankAccount | string | ✅ | Organization bank account | `40702810500000001234` |
| receiptFileUrl | string | ❌ | Link to the receipt | `https://example.com/receipt.pdf` |
| purpose | string | ✅ | Payment purpose for bank transfer | `Квартплата за август 2025 г. по лицевому счету ЛС-1234567890` |

## Response example

```json
{
"data": [
{
"id": "c7f3a892-e5b1-4d6c-8a9f-1234567890ab",
"category": "Квартплата",
"account": "ЛС-7845123690",
"toPay": "15620.50",
"period": "2025-08-01",
"address": "г Москва, ул Тверская, д 15, кв 42",
"organization": "ООО УК \"Столичный дом\"",
"tin": "7712345678",
"iec": "770101001",
"routingNumber": "044525555",
"bankAccount": "40702810500000001234",
"receiptFileUrl": "https://teststorage.com/receipts/august-2025.pdf",
"purpose": "Оплата жилищно-коммунальных услуг за август 2025"
},
]
}
```

## Error Codes

| Код ошибки | HTTP статус | Сообщение | Причина | Решение |
|-------------------------|-------------|-----------------------------|------------------------------------|------------------------------------|
| `VALIDATION_FAILED` | 400 | Invalid format of input | Parameter validation error | Check the parameter format |
| `ACCOUNT_NOT_FOUND` | 404 | Account number is not found | Accrual for this account not found | Verify the account number |
| `INTERNAL_SERVER_ERROR` | 500 | Internal server error | Internal server error | Try again later or contact support |
70 changes: 70 additions & 0 deletions apps/dev-portal-web/docs/accruals-gateway/check.ru.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
`GET /api/check`

Возвращает список начислений по ИНН организации и лицевому счёту. Ответ всегда представляет собой массив, если найдены начисления, иначе ошибка 404.

## 🔐 Авторизация

[Посмотреть документацию по авторизации →](/docs/accruals-gateway/auth)

## Query parameters

| Параметр | Тип/Формат | Обязательный | Описание | Пример |
|----------|--------------------------------|--------------|------------------|-----------------|
| tin | string\<от 10 до 12 символов\> | ✅ | ИНН организации | `7712345678` |
| account | string\<от 1 до 100 символов\> | ✅ | Лицевой счёт | `ЛС-1234567890` |

## Пример запроса

```
GET /api/check?tin=9731062087&account=ЛС-1234567890
```

## Ответ

| Параметр | Тип/Формат | Обязательный | Описание | Пример |
|----------------|----------------------|--------------|---------------------------------------------|----------------------------------------------------------------|
| id | string\<uuid\> | ✅ | Уникальный идентификатор начисления | `75b12bb4-a87b-4c5d-8e4d-900802c67ed3` |
| category | string | ✅ | Категория начисления | `Квартплата`, `Электроэнергия` |
| account | string | ✅ | Лицевой счет плательщика | `ЛС-1234567890` |
| toPay | string | ✅ | Сумма к оплате | `15620.50` |
| period | string\<ГГГГ-ММ-01\> | ✅ | Период начисления | `2025-08-01` |
| address | string | ✅ | Адрес объекта недвижимости | `Краснодарский край, г Сочи, ул Макаренко, д 30` |
| organization | string | ✅ | Наименование организации-получателя | `ООО УК "Столичный дом"` |
| tin | string | ✅ | ИНН организации | `9731062087` |
| iec | string | ❌ | КПП организации | `770101001` |
| routingNumber | string | ✅ | БИК банка получателя | `044525555` |
| bankAccount | string | ✅ | Расчетный счет организации | `40702810500000001234` |
| receiptFileUrl | string | ❌ | Ссылка на начисление | `https://example.com/receipt.pdf` |
| purpose | string | ✅ | Назначение платежа для банковского перевода | `Квартплата за август 2025 г. по лицевому счету ЛС-1234567890` |

## Пример ответа

```json
{
"data": [
{
"id": "c7f3a892-e5b1-4d6c-8a9f-1234567890ab",
"category": "Квартплата",
"account": "ЛС-7845123690",
"toPay": "15620.50",
"period": "2025-08-01",
"address": "г Москва, ул Тверская, д 15, кв 42",
"organization": "ООО УК \"Столичный дом\"",
"tin": "7712345678",
"iec": "770101001",
"routingNumber": "044525555",
"bankAccount": "40702810500000001234",
"receiptFileUrl": "https://teststorage.com/receipts/august-2025.pdf",
"purpose": "Квартплата за август 2025 г. по лицевому счету ЛС-1234567890"
},
]
}
```

## Коды ошибок

| Код ошибки | HTTP статус | Сообщение | Причина | Решение |
|-------------------------|-------------|-----------------------------|------------------------------|---------------------------------------------|
| `VALIDATION_FAILED` | 400 | Invalid format of input | Ошибка валидации параметров | Проверьте формат входных данных |
| `ACCOUNT_NOT_FOUND` | 404 | Account number is not found | Начисление по Л/С не найдено | Уточните поисковый запрос |
| `INTERNAL_SERVER_ERROR` | 500 | Internal server error | Внутренняя ошибка сервера | Попробуйте позже или обратитесь в поддержку |
72 changes: 72 additions & 0 deletions apps/dev-portal-web/docs/accruals-gateway/pay.en.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
`POST /api/pay`

Registers a payment for an accrual.

## 🔐Authentication

[View authentication documentation →](/docs/accruals-gateway/auth)

## Body parameters

| Parameter | Type/Format | Required | Description | Example |
|------------|---------------------------------|----------|------------------------------------|----------------------------------------|
| id | string\<uuid\> | ✅ | Accrual identifier | `452f081a-7612-48e1-bc4e-89d6cea366e7` |
| txnId | string\<1 to 100 characters\> | ✅ | Client-side transaction identifier | `1` |
| txnDate | string\<ISO 8601\> | ✅ | Client-side transaction date | `2024-01-01T12:00:00Z` |
| amount | string\<^\d{1,9}(\.\d{1,2})?$\> | ✅ | Payment amount | `1500.75` |
| receiptUrl | string\<URL\> | ❌ | Link to receipt | `https://example.com/receipt.pdf` |

## Request example

```bash
curl -X POST "https://accruals-gateway.doma.ai/api/pay" \
-H "Content-Type: application/json" \
-H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=" \
-d '{
"id": "452f081a-7612-48e1-bc4e-89d6cea366e7",
"txnId": "1234567891111",
"txnDate": "2024-01-01T12:00:00Z",
"amount": "1500.75",
"receiptUrl": "https://example.com/receipt.pdf"
}'
```

## Request body
```json
{
"id": "452f081a-7612-48e1-bc4e-89d6cea366e7",
"txnId": "1234567891111",
"txnDate": "2024-01-01T12:00:00Z",
"amount": "1500.75",
"receiptUrl": "https://example.com/receipt.pdf"
}
```

## Response

| Parameter | Type/Format | Required | Description | Example |
|-----------|--------------------------------|----------|-------------------------------------------------|----------------------------|
| txnId | string\<1 to 100 characters\> | ✅ | Transaction identifier (as provided in request) | `1234567891111` |
| txnDate | string\<datetime\> | ✅ | Transaction date in ISO 8601 format | `2025-12-04T22:25:01.243Z` |
| regDate | string\<datetime\> | ✅ | Payment registration date in system (ISO 8601) | `2025-12-09T12:59:34.887Z` |

## Response example

```json
{
"data": {
"txnId": "1234567891111",
"txnDate": "2025-12-04T22:25:01.243Z",
"regDate": "2025-12-09T12:59:34.887Z"
}
}
```

## Error Codes

| Error Code | HTTP Status | Message | Cause | Solution |
|--------------------------|-------------|-------------------------|--------------------------------------------|------------------------------------|
| `VALIDATION_FAILED` | 400 | Invalid format of input | Parameter validation error | Check parameter formats |
| `PAYMENT_ALREADY_EXISTS` | 400 | Payment already exists | Payment with this txnId already registered | Use a different txnId |
| `ACCRUAL_NOT_FOUND` | 404 | Accrual is not found | Accrual with specified id not found | Verify the accrual id |
| `INTERNAL_SERVER_ERROR` | 500 | Internal server error | Internal server error | Try again later or contact support |
Loading
Loading