openapi: 3.0.0
info:
  title: AddressBook
  version: 2.0.0
  description: |
    An **AddressBook** is a contact entry. It links contact information
    (phone, email, PEC, fax, etc.) to an entity on the platform: a person,
    an office, a project, or a supplier.

    Use this API to:
    - Add a contact (email, phone, etc.) to a person, office, or supplier
    - Find all contacts for an entity (filter by `entity_id`)
    - Search for a contact by value (e.g. find who has a specific phone number)
servers:
  - url: http://service.4hse.com/
security:
  - OAuth2: []
  - AccessToken: []
paths:
  /v2/address-book/index:
    post:
      summary: index
      operationId: indexAddressBook
      tags:
        - AddressBook
      description: >
        Returns a paginated list of contacts.


        The `entity_id` query parameter is optional. If provided, filters
        contacts

        for that specific entity. If omitted, returns contacts for all
        accessible

        entities in the project (people, offices, suppliers).


        Most useful filters:

        - `entity_id`: all contacts for a person, office, or supplier

        - `type`: filter by contact type (e.g. `Email`, `telephone`)

        - `value`: search by contact value
      parameters:
        - name: entity_id
          in: query
          description: Filter contacts for this entity (person_id, office_id, project_id,
            or unit_id).
          required: false
          schema:
            type: string
            format: uuid
      requestBody:
        description: Parameters for searching contacts
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AddressBookIndexParams"
            example:
              filter:
                type: Email
              per-page: 20
              page: 1
              sort: type
      responses:
        "200":
          description: List of contacts
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/AddressBook"
          headers:
            X-Pagination-Current-Page:
              schema:
                type: integer
              description: Current page
            X-Pagination-Page-Count:
              schema:
                type: integer
              description: Total number of pages
            X-Pagination-Per-Page:
              schema:
                type: integer
              description: Number of items per page
            X-Pagination-Total-Count:
              schema:
                type: integer
              description: Total number of items
  /v2/address-book/create:
    post:
      summary: create
      operationId: createAddressBook
      tags:
        - AddressBook
      description: >
        Creates a new contact entry.


        Requires `entity_id`, `type`, and `value`.

        The `delivery_id` is auto-generated if not provided.


        The `entity_id` can be a `person_id`, `office_id`, `project_id`, or
        `unit_id`.
      requestBody:
        description: Contact to create
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AddressBook"
            example:
              entity_id: e3a1f5d2-8c4b-4e7a-9f6d-2b1c3d4e5f6a
              type: Email
              value: john.smith@example.com
              description: Work email
      responses:
        "201":
          description: Contact created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AddressBook"
              example:
                delivery_id: 7e8f9012-3456-7890-abcd-ef7890123456
                entity_id: e3a1f5d2-8c4b-4e7a-9f6d-2b1c3d4e5f6a
                type: Email
                value: john.smith@example.com
                description: Work email
  /v2/address-book/view/{id}:
    get:
      summary: view
      operationId: viewAddressBook
      tags:
        - AddressBook
      description: Retrieves a single contact by its ID.
      parameters:
        - name: id
          in: path
          description: The delivery_id to retrieve.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Contact found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AddressBook"
        "404":
          description: Contact not found
  /v2/address-book/update/{id}:
    put:
      summary: update
      operationId: updateAddressBook
      tags:
        - AddressBook
      description: Updates an existing contact.
      parameters:
        - name: id
          in: path
          description: The delivery_id to update.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        description: Fields to update
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AddressBook"
            example:
              value: john.smith.new@example.com
      responses:
        "200":
          description: Contact updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AddressBook"
        "404":
          description: Contact not found
  /v2/address-book/delete/{id}:
    delete:
      summary: delete
      operationId: deleteAddressBook
      tags:
        - AddressBook
      description: Deletes a contact.
      parameters:
        - name: id
          in: path
          description: The delivery_id to delete.
          required: true
          schema:
            type: string
            format: uuid
        - name: force
          in: query
          description: If true, deletes the contact.
          schema:
            type: boolean
            default: false
      responses:
        "204":
          description: Contact deleted successfully
        "400":
          description: Preview of affected entities (returned when force=false)
components:
  schemas:
    AddressBook:
      type: object
      required:
        - entity_id
        - type
        - value
      properties:
        delivery_id:
          type: string
          format: uuid
          description: Unique identifier of the contact entry. Auto-generated if not
            provided.
        type:
          type: string
          maxLength: 50
          enum:
            - telephone
            - Email
            - mobilephone
            - Fax
            - Skype
            - Web
            - PEC
          description: |
            Contact type:
            - `telephone`: landline phone
            - `mobilephone`: mobile phone
            - `Email`: email address
            - `PEC`: certified email
            - `Fax`: fax number
            - `Skype`: Skype contact
            - `Web`: website URL
        value:
          type: string
          maxLength: 70
          description: The contact value (e.g. phone number, email address, website URL).
        description:
          type: string
          maxLength: 140
          description: Optional description of the contact (e.g. "Work", "Personal",
            "Emergency").
        note:
          type: string
          maxLength: 255
          description: Additional notes.
        entity_id:
          type: string
          format: uuid
          description: |
            The entity this contact belongs to. Can be:
            - A `person_id` for a person's contact
            - An `office_id` for an office's contact
            - A `project_id` for a project's contact
            - A `unit_id` for a supplier's contact
    AddressBookIndexParams:
      type: object
      properties:
        filter:
          $ref: "#/components/schemas/AddressBook"
        per-page:
          type: integer
          minimum: 1
          default: 100
        page:
          type: integer
          minimum: 1
          default: 1
        sort:
          type: string
          enum:
            - type
            - entity_id
            - value
      example:
        filter:
          type: Email
        per-page: 100
        page: 1
        sort: type
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        password:
          tokenUrl: https://auth.4hse.com/realms/4hse/protocol/openid-connect/token
          scopes: {}
    AccessToken:
      type: apiKey
      in: query
      name: access-token
