Contract Creation (With Cost Center Distribution)¶

ID: UC-NFS-CNTRCT-W002
Complexity: Advanced
Description: Complete 8-step workflow for creating a contract in Nakisa Financial Suite (NFS) using REST APIs. This use case includes cost center distribution functionality across multiple cost centers (60/40 split).
Scenario: A developer or integration specialist needs to create a complete contract in NFS through an 8-step workflow, including multi-cost center distribution (60/40 split), from initial contract creation to approval readiness.
Business Value: Enables automated contract creation workflows with multi-cost center distribution, reduces manual data entry errors, ensures proper cost allocation.

Prerequisites¶

Valid API key for NFS API
Access to NFS API environment
Master Agreement ID (provided by Nakisa support team)
ERP System ID (provided by Nakisa support team)
Understanding of contract DTO data structure
Cost center configuration

Steps¶

1. Create Contract¶

Create the initial contract and obtain contract revision ID

Endpoint: PUT /api/v1/contracts/createOrUpdate

HTTP Request

curl -X PUT 'https://{base-url}/data/api/v1/contracts/createOrUpdate' 
  -H 'x-api-key: YOUR_API_KEY' 
  -H 'Content-Type: application/json' 
  -d '{
    "name": "Sample Contract with CCD",
    "principalPositionType": {
        "name": "LESSEE"
    },
    "leaseType": {
        "name": "LEASE_CONTRACT_FIX"
    },
    "currency": {
        "displayId": "USD"
    },
    "leaseArea": {
        "displayId": "0001"
    },
    "businessUnit": {
        "displayId": "BU0001"
    },
    "companyCode": {
        "displayId": "1000",
        "erpSystemId": 10000001,
        "erpSystemDisplayId": "FINQ8S-300"
    },
    "masterAgreementId": 10000445
  }'

Expected Response: HTTP 200 with contract revision ID in response body

Notes: Save the contractRevisionId from the response for use in subsequent steps

2. Get Lease Determination by Contract Revision ID¶

Retrieve lease determination data using the contract revision ID from step 1

Endpoint: GET /api/v1/lease-determinations/contract/{contract-revision-id}

HTTP Request

curl -X GET 'https://{base-url}/data/api/v1/lease-determinations/contract/{contract-revision-id}' 
  -H 'x-api-key: YOUR_API_KEY' 
  -H 'Content-Type: application/json'

Expected Response: HTTP 200 with lease determination data

Notes: Replace {contract-revision-id} with the ID from Step 1. Save the determination ID for Step 3

3. Update Lease Determination¶

Update lease determination with required fields including determination questions

Endpoint: PUT /api/v1/lease-determinations/{id}

HTTP Request

curl -X PUT 'https://{base-url}/data/api/v1/lease-determinations/{id}' 
  -H 'x-api-key: YOUR_API_KEY' 
  -H 'Content-Type: application/json' 
  -d '{
    "id": 10001627,
    "principalPositionType": {
        "name": "LESSEE"
    },
    "contractRevisionId": 10001649,
    "hasIdentifiedAsset": true,
    "isServiceContract": false,
    "hasEconomicBenefit": true,
    "whoHasRightToDirect": "Customer",
    "isShortTermNoPurchase": false,
    "isLowValueAsset": true,
    "type": "LESSEE",
    "allowsSystemGenerateNewId": true
  }'

Expected Response: HTTP 200 with updated lease determination

Notes: Replace {id} with the determination ID from Step 2. Update contractRevisionId with the ID from Step 1

4. Create Contract Partners¶

Add contract partners using bulk creation endpoint

Endpoint: POST /api/v1/contract-partners/bulk

HTTP Request

curl -X POST 'https://{base-url}/data/api/v1/contract-partners/bulk' 
  -H 'x-api-key: YOUR_API_KEY' 
  -H 'Content-Type: application/json' 
  -d '{
    "contractRevisionId": "10001649",
    "partners": [
      {
        "id": 10000303,
        "displayId": "40"
      }
  ]
  }'

Expected Response: HTTP 200 with created contract partners

Notes: Set contractRevisionId with the ID from Step 1.

5. Get Contract Accounting by Contract Revision ID¶

Retrieve contract accounting data using the contract revision ID

Endpoint: GET /api/v1/contract-accountings/contract/{contract-revision-id}

HTTP Request

curl -X GET 'https://{base-url}/data/api/v1/contract-accountings/contract/{contract-revision-id}' 
  -H 'x-api-key: YOUR_API_KEY' 
  -H 'Content-Type: application/json'

