Yokoy FX rates API

openapi: 3.2.0
info:
  description: Public API of the Yokoy Application
  title: Yokoy Card account FX rates API
  version: 1.41.0
servers:
- description: API server scoped to organization with ID `organizationId`
  url: https://api.yokoy.ai/v1/organizations/{organizationId}
  variables:
    organizationId:
      default: AbcDeF1234
      description: Yokoy organization ID
- description: API test server scoped to organization with ID `organizationId`
  url: https://api.test.yokoy.ai/v1/organizations/{organizationId}
  variables:
    organizationId:
      default: AbcDeF1234
      description: Yokoy organization ID
tags:
- description: 'Extend the offered and Yokoy-managed foreign exchange rates (Open Exchange Rates, CNB, NPB and NBS national bank rates) with your own customer-specific FX rates. The created FX rate sources are equivalent to Yokoy-managed FX rate sources and can be applied in **Admin > Company**, **General**. Currencies are assigned on a legal entity level.

    '
  name: FX rates
paths:
  /fx-rate-sources:
    parameters:
    - $ref: '#/components/parameters/YokoyAuthMethod'
    - $ref: '#/components/parameters/YokoyCorrelationId'
    get:
      description: Returns all foreign exchange rate sources.
      operationId: listFxRateSources
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  fxRateSources:
                    items:
                      $ref: '#/components/schemas/FxRateSource'
                    type: array
                type: object
          description: OK
        '400':
          content:
            application/json:
              example:
                code: 400
                message: Invalid request
              schema:
                $ref: '#/components/schemas/Error'
          description: The request was not valid.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '502':
          $ref: '#/components/responses/GatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      security:
      - OAuth2: []
      summary: List FX rate sources
      tags:
      - FX rates
    post:
      description: Creates a new foreign exchange rate source and returns the created entity.
      operationId: createFxRateSource
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FxRateSource'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FxRateSource'
          description: Created
        '400':
          content:
            application/json:
              example:
                code: 400
                message: 'ValidationError: name has to be set'
              schema:
                $ref: '#/components/schemas/Error'
          description: The request was not valid.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '502':
          $ref: '#/components/responses/GatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      security:
      - OAuth2: []
      summary: Create FX rate source
      tags:
      - FX rates
  /fx-rate-sources/{fxRateSourceId}/fx-rates/{isoDate}:
    parameters:
    - $ref: '#/components/parameters/YokoyAuthMethod'
    - $ref: '#/components/parameters/YokoyCorrelationId'
    - description: Yokoy ID of the foreign exchange rate source.
      example: aB9jQoE3HE
      in: path
      name: fxRateSourceId
      required: true
      schema:
        pattern: '[\w-]+'
        type: string
    - description: Effective date of the exchange rate. Expressed in YYYY-MM-DD format.
      in: path
      name: isoDate
      required: true
      schema:
        example: '2023-03-31'
        pattern: \d{4}-\d{2}-\d{2}
        type: string
    put:
      description: Sets the foreign exchange rates as per the specified source and date.
      operationId: applyFxRate
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FxRates'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FxRates'
          description: OK
        '400':
          content:
            application/json:
              example:
                code: 400
                message: 'ValidationError: fxRates have to be set'
              schema:
                $ref: '#/components/schemas/Error'
          description: The request was not valid.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '502':
          $ref: '#/components/responses/GatewayError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      security:
      - OAuth2: []
      summary: Apply FX rate
      tags:
      - FX rates
