amocrm/openapi.yaml

openapi: 3.0.3
info:
  title: QUIZ AMOCRM integration
  description: Интеграция с Амо. Ключевая задача - создавать заявки в соответствующей воронкой подключенного аккаунта
  version: 1.0.0

paths:
  /account:
    post:
      description: подключение аккаунта амо к аккаунту quiz. На вход получает только токен. На выход отдаёт ссылку для подключения. Создаёт модель аккаунта, имеющую связь с основным аккаунтом
      responses:
        '200':
          description: успешное создание ссылки для авторизации
          content:
            'application/json':
              schema:
                type: object
                properties:
                  link: 
                    type: string
                    description: ссылка для авторизации в амо
    delete:
      description: мягкое удаление аккаунта. Юзер должен иметь возможность создать новый аккаунт, взамен удалённого
      responses:
        '200':
          description: успешное удаление аккаунта
    get:
      description: получение текущего аккаунта
      responses:
        '200':
          description: аккаунт интеграции с амо
          сontent:
            'application/json':
              schema:
                type: object
                properties:
                  ID:
                    type: string
                    description: uuid
                  AccountID:
                    type: string
                    description: связь с аккаунтом в квизе
                  AmocrmID:
                    type: integer
                    description: связь с аккаунтом в амо
                  Name:
                    type: string
                    description: имя аккаунта в амо
                  Subdomain:
                    type: string
                    description: поддомен организации в амо
                  AmoUserID:
                    type: integer
                    description: айдишник пользвателя, который подключал интеграцию
                  Country:
                    type: string
                    description: страна указанная в настройках амо
                  CreatedAt:
                    type: integer
                    description: таймштамп создания аккаунта
  /webhook/create:
    get:
      description: это метод для получения пары токенов для аккаунта. Пары токенов стоит хранить в отдельной таблице и завести воркер, который будет обновлять рефреш. https://www.amocrm.ru/developers/content/oauth/step-by-step - вот дока для этого метода
  /webhook/delete:
    get:
      description: это метод для оповещения об удалении итеграции из учетки в амо. При его вызове надо мягко удалить соответствующий аккаунт. https://www.amocrm.ru/developers/content/oauth/step-by-step#%D0%A5%D1%83%D0%BA-%D0%BE%D0%B1-%D0%BE%D1%82%D0%BA%D0%BB%D1%8E%D1%87%D0%B5%D0%BD%D0%B8%D0%B8-%D0%B8%D0%BD%D1%82%D0%B5%D0%B3%D1%80%D0%B0%D1%86%D0%B8%D0%B8
  /utms:
    get:
      description: получение списка заданных юзером utm меток. Это чисто наша сущность, в амо она представлена кастомными полями сделки
      parameters:
        $ref: "#/components/parameters/Pagination"  
      responses:
        '200':
          description: успешное получение списка пользователей 
          content:
            'application/json':
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    description: общее количество юзеров, которые у нас закешированы для этого пользователя
                  items:
                    type: array
                    description: список юзеров, которые были закешированы нашим сервисом
                    items:
                      $ref: "#/components/schemas/UTM"
    post:
      description: сохранение списка заданных юзером utm меток
      requestBody:
        content:
          'application/json':
            schema:
              type: object
              properties:
                utms:
                  type: array
                  description: список utm для сохранения. сохранять только те, которых в этом аккаунте ещё нет
                  items:
                    type: string
      responses:
        '200':
          description: успешное сохранение списка utm меток
          content:
            'application/json':
              schema:
                type: array
                description:  список айдишников сохранённых меток
                items:
                  type: string
    delete:
      description:  удаление utm  по айдишникам
      requestBody:
        content:
          'application/json':
            schema:
              type: object
              properties:
                utms:
                  type: array
                  description: список айдишников utm которые удалить
                  items:
                    type: integer
  /users:
    get:
      description: получение списка юзеров, закешированных у нас, с пагинацией https://www.amocrm.ru/developers/content/crm_platform/users-api#users-list
      parameters:
        $ref: "#/components/parameters/Pagination"  
      responses:
        '200':
          description: успешное получение списка пользователей 
          content:
            'application/json':
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    description: общее количество юзеров, которые у нас закешированы для этого пользователя
                  items:
                    type: array
                    description: список юзеров, которые были закешированы нашим сервисом
                    items:
                      $ref: "#/components/schemas/User"
    patch:
      description: обновление списка юзеров
  /pipelines:
    get:
      description: получение списка воронок, закешированных у нас, с пагинацией https://www.amocrm.ru/developers/content/crm_platform/leads_pipelines
      parameters:
        $ref: "#/components/parameters/Pagination"  
      responses:
        '200':
          description: успешное получение списка воронок 
          content:
            'application/json':
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    description: общее количество воронок, которые у нас закешированы для этого пользователя
                  items:
                    type: array
                    description: список воронок, которые были закешированы нашим сервисом
                    items:
                      $ref: "#/components/schemas/Pipeline"
    patch:
      description: обновление списка воронок
  /steps:
    get:
      description: получение списка этапов воронок, закешированных у нас, с пагинацией https://www.amocrm.ru/developers/content/crm_platform/leads_pipelines#%D0%A1%D0%BF%D0%B8%D1%81%D0%BE%D0%BA-%D1%81%D1%82%D0%B0%D1%82%D1%83%D1%81%D0%BE%D0%B2-%D0%B2%D0%BE%D1%80%D0%BE%D0%BD%D0%BA%D0%B8-%D1%81%D0%B4%D0%B5%D0%BB%D0%BE%D0%BA
      parameters:
        $ref: "#/components/parameters/Pagination"  
      responses:
        '200':
          description: успешное получение списка шагов воронок 
          content:
            'application/json':
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    description: общее количество шагов воронок, которые у нас закешированы для этого пользователя
                  items:
                    type: array
                    description: список шагов воронок, которые были закешированы нашим сервисом
                    items:
                      $ref: "#/components/schemas/Steps"
    patch:
      description: обновление списка этапов воронок
  /fields:
    get:
      description: получение списка кастомных полей, закешированных у нас, с пагинацией https://www.amocrm.ru/developers/content/crm_platform/custom-fields#%D0%A1%D0%BF%D0%B8%D1%81%D0%BE%D0%BA-%D0%BF%D0%BE%D0%BB%D0%B5%D0%B9-%D1%81%D1%83%D1%89%D0%BD%D0%BE%D1%81%D1%82%D0%B8
      parameters:
        $ref: "#/components/parameters/Field"  
      responses:
        '200':
          description: успешное получение списка тегов 
          content:
            'application/json':
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    description: общее количество кастомных полей, которые у нас закешированы для этого пользователя
                  items:
                    type: array
                    description: список кастомных полей, которые были закешированы нашим сервисом
                    items:
                      $ref: "#/components/schemas/Field"
    patch:
      description: обновление списка кастомных полей
  /tags:
    get:
      description: получение списка тегов, закешированных у нас, с пагинацией https://www.amocrm.ru/developers/content/crm_platform/tags-api#%D0%A1%D0%BF%D0%B8%D1%81%D0%BE%D0%BA-%D1%82%D0%B5%D0%B3%D0%BE%D0%B2-%D0%B4%D0%BB%D1%8F-%D1%81%D1%83%D1%89%D0%BD%D0%BE%D1%81%D1%82%D0%B8
      parameters:
        $ref: "#/components/parameters/Pagination"  
      responses:
        '200':
          description: успешное получение списка тегов 
          content:
            'application/json':
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    description: общее количество тегов, которые у нас закешированы для этого пользователя
                  items:
                    type: array
                    description: список тегов, которые были закешированы нашим сервисом
                    items:
                      $ref: "#/components/schemas/Tag"
    patch:
      description: обновление списка тегов. никакого тела у этого запроса нет, просто он обновляет данные по тегам в приказном порядке, т.е. просто ставит задачу в очередь на переполучение данных от амо
  /rules/{quizID}:
    get: 
      description: получение настроек интеграции для конкретного квиза
    post:
      description: создание настроек интеграции для конкретного квиза
    patch:
      description: изменение настроек интеграции для конкретного квиза

