sfera/docs/API.md

# API Documentation

## GraphQL Schema Overview

### Основные типы

#### Organization Types
```graphql
enum OrganizationType {
  SELLER       # Селлер
  WHOLESALE    # Поставщик
  FULFILLMENT  # Фулфилмент
  LOGIST       # Логистика
}
```

#### Product Types
```graphql
enum ProductType {
  PRODUCT      # Товар
  CONSUMABLE   # Расходники
  DEFECT       # Брак (планируется)
  FINISHED_PRODUCT # Готовый продукт (планируется)
}
```

#### Supply Order Statuses
```graphql
enum SupplyOrderStatus {
  PENDING
  SUPPLIER_APPROVED
  CONFIRMED
  LOGISTICS_CONFIRMED
  SHIPPED
  IN_TRANSIT
  DELIVERED
  CANCELLED
}
```

## Основные Query запросы

### Аутентификация и пользователи
- `me` - Текущий пользователь
- `checkUserExists(phone: String!)` - Проверка существования пользователя

### Организации и партнеры
- `myOrganization` - Организация текущего пользователя
- `myCounterparties` - Список партнеров
- `myCounterpartyRequests` - Заявки на партнерство
- `searchOrganizations(search: String, type: OrganizationType)` - Поиск организаций

### Товары и склад
- `myProducts` - Товары организации
- `organizationProducts(organizationId: ID!, type: ProductType)` - Товары конкретной организации
- `getSupplierGoods(supplierId: ID!)` - Товары поставщика
- `myWarehouseStats` - Статистика склада
- `fulfillmentWarehouseStats` - Статистика фулфилмент склада

### Поставки
- `mySupplyOrders` - Заказы поставок
- `mySupplies` - Поставки организации
- `getSupplySuppliers` - Поставщики для поставок

### Услуги (Фулфилмент)
- `myServices` - Услуги фулфилмента
- `myLogistics` - Логистические маршруты
- `myEmployees` - Сотрудники
- `employeeSchedule(employeeId: ID!, year: Int!, month: Int!)` - График сотрудника

### Wildberries интеграция
- `getWBProducts` - Товары из WB
- `getWBWarehouseData` - Данные склада WB
- `getWBReturnClaims` - Заявки на возврат WB

## Основные Mutations

### Аутентификация
- `sendSmsCode(phone: String!)` - Отправка SMS кода
- `verifySmsCode(phone: String!, code: String!)` - Верификация кода
- `updateUserAvatar(avatar: String!)` - Обновление аватара

### Организации
- `createOrganization(input: CreateOrganizationInput!)` - Создание организации
- `updateOrganization(input: UpdateOrganizationInput!)` - Обновление организации

### Товары
- `createProduct(input: CreateProductInput!)` - Создание товара
- `updateProduct(id: ID!, input: UpdateProductInput!)` - Обновление товара
- `deleteProduct(id: ID!)` - Удаление товара
- `toggleProductStatus(id: ID!)` - Изменение статуса товара

### Поставки
- `createSupplyOrder(input: CreateSupplyOrderInput!)` - Создание заказа
- `updateSupplyOrderStatus(id: ID!, status: SupplyOrderStatus!)` - Обновление статуса
- `createWildberriesSupply(input: CreateWildberriesSupplyInput!)` - Создание WB поставки

### Партнерство
- `sendCounterpartyRequest(receiverId: ID!, message: String)` - Отправка заявки
- `acceptCounterpartyRequest(requestId: ID!)` - Принятие заявки
- `rejectCounterpartyRequest(requestId: ID!)` - Отклонение заявки

### Услуги (Фулфилмент)
- `createService(input: CreateServiceInput!)` - Создание услуги
- `updateService(id: ID!, input: UpdateServiceInput!)` - Обновление услуги
- `deleteService(id: ID!)` - Удаление услуги

### Сотрудники (Фулфилмент)
- `createEmployee(input: CreateEmployeeInput!)` - Создание сотрудника
- `updateEmployee(id: ID!, input: UpdateEmployeeInput!)` - Обновление сотрудника
- `deleteEmployee(id: ID!)` - Удаление сотрудника
- `updateEmployeeSchedule(input: UpdateEmployeeScheduleInput!)` - Обновление графика

## Правила доступа

### Общие правила
- Все запросы требуют аутентификации (кроме auth endpoints)
- Доступ ограничен типом организации пользователя
- Фулфилмент имеет максимальные права доступа

### Специфичные ограничения
- **Создание товаров**: Только WHOLESALE
- **Создание услуг**: Только FULFILLMENT
- **Управление сотрудниками**: Только FULFILLMENT
- **Просмотр всех заказов**: FULFILLMENT и участники заказа

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

### Получение товаров поставщика
```graphql
query GetSupplierProducts($organizationId: ID!) {
  organizationProducts(organizationId: $organizationId, type: PRODUCT) {
    id
    name
    article
    price
    quantity
    images
  }
}
```

### Создание заказа поставки
```graphql
mutation CreateSupplyOrder($input: CreateSupplyOrderInput!) {
  createSupplyOrder(input: $input) {
    id
    status
    items {
      product {
        name
      }
      quantity
      price
    }
  }
}
```

### Обновление статуса поставки
```graphql
mutation UpdateSupplyStatus($id: ID!, $status: SupplyOrderStatus!) {
  updateSupplyOrderStatus(id: $id, status: $status) {
    id
    status
    updatedAt
  }
}
```

---

*Последнее обновление: ${new Date().toISOString().split('T')[0]}*