openapi: 3.0.3
info:
  title: API ориентировок для партнеров
  version: 1.0.0
  description: |-
    HTTP API для партнеров Где мои дети, которые распространяют активные ориентировки о пропавших детях среди своих пользователей в согласованном кобрендинговом формате.

    Партнеру выдается токен доступа. Токен передается в query-параметре `u` и обязателен для всех методов.

    Поля `parentId` и `phone` относятся к чувствительным данным. Их получение, хранение, отображение и передача третьим лицам допустимы только в рамках отдельного соглашения с Где мои дети.
servers:
  - url: https://api.gdemoideti.ru
    description: Production API Где мои дети
tags:
  - name: Amber Alerts
    description: Получение активных ориентировок
paths:
  /poi/v1/getWebsiteActiveAmberAlerts:
    get:
      tags:
        - Amber Alerts
      operationId: getWebsiteActiveAmberAlerts
      summary: Получить полный список активных ориентировок
      description: |-
        Возвращает полный список опубликованных активных ориентировок, доступных для распространения партнерами.

        Метод подходит для федерального фида и серверной синхронизации витрины ориентировок.
      security:
        - PartnerToken: []
      parameters:
        - $ref: "#/components/parameters/PartnerToken"
      responses:
        "200":
          description: Список активных ориентировок
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetAmberAlertsResponse"
              examples:
                success:
                  $ref: "#/components/examples/AmberAlertsResponse"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /poi/v1/getAmberAlertsPoints:
    get:
      tags:
        - Amber Alerts
      operationId: getAmberAlertsPoints
      summary: Получить точки ориентировок в области карты
      description: |-
        Возвращает точки опубликованных ориентировок внутри заданной прямоугольной области.

        В ответе нет детальной информации по ребенку: только координаты и `pointId`. Для получения карточки используйте `GET /poi/v1/getAmberAlert`.
      security:
        - PartnerToken: []
      parameters:
        - $ref: "#/components/parameters/PartnerToken"
        - $ref: "#/components/parameters/LatBottom"
        - $ref: "#/components/parameters/LongBottom"
        - $ref: "#/components/parameters/LatUp"
        - $ref: "#/components/parameters/LongUp"
      responses:
        "200":
          description: Список точек ориентировок
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetAmberAlertsPointsResponse"
              examples:
                success:
                  $ref: "#/components/examples/AmberAlertsPointsResponse"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /poi/v1/getAmberAlert:
    get:
      tags:
        - Amber Alerts
      operationId: getAmberAlert
      summary: Получить детальную карточку ориентировки
      description: Возвращает детальную информацию по опубликованной ориентировке.
      security:
        - PartnerToken: []
      parameters:
        - $ref: "#/components/parameters/PartnerToken"
        - $ref: "#/components/parameters/PointId"
      responses:
        "200":
          description: Детальная карточка ориентировки
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetAmberAlertResponse"
              examples:
                success:
                  $ref: "#/components/examples/AmberAlertResponse"
        "404":
          description: Ориентировка по `pointId` не найдена или не опубликована
        "500":
          $ref: "#/components/responses/InternalServerError"

