openapi: 3.0.0
info:
  title: Indonesia Bank Rate API
  description: >-
    Complete API collection for the Bank Rate API - Access Indonesian bank exchange rates.


    ## Features

    - Get all available bank codes

    - Get exchange rates by bank code

    - Multiple rate types (TT Counter, E-Rate, Special Rate, Bank Notes)

    - Jakarta timezone timestamps


    ## Authentication

    All requests require an API key in the `x-api-co-id` header.


    ## Base URL

    - Production: `https://use.api.co.id`

    - Development: `http://localhost:3000`


    ## Supported Banks

    - BRI (bri)

    - Bank Mandiri (mandiri)

    - BCA (bca)

    - And more...

  version: 1.0.0
servers:
  - url: https://use.api.co.id
tags:
  - name: Bank Rates
    description: Endpoints for accessing Indonesian bank exchange rate data.
paths:
  /api/bank-rates/codes:
    get:
      tags:
        - Bank Rates
      summary: Get Available Bank Codes
      description: >-
        Get all unique bank codes available in the system.

        ### Features

        - Returns list of all available bank codes

        - Use this to discover which banks have rate data

        - Alphabetically sorted

        ### Use Cases

        - Bank selection dropdowns

        - Dynamic bank code discovery

        - API integration setup
      parameters:
        - name: x-api-co-id
          in: header
          required: true
          schema:
            type: string
          description: Your API key for authentication
          example: '{{api_key}}'
      responses:
        '200':
          description: Success - Available Bank Codes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankCodesResponse'
              examples:
                success:
                  summary: Success - Available Bank Codes
                  value:
                    is_success: true
                    message: Success
                    data:
                      bank_codes:
                        - bca
                        - bri
                        - mandiri
        '400':
          description: Bad Request - Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                badRequest:
                  summary: Error - Bad Request
                  value:
                    is_success: false
                    message: 'Invalid request parameters'
                    errors: ''
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unauthorized:
                  summary: Error - Unauthorized
                  value:
                    is_success: false
                    message: 'Unauthorized - Invalid or missing API key'
                    errors: ''
        '429':
          description: Too Many Requests - Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                rateLimitExceeded:
                  summary: Rate Limit Exceeded
                  value:
                    is_success: false
                    message: 'Rate limit exceeded. Please try again later'
                    errors: ''
  /api/bank-rates:
    get:
      tags:
        - Bank Rates
      summary: Get Bank Rate by Code
      description: >-
        Get exchange rate data for a specific bank.

        ### Query Parameters

        - `bank_code` (required): Bank code identifier

          - Examples: `bri`, `mandiri`, `bca`

          - Case insensitive

        ### Rate Types

        Different banks provide different rate types:

        - **tt-counter**: Tellers counter rates

        - **e-rate**: Electronic rates

        - **special-rate**: Special rates for specific currencies

        - **bank-notes**: Bank notes rates

        ### Response Fields

        - `bank_code`: Bank identifier

        - `rate`: JSON object containing all rate types and currencies

        - `last_fetched_at`: Timestamp in Jakarta timezone (Unix milliseconds)

        ### Use Cases

        - Currency exchange applications

        - Bank rate comparison

        - Financial dashboards

        - Multi-bank rate comparison

        - Best rate finder

        - Currency exchange services
      parameters:
        - name: x-api-co-id
          in: header
          required: true
          schema:
            type: string
          description: Your API key for authentication
          example: '{{api_key}}'
        - name: bank_code
          in: query
          required: true
          schema:
            type: string
          description: Bank code (e.g., bri, mandiri, bca)
          example: bri
      responses:
        '200':
          description: Success - Bank Rates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankRateResponse'
              examples:
                bri:
                  summary: Success - BRI Rates
                  value:
                    is_success: true
                    message: Success
                    data:
                      bank_code: bri
                      rate:
                        'tt-counter':
                          usd:
                            buy: 16975
                            sell: 16675
                          eur:
                            buy: 20002.72
                            sell: 19489.67
                          sgd:
                            buy: 13412.48
                            sell: 12959.93
                          myr:
                            buy: 4476.19
                            sell: 3954.82
                        'e-rate':
                          usd:
                            buy: 16890
                            sell: 16788
                          eur:
                            buy: 19881.463
                            sell: 19716.1848
                          sgd:
                            buy: 13238.6398
                            sell: 13123.8274
                      last_fetched_at: 1737771218000
                mandiri:
                  summary: Success - Mandiri Rates
                  value:
                    is_success: true
                    message: Success
                    data:
                      bank_code: mandiri
                      rate:
                        'special-rate':
                          usd:
                            buy: 16830
                            sell: 16860
                          eur:
                            buy: 19792
                            sell: 19846
                          sgd:
                            buy: 13155
                            sell: 13193
                        'tt-counter':
                          usd:
                            buy: 16620
                            sell: 16920
                          eur:
                            buy: 19444
                            sell: 19967
                          sgd:
                            buy: 12900
                            sell: 13297
                        'bank-notes':
                          usd:
                            buy: 16620
                            sell: 16920
                          eur:
                            buy: 19444
                            sell: 19967
                      last_fetched_at: 1737771219000
                bca:
                  summary: Success - BCA Rates
                  value:
                    is_success: true
                    message: Success
                    data:
                      bank_code: bca
                      rate:
                        'e-rate':
                          USD:
                            buy: 16790
                            sell: 16850
                          EUR:
                            buy: 19855.92
                            sell: 19939.42
                          SGD:
                            buy: 13192.55
                            sell: 13259.03
                        'tt-counter':
                          USD:
                            buy: 16673
                            sell: 16973
                          EUR:
                            buy: 19551.55
                            sell: 19955.55
                          SGD:
                            buy: 13029.2
                            sell: 13274.2
                        'bank-notes':
                          USD:
                            buy: 16705
                            sell: 17005
                          EUR:
                            buy: 19600
                            sell: 20002
                          SGD:
                            buy: 13034
                            sell: 13278
                      last_fetched_at: 1737772712000
        '400':
          description: Bad Request - Missing or invalid bank_code parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missingBankCode:
                  summary: Error - Missing Bank Code
                  value:
                    is_success: false
                    message: 'bank_code query parameter is required (e.g., ?bank_code=BCA)'
                    errors: ''
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unauthorized:
                  summary: Error - Unauthorized
                  value:
                    is_success: false
                    message: 'Unauthorized - Invalid or missing API key'
                    errors: ''
        '404':
          description: Not Found - Bank code not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                notFound:
                  summary: Error - Bank Code Not Found
                  value:
                    is_success: false
                    message: 'bank rate not found for bank_code: invalid'
                    errors: ''
        '429':
          description: Too Many Requests - Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                rateLimitExceeded:
                  summary: Rate Limit Exceeded
                  value:
                    is_success: false
                    message: 'Rate limit exceeded. Please try again later'
                    errors: ''
