openapi: 3.0.0
info:
  title: Sale API - Apigee
  description: >-
    Sale API documentation <h2>Authentication & Authorization</h2> <p>You will
    need to be identified before calling any endpoints. </p> <p>In order to be
    recognized and authorized to access our Sale API, we put in place 2
    mechanisms:</p><ul><li>Authentication mechanism is done with a client id
    dedicated to you. <br/>Remember that the client id provided should be shared
    with care.<br/> The client id must be inserted in the header of the request
    in the appropriate field</li><li>Authorization mechanism is done by a
    well-known authorization flow for REST Web API: <strong>Basic auth
    flow.</strong></li></ul>
  license:
    name: Internal usage only
  version: 1.0.0
servers:
  - url: https://indus.api.euromaster.com
    description: APIGEE UAT
  - url: https://api.euromaster.com
    description: APIGEE PROD
tags:
  - name: Sales
    description: Sales operation with all operation types
paths:
  /sale-erm/v1/sales:
    summary: Sales endpoints
    get:
      summary: Get Sales data
      description: Get sales data filtered by parameters
      operationId: getSales
      tags:
        - Sales
      parameters:
        - in: query
          name: pageNumber
          schema:
            $ref: '#/components/schemas/PageNumberParam'
          required: true
          description: The page number
        - in: query
          name: pageSize
          schema:
            $ref: '#/components/schemas/PageSizeParam'
          required: true
          description: The page size
        - in: query
          name: lastModifiedDateFrom
          required: false
          description: Date from for last update date of data
          schema:
            $ref: '#/components/schemas/lastModifiedDateFromParam'
        - in: query
          name: lastModifiedDateTo
          required: false
          description: Date to for last update date of data
          schema:
            $ref: '#/components/schemas/lastModifiedDateToParam'
        - in: query
          name: externalRef
          required: false
          description: Identifier of the external reference
          schema:
            $ref: '#/components/schemas/ExternalRefQueryParam'
        - in: query
          name: source
          required: false
          description: Source of the external reference
          schema:
            $ref: '#/components/schemas/SourceQueryParam'
      responses:
        '200':
          $ref: '#/components/responses/SalesResponseDTO'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestDTO'
              examples:
                InvalidPageSize:
                  value:
                    errors:
                      - error: must be greater than or equal to 1
                        property: pageSize
                InvalidPageNumber:
                  value:
                    errors:
                      - error: must be greater than or equal to 1
                        property: pageNumber
                InvalidDatesOrder:
                  value:
                    errors:
                      - error: 'dateFrom : 2024-07-01T00:00:00 is greater than dateTo'
                        property: lastModifiedDateFrom
        '500':
          description: Internal error
  /sale-erm/v1/sales/external:
    summary: Sales external endpoints
    post:
      summary: Create sale data
      description: Create sale
      operationId: createSale
      tags:
        - Sales
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSaleQueryDTO'
            examples:
              standardBody:
                summary: Create sale
                description: Create a sale with the given information
                value:
                  externalRef: '12345'
                  billToExternalRef: AA123
                  sellerExternalRef: IUA829
                  vehicleExternalRef: UYT9182
                  date: '2024-10-10T17:31:00'
                  currency: EUR
                  amountInclVat: '100'
                  lines:
                    - number: 1
                      articleCode: '1000003'
                      unitPriceInclVat: 12.5
                      quantity: 4
                      quantityUOM: PCE
                    - number: 2
                      articleCode: '1000075'
                      unitPriceInclVat: 12.5
                      quantity: 4
                      quantityUOM: PCE
                    - number: 3
                      articleCode: '1000234'
                      unitPriceInclVat: 12.5
                      quantity: 1
                      quantityUOM: PCE
      responses:
        '200':
          $ref: '#/components/responses/CreateSaleResponseDTO'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestDTO'
              examples:
                missing mandatory field:
                  value:
                    errors:
                      - error: Missing mandatory tag
                        property: externalRef
        '500':
          description: Internal error
