laxmanhalaki 8dc7fd3307 delaer sla tracker functionalities enhanced

2025-12-17 13:06:32 +05:30

13 KiB

Raw Blame History

DMS Integration API Documentation

Overview

This document describes the data exchange between the Royal Enfield Workflow System and the DMS (Document Management System) for:

E-Invoice Generation - Submitting claim data to DMS for e-invoice creation
Credit Note Generation - Fetching/Generating credit note from DMS

1. E-Invoice Generation (DMS Push)

When It's Called

This API is called when:

Step 6 of the claim management workflow is approved (Requestor approves the claim)
User manually pushes claim data to DMS via the "Push to DMS" action
System auto-generates e-invoice after claim approval

Request Details

Endpoint: POST {DMS_BASE_URL}/api/invoices/generate

Headers:

Authorization: Bearer {DMS_API_KEY}
Content-Type: application/json

Request Body:

{
  "request_number": "REQ-2025-001234",
  "dealer_code": "DLR001",
  "dealer_name": "ABC Motors",
  "amount": 150000.00,
  "description": "E-Invoice for claim request REQ-2025-001234",
  "io_number": "IO-2025-001",
  "tax_details": {
    "cgst": 0,
    "sgst": 0,
    "igst": 0,
    "total_tax": 0
  }
}

Request Field Descriptions

Field	Type	Required	Description
`request_number`	string	Yes	Unique request number from RE Workflow System (e.g., "REQ-2025-001234")
`dealer_code`	string	Yes	Dealer's unique code/identifier
`dealer_name`	string	Yes	Dealer's business name
`amount`	number	Yes	Total invoice amount (in INR, decimal format)
`description`	string	Yes	Description of the invoice/claim
`io_number`	string	No	Internal Order (IO) number if available
`tax_details`	object	No	Tax breakdown (CGST, SGST, IGST, Total Tax)

Expected Response

Success Response (200 OK):

{
  "success": true,
  "e_invoice_number": "EINV-2025-001234",
  "dms_number": "DMS-2025-001234",
  "invoice_date": "2025-12-17T10:30:00.000Z",
  "invoice_url": "https://dms.example.com/invoices/EINV-2025-001234"
}

Response Field Descriptions

Field	Type	Description
`success`	boolean	Indicates if the request was successful
`e_invoice_number`	string	Generated e-invoice number (unique identifier)
`dms_number`	string	DMS internal tracking number
`invoice_date`	string (ISO 8601)	Date when the invoice was generated
`invoice_url`	string	URL to view/download the invoice document

Error Response

Error Response (400/500):

{
  "success": false,
  "error": "Error message describing what went wrong",
  "error_code": "INVALID_DEALER_CODE"
}

Error Scenarios

Error Code	Description	Possible Causes
`INVALID_DEALER_CODE`	Dealer code not found in DMS	Dealer not registered in DMS
`INVALID_AMOUNT`	Amount validation failed	Negative amount or invalid format
`IO_NOT_FOUND`	IO number not found	Invalid or non-existent IO number
`DMS_SERVICE_ERROR`	DMS internal error	DMS system unavailable or processing error

Example cURL Request

curl -X POST "https://dms.example.com/api/invoices/generate" \
  -H "Authorization: Bearer YOUR_DMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_number": "REQ-2025-001234",
    "dealer_code": "DLR001",
    "dealer_name": "ABC Motors",
    "amount": 150000.00,
    "description": "E-Invoice for claim request REQ-2025-001234",
    "io_number": "IO-2025-001"
  }'

2. Credit Note Generation (DMS Fetch)

When It's Called

This API is called when:

Step 8 of the claim management workflow is initiated (Credit Note Confirmation)
User requests to generate/fetch credit note from DMS
System auto-generates credit note after e-invoice is confirmed

Request Details

Endpoint: POST {DMS_BASE_URL}/api/credit-notes/generate

Headers:

Authorization: Bearer {DMS_API_KEY}
Content-Type: application/json

Request Body:

{
  "request_number": "REQ-2025-001234",
  "e_invoice_number": "EINV-2025-001234",
  "dealer_code": "DLR001",
  "dealer_name": "ABC Motors",
  "amount": 150000.00,
  "reason": "Claim settlement",
  "description": "Credit note for claim request REQ-2025-001234"
}

