Contract Creation (No Cost Center Distribution)¶

ID: UC-NFS-CNTRCT-W001
Complexity: Advanced
Description: Complete 7-step workflow for creating a contract in Nakisa Financial Suite (NFS) using REST APIs, preparing it for approval.
Scenario: A developer or integration specialist needs to create a complete contract in NFS through a 7-step workflow, from initial contract creation to approval readiness.
Business Value: Enables automated contract creation workflows, reduces manual data entry errors, and ensures data consistency.

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

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": "MingTest",
    "principalPositionType": {
        "name": "LESSEE",
        "captionKey": "enum.principalPositionType.lessee",
        "caption": "Lessee"
    },
    "leaseType": {
        "name": "LEASE_CONTRACT_FIX",
        "captionKey": "enum.leaseType.fix",
        "principalPositionType": "LESSEE",
        "caption": "Lease contract (fix)"
    },
    "currency": {
        "id": 10000197,
        "displayId": "UF",
        "status": {
            "name": "ACTIVE",
            "captionKey": "enum.objectStatus.active",
            "caption": "enum.objectStatus.active",
            "active": true
        },
        "name": "Ukraine Hryvnia",
        "decimalPoints": 2
    },
    "leaseArea": {
        "id": 10000001,
        "displayId": "0001",
        "status": {
            "name": "ACTIVE",
            "captionKey": "enum.objectStatus.active",
            "caption": "enum.objectStatus.active",
            "active": true
        },
        "name": "Global Lease Area"
    },
    "businessUnit": {
        "id": 10000002,
        "displayId": "BU0001",
        "status": {
            "name": "ACTIVE",
            "captionKey": "enum.objectStatus.active",
            "caption": "enum.objectStatus.active",
            "active": true
        },
        "name": "Global Business Unit"
    },
    "companyCode": {
        "id": 10000001,
        "displayId": "1000",
        "status": {
            "name": "ACTIVE",
            "captionKey": "enum.objectStatus.active",
            "caption": "enum.objectStatus.active",
            "active": true
        },
        "erpSystemId": 10000001,
        "erpSystemDisplayId": "FINQ8S-300",
        "countryId": 10000048,
        "countryDisplayId": "CA"
    },
    "masterAgreementId": 10000001
  }'

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 /data/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 /data/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": 12345,
    "displayId": "10000001",
    "principalPositionType": {
        "name": "LESSEE",
        "captionKey": "enum.principalPositionType.lessee",
        "caption": "Lessee"
    },
    "systemDeterminedLeaseType": {
        "name": "LEASE_CONTRACT_FIX",
        "captionKey": "enum.leaseType.fix",
        "principalPositionType": "LESSEE",
        "caption": "Lease contract (fix)"
    },
    "userDeterminedLeaseType": {
        "name": "LEASE_CONTRACT_FIX",
        "captionKey": "enum.leaseType.fix",
        "principalPositionType": "LESSEE",
        "caption": "Lease contract (fix)"
    },
    "contractRevisionId": 67890,
    "contractId": 54321,
    "contractDisplayId": "CT-10001",
    "hasIdentifiedAsset": true,
    "isServiceContract": false,
    "hasEconomicBenefit": true,
    "whoHasRightToDirect": "Customer",
    "isShortTermNoPurchase": false,
    "isLowValueAsset": false,
    "type": "LESSEE",
    "allowsSystemGenerateNewId": false
  }'

Expected Response: HTTP 200 with updated lease determination

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

4. Create Contract Partners¶

Add or update contract partners

Endpoint: PUT /api/v1/contract-partners/createOrUpdate

HTTP Request

curl -X PUT 'https://{base-url}/data/api/v1/contract-partners/createOrUpdate' 
  -H 'x-api-key: YOUR_API_KEY' 
  -H 'Content-Type: application/json' 
  -d '{
    "contractRevisionId": "67890",
    "partner": {
      "id": 10000303,
      "displayId": "Lessee Partner"
    },
    "partnerRole": {
      "id": 10000004,
      "displayId": "40"
    },
    "fromDate": null,
    "toDate": null,
    "replacedPartner": null
  }'

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": "ACC-10001",
    "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": 10000245,
        "displayId": "0000011010",
        "status": {
            "name": "ACTIVE",
            "captionKey": "enum.objectStatus.active",
            "caption": "enum.objectStatus.active",
            "active": true
        },
        "name": "Operations Nakisa Canada 1000"
    },
    "contractId": 54321,
    "contractDisplayId": "CT-10001",
    "contractRevisionId": 67890,
    "transactionTypePosting": false,
    "costCenterAllocations": [],
    "useIbrRate": false,
    "embeddedDerivative": false,
    "spreading": false,
    "type": "LESSEE",
    "allowsSystemGenerateNewId": false
  }'

Expected Response: HTTP 200 with updated contract accounting

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

7. 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 '[
  {
    "id": 0,
    "topic": {
      "name": "WORKFLOW_EVENTS",
      "captionKey": "enum.nfsNotificationTopicType.workflowEvents",
      "priority": "MEDIUM",
      "enCaption": "Workflow Events",
      "frCaption": "Événements du flux de travail",
      "caption": "Workflow Events"
    },
    "contractId": 54321,
    "contractDisplayId": "CT-88888992",
    "username": "abc@nakisa.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¶

Follow the steps in exact order as dependencies exist between steps
Save response data from each step for use in subsequent steps
Implement proper error handling and retry logic for each API call
Validate all required fields before making API requests
Log all API calls and responses for debugging purposes
Implement rollback logic in case of partial failures
Test the complete workflow in a development environment first
Monitor API response times and implement appropriate delays
Ensure data consistency across all contract components