components:
  securitySchemes:
    PartnerToken:
      type: apiKey
      in: query
      name: u
      description: Партнерский токен доступа, выданный Где мои дети.

  parameters:
    PartnerToken:
      name: u
      in: query
      required: true
      schema:
        type: string
      description: Партнерский токен доступа.
      example: partner_token
    PointId:
      name: pointId
      in: query
      required: true
      schema:
        type: integer
        format: uint64
        minimum: 1
      description: Идентификатор ориентировки.
      example: 12345
    LatBottom:
      name: latBottom
      in: query
      required: true
      schema:
        type: number
        format: double
        minimum: -90
        maximum: 90
      description: Широта нижнего угла области в WGS 84.
      example: 55.55
    LongBottom:
      name: longBottom
      in: query
      required: true
      schema:
        type: number
        format: double
        minimum: -180
        maximum: 180
      description: Долгота нижнего угла области в WGS 84.
      example: 37.35
    LatUp:
      name: latUp
      in: query
      required: true
      schema:
        type: number
        format: double
        minimum: -90
        maximum: 90
      description: Широта верхнего угла области в WGS 84.
      example: 55.95
    LongUp:
      name: longUp
      in: query
      required: true
      schema:
        type: number
        format: double
        minimum: -180
        maximum: 180
      description: Долгота верхнего угла области в WGS 84.
      example: 37.95

  responses:
    InternalServerError:
      description: Внутренняя ошибка сервиса
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            internalError:
              value:
                error: 1
                errorText: internal server error
                instance: apps-6d8cd5947c-8jngp
                release: v1-1-1
                execTime: 0.04
                result: null

  schemas:
    BaseResponse:
      type: object
      required:
        - error
        - errorText
        - instance
        - release
        - execTime
      properties:
        error:
          type: integer
          format: uint64
          minimum: 0
          description: Код ошибки. `0` означает успешный запрос.
          example: 0
        errorText:
          type: string
          description: Текст ошибки. При успешном запросе пустая строка.
          example: ""
        instance:
          type: string
          description: Внутренний идентификатор инстанса сервиса.
          example: apps-6d8cd5947c-8jngp
        release:
          type: string
          description: Версия релиза сервиса.
          example: v1-1-1
        execTime:
          type: number
          format: double
          description: Время выполнения запроса в секундах.
          example: 0.12

    ErrorResponse:
      allOf:
        - $ref: "#/components/schemas/BaseResponse"
        - type: object
          required:
            - result
          properties:
            result:
              nullable: true
              description: При ошибке результат отсутствует.
              example: null

    GetAmberAlertsResponse:
      allOf:
        - $ref: "#/components/schemas/BaseResponse"
        - type: object
          required:
            - result
          properties:
            result:
              type: array
              description: Список активных ориентировок.
              items:
                $ref: "#/components/schemas/AmberAlert"

    GetAmberAlertsPointsResponse:
      allOf:
        - $ref: "#/components/schemas/BaseResponse"
        - type: object
          required:
            - result
          properties:
            result:
              type: array
              description: Список точек ориентировок.
              items:
                $ref: "#/components/schemas/AmberAlertPoint"

    GetAmberAlertResponse:
      allOf:
        - $ref: "#/components/schemas/BaseResponse"
        - type: object
          required:
            - result
          properties:
            result:
              $ref: "#/components/schemas/AmberAlert"

    AmberAlertPoint:
      type: object
      required:
        - location
        - pointId
      properties:
        location:
          $ref: "#/components/schemas/Location"
        pointId:
          type: integer
          format: uint64
          description: Идентификатор ориентировки.
          example: 12345

    AmberAlert:
      type: object
      description: Опубликованная ориентировка о пропавшем ребенке.
      required:
        - pointId
        - expirationDate
        - parentId
        - childName
        - childAge
        - missingDate
        - status
      properties:
        pointId:
          type: integer
          format: uint64
          description: Идентификатор ориентировки.
          example: 12345
        expirationDate:
          type: integer
          format: uint64
          description: Unix timestamp даты снятия с публикации.
          example: 1716201563
        parentId:
          type: integer
          format: uint64
          description: Идентификатор обратившегося родителя. Чувствительное поле, доступно только в рамках соглашения.
          example: 98765
          x-sensitive: true
        childName:
          type: string
          description: Имя ребенка.
          example: Михаил
        childAge:
          type: integer
          description: Возраст ребенка.
          example: 13
        missingDate:
          type: integer
          format: uint64
          description: Unix timestamp времени, когда ребенка видели последний раз.
          example: 1715769563
        location:
          $ref: "#/components/schemas/Location"
        address:
          type: string
          description: Адрес или описание места последнего появления.
          example: г. Пермь, ул. Красноармейская, 12
        childDescription:
          type: string
          description: Приметы, одежда и другая информация для поиска.
          example: Был одет в джинсовку и джинсы
        childPhoto:
          type: string
          format: uri
          description: URL фотографии ребенка.
          example: https://example.com/photo.png
        status:
          $ref: "#/components/schemas/AmberAlertStatus"
        description:
          type: string
          description: Дополнительная информация.
          example: Дополнительная информация по поиску
        phone:
          type: string
          description: Телефон для связи. Чувствительное поле, доступно только в рамках соглашения.
          example: "+7 999 123-12-12"
          x-sensitive: true

    AmberAlertStatus:
      type: string
      description: Статус ориентировки.
      enum:
        - PUBLISHED
        - UNPUBLISHED
        - CANCELED
      example: PUBLISHED

    Location:
      type: object
      description: Координаты точки в WGS 84.
      required:
        - lat
        - long
      properties:
        lat:
          type: number
          format: double
          minimum: -90
          maximum: 90
          description: Широта.
          example: 58.0105
        long:
          type: number
          format: double
          minimum: -180
          maximum: 180
          description: Долгота.
          example: 56.2502

  examples:
    AmberAlertsResponse:
      value:
        error: 0
        errorText: ""
        instance: apps-6d8cd5947c-8jngp
        release: v1-1-1
        execTime: 0.12
        result:
          - pointId: 12345
            expirationDate: 1716201563
            parentId: 98765
            childName: Михаил
            childAge: 13
            missingDate: 1715769563
            location:
              lat: 58.0105
              long: 56.2502
            address: г. Пермь, ул. Красноармейская, 12
            childDescription: Был одет в джинсовку и джинсы
            childPhoto: https://example.com/photo.png
            status: PUBLISHED
            description: Дополнительная информация по поиску
            phone: "+7 999 123-12-12"
    AmberAlertsPointsResponse:
      value:
        error: 0
        errorText: ""
        instance: apps-6d8cd5947c-8jngp
        release: v1-1-1
        execTime: 0.08
        result:
          - location:
              lat: 55.7512
              long: 37.6184
            pointId: 12345
    AmberAlertResponse:
      value:
        error: 0
        errorText: ""
        instance: apps-6d8cd5947c-8jngp
        release: v1-1-1
        execTime: 0.06
        result:
          pointId: 12345
          expirationDate: 1716201563
          parentId: 98765
          childName: Михаил
          childAge: 13
          missingDate: 1715769563
          location:
            lat: 58.0105
            long: 56.2502
          address: г. Пермь, ул. Красноармейская, 12
          childDescription: Был одет в джинсовку и джинсы
          childPhoto: https://example.com/photo.png
          status: PUBLISHED
          description: Дополнительная информация по поиску
          phone: "+7 999 123-12-12"
