Create/Update Exchange Rates

ID: UC-FOS-MSTRDT-D001
Complexity: Basic
Description: Create or update exchange rates for currency pairs to support exchange rate conversion.
Scenario: A financial administrator needs to set up and maintain exchange rates for various currency pairs (e.g., between contract currency and company currency) to support financial reporting.
Business Value: Enables accurate currency conversion for financial operations (e.g., contract to company currency), supports multi-currency reporting, and ensures compliance with financial regulations.

Steps

1. Create/Update Exchange Rates

Create or update the exchange rates using the bulk endpoint

Endpoint: PUT /api/v1/exchange-rates/createOrUpdate/bulk

HTTP Request

curl -X PUT 'https://{base-url}/api/v1/exchange-rates/createOrUpdate/bulk' 
  -H 'x-api-key: YOUR_API_KEY' 
  -H 'Content-Type: application/json' 
  -d '[
    {
      "status": {
        "name": "CREATED"
      },
      "displayId": "M-USD-EUR-2000-01-01",
      "erpSystemId": 10000001,
      "erpSystemDisplayId": "FINQ8S-300",
      "validFrom": "2000-01-01",
      "rate": 0.8520,
      "fromFactor": 1.0,
      "toFactor": 1.0,
      "indirectExchangeRate": 1.1737,
      "indirectFromFactor": 1.0,
      "indirectToFactor": 1.0,
      "validTo": "2025-12-31",
      "fromCurrencyDisplayId": "USD",
      "toCurrencyDisplayId": "EUR",
      "exchangeRateType": "M"
    }
  ]'

Expected Response: HTTP 200 OK with the created or updated exchange rate details.

Notes: Ensure that the ERP System and currencies exist in the system before creating an exchange rate.

Best Practices

  • Always validate currency display IDs before creating exchange rates

  • Use meaningful display IDs that include currency pair and date information

  • Set appropriate from/to factors for currencies with different decimal places

  • Regularly update exchange rates to reflect current market conditions

  • Implement proper error handling for currency conversion operations

  • Monitor exchange rate changes and maintain audit trails

  • Use bulk operations for creating multiple exchange rates efficiently

  • Set up automated processes for regular exchange rate updates

  • Validate exchange rate accuracy against external sources

  • Implement proper security measures for exchange rate management

  • Document exchange rate policies and procedures

  • Use appropriate status values (ACTIVE, CREATED, DECOMMISSIONED) for lifecycle management

  • Consider implementing exchange rate validation rules based on business requirements

  • Set up alerts for significant exchange rate changes

  • Maintain historical exchange rate data for reporting and compliance

  • Implement proper backup and recovery procedures for exchange rate data

  • Regularly review and update exchange rate management procedures

Performance Tips

  • Use bulk operations when updating multiple exchange rates

  • Cache exchange rates locally for high-volume conversion operations