Request Field Descriptions

Field	Type	Required	Description
`request_number`	string	Yes	Original request number from RE Workflow System
`e_invoice_number`	string	Yes	E-invoice number that was generated earlier (must exist in DMS)
`dealer_code`	string	Yes	Dealer's unique code/identifier (must match invoice)
`dealer_name`	string	Yes	Dealer's business name
`amount`	number	Yes	Credit note amount (in INR, decimal format) - typically matches invoice amount
`reason`	string	Yes	Reason for credit note (e.g., "Claim settlement", "Return", "Adjustment")
`description`	string	No	Additional description/details about the credit note

Expected Response

Success Response (200 OK):

{
  "success": true,
  "credit_note_number": "CN-2025-001234",
  "credit_note_date": "2025-12-17T10:30:00.000Z",
  "credit_note_amount": 150000.00,
  "credit_note_url": "https://dms.example.com/credit-notes/CN-2025-001234"
}

Response Field Descriptions

Field	Type	Description
`success`	boolean	Indicates if the request was successful
`credit_note_number`	string	Generated credit note number (unique identifier)
`credit_note_date`	string (ISO 8601)	Date when the credit note was generated
`credit_note_amount`	number	Credit note amount (should match request amount)
`credit_note_url`	string	URL to view/download the credit note document

Error Response

Error Response (400/500):

{
  "success": false,
  "error": "Error message describing what went wrong",
  "error_code": "INVOICE_NOT_FOUND"
}

Error Scenarios

Error Code	Description	Possible Causes
`INVOICE_NOT_FOUND`	E-invoice number not found in DMS	Invoice was not generated or invalid invoice number
`INVALID_AMOUNT`	Amount validation failed	Amount mismatch with invoice or invalid format
`DEALER_MISMATCH`	Dealer code/name doesn't match invoice	Different dealer code than original invoice
`CREDIT_NOTE_EXISTS`	Credit note already generated for this invoice	Duplicate request for same invoice
`DMS_SERVICE_ERROR`	DMS internal error	DMS system unavailable or processing error

Example cURL Request

curl -X POST "https://dms.example.com/api/credit-notes/generate" \
  -H "Authorization: Bearer YOUR_DMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_number": "REQ-2025-001234",
    "e_invoice_number": "EINV-2025-001234",
    "dealer_code": "DLR001",
    "dealer_name": "ABC Motors",
    "amount": 150000.00,
    "reason": "Claim settlement",
    "description": "Credit note for claim request REQ-2025-001234"
  }'

Configuration

Environment Variables

The following environment variables need to be configured in the RE Workflow System:

# DMS Integration Configuration
DMS_BASE_URL=https://dms.example.com
DMS_API_KEY=your_dms_api_key_here

# Alternative: Username/Password Authentication
DMS_USERNAME=your_dms_username
DMS_PASSWORD=your_dms_password

Authentication Methods

DMS supports two authentication methods:

API Key Authentication (Recommended)
- Set DMS_API_KEY in environment variables
- Header: Authorization: Bearer {DMS_API_KEY}
Username/Password Authentication
- Set DMS_USERNAME and DMS_PASSWORD in environment variables
- Use Basic Auth or custom authentication as per DMS requirements

Integration Flow

E-Invoice Generation Flow

┌─────────────────┐
│ RE Workflow     │
│ System          │
│ (Step 6)        │
└────────┬────────┘
         │
         │ POST /api/invoices/generate
         │ { request_number, dealer_code, amount, ... }
         │
         ▼
┌─────────────────┐
│ DMS System      │
│                 │
│ - Validates     │
│ - Generates     │
│   E-Invoice     │
└────────┬────────┘
         │
         │ Response: { e_invoice_number, dms_number, ... }
         │
         ▼
┌─────────────────┐
│ RE Workflow     │
│ System          │
│                 │
│ - Stores        │
│   invoice data  │
│ - Updates       │
│   workflow      │
└─────────────────┘

Credit Note Generation Flow

