openapi: 3.1.0
info:
  version: 2.0.0
  title: PreETA API
  description: PreETA API - Managed by the Tracking Tribe
  license:
    name: Proprietary
    url: https://bettermile.com/legal-notice
  contact:
    name: Bettermile - Data Solutions Team
    email: datasolutions@bettermile.com
servers:
  - url: https://data-solutions-v2.bettermile.com
    description: Production Environment
tags:
  - name: Address Based PreETA
    description: Endpoints related to PreETA
paths:
  /pre-eta/api/v2/get-address-based-pre-eta:
    post:
      tags:
        - Address Based PreETA
      description: This endpoint allows you to get the PreETAs for a given address
      operationId: getAddressBasedPreETA
      security:
        - ClientCredentialsFlow:
            - read
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PreETARequestBody'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreETAResponseBody'
        '400':
          description: Validation errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreETA400Error'
        '401':
          description: Unauthorized
        '404':
          description: PreETA not available
        '422':
          description: PreETA not available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreETA422Error'
        '500':
          description: Server error
  /pre-eta/api/v2/loading-zones: {}
components:
  schemas:
    PreETARequestBody:
      type: object
      properties:
        parcelNumber:
          type: string
        estimatedDeliveryDate:
          type: string
        address:
          type: object
          properties:
            street:
              type: string
            countryCode:
              type: string
            houseNumber:
              type: string
            postalCode:
              type: string
            locality:
              type: string
            province:
              type: string
          required:
            - street
            - countryCode
      required:
        - parcelNumber
        - estimatedDeliveryDate
        - address
    PreETAResponseBody:
      type: array
      items:
        type: object
        properties:
          lowerBound:
            type: string
            example: '10:15:00'
          upperBound:
            type: string
            example: '13:15:00'
          date:
            type: string
            example: '2025-08-15'
    PreETA422Error:
      type: object
      required:
        - id
        - reason
      properties:
        id:
          type: string
          example: PRE_ETA_2
        reason:
          type: string
          example: failed to geocode address
        details:
          type: string
          description: >-
            Optional field for additional technical details or validation
            errors.
          nullable: true
    PreETA400Error:
      type: object
      required:
        - id
        - reason
      properties:
        id:
          type: string
          example: PRE_ETA_3
        reason:
          type: string
          example: Request validation failed
        details:
          type: array
          description: A list of specific validation or business logic failures.
          items:
            type: string
          example:
            - street cannot be empty
            - countryCode cannot be empty
          nullable: true
    LoadingZonesConfig:
      type: object
      properties:
        tenant_id:
          type: string
          example: gls-de
        internal_depot_id:
          type: string
          example: '35'
      required:
        - tenant_id
        - internal_depot_id
    LoadingZonesJob:
      type: object
      properties:
        external_job_id:
          type: string
          example: '90437913133'
        lat:
          type: number
          description: Geographic latitude coordinate
          example: 50.9098881
        lng:
          type: number
          description: Geographic longitude coordinate
          example: 9.5806327
      required:
        - external_job_id
        - lat
        - lng
    LoadingZonesRequestBody:
      type: object
      properties:
        config:
          $ref: '#/components/schemas/LoadingZonesConfig'
        jobs:
          type: array
          items:
            $ref: '#/components/schemas/LoadingZonesJob'
      required:
        - config
        - jobs
    LoadingZones:
      type: object
      properties:
        zone_id:
          type: string
          enum:
            - A
            - B
            - C
        lower_bound:
          type: string
          format: time
          example: '10:30:00'
        upper_bound:
          type: string
          format: time
          example: '12:30:00'
        external_job_ids:
          type: array
          items:
            type: string
            example: '90437913133'
      required:
        - zone_id
        - lower_bound
        - upper_bound
        - external_job_ids
    LoadingZonesResponse:
      type: object
      properties:
        config:
          $ref: '#/components/schemas/LoadingZonesConfig'
        zones:
          type: array
          items:
            $ref: '#/components/schemas/LoadingZones'
      required:
        - config
        - zones
  securitySchemes:
    bearerToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
    ClientCredentialsFlow:
      type: oauth2
      description: >-
        This API uses the OAuth 2.0 Client Credentials flow for
        machine-to-machine authentication.
      flows:
        clientCredentials:
          tokenUrl: https://auth.bettermile.com/api/v1/machines/token
          scopes:
            read: Grants read access to resources
security:
  - bearerToken: []
  - ClientCredentialsFlow:
      - read
      - write