components:
  parameters:
    YokoyAuthMethod:
      example: yokoy
      in: header
      name: X-Yk-Auth-Method
      required: true
      schema:
        enum:
        - yokoy
        type: string
    YokoyCorrelationId:
      description: Correlation ID that can be used to trace a request in the flow.
      example: 4ea8985e-80a2-40a0-8a40-401a1a1374b3
      in: header
      name: X-Yk-Correlation-Id
      required: false
      schema:
        type: string
  schemas:
    Error:
      properties:
        code:
          type: integer
        message:
          type: string
      required:
      - code
      - message
      type: object
    FxRateSource:
      properties:
        id:
          description: Yokoy ID of the foreign exchange rate source.
          example: 9L7rovNzNhTCsJSTkbfq
          pattern: '[\w-]+'
          readOnly: true
          type: string
        label:
          description: Name of the foreign exchange rate.
          example: Organization A FX conversion rate
          type: string
      required:
      - label
      - id
      type: object
    FxRates:
      properties:
        baseCurrency:
          description: Optional base currency (if not provided, USD is assumed to be the base currency).
          example: EUR
          type: string
        fxRates:
          description: Foreign exchange reference rates. All currencies are quoted against the base currency (USD default).
          example:
            CHF: 1.0759
            EUR: 1
            JPY: 162.3675
            USD: 1.0516
          type: object
      required:
      - fxRates
      type: object
  responses:
    Unauthorized:
      content:
        application/json:
          example:
            code: 401
            message: Token expired
          schema:
            $ref: '#/components/schemas/Error'
      description: The server was unable to establish the identity of the client.
    GatewayError:
      content:
        application/json:
          example:
            code: 502
            message: Gateway error
          schema:
            $ref: '#/components/schemas/Error'
      description: An issue occurred in a downstream service. Please try again later.
    TooManyRequests:
      content:
        application/json:
          example:
            code: 429
            message: Too many requests
          schema:
            $ref: '#/components/schemas/Error'
      description: The request cannot be processed by the server due to too many concurrent requests.
    ServiceUnavailable:
      content:
        application/json:
          example:
            code: 503
            message: Service unavailable
          schema:
            $ref: '#/components/schemas/Error'
      description: The server is unavailable. Please try again later
    Forbidden:
      content:
        application/json:
          example:
            code: 403
            message: User not authorized to access organization
          schema:
            $ref: '#/components/schemas/Error'
      description: The client is not authorized to perform the requested operation.
    InternalError:
      content:
        application/json:
          example:
            code: 500
            message: Server error
          schema:
            $ref: '#/components/schemas/Error'
      description: An internal error occurred.
  securitySchemes:
    OAuth2:
      description: "Authentication to the Yokoy API relies on the standard OAuth2 client credentials flow.\n\n**1. Obtain an access token**\n\nPerform a `POST` request to\n`https://accounts.yokoy.ai/oauth2/token`. Pass the client ID\nand client secret as username and password in a basic auth\nheader. Set the content-type to\n`application/x-www-form-urlencoded` and specify\n`grant_type=client_credentials` in the body.\n\n> Note: For the Yokoy test environment, use `https://accounts.test.yokoy.ai/oauth2/token` instead.\n\nExample request for the client ID `ClientId` and client\nsecret `ClientSecret`:\n```\nPOST https://accounts.yokoy.ai/oauth2/token\nAuthorization: Basic Q2xpZW50SWQ6Q2xpZW50U2VjcmV0\nContent-Type: application/x-www-form-urlencoded\ngrant_type=client_credentials\n```\nIn this example, the string `Q2xpZW50SWQ6Q2xpZW50U2VjcmV0` is\nobtained by base64-encoding the string\n`ClientId:ClientSecret`, as required for basic access authentication.\n\n> Note: Yokoy does not require or use scopes.\n\n\nThe JSON response contains the access token in the attribute\n`access_token`. The response also contains the expiration in\nseconds.\n\nExample response:\n```\n{\n    \"access_token\": \"SOME_KEY\",\n    \"expires_in\": 3900,\n    \"token_type\": \"Bearer\"\n}\n```\n\n**2. Pass the bearer token**\n\nPass the access token from step 1 as a bearer token in subsequent requests to the API.\n\nExample header field for the example response from step 1:\n```\nAuthorization: Bearer 4lDvPkrBF87WHuyvlINQD\n```\n\nFor more information, see (Authentication & authorization)[https://developer.yokoy.ai/docs/overview/authentication].\n"
      flows:
        clientCredentials:
          scopes: {}
          tokenUrl: https://accounts[.test].yokoy.ai/oauth2/token
      type: oauth2