openapi: 3.0.1
info:
  title: Company API
  description: |
    ## Purpose

     This API lets you manage companies and their images in Pagero Online.

    ## Key Concepts

    **Company** - A company entity with metadata (typically created by an administrator).

    **Image** - An image associated with a company profile.

    **ImageType** - Specifies the image's intended use (for example, WebLogo or MailLogo).
  version: 1.0.1
servers:
- url: https://api.pageroonline.com/company/v1
  description: Production server. Will use `europe1` region by default.
  x-internal: false
- url: "https://api.{region}.pageroonline.com/company/v1"
  description: Regional API URL for production server.
  variables:
    region:
      description: The geographic region for data residency.
      default: europe1
  x-internal: false
tags:
- name: Company
  description: Handle companies
- name: Image
  description: Handle company images
paths:
  /companies:
    get:
      tags:
      - Company
      summary: Get all companies.
      description: Get all companies the currently authenticated user has access to. The companies are sorted in alphabetic order by company name.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Company"
              example:
              - id: b7e2c1e2-6a2e-4e7a-9b2a-1c3e8e2f4d5a
                name: Lemon Inc.
                department: Sales
                address:
                  street: 123 Main St
                  postBox: PO Box 456
                  postCode: "12345"
                  town: Sampletown
                  province: Sampleprovince
                  countryCode: SE
                identifiers:
                - idType: VAT
                  value: SE1234567890
                contact:
                  email: info@example.com
                  phone: "+46123456789"
                  fax: "+46123456780"
                  webpage: https://www.example.com
                customerNumber: CUST-001
                unitNumber: U001
                region:
                  id: europe1
                  baseUrl: https://api.europe1.pageroonline.com
              - id: e3a1c2b4-8f7d-4c2a-9e1b-2d4f6a7b8c9d
                name: Orange Solutions
                address:
                  street: 456 Innovation Ave
                  postCode: "67890"
                  town: Innoville
                  countryCode: SE
                identifiers:
                - idType: VAT
                  value: SE9876543210
                contact:
                  email: contact@orangesolutions.com
                  phone: "+46109876543"
                customerNumber: CUST-002
                region:
                  id: europe1
                  baseUrl: https://api.europe1.pageroonline.com
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/UnAuthorizedErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/InternalServerError"
  /companies/{id}:
    get:
      tags:
      - Company
      summary: Get a company.
      description: Get the company when the calling user has access to it.
      parameters:
      - name: id
        in: path
        description: Id of Company
        required: true
        schema:
          type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CompanyWithCompanyGroup"
              example:
                id: b7e2c1e2-6a2e-4e7a-9b2a-1c3e8e2f4d5a
                name: Lemon Inc.
                department: Sales
                address:
                  street: 123 Main St
                  postBox: PO Box 456
                  postCode: "12345"
                  town: Sampletown
                  province: Sampleprovince
                  countryCode: SE
                identifiers:
                - idType: VAT
                  value: SE1234567890
                contact:
                  email: info@example.com
                  phone: "+46123456789"
                  fax: "+46123456780"
                  webpage: https://www.example.com
                customerNumber: CUST-001
                region:
                  id: europe1
                  baseUrl: https://api.europe1.pageroonline.com
                companyGroup:
                  id: group-001
                  name: Sample Group
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/UnAuthorizedErrorResponse"
        "404":
          description: Company not found
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/NotFoundErrorResponse"
              example:
              - errorCode: NOT_AVAILABLE_IN_REGION
                description: Not available in current region.
                technicalDescription: Company does not exist in this region.
                resourceUrl: https://api.europe1.pageroonline.com/company/v1/companies/b7e2c1e2-6a2e-4e7a-9b2a-1c3e8e2f4d5a
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/InternalServerError"
  /companies/{id}/availableroles:
    get:
      tags:
      - Company
      summary: Get available company roles.
      description: Get all available roles for a company.
      parameters:
      - name: id
        in: path
        description: Id of the Company
        required: true
        schema:
          type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  roles:
                    type: array
                    items:
                      type: string
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/UnAuthorizedErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ForbiddenErrorResponse"
        "404":
          description: Company not found
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/NotFoundErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/InternalServerError"
  /companies/{companyId}/image:
    get:
      tags:
      - Image
      summary: Get a company image.
      description: All company users can get the company image.
      parameters:
      - name: companyId
        in: path
        description: Id of the Company
        required: true
        schema:
          type: string
      - name: imageType
        in: query
        description: The imageType (the usage of image with company profile)
        required: true
        schema:
          type: string
          enum:
          - WebLogo
          - PdfLogo
          - MailLogo
          - WebBanner
      - name: width
        in: query
        description: How wide in pixels the image will be presented. This is used to pick the most efficient size  in the response.
        required: false
        schema:
          type: integer
      responses:
        "200":
          description: OK
          content:
            image/*:
              schema:
                type: string
                format: binary
        "204":
          description: No image found
          content: {}
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/InternalServerError"
    put:
      tags:
      - Image
      summary: Update a company image.
      description: Company admins can update a company image.
      parameters:
      - name: companyId
        in: path
        description: Id of the Company
        required: true
        schema:
          type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
              - image
              - imageType
              - mimeType
              type: object
              properties:
                image:
                  type: string
                  description: The image file to upload
                  format: binary
                imageType:
                  type: string
                  description: The type of image
                  example: "WebLogo, PdfLogo, MailLogo, WebBanner"
                mimeType:
                  type: string
                  description: The MIME type of the image
                  example: "image/jpeg, image/png"
        required: true
      responses:
        "202":
          description: Request accepted for processing
          content: {}
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/UnAuthorizedErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ForbiddenErrorResponse"
        "404":
          description: Company not found
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/NotFoundErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/InternalServerError"
    delete:
      tags:
      - Image
      summary: Delete a company image.
      description: Company admins can delete a company image.
      parameters:
      - name: companyId
        in: path
        description: Id of the Company
        required: true
        schema:
          type: string
      - name: imageType
        in: query
        description: The imageType
        required: true
        schema:
          type: string
          enum:
          - WebLogo
          - PdfLogo
          - MailLogo
          - WebBanner
      responses:
        "202":
          description: Request accepted for processing; image deletion will be performed asynchronously.
          content: {}
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/UnAuthorizedErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ForbiddenErrorResponse"
        "404":
          description: Company not found
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/NotFoundErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/InternalServerError"
components:
  schemas:
    Address:
      type: object
      properties:
        street:
          type: string
          description: "Street address, line 1"
        postBox:
          type: string
          description: Post box
        postCode:
          type: string
          description: Post code
        town:
          type: string
          description: Town
        province:
          type: string
          description: Province
        countryCode:
          type: string
          description: CountryCode is an ISO 3166-1 alpha-2 code
    Region:
      type: object
      properties:
        id:
          type: string
          description: The name of the region
        baseUrl:
          type: string
          description: The base url to the region where the company exists.
    Company:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
          description: The company name
        department:
          type: string
          description: The department
        address:
          $ref: "#/components/schemas/Address"
        identifiers:
          type: array
          items:
            $ref: "#/components/schemas/CompanyId"
        contact:
          $ref: "#/components/schemas/ContactInformation"
        customerNumber:
          type: string
        unitNumber:
          type: string
          description: The unit number of the company
        region:
          $ref: "#/components/schemas/Region"
    CompanyGroup:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
          description: The company group name
    CompanyWithCompanyGroup:
      allOf:
      - $ref: "#/components/schemas/Company"
      - type: object
        properties:
          companyGroup:
            $ref: "#/components/schemas/CompanyGroup"
    CompanyId:
      type: object
      properties:
        idType:
          type: string
          description: Type of id
        value:
          type: string
          description: The id value
    ContactInformation:
      type: object
      properties:
        email:
          type: string
          description: The company's email address
        phone:
          type: string
          description: The company's phone number
        fax:
          type: string
          description: The company's fax number
        webpage:
          type: string
          description: The company's webpage
    ForbiddenErrorResponse:
      type: object
      properties:
        errorCode:
          type: string
          description: |
            Error code. Possible values:
             - **FORBIDDEN** Not authorized to perform action
          example: FORBIDDEN
        description:
          type: string
          description: The translated errormessage.
        technicalDescription:
          type: string
          description: A more detailed description of the error in English.
    InternalServerError:
      type: object
      properties:
        errorCode:
          type: string
          description: |
            Error code. Possible values:
             - **INTERNAL_SERVER_ERROR** Unknown error
          example: INTERNAL_SERVER_ERROR
        description:
          type: string
          description: The translated errormessage.
        technicalDescription:
          type: string
          description: A more detailed description of the error in English.
    NotFoundErrorResponse:
      type: object
      properties:
        errorCode:
          type: string
          description: |
            Error code. Possible values:
             - **NOT_FOUND** The company can not be found
             - **NOT_AVAILABLE_IN_REGION** The company is not in current region
          example: NOT_FOUND
        description:
          type: string
          description: The translated errormessage.
        technicalDescription:
          type: string
          description: A more detailed description of the error in English.
        resourceUrl:
          type: string
          description: The url to the requested resource if errorCode is NOT_AVAILABLE_IN_REGION.
    UnAuthorizedErrorResponse:
      type: object
      properties:
        errorCode:
          type: string
          description: |
            Error code. Possible values:
             - **UNAUTHORIZED** The authorization code is not active
          example: UNAUTHORIZED
        description:
          type: string
          description: The translated errormessage.
        technicalDescription:
          type: string
          description: A more detailed description of the error in English.