Expected Response: HTTP 200 with contract accounting data

Notes: Replace {contract-revision-id} with the ID from Step 1. Save the accounting ID for Step 6

6. Update Contract Accounting¶

Update contract accounting with required financial parameters

Endpoint: PUT /api/v1/contract-accountings/{id}

HTTP Request

curl -X PUT 'https://{base-url}/data/api/v1/contract-accountings/{id}' 
  -H 'x-api-key: YOUR_API_KEY' 
  -H 'Content-Type: application/json' 
  -d '{
    "id": 10001285,
    "displayId": "1185393783-20250321-191610",
    "principalPositionType": {
        "name": "LESSEE",
        "captionKey": "enum.principalPositionType.lessee",
        "caption": "Lessee"
    },
    "contractRate": 0.3,
    "straightLineNonLeaseIncomeForPosting": false,
    "compoundingFrequency": {
        "name": "MONTHLY",
        "captionKey": "enum.compoundingFrequency.monthly",
        "length": 12,
        "times": 12,
        "caption": "Monthly"
    },
    "trackCost": false,
    "generateVendorInvoice": false,
    "calculateTax": false,
    "calendarType": {
        "name": "_360",
        "captionKey": "enum.calendarType.360",
        "caption": "360 Convention"
    },
    "fiscalVariant": {
        "id": 10000031,
        "displayId": "NAK1",
        "status": {
            "name": "ACTIVE",
            "captionKey": "enum.objectStatus.active",
            "caption": "enum.objectStatus.active",
            "active": true
        },
        "isCalendarYear": true,
        "yearDependent": false,
        "erpSystemDisplayId": "DIS1"
    },
    "costCenter": {
        "id": 10000303,
        "displayId": "0000011050",
        "status": {
            "name": "ACTIVE",
            "captionKey": "enum.objectStatus.active",
            "caption": "enum.objectStatus.active",
            "active": true
        },
        "name": "Administration Nakisa Canada"
    },
    "contractId": 10001324,
    "contractDisplayId": "CT-100011228",
    "contractRevisionId": 10001338,
    "transactionTypePosting": false,
    "costCenterAllocations": [],
    "useIbrRate": false,
    "embeddedDerivative": false,
    "spreading": false,
    "type": "LESSEE",
    "allowsSystemGenerateNewId": true
}'

Expected Response: HTTP 200 with updated contract accounting

Notes: Replace {id} with the accounting ID from Step 5. Update contractRevisionId with the ID from Step 1

7. Update Cost Center Distribution¶

Attach multiple cost center allocations to the contract accounting

Endpoint: PATCH /api/v1/contract-accountings/{id}

HTTP Request

curl -X PATCH 'https://{base-url}/data/api/v1/contract-accountings/{id}' 
  -H 'x-api-key: YOUR_API_KEY' 
  -H 'Content-Type: application/json' 
  -d '[
    {
      "op": "add",
      "path": "/costCenterAllocations",
      "value": [
        {
          "costCenter": {
            "displayId": "C8890JNU"
          },
          "profitCenter": null,
          "mainCostCenter": true,
          "allocationPercentage": 60
        },
        {
          "costCenter": {
            "displayId": "C9900KMW"
          },
          "profitCenter": null,
          "mainCostCenter": false,
          "allocationPercentage": 40
        }
      ]
    }
  ]'

Expected Response: HTTP 200 with updated cost center allocations

Notes: Replace {id} with the accounting ID from Step 6. Ensure allocation percentages sum to 100%

8. Create or Update Contract Notification¶

Set up contract notifications for approval workflow

Endpoint: PUT /api/v1/contract-subscription/createOrUpdate/bulk

HTTP Request

curl -X PUT 'https://{base-url}/data/api/v1/contract-subscription/createOrUpdate/bulk' 
  -H 'x-api-key: YOUR_API_KEY' 
  -H 'Content-Type: application/json' 
  -d '[
    {
      "topic": {
        "name": "WORKFLOW_EVENTS"
      },
      "contractId": 10001613,
      "username": "johndoe@company.com",
      "targetType": "CONTRACT"
    }
  ]'

Expected Response: HTTP 200 with created contract notifications

Notes: Replace contractId with the contract ID from Step 1. Update username as needed

Best Practices¶

Always validate that the sum of all allocation percentages in Step 7 is exactly 100.
The primary cost center should typically have ‘mainCostCenter’ set to true.
Follow the sequence precisely as ID dependencies exist between steps.
Implement proper logging for each PATCH operation to track data changes.