components:
  schemas:
    Pipeline:
      type: object
      description: объект воронки амо
      properties:
        ID:
          type: integer
          description:  айдишник в нашей системе
        AmoID:
          type: integer
          description: айдишник воронки в амо
        AccountID: 
          type: string
          description: связь с аккаунтом в интеграции амо
        Name:
          type: string
          description:  название воронки в амо
        IsArchive:
          type: boolean
          description: флаг архивной воронки в амо
        Deleted:
          type: boolean
          description: флаг мягкого удаления
        CreatedAt:
          type: integer
          description: таймштамп создания воронки в нашей системе
    Step:
      type: object
      description: объект шага воронки амо
      properties:
        ID:
          type: integer
          description:  айдишник в нашей системе
        AmoID:
          type: integer
          description: айдишник шага воронки в амо
        PipelineID:
          type: integer
          description: айдишник воронки в амо
        AccountID: 
          type: string
          description: связь с аккаунтом в интеграции амо
        Name:
          type: string
          description:  название воронки в амо
        Color:
          type: string
          description:  цвет шага в амо
        Deleted:
          type: boolean
          description: флаг мягкого удаления
        CreatedAt:
          type: integer
          description: таймштамп создания воронки в нашей системе
    Field:
      type: object
      description: объект кастомного поля амо
      properties:
        ID:
          type: integer
          description:  айдишник в нашей системе
        AmoID:
          type: integer
          description: айдишник кастомного поля в амо
        Code:
          type: string
          description: кодовое слово в амо
        AccountID: 
          type: string
          description: связь с аккаунтом в интеграции амо
        Name:
          type: string
          description:  название воронки в амо
        EntityType:
          type: string
          description: тип сущности в амо, для которой это кастомное поле
        Type:
          type: string
          description: тип поля https://www.amocrm.ru/developers/content/crm_platform/custom-fields#%D0%94%D0%BE%D1%81%D1%82%D1%83%D0%BF%D0%BD%D1%8B%D0%B5-%D1%82%D0%B8%D0%BF%D1%8B-%D0%BF%D0%BE%D0%BB%D0%B5%D0%B9
        Deleted:
          type: boolean
          description: флаг мягкого удаления
        CreatedAt:
          type: integer
          description: таймштамп создания воронки в нашей системе
    UTM:
      type: object
      description: объект настройки UTM, данные о которых мы сохраняем в амо
      properties:
        ID:
          type: integer
          description:  айдишник в нашей системе
        AmoFieldID:
          type: integer
          description: айдишник кастомного поля в амо
        AccountID: 
          type: string
          description: связь с аккаунтом в интеграции амо
        Name:
          type: string
          description:  название тега в амо
        Deleted:
          type: boolean
          description: флаг мягкого удаления
        CreatedAt:
          type: integer
          description: таймштамп создания тега в нашей системе
    Tag:
      type: object
      description: объект тега из амо
      properties:
        ID:
          type: integer
          description:  айдишник в нашей системе
        AmoID:
          type: integer
          description: айдишник тега в амо
        AccountID: 
          type: string
          description: связь с аккаунтом в интеграции амо 
        Entity:
          type: string
          description:  сущность, к которой принадлежит этот тег. Наверное, стоит сделать через enum в базе
        Name:
          type: string
          description:  название тега в амо
        Color:
          type: string
          description:  цвет тега в амо
        Deleted:
          type: boolean
          description: флаг мягкого удаления
        CreatedAt:
          type: integer
          description: таймштамп создания тега в нашей системе
    User:
      type: object
      description: объект пользователя из амо
      properties:
        ID:
          type: integer
          description: айдишник в нашей системе
        AccountID: 
          type: string
          description: связь с аккаунтом в интеграции амо 
        AmoID:
          type: integer
          description: айдишник пользователя в амо
        Name:
          type: string
          description: имя пользователя в амо
        Email:
          type: string
          description: почта пользователя из амо
        Role:
          type: string
          description: роль пользователя в амо
        Group:
          type: string
          description: руппа пользователя в амо
        Deleted:
          type: boolean
          description: флаг мягкого удаления
        CreatedAt:
          type: integer
          description: таймштамп создания тега в нашей системе
        
  parameters:
    Pagination:
    - page:
      in: query
      description: указание страницы пагинации. Если страница не указана, применять 0
      required: true
      schema:
        type: integer
      example: 1
    - size:
      in: query
      description: указание размера страницы пагинации. По умолчанию применять 25
      required: true
      schema:
        type: integer
      example: 100