openapi: 3.0.3
info:
  title: ChargeIndia Hub OCPI API
  description: |
    Hub-specific OCPI 2.2.1 endpoints for ChargeIndia Hub.

    Payload shapes follow the [OCPI 2.2.1 specification](https://evroaming.org/).
    This document covers Hub paths, roles, and integration notes only.

    Authenticate with `Authorization: Token {Base64(UTF-8(raw-token))}` unless noted.
  version: 1.0.0

servers:
  - url: https://{hub-domain}/ocpi
    variables:
      hub-domain:
        default: hub.chargeindia.com

tags:
  - name: Versions
  - name: Credentials
  - name: HubClientInfo
  - name: Locations
  - name: Tariffs
  - name: Tokens
  - name: Commands
  - name: Sessions
  - name: CDRs

paths:
  /versions:
    get:
      tags: [Versions]
      summary: List supported OCPI versions
      security:
        - ocpiToken: []
      responses:
        "200":
          description: OCPI version list

  /2.2.1:
    get:
      tags: [Versions]
      summary: Version details and module URLs
      security:
        - ocpiToken: []
      responses:
        "200":
          description: Module endpoints for Hub role SENDER/RECEIVER

  /2.2.1/credentials:
    get:
      tags: [Credentials]
      summary: Retrieve current credentials
      security:
        - ocpiToken: []
      responses:
        "200":
          description: Current credentials object
    post:
      tags: [Credentials]
      summary: Initial credentials exchange
      description: Used during onboarding. Hub responds with HUB role (`IN` / `CIH`).
      security:
        - ocpiToken: []
      responses:
        "200":
          description: Hub token and endpoint URLs
    put:
      tags: [Credentials]
      summary: Update or confirm credentials
      security:
        - ocpiToken: []
      responses:
        "200":
          description: Credentials updated

  /2.2.1/hubclientinfo:
    get:
      tags: [HubClientInfo]
      summary: Connected party statuses
      security:
        - ocpiToken: []
      responses:
        "200":
          description: Routing and connection health for registered parties

  /2.2.1/locations:
    get:
      tags: [Locations]
      summary: List locations (eMSP, routing-filtered)
      security:
        - ocpiToken: []
      parameters:
        - name: offset
          in: query
          schema:
            type: integer
        - name: limit
          in: query
          schema:
            type: integer
      responses:
        "200":
          description: Paginated location list

  /2.2.1/locations/{country_code}/{party_id}/{location_id}:
    put:
      tags: [Locations]
      summary: Create or replace location (CPO push)
      description: Use your CPO identifiers in path and body. Hub forwards async to routed eMSPs.
      security:
        - ocpiToken: []
      parameters:
        - $ref: "#/components/parameters/countryCode"
        - $ref: "#/components/parameters/partyId"
        - name: location_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Location accepted
    patch:
      tags: [Locations]
      summary: Partial location update (CPO push)
      security:
        - ocpiToken: []
      parameters:
        - $ref: "#/components/parameters/countryCode"
        - $ref: "#/components/parameters/partyId"
        - name: location_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Location patched

  /2.2.1/tariffs/{country_code}/{party_id}/{tariff_id}:
    put:
      tags: [Tariffs]
      summary: Create or replace tariff (CPO push)
      security:
        - ocpiToken: []
      parameters:
        - $ref: "#/components/parameters/countryCode"
        - $ref: "#/components/parameters/partyId"
        - name: tariff_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Tariff accepted

  /2.2.1/tokens/{country_code}/{party_id}/{token_uid}/authorize:
    put:
      tags: [Tokens]
      summary: Realtime token authorization
      description: eMSP calls Hub; Hub forwards to owning CPO synchronously. Rate limit 100/min per party.
      security:
        - ocpiToken: []
      parameters:
        - $ref: "#/components/parameters/countryCode"
        - $ref: "#/components/parameters/partyId"
        - name: token_uid
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Authorization result (ALLOWED, BLOCKED, etc.)

  /2.2.1/commands/{command}:
    post:
      tags: [Commands]
      summary: Send remote command
      description: |
        eMSP sends START_SESSION, STOP_SESSION, etc. Hub forwards to CPO.
        Include `response_url` for async results (Hub rewrites CPO callback).
      security:
        - ocpiToken: []
      parameters:
        - name: command
          in: path
          required: true
          schema:
            type: string
            enum: [START_SESSION, STOP_SESSION, RESERVE_NOW, CANCEL_RESERVATION]
      responses:
        "200":
          description: Command accepted or rejected

  /2.2.1/commands/callback/{command_id}:
    post:
      tags: [Commands]
      summary: Async command callback (unauthenticated)
      description: Called by CPOs; Hub validates via command context, not bearer token.
      security: []
      parameters:
        - name: command_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Callback received

  /2.2.1/sessions/{country_code}/{party_id}/{session_id}:
    put:
      tags: [Sessions]
      summary: Push session update (CPO)
      description: Must include `cdr_token` identifying the eMSP for async routing.
      security:
        - ocpiToken: []
      parameters:
        - $ref: "#/components/parameters/countryCode"
        - $ref: "#/components/parameters/partyId"
        - name: session_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Session stored and queued for async forward

  /2.2.1/cdrs:
    post:
      tags: [CDRs]
      summary: Post charge detail record (CPO)
      description: Hub forwards asynchronously to eMSP identified by session/CDR token.
      security:
        - ocpiToken: []
      responses:
        "200":
          description: CDR accepted

components:
  securitySchemes:
    ocpiToken:
      type: apiKey
      in: header
      name: Authorization
      description: "OCPI token: `Token {Base64(UTF-8(raw-token))}`"

  parameters:
    countryCode:
      name: country_code
      in: path
      required: true
      schema:
        type: string
        example: IN
    partyId:
      name: party_id
      in: path
      required: true
      schema:
        type: string
        example: ABC

security:
  - ocpiToken: []
