openapi: 3.0.0
info:
  version: "0.0"
  title: Qomon
  description: |-
    This openapi specification describes endpoints used during customer onboarding and space (aka group) creation in Qomon.

    To get an authorization go to [Qomon's setting page](https://qomon.app/settings/extensions/connect) and create an API key.

tags:
  - name: Create and setup group
    description: Endpoints to create and configure a group (space) in Qomon
  - name: Customer
    description: Endpoints to manage customer data for CSM purposes.

paths:
  /customer/{customerId}/group:
    post:
      tags:
        - Create and setup group
      description: |-
        Called by pay service to billing service to trigger group creation based on customer subscription.
      parameters:
        - name: customerId
          in: path
          required: true
          schema:
            type: string
          description: ID of the customer for whom the group is created.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - mail
              properties:
                mail:
                  type: string
                  description: Email of the user to bind to the group. If the user doesn't exist, password is also required and user is created.
                password:
                  type: string
                first_name:
                  type: string
                last_name:
                  type: string
                phone:
                  type: string
                locale:
                  type: string
      responses:
        '201':
          description: Group created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  data:
                    type: object
                    properties:
                      group_id:
                        type: integer
                      description:
                        type: string      
  /onboarding/groups:
    post:
      tags:
        - Create and setup group
      description: Create a group (space) in Qomon. This endpoint is called by billing service. Group is created and user bind to it. Group isn't fully configured, it needs to be PATCH. Users is created if it doesn't exist. Need ultraadmin cookie.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    group:
                      type: object
                      properties:
                        features:
                          type: object
                        check_doublon:
                          type: boolean
                        around_me_disabled:
                          type: boolean
                        disable_autourdesoi:
                          type: string
                          enum:
                            - "true"
                            - "false"
                        code_edit_form:
                          type: string
                          enum:
                            - "true"
                            - "false"
                        code_edit_form_enabled:
                          type: boolean
                        create_refused_contacts_enabled:
                          type: boolean
                        allow_team_select:
                          type: boolean
                        allow_multiple_team_select:
                          type: boolean
                    user:
                      type: object
                      properties:
                        email:
                          type: string
      responses:
        '201':
          description: Group created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      description:
                        type: string
                      group_id:
                        type: integer
    patch:
      description: Setup a group (space) in Qomon. This endpoint is used during in app onboarding.
      tags:
        - Create and setup group
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    name:
                      type: string
                      description: Name of the group (space)
                    space_main_goal:
                      type: string
                      description: Main goal of the group, used to configure forms
                    country:
                      type: string
                      description: Alpha-3 code of the country where the group is located, used to configure geocoding
                    locale:
                      type: string
                      description: Locale of the group, used to configure form and geocoding language
                    data_parent_territories_administrative_ids:
                      type: string
                      description: Used to configure carto feature, need administrative ids of OSM georoot 
                    data_parent_territories_scale:
                      type: string
                      description: Used to configure carto feature, need scale of OSM georoot
                    data_map_root_label:
                      type: string
                      description: Used to configure carto feature, must be the label of the administrative id 
      responses:
        '200':
          description: Group updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    description: Group data
  /onboarding/territories:
    get:
      tags:
        - Create and setup group
      description: Search osm territories to setup a group.
      parameters:
        - name: query
          in: query
          required: true
          schema:
            type: string
          description: Search query for territories, e.g. "France"
        - name: language
          in: query
          required: true
          schema:
            type: string
        - name: country
          in: query
          required: true
          schema:
            type: string
            description: Alpha-3 code of the country to search in.
      responses:
        '200':
          description: Territories retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        name:
                          type: string
                        administrative_id:
                          type: string    
  /onboarding/groups/features:
    patch:
      tags:
        - Create and setup group
      description: Update features of a group. Allow for starter products to select the action type of the group.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                "actions.event_creation":
                  type: string
                  enum: ["enabled", "disabled"]
                "actions.sharing_creation":
                  type: string
                  enum: ["enabled", "disabled"]
                "actions.call_creation":
                  type: string
                  enum: ["enabled", "disabled"]
                "actions.canvassing_creation":
                  type: string
                  enum: ["enabled", "disabled"]
      responses:
        '200':
          description: Features updated successfully. Empty response.


  /billing/customer/group:
    patch:
      tags:
        - Customer
      description: Update customer data for a group in Qomon. This endpoint is used to inform CSM about customer preferences and needs.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                  space_main_goal:
                    type: string
                  organisation_size:
                    type: string
                  awareness_level:
                    type: string
      responses:
        '200':
          description: Customer data updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: string
                  data:
                    type: object
                    properties:
                      description:
                        type: string