openapi: 3.0.3
info:
  title: CoDeliver External API
  version: "1.3.5"
  description: |
    External API for approved CoDeliver integration partners.

    ## Purpose
    This API is used by partner systems (for example POS, order-taking, or ERP) to create and manage
    delivery requests in CoDeliver.

    ## Intended Consumers
    - Server-side integrations operated by approved partners
    - Technical teams implementing order lifecycle orchestration

    ## Typical Lifecycle
    1. (Optional) Estimate delivery using `precalculate`
    2. Create a delivery request using `create`
    3. Mark order as pickup-ready when preparation is complete
    4. Cancel request when order should not be executed

    ## Security Model
    - HTTPS only
    - Shared secret via `Authorization` header
    - Credentials are provisioned privately during onboarding
servers:
  - url: https://d9p03pgzcl.execute-api.eu-west-1.amazonaws.com/prod
    description: Production
security:
  - SharedSecretAuth: []
tags:
  - name: Requests
    description: Endpoints for external request lifecycle management.
paths:
  /codeliver-external-precalculate-request:
    post:
      tags: [Requests]
      operationId: precalculateRequest
      summary: Precalculate delivery estimate
      description: |
        Returns estimate data before request creation.

        Use this endpoint when you want to show cost/time context before creating
        a delivery request.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PrecalculateRequest"
            examples:
              estimate:
                summary: Precalculate example
                value:
                  group: demo
                  store_id: S1
                  userLat: 37.98
                  userLng: 23.72
      responses:
        "200":
          description: Estimate result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
              examples:
                success:
                  value:
                    ok: true
                    message: estimate_success
                    data:
                      estimated_cost: 2.4
                      estimated_eta_minutes: 24
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
              examples:
                invalid_payload:
                  value:
                    ok: false
                    message: missing_required_fields
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
              examples:
                unauthorized:
                  value:
                    ok: false
                    message: unauthorized

  /codeliver-create-external-request:
    post:
      tags: [Requests]
      operationId: createExternalRequest
      summary: Create external delivery request
      description: |
        Creates a delivery request in CoDeliver.

        `request_id` must remain stable per order so retries do not create duplicate requests.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateRequest"
            examples:
              create:
                summary: Create request example
                value:
                  group: demo
                  store_id: S1
                  request_id: demo_R1
                  vendor_reference_id: POS-10342
                  mobile: "6900000000"
                  grand_total: 12.3
                  userLat: 37.98
                  userLng: 23.72
                  selected_address:
                    googleLat: 37.98
                    googleLng: 23.72
                    unverified: false
      responses:
        "200":
          description: Request created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
              examples:
                success:
                  value:
                    ok: true
                    message: request_created
                    data:
                      request_id: demo_R1
                      status: created
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /codeliver-external-request-cancel:
    post:
      tags: [Requests]
      operationId: cancelExternalRequest
      summary: Cancel external delivery request
      description: |
        Cancels an already created delivery request.

        Use when order cancellation is confirmed before execution.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CancelRequest"
            examples:
              cancel:
                summary: Cancel request example
                value:
                  group: demo
                  store_id: S1
                  request_id: demo_R1
                  canceled_reason: vendor_canceled
      responses:
        "200":
          description: Request canceled
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
              examples:
                success:
                  value:
                    ok: true
                    message: request_canceled
                    data:
                      request_id: demo_R1
                      status: canceled
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

  /codeliver-external-request-pickup-ready:
    post:
      tags: [Requests]
      operationId: setPickupReady
      summary: Mark request as pickup-ready
      description: |
        Updates a created request to pickup-ready state.

        Use when order preparation has finished and handoff to rider can begin.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PickupReadyRequest"
            examples:
              pickup_ready:
                summary: Pickup-ready example
                value:
                  group: demo
                  store_id: S1
                  request_id: demo_R1
      responses:
        "200":
          description: Request updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
              examples:
                success:
                  value:
                    ok: true
                    message: pickup_ready_updated
                    data:
                      request_id: demo_R1
                      status: pickup_ready
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiResponse"

components:
  securitySchemes:
    SharedSecretAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Shared secret assigned during onboarding (for example `Authorization: <shared-secret>`).

  schemas:
    ApiResponse:
      type: object
      description: Standard response envelope used by External API endpoints.
      properties:
        ok:
          type: boolean
          description: Indicates whether the request was handled successfully.
        message:
          type: string
          description: Human-readable outcome code or message.
        data:
          type: object
          description: Endpoint-specific payload.
          additionalProperties: true
      additionalProperties: true

    BaseRequest:
      type: object
      required:
        - group
        - store_id
      properties:
        group:
          type: string
          description: Tenant / organization identifier assigned during onboarding.
          example: demo
        store_id:
          type: string
          description: Store identifier in CoDeliver.
          example: S1

    PrecalculateRequest:
      allOf:
        - $ref: "#/components/schemas/BaseRequest"
        - type: object
          required:
            - userLat
            - userLng
          properties:
            userLat:
              type: number
              format: double
              description: End-customer latitude for route and estimate calculation.
              example: 37.98
            userLng:
              type: number
              format: double
              description: End-customer longitude for route and estimate calculation.
              example: 23.72

    AddressPayload:
      type: object
      description: Optional geocoded address metadata when already available at partner side.
      properties:
        googleLat:
          type: number
          format: double
          description: Geocoded latitude.
          example: 37.98
        googleLng:
          type: number
          format: double
          description: Geocoded longitude.
          example: 23.72
        distance_by_store_id:
          type: number
          format: double
          description: Pre-calculated distance from store (km), if available.
          example: 1.2
        radius_distance_by_store_id:
          type: number
          format: double
          description: Radius distance from store (km), if available.
          example: 1.1
        address_components:
          type: array
          description: Structured address parts from geocoder.
          items:
            type: object
            additionalProperties: true
        unverified:
          type: boolean
          description: Whether address has not been fully verified.
          example: false
      additionalProperties: true

    CreateRequest:
      allOf:
        - $ref: "#/components/schemas/BaseRequest"
        - type: object
          required:
            - request_id
            - vendor_reference_id
            - mobile
            - grand_total
            - userLat
            - userLng
          properties:
            request_id:
              type: string
              description: Unique request identifier used for idempotent retries.
              example: demo_R1
            vendor_reference_id:
              type: string
              description: Partner-side reference (for example POS order id).
              example: POS-10342
            mobile:
              type: string
              description: End-customer mobile phone number.
              example: "6900000000"
            grand_total:
              type: number
              format: double
              description: Final order total amount.
              example: 12.3
            userLat:
              type: number
              format: double
              description: End-customer latitude.
              example: 37.98
            userLng:
              type: number
              format: double
              description: End-customer longitude.
              example: 23.72
            selected_address:
              $ref: "#/components/schemas/AddressPayload"
          additionalProperties: true

    CancelRequest:
      allOf:
        - $ref: "#/components/schemas/BaseRequest"
        - type: object
          required:
            - request_id
            - canceled_reason
          properties:
            request_id:
              type: string
              description: Previously created request identifier.
              example: demo_R1
            canceled_reason:
              type: string
              description: Cancel reason supplied by partner system.
              example: vendor_canceled
          additionalProperties: true

    PickupReadyRequest:
      allOf:
        - $ref: "#/components/schemas/BaseRequest"
        - type: object
          required:
            - request_id
          properties:
            request_id:
              type: string
              description: Previously created request identifier.
              example: demo_R1
          additionalProperties: true