security:
  - OAuth2: []
    ApiKeyAuth: []
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows: {}
    ApiKeyAuth:
      type: apiKey
      in: header
      name: clientid
  schemas:
    InternalErrorDTO:
      type: object
      properties:
        error:
          type: string
          example: >-
            An internal error occurred, please try again later. Thank you for
            your understanding
    BadRequestDTO:
      type: object
      properties:
        errors:
          type: array
          minItems: 1
          items:
            type: object
            properties:
              error:
                type: string
                format: string
                description: Error message
              property:
                type: string
                format: string
                description: Name of the field affected by the error
    UnauthorizedDTO:
      type: object
      properties:
        errors:
          type: array
          minItems: 1
          items:
            type: object
            properties:
              error:
                type: string
                format: string
                description: Error message
              property:
                type: string
                format: string
                description: Name of the field affected by the error
    CreateSaleLineQueryDTO:
      type: object
      properties:
        number:
          $ref: '#/components/schemas/LineNumber'
        articleExternalRef:
          description: External ref of the article
          type: string
          maxLength: 255
          example: '1000234'
        unitPriceInclVat:
          $ref: '#/components/schemas/UnitPriceInclVat'
        quantity:
          $ref: '#/components/schemas/Quantity'
        quantityUOM:
          $ref: '#/components/schemas/QuantityUOM'
    LineNumber:
      description: Line number of the sale
      type: integer
      example: 1
    UnitPriceInclVat:
      description: Unit price of the sale line including VAT
      type: number
      format: float
      example: 12.5
    Quantity:
      description: Quantity of the sale article
      type: number
      format: float
      example: 1
    QuantityUOM:
      description: Unit of the quantity of the sale article
      type: string
      maxLength: 255
      example: PCE
    CreateSaleQueryDTO:
      type: object
      properties:
        externalRef:
          $ref: '#/components/schemas/ExternalRef'
        billToExternalRef:
          description: External ref of the bill to
          type: string
          maxLength: 255
          example: '12345678'
        sellerExternalRef:
          $ref: '#/components/schemas/SellerExternalRef'
        vehicleExternalRef:
          description: External ref of the vehicle
          type: string
          maxLength: 255
          example: '12345678'
        date:
          $ref: '#/components/schemas/SaleDate'
        currency:
          description: Currency used for the sale
          $ref: '#/components/schemas/CurrencyEnum'
        amountInclVat:
          $ref: '#/components/schemas/AmountInclVat'
        lines:
          description: List of lines of the sale
          type: array
          items:
            $ref: '#/components/schemas/CreateSaleLineQueryDTO'
      required:
        - externalRef
    ExternalRef:
      description: Source application code of the sale
      type: string
      maxLength: 255
      example: '12345678'
    AmountInclVat:
      description: Total amount of the sale including VAT
      type: number
      format: float
      example: 100
    SaleDate:
      description: Date of the sale
      type: string
      format: date-time
      example: '2028-09-10T10:00:00'
    CurrencyEnum:
      type: string
      enum:
        - EUR
        - CHF
        - GBP
    CreateSaleResponseDTO:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/SaleCode'
    SellerExternalRef:
      description: External ref of the seller
      type: string
      maxLength: 255
      example: '12345678'
    SaleCode:
      type: integer
      format: int32
      example: '1000001'
      description: Unique identifier of the sale
    BillToCode:
      type: integer
      format: int32
      example: '1000001'
      description: Unique identifier of the bill to
    SellerCode:
      type: integer
      format: int32
      example: '1000001'
      description: Unique identifier of the seller
    VehicleCode:
      type: integer
      format: int32
      example: '1000001'
      description: Unique identifier of the vehicle
    PageNumberParam:
      type: integer
      format: int32
      example: '2'
      minimum: 1
      maximum: 1000
      description: Number of the page requested, minimum 1
    PageSizeParam:
      type: integer
      format: int32
      example: '2'
      minimum: 1
      maximum: 1000
      description: Size of the page
    lastModifiedDateFromParam:
      type: string
      format: date-time
      example: '2024-05-02T10:00:00'
      description: Last modified date from, must have the format yyyy-MM-ddTHH:mm:ss
    lastModifiedDateToParam:
      type: string
      format: date-time
      example: '2024-05-02T10:00:00'
      description: Last modified date to, must have the format yyyy-MM-ddTHH:mm:ss
    ExternalRefQueryParam:
      type: string
      example: '1000045'
      description: Source application code of the sale
      maxLength: 255
    SourceQueryParam:
      type: string
      example: GENES
      description: Source of the external reference
      maxLength: 255
    SalesResponseDTO:
      type: object
      properties:
        pagination:
          description: Pagination information
          $ref: '#/components/schemas/PaginationDTO'
        sales:
          type: array
          maxItems: 1000
          items:
            description: Sales information
            $ref: '#/components/schemas/SaleDTO'
    PaginationDTO:
      type: object
      additionalProperties: false
      properties:
        next:
          type: string
          maxLength: 200
          description: Url for next page
          example: /vehicle-erm/v1/vehicles?pageNumber=3&pageSize=50
        previous:
          type: string
          maxLength: 200
          description: Url for previous page
          example: /vehicle-erm/v1/vehicles?pageNumber=1&pageSize=50
        pageTotal:
          type: integer
          format: int32
          example: '2'
          minimum: 0
          maximum: 1000
          description: Number total of page available
        totalElements:
          type: integer
          format: int32
          example: '200'
          minimum: 0
          maximum: 10000
          description: Number total of elements available
    SaleDTO:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/SaleCode'
        billToCode:
          $ref: '#/components/schemas/BillToCode'
        sellerCode:
          $ref: '#/components/schemas/SellerCode'
        sellerExternalRef:
          $ref: '#/components/schemas/SellerExternalRef'
        vehicleCode:
          $ref: '#/components/schemas/VehicleCode'
        date:
          $ref: '#/components/schemas/SaleDate'
        currency:
          description: Currency used for the sale
          $ref: '#/components/schemas/CurrencyEnum'
        amountInclVat:
          $ref: '#/components/schemas/AmountInclVat'
        lines:
          type: array
          maxItems: 1000
          items:
            description: Sale lines
            $ref: '#/components/schemas/LineDTO'
        references:
          type: array
          maxItems: 1000
          items:
            description: Sale references
            $ref: '#/components/schemas/SaleReferenceDTO'
    LineDTO:
      type: object
      properties:
        number:
          $ref: '#/components/schemas/LineNumber'
        articleCode:
          type: integer
          format: int32
          example: '1000001'
          description: Unique identifier of the article
        unitPriceInclVat:
          $ref: '#/components/schemas/UnitPriceInclVat'
        quantity:
          $ref: '#/components/schemas/Quantity'
        quantityUOM:
          $ref: '#/components/schemas/QuantityUOM'
    SaleReferenceDTO:
      type: object
      properties:
        source:
          type: string
          example: ES_EQUITY
          maxLength: 20
          description: Reference source
        externalRef:
          $ref: '#/components/schemas/ExternalRef'
        countryCode:
          type: string
          example: ES
          maxLength: 255
          description: Reference country code
        lastModifiedDate:
          description: Date when the external reference was last modified.
          type: string
          example: '2024-05-02T10:00:00'
          pattern: >-
            ^([0-9]{4})-(?:[0-9]{2})-([0-9]{2})T([01][0-9]|2[0-3]):([0-5][0-9]):([0-5][0-9])$
  responses:
    InternalErrorDTO:
      description: An internal error occurred
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InternalErrorDTO'
          examples:
            internalError:
              summary: An internal error occurred
              value:
                errors:
                  - error: >-
                      An internal error occurred, please try again later. Thank
                      you for your understanding
    UnauthorizedDTO:
      description: The requester is not recognized by our system.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnauthorizedDTO'
          examples:
            Unknown client id:
              summary: Unknown client id
              value:
                errors:
                  - error: Unknown client id, please contact our API service support
                    property: clientid
            Missing client id:
              summary: Missing client id
              value:
                errors:
                  - error: The client id is missing
                    property: clientid
            Bad credentials:
              summary: The credentials are wrong
              value:
                errors:
                  - error: The credentials are wrong
                    property: Authorization
            Missing credentials:
              summary: The credentials are missing
              value:
                errors:
                  - error: The credentials are missing
                    property: Authorization
    CreateSaleResponseDTO:
      description: Sales
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateSaleResponseDTO'
          examples:
            standardResponse:
              value:
                code: '1000293'
    SalesResponseDTO:
      description: Sales
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SalesResponseDTO'
          examples:
            standardResponse:
              value:
                '[object Object]': null
