openapi: 3.1.0
info:
  title: Parcel
  version: 1.0.0
  description: Fictional label API for a custom workflow example. No live service exists.
servers:
  - url: https://api.parcel.example
security:
  - bearerAuth: []
paths:
  /shipments/{shipment_id}:
    get:
      operationId: getShipment
      tags: [shipments]
      parameters:
        - name: shipment_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Shipment readiness
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Shipment'
  /labels:
    post:
      operationId: createLabel
      tags: [labels]
      description: Request one label. Repeating a key with the same shipment returns the original label; a different shipment with that key is rejected.
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema: { type: string, minLength: 1 }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [shipment_id]
              properties:
                shipment_id: { type: string }
      responses:
        '202':
          description: Label request accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Label'
  /labels/{label_id}:
    get:
      operationId: getLabel
      tags: [labels]
      parameters:
        - name: label_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Current label state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Label'
components:
  securitySchemes:
    bearerAuth: { type: http, scheme: bearer }
  schemas:
    Shipment:
      type: object
      required: [shipment_id, address_verified]
      properties:
        shipment_id: { type: string }
        address_verified: { type: boolean }
        review_url: { type: string }
    Label:
      type: object
      required: [label_id, status]
      properties:
        label_id: { type: string }
        status:
          type: string
          enum: [processing, ready, action_required, failed]
        download_url: { type: string }
        action_url: { type: string }
        message: { type: string }