┌─────────────────┐
│ RE Workflow     │
│ System          │
│ (Step 8)        │
└────────┬────────┘
         │
         │ POST /api/credit-notes/generate
         │ { e_invoice_number, request_number, amount, ... }
         │
         ▼
┌─────────────────┐
│ DMS System      │
│                 │
│ - Validates     │
│   invoice       │
│ - Generates     │
│   Credit Note   │
└────────┬────────┘
         │
         │ Response: { credit_note_number, credit_note_date, ... }
         │
         ▼
┌─────────────────┐
│ RE Workflow     │
│ System          │
│                 │
│ - Stores        │
│   credit note   │
│ - Updates       │
│   workflow      │
└─────────────────┘

Data Mapping

RE Workflow System → DMS

RE Workflow Field	DMS Request Field	Notes
`request.requestNumber`	`request_number`	Direct mapping
`claimDetails.dealerCode`	`dealer_code`	Direct mapping
`claimDetails.dealerName`	`dealer_name`	Direct mapping
`budgetTracking.closedExpenses`	`amount`	Total claim amount
`internalOrder.ioNumber`	`io_number`	Optional, if available
`claimInvoice.invoiceNumber`	`e_invoice_number`	For credit note only

DMS → RE Workflow System

DMS Response Field	RE Workflow Field	Notes
`e_invoice_number`	`ClaimInvoice.invoiceNumber`	Stored in database
`dms_number`	`ClaimInvoice.dmsNumber`	Stored in database
`invoice_date`	`ClaimInvoice.invoiceDate`	Converted to Date object
`credit_note_number`	`ClaimCreditNote.creditNoteNumber`	Stored in database
`credit_note_date`	`ClaimCreditNote.creditNoteDate`	Converted to Date object
`credit_note_amount`	`ClaimCreditNote.creditNoteAmount`	Stored in database

Testing

Mock Mode

When DMS is not configured, the system operates in mock mode:

Returns mock invoice/credit note numbers
Logs warnings instead of making actual API calls
Useful for development and testing

Test Data

E-Invoice Test Request:

{
  "request_number": "REQ-TEST-001",
  "dealer_code": "TEST-DLR-001",
  "dealer_name": "Test Dealer",
  "amount": 10000.00,
  "description": "Test invoice generation"
}

Credit Note Test Request:

{
  "request_number": "REQ-TEST-001",
  "e_invoice_number": "EINV-TEST-001",
  "dealer_code": "TEST-DLR-001",
  "dealer_name": "Test Dealer",
  "amount": 10000.00,
  "reason": "Test credit note",
  "description": "Test credit note generation"
}

Notes

Idempotency: Both APIs should be idempotent - calling them multiple times with the same data should not create duplicates.
Amount Validation: DMS should validate that credit note amount matches or is less than the original invoice amount.
Invoice Dependency: Credit note generation requires a valid e-invoice to exist in DMS first.
Error Handling: RE Workflow System handles DMS errors gracefully and allows manual entry if DMS is unavailable.
Retry Logic: Consider implementing retry logic for transient DMS failures.
Webhooks (Optional): DMS can send webhooks to notify RE Workflow System when invoice/credit note status changes.

Support

For issues or questions regarding DMS integration:

Backend Team: Check logs in Re_Backend/src/services/dmsIntegration.service.ts
DMS Team: Contact DMS support for API-related issues
Documentation: Refer to DMS API documentation for latest updates

Last Updated: December 17, 2025
Version: 1.0

13 KiB Raw Blame History

DMS Integration API Documentation

Overview

1. E-Invoice Generation (DMS Push)

When It's Called

Request Details

Request Field Descriptions

Expected Response

Response Field Descriptions

Error Response

Error Scenarios

Example cURL Request

2. Credit Note Generation (DMS Fetch)

When It's Called

Request Details

Request Field Descriptions

Expected Response

Response Field Descriptions

Error Response

Error Scenarios

Example cURL Request

Configuration

Environment Variables

Authentication Methods

Integration Flow

E-Invoice Generation Flow

Credit Note Generation Flow

Data Mapping

RE Workflow System → DMS

DMS → RE Workflow System

Testing

Mock Mode

Test Data

Notes

Support

13 KiB

Raw Blame History