Create/Update Profit Center and Cost Center with Attachment¶

ID: UC-FOS-MSTRDT-W001
Complexity: Intermediate
Description: Create or update profit centers and cost centers, then attach them together in a three-step workflow
Scenario: A user needs to create or update profit centers and cost centers in the Financial Organization Structure, then establish the relationship between them by attaching the profit center to the cost center.
Business Value: Automates creation and linking of cost and profit centers to maintain accurate financial structures, reduce manual work, and improve cost tracking.

Prerequisites¶

Valid API key for FOS API
Access to FOS API environment
Understanding of profit centers and cost centers
Basic knowledge of REST API concepts

Steps¶

1. Create/Update Profit Center¶

Create or update a profit center

Endpoint: PUT /api/v1/profit-centers/createOrUpdate

HTTP Request

curl -X PUT 'https://{base-url}/api/v1/profit-centers/createOrUpdate' 
  -H 'x-api-key: YOUR_API_KEY' 
  -H 'Content-Type: application/json' 
  -d '{
    "status": {
      "name": "ACTIVE"
    },
    "displayId": "PC00000001",
    "erpSystemDisplayId": "FINQ8S-300",
    "name": "Profit Center 1",
    "validTo": "2019-08-24",
    "controllingAreaDisplayId": "SYS1"
  }'

Expected Response: HTTP 200 with created/updated profit center details

Notes: This creates a profit center with display ID PC00000001. Save the returned profit center ID for use in step 3.

2. Create/Update Cost Center¶

Create or update a cost center

Endpoint: PUT /api/v1/cost-centers/createOrUpdate

HTTP Request

curl -X PUT 'https://{base-url}/api/v1/cost-centers/createOrUpdate' 
  -H 'x-api-key: YOUR_API_KEY' 
  -H 'Content-Type: application/json' 
  -d '{
    "status": {
      "name": "ACTIVE"
    },
    "displayId": "CC00000001",
    "erpSystemDisplayId": "FINQ8S-300",
    "name": "Cost Center 1",
    "controllingAreaDisplayId": "SYS1",
    "profitCenterRelationValidFrom": "2019-08-24",
    "companyRelationValidFrom": "2019-08-24",
    "companyId": 10000001,
    "blocked": false
  }'

Expected Response: HTTP 200 with created/updated cost center details

Notes: This creates a cost center with display ID CC00000001. Save the returned cost center ID for use in step 3.

3. Attach Profit Center to Cost Center¶

Attach the profit center to the cost center using the profit center ID and cost center ID

Endpoint: POST /api/v1/cost-centers/attach/profit-center/{profit-center-id}

HTTP Request

curl -X POST 'https://{base-url}/api/v1/cost-centers/attach/profit-center/10000001' 
  -H 'x-api-key: YOUR_API_KEY' 
  -H 'Content-Type: application/json' 
  -d '[
    {
      "id": 10000002,
      "displayId": "CC00000001",
      "erpSystemDisplayId": "FINQ8S-300",
      "controllingAreaDisplayId": "SYS1",
      "profitCenterRelationValidFrom": "2019-08-24",
      "profitCenterRelationValidTo": "2019-08-24"
    }
  ]'

Expected Response: HTTP 200 with attachment confirmation

Notes: Replace 10000001 with the actual profit center ID from step 1, and 10000002 with the actual cost center ID from step 2.

Error Scenarios¶

Profit Center Status Not Active (400): Verify profit center status before attempting attachment Recovery: Update profit center status to ACTIVE or use a different profit center

Invalid ERP System Display ID (400): Validate ERP system display ID exists before creating entities Recovery: Check ERP system configuration and use valid display ID

Cost Center ID Missing in Request (400): Include cost center ID in the attachment request body Recovery: Add the required costCenterId field to the request payload

Profit Center Not Found (404): Verify that the profit center ID exists and you have access permissions Recovery: Check profit center ID validity and ensure proper authorization

Cost Center Not Found (404): Verify that the cost center ID exists and you have access permissions Recovery: Check cost center ID validity and ensure proper authorization

Unauthorized Access (403): Verify that your API key has the necessary permissions Recovery: Contact the Nakisa Support team to grant appropriate permissions

Best Practices¶

Always ensure profit centers are set to ACTIVE status before attachment
Validate ERP system and controlling area display IDs before creating entities
Save response data from each step for use in subsequent steps
Implement proper error handling for each API call
Consider implementing validation for required fields before API calls
Monitor the status of created entities to ensure they are properly configured
Test the attachment process with small datasets before scaling up
Use consistent date formats (YYYY-MM-DD) for all date fields
Validate that both profit center and cost center exist before attempting attachment
Implement retry logic for failed requests with exponential backoff

Performance Tips¶

Cache frequently accessed profit center and cost center data
Implement proper connection pooling for API requests
Monitor API response times and implement timeouts