components:
  schemas:
    BankCodesResponse:
      type: object
      properties:
        is_success:
          type: boolean
          description: Indicates if the request was successful
          example: true
        message:
          type: string
          description: Response message
          example: Success
        data:
          type: object
          properties:
            bank_codes:
              type: array
              items:
                type: string
              description: List of available bank codes
              example:
                - bca
                - bri
                - mandiri
    BankRateResponse:
      type: object
      properties:
        is_success:
          type: boolean
          description: Indicates if the request was successful
          example: true
        message:
          type: string
          description: Response message
          example: Success
        data:
          type: object
          properties:
            bank_code:
              type: string
              description: Bank code identifier
              example: bri
            rate:
              type: object
              description: Exchange rates organized by rate type and currency
              additionalProperties:
                type: object
                description: Rate type (e.g., tt-counter, e-rate, special-rate, bank-notes)
                additionalProperties:
                  type: object
                  description: Currency code (e.g., usd, eur, sgd)
                  properties:
                    buy:
                      type: number
                      description: Buy rate
                      example: 16975
                    sell:
                      type: number
                      description: Sell rate
                      example: 16675
            last_fetched_at:
              type: integer
              format: int64
              description: Timestamp in Jakarta timezone (Unix milliseconds)
              example: 1737771218000
    ErrorResponse:
      type: object
      properties:
        is_success:
          type: boolean
          description: Indicates if the request was successful
          example: false
        message:
          type: string
          description: Error message
          example: 'bank rate not found for bank_code: invalid'
        errors:
          type: string
          description: Additional error details
          example: ''
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-co-id
      description: Your API key for authentication
security:
  - ApiKeyAuth: []



