openapi: 3.0.0
info:
  title: Account API
  version: 1.0.0
  description: >-
    The Account API manages customer accounts, billing addresses, and contact
    information for the Hauler Hero platform. All endpoints require API key
    authentication using the HERO-API-KEY header.
servers:
  - url: https://api.haulerhero.com
    description: Production server
security:
  - apiKey: []
tags:
  - name: Accounts
    description: Customer account management operations
paths:
  /hero-api/v1/accounts:
    post:
      tags:
        - Accounts
      summary: Create a new account
      description: >-
        Creates a new customer account with billing address and primary contact
        information
      operationId: createAccount
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountView'
            examples:
              newAccount:
                summary: New account example
                value:
                  accountName: Acme Corporation
                  billingAddress:
                    street: 123 Main St
                    city: San Francisco
                    state: CA
                    country: USA
                    zip: '94105'
                  primaryContact:
                    firstName: John
                    lastName: Doe
                    email: john.doe@acme.com
                    phone: +1-555-0123
      responses:
        '200':
          description: Account created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountView'
              examples:
                success:
                  value:
                    accountId: acc-789xyz
                    accountNumber: ACC-2024-0001
                    accountName: Acme Corporation
                    billingAddress:
                      addressId: addr-123
                      street: 123 Main St
                      city: San Francisco
                      state: CA
                      country: USA
                      zip: '94105'
                    primaryContact:
                      contactId: cont-456
                      firstName: John
                      lastName: Doe
                      email: john.doe@acme.com
                      phone: +1-555-0123
        '400':
          description: Invalid input - missing required fields or invalid format
        '401':
          description: Unauthorized - invalid or missing API key
        '409':
          description: Conflict - account already exists with this name
components:
  schemas:
    AccountView:
      type: object
      required:
        - accountName
      properties:
        accountId:
          type: string
          description: Unique identifier for the account (auto-generated)
          readOnly: true
          example: acc-789xyz
        accountNumber:
          type: string
          description: Unique account number (auto-generated)
          readOnly: true
          example: ACC-2024-0001
        accountName:
          type: string
          description: Name of the account/company
          minLength: 1
          maxLength: 200
          example: Acme Corporation
        billingAddress:
          $ref: '#/components/schemas/AddressView'
        primaryContact:
          $ref: '#/components/schemas/ContactView'
    AddressView:
      type: object
      properties:
        addressId:
          type: string
          description: Unique identifier for the address (auto-generated)
          readOnly: true
          example: addr-123
        street:
          type: string
          maxLength: 100
          example: 123 Main St
        unit:
          type: string
          maxLength: 20
          example: Suite 100
        city:
          type: string
          maxLength: 50
          example: San Francisco
        state:
          type: string
          maxLength: 2
          pattern: ^[A-Z]{2}$
          example: CA
        country:
          type: string
          maxLength: 50
          example: USA
        zip:
          type: string
          pattern: ^\d{5}(-\d{4})?$
          example: '94105'
    ContactView:
      type: object
      properties:
        contactId:
          type: string
          description: Unique identifier for the contact (auto-generated)
          readOnly: true
          example: cont-456
        firstName:
          type: string
          maxLength: 50
          example: John
        lastName:
          type: string
          maxLength: 50
          example: Doe
        email:
          type: string
          format: email
          maxLength: 100
          example: john.doe@acme.com
        phone:
          type: string
          pattern: ^[+]?[\d\s()-]+$
          maxLength: 20
          example: +1-555-0123
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: HERO-API-KEY
      description: |
        API key for authenticating requests.

        To obtain an API key:
        - Contact your account manager
        - Email: api-support@haulerhero.com

        Include in request header: `HERO-API-KEY: your_api_key_here`
