post:
  operationId: createStation
  summary: Create a new station
  description: |
    Permission: **ADMIN, OWNER**

    Creates a new station locally, then attempts to register it on the
    supplier (provider) system in the same request.

    **Station creation is a two-phase operation:**
    1. Local station is saved with `provisioning_status = CREATING_PROVIDER`.
    2. The supplier system is called to register the station.
       - On success: `provisioning_status` is updated to `ACTIVE`.
       - On failure/timeout: `provisioning_status` stays `PROVIDER_CREATE_FAILED`.
         The station is still created locally and visible on the Admin Portal
         and client Mobile App, but device linking is unavailable until resolved.

    **Client eligibility:** only clients with `status = ACTIVE` and
    `number_of_stations < 10` can be selected.
  tags: [Station]
  security:
    - bearerAuth: []
  requestBody:
    required: true
    content:
      application/json:
        schema:
          $ref: "../../components.yaml#/components/schemas/CreateStationRequest"
        example:
          client_id: "6656c2b3f1a2b3c4d5e6f701"
          provider_code: "growatt"
          station_name: "Casa Jalisco 1"
          type: "Residential"
          capacity_kwp: 5.5
          address:
            country_id: "MX"
            state_province_id: "MX|Mexico|Jalisco"
            city_id: "MX|Jalisco|Guadalajara"
            district: "Providencia"
            street: "Av. Vallarta"
            house_number: "1234"
          notes: "Rooftop installation"
          created_by: "6656c2b3f1a2b3c4d5e6f001"
  responses:
    "200":
      description: |
        Station created locally. Check `provisioning_status` to know whether
        the supplier system registration also succeeded.
      content:
        application/json:
          schema:
            $ref: "../../components.yaml#/components/schemas/CreateStationResponse"
          examples:
            success:
              summary: Supplier registration succeeded
              value:
                station_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                client_id: "6656c2b3f1a2b3c4d5e6f701"
                station_name: "Casa Jalisco 1"
                provider_code: "growatt"
                provider_station_id: "GW-PLANT-00123"
                provisioning_status: "ACTIVE"
            provider_failed:
              summary: Supplier registration failed — station still created locally
              value:
                station_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                client_id: "6656c2b3f1a2b3c4d5e6f701"
                station_name: "Casa Jalisco 1"
                provider_code: "growatt"
                provider_station_id: ""
                provisioning_status: "PROVIDER_CREATE_FAILED"
    "400":
      $ref: "../../components.yaml#/components/responses/Failure"
    "403":
      $ref: "../../components.yaml#/components/responses/Failure"
    "404":
      $ref: "../../components.yaml#/components/responses/Failure"
    "500":
      $ref: "../../components.yaml#/components/responses/Failure"