laxmanhalaki/Re_Backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
fbbde44d46
Re_Backend/docs/DMS_INTEGRATION_API.md

26 KiB
Raw Blame History

DMS Integration API Documentation

Overview

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

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

Data Flow Overview

Inputs from RE-Flow System

The following data is sent FROM RE-Flow System TO DMS:

  1. Dealer Code - Unique dealer identifier
  2. Dealer Name - Dealer business name
  3. Activity Name - Name of the activity/claim type (see Activity Types below)
  4. Activity Description - Detailed description of the activity
  5. Claim Amount - Total claim amount (before taxes)
  6. Request Number - Unique request identifier from RE-Flow (e.g., "REQ-2025-12-0001")
  7. IO Number - Internal Order number (if available)

Inputs from DMS Team

The following data is PROVIDED BY DMS Team TO RE-Flow System (via webhook):

  1. Document No - Generated invoice/credit note number
  2. Document Type - Type of document ("E-INVOICE", "INVOICE", or "CREDIT_NOTE")
  3. Item Code No - Item code number (same as provided in request, used for GST calculation)
  4. HSN/SAC Code - HSN/SAC code for tax calculation (determined by DMS based on Item Code No)
  5. CGST % - CGST percentage (e.g., 9.0 for 9%) - calculated by DMS based on Item Code No and dealer location
  6. SGST % - SGST percentage (e.g., 9.0 for 9%) - calculated by DMS based on Item Code No and dealer location
  7. IGST % - IGST percentage (0.0 for intra-state, >0 for inter-state) - calculated by DMS based on Item Code No and dealer location
  8. CGST Amount - CGST amount in INR - calculated by DMS
  9. SGST Amount - SGST amount in INR - calculated by DMS
  10. IGST Amount - IGST amount in INR - calculated by DMS
  11. Credit Type - Type of credit: "GST" or "Commercial Credit" (for credit notes only)
  12. IRN No - Invoice Reference Number from GST portal (response from GST system)
  13. SAP Credit Note No - SAP Credit Note Number (response from SAP system, for credit notes only)

Important: Item Code No is used by DMS for GST calculation. DMS determines HSN/SAC code, tax percentages, and tax amounts based on the Item Code No and dealer location.

Predefined Activity Types

The following is the complete list of predefined Activity Types that RE-Flow System uses. DMS Team must provide Item Code No mapping for each Activity Type:

  • Riders Mania Claims
  • Marketing Cost – Bike to Vendor
  • Media Bike Service
  • ARAI Motorcycle Liquidation
  • ARAI Certification – STA Approval CNR
  • Procurement of Spares/Apparel/GMA for Events
  • Fuel for Media Bike Used for Event
  • Motorcycle Buyback and Goodwill Support
  • Liquidation of Used Motorcycle
  • Motorcycle Registration CNR (Owned or Gifted by RE)
  • Legal Claims Reimbursement
  • Service Camp Claims
  • Corporate Claims – Institutional Sales PDI

Item Code No Lookup Process:

  1. RE-Flow sends activity_name to DMS
  2. DMS responds with corresponding item_code_no based on activity type mapping
  3. RE-Flow includes the item_code_no in invoice/credit note generation payload
  4. DMS uses item_code_no to determine HSN/SAC code and calculate GST (CGST/SGST/IGST percentages and amounts)

Note: DMS Team must configure the Activity Type → Item Code No mapping in their system. This mapping is used for GST calculation.

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 (Complete Payload):

{
  "request_number": "REQ-2025-12-0001",
  "dealer_code": "DLR001",
  "dealer_name": "ABC Motors",
  "activity_name": "Marketing Cost – Bike to Vendor",
  "activity_description": "Q4 Marketing Campaign for Royal Enfield",
  "claim_amount": 150000.00,
  "io_number": "IO-2025-001",
  "item_code_no": "ITEM-001"
}

Complete Webhook Response Payload (from DMS to RE-Flow):

After processing, DMS will send the following complete payload to RE-Flow webhook endpoint POST /api/v1/webhooks/dms/invoice:

{
  "request_number": "REQ-2025-12-0001",
  "document_no": "EINV-2025-001234",
  "document_type": "E-INVOICE",
  "document_date": "2025-12-17T10:30:00.000Z",
  "dealer_code": "DLR001",
  "dealer_name": "ABC Motors",
  "activity_name": "Marketing Cost – Bike to Vendor",
  "activity_description": "Q4 Marketing Campaign for Royal Enfield",
  "claim_amount": 150000.00,
  "io_number": "IO-2025-001",
  "item_code_no": "ITEM-001",
  "hsn_sac_code": "998314",
  "cgst_percentage": 9.0,
  "sgst_percentage": 9.0,
  "igst_percentage": 0.0,
  "cgst_amount": 13500.00,
  "sgst_amount": 13500.00,
  "igst_amount": 0.00,
  "total_amount": 177000.00,
  "irn_no": "IRN123456789012345678901234567890123456789012345678901234567890",
  "invoice_file_path": "https://dms.example.com/invoices/EINV-2025-001234.pdf",
  "error_message": null,
  "timestamp": "2025-12-17T10:30:00.000Z"
}

Important Notes:

  • RE-Flow sends all required details including item_code_no (determined by DMS based on activity_name mapping)
  • DMS processes the invoice generation asynchronously
  • DMS responds with acknowledgment only
  • Status Verification (Primary Method): DMS sends webhook to RE-Flow webhook URL POST /api/v1/webhooks/dms/invoice (see DMS_WEBHOOK_API.md) to notify when invoice is generated with complete details
  • item_code_no is used by DMS for GST calculation (HSN/SAC code, tax percentages, tax amounts)
  • Status Verification (Backup Method): If webhook fails, RE-Flow can use backup status check API (see section "Backup: Status Check API" below)

Request Field Descriptions

Field Type Required Description
request_number string ✅ Yes Unique request number from RE-Flow System (e.g., "REQ-2025-12-0001")
dealer_code string ✅ Yes Dealer's unique code/identifier
dealer_name string ✅ Yes Dealer's business name
activity_name string ✅ Yes Activity type name (must match one of the predefined Activity Types)
activity_description string ✅ Yes Detailed description of the activity/claim
claim_amount number ✅ Yes Total claim amount before taxes (in INR, decimal format)
io_number string No Internal Order (IO) number if available
item_code_no string ✅ Yes Item code number determined by DMS based on activity_name mapping. RE-Flow includes this in the request. Used by DMS for GST calculation.

Expected Response

Success Response (200 OK):

Note: DMS should respond with a simple acknowledgment. The actual invoice details (document number, tax calculations, IRN, etc.) will be sent back to RE-Flow via webhook (see DMS_WEBHOOK_API.md).

{
  "success": true,
  "message": "Invoice generation request received and queued for processing",
  "request_number": "REQ-2025-12-0001"
}

Response Field Descriptions

Field Type Description
success boolean Indicates if the request was accepted
message string Status message
request_number string Echo of the request number for reference

Important:

  • The actual invoice generation happens asynchronously
  • DMS will send the complete invoice details (including document number, tax calculations, IRN, file path, item_code_no, etc.) via webhook to RE-Flow System once processing is complete
  • Webhook endpoint: POST /api/v1/webhooks/dms/invoice (see DMS_WEBHOOK_API.md for details)
  • If webhook delivery fails, RE-Flow can use the backup status check API (see section "Backup: Status Check API" below)

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-12-0001",
    "dealer_code": "DLR001",
    "dealer_name": "ABC Motors",
    "activity_name": "Marketing Cost – Bike to Vendor",
    "activity_description": "Q4 Marketing Campaign for Royal Enfield",
    "claim_amount": 150000.00,
    "io_number": "IO-2025-001",
    "item_code_no": "ITEM-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 (Complete Payload):

{
  "request_number": "REQ-2025-12-0001",
  "e_invoice_number": "EINV-2025-001234",
  "dealer_code": "DLR001",
  "dealer_name": "ABC Motors",
  "activity_name": "Marketing Cost – Bike to Vendor",
  "activity_description": "Q4 Marketing Campaign for Royal Enfield",
  "claim_amount": 150000.00,
  "io_number": "IO-2025-001",
  "item_code_no": "ITEM-001"
}

Complete Webhook Response Payload (from DMS to RE-Flow):

After processing, DMS will send the following complete payload to RE-Flow webhook endpoint POST /api/v1/webhooks/dms/credit-note:

{
  "request_number": "REQ-2025-12-0001",
  "document_no": "CN-2025-001234",
  "document_type": "CREDIT_NOTE",
  "document_date": "2025-12-17T11:00:00.000Z",
  "dealer_code": "DLR001",
  "dealer_name": "ABC Motors",
  "activity_name": "Marketing Cost – Bike to Vendor",
  "activity_description": "Q4 Marketing Campaign for Royal Enfield",
  "claim_amount": 150000.00,
  "io_number": "IO-2025-001",
  "item_code_no": "ITEM-001",
  "hsn_sac_code": "998314",
  "cgst_percentage": 9.0,
  "sgst_percentage": 9.0,
  "igst_percentage": 0.0,
  "cgst_amount": 13500.00,
  "sgst_amount": 13500.00,
  "igst_amount": 0.00,
  "total_amount": 177000.00,
  "credit_type": "GST",
  "irn_no": "IRN987654321098765432109876543210987654321098765432109876543210",
  "sap_credit_note_no": "SAP-CN-2025-001234",
  "credit_note_file_path": "https://dms.example.com/credit-notes/CN-2025-001234.pdf",
  "error_message": null,
  "timestamp": "2025-12-17T11:00:00.000Z"
}

Important Notes:

  • RE-Flow sends activity_name in the request
  • DMS should use the same Item Code No from the original invoice (determined by activity_name)
  • DMS returns item_code_no in the webhook response (see DMS_WEBHOOK_API.md)
  • item_code_no is used by DMS for GST calculation (HSN/SAC code, tax percentages, tax amounts)

Request Field Descriptions

Field Type Required Description
request_number string ✅ Yes Original request number from RE-Flow 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
activity_name string ✅ Yes Activity type name (must match original invoice)
activity_description string ✅ Yes Activity description (must match original invoice)
claim_amount number ✅ Yes Credit note amount (in INR, decimal format) - typically matches invoice amount
io_number string No Internal Order (IO) number if available
item_code_no string ✅ Yes Item code number (same as original invoice, determined by activity_name mapping). RE-Flow includes this in the request. Used by DMS for GST calculation.

Expected Response

Success Response (200 OK):

Note: DMS should respond with a simple acknowledgment. The actual credit note details (document number, tax calculations, SAP credit note number, IRN, etc.) will be sent back to RE-Flow via webhook (see DMS_WEBHOOK_API.md).

{
  "success": true,
  "message": "Credit note generation request received and queued for processing",
  "request_number": "REQ-2025-12-0001"
}

Response Field Descriptions

Field Type Description
success boolean Indicates if the request was accepted
message string Status message
request_number string Echo of the request number for reference

Important: The actual credit note generation happens asynchronously. DMS will send the complete credit note details (including document number, tax calculations, SAP credit note number, IRN, file path, etc.) via webhook to RE-Flow System once processing is complete.

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-12-0001",
    "e_invoice_number": "EINV-2025-001234",
    "dealer_code": "DLR001",
    "dealer_name": "ABC Motors",
    "activity_name": "Marketing Cost – Bike to Vendor",
    "activity_description": "Q4 Marketing Campaign for Royal Enfield",
    "claim_amount": 150000.00,
    "io_number": "IO-2025-001",
    "item_code_no": "ITEM-001"
  }'

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:

  1. API Key Authentication (Recommended)

    • Set DMS_API_KEY in environment variables
    • Header: Authorization: Bearer {DMS_API_KEY}

  2. 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-Flow System  │
│ (Step 6)        │
└────────┬────────┘
         │
         │ POST /api/invoices/generate
         │ { request_number, dealer_code, activity_name,
         │   claim_amount, item_code_no, ... }
         │
         ▼
┌─────────────────┐
│ DMS System      │
│                 │
│ - Validates     │
│ - Queues for    │
│   processing    │
│                 │
│ Response:       │
│ { success: true }│
└────────┬────────┘
         │
         │ (Asynchronous Processing)
         │
         │ - Determines Item Code No
         │ - Calculates GST
         │ - Generates E-Invoice
         │ - Gets IRN from GST
         │
         │ POST /api/v1/webhooks/dms/invoice
         │ { document_no, item_code_no, 
         │   hsn_sac_code, tax details,
         │   irn_no, invoice_file_path, ... }
         │
         ▼
┌─────────────────┐
│ RE-Flow System  │
│                 │
│ - Receives      │
│   webhook       │
│ - Stores        │
│   invoice data  │
│ - Updates       │
│   workflow      │
│ - Moves to      │
│   Step 8        │
└─────────────────┘

Backup (if webhook fails):
┌─────────────────┐
│ RE-Flow System  │
│                 │
│ GET /api/invoices/status/{request_number}
│                 │
         ▼
┌─────────────────┐
│ DMS System      │
│                 │
│ Returns current │
│ invoice status  │
│ and details     │
└─────────────────┘

Credit Note Generation Flow

┌─────────────────┐
│ RE-Flow System  │
│ (Step 8)        │
└────────┬────────┘
         │
         │ POST /api/credit-notes/generate
         │ { e_invoice_number, request_number, 
         │   activity_name, claim_amount,
         │   item_code_no, ... }
         │
         ▼
┌─────────────────┐
│ DMS System      │
│                 │
│ - Validates     │
│   invoice       │
│ - Queues for    │
│   processing    │
│                 │
│ Response:       │
│ { success: true }│
└────────┬────────┘
         │
         │ (Asynchronous Processing)
         │
         │ - Uses Item Code No from invoice
         │ - Calculates GST
         │ - Generates Credit Note
         │ - Gets IRN from GST
         │ - Gets SAP Credit Note No
         │
         │ POST /api/v1/webhooks/dms/credit-note
         │ { document_no, item_code_no,
         │   hsn_sac_code, tax details,
         │   irn_no, sap_credit_note_no,
         │   credit_note_file_path, ... }
         │
         ▼
┌─────────────────┐
│ RE-Flow System  │
│                 │
│ - Receives      │
│   webhook       │
│ - Stores        │
│   credit note   │
│ - Updates       │
│   workflow      │
│ - Completes     │
│   request       │
└─────────────────┘

Backup (if webhook fails):
┌─────────────────┐
│ RE-Flow System  │
│                 │
│ GET /api/credit-notes/status/{request_number}
│                 │
         ▼
┌─────────────────┐
│ DMS System      │
│                 │
│ Returns current │
│ credit note     │
│ status and      │
│ details         │
└─────────────────┘

Data Mapping

RE-Flow System → DMS (API Request)

RE-Flow Field DMS Request Field Notes
request.requestNumber request_number Direct mapping
claimDetails.dealerCode dealer_code Direct mapping
claimDetails.dealerName dealer_name Direct mapping
claimDetails.activityName activity_name Must match predefined Activity Types
claimDetails.activityDescription activity_description Direct mapping
budgetTracking.closedExpenses claim_amount Total claim amount (before taxes)
internalOrder.ioNumber io_number Optional, if available
itemCodeNo (determined by DMS) item_code_no Included in payload. DMS determines this based on activity_name mapping. Used by DMS for GST calculation.
claimInvoice.invoiceNumber e_invoice_number For credit note request only

DMS → RE-Flow System (Webhook Response)

Note: All invoice and credit note details are sent via webhook (see DMS_WEBHOOK_API.md), not in the API response.

DMS Webhook Field RE-Flow Database Field Table Notes
document_no invoice_number / credit_note_number claim_invoices / claim_credit_notes Generated by DMS
document_date invoice_date / credit_note_date claim_invoices / claim_credit_notes Converted to Date object
total_amount invoice_amount / credit_amount claim_invoices / claim_credit_notes Includes taxes
invoice_file_path invoice_file_path claim_invoices URL/path to PDF
credit_note_file_path credit_note_file_path claim_credit_notes URL/path to PDF
irn_no Stored in description field Both tables From GST portal
sap_credit_note_no sap_document_number claim_credit_notes From SAP system
item_code_no Stored in description field Both tables Provided by DMS based on activity
hsn_sac_code Stored in description field Both tables Provided by DMS
cgst_amount, sgst_amount, igst_amount Stored in description field Both tables Tax breakdown
credit_type Stored in description field claim_credit_notes "GST" or "Commercial Credit"

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",
  "activity_name": "Marketing Cost – Bike to Vendor",
  "activity_description": "Test invoice generation for marketing activity",
  "claim_amount": 10000.00,
  "io_number": "IO-TEST-001",
  "item_code_no": "ITEM-001"
}

Credit Note Test Request:

{
  "request_number": "REQ-TEST-001",
  "e_invoice_number": "EINV-TEST-001",
  "dealer_code": "TEST-DLR-001",
  "dealer_name": "Test Dealer",
  "activity_name": "Marketing Cost – Bike to Vendor",
  "activity_description": "Test credit note generation for marketing activity",
  "claim_amount": 10000.00,
  "io_number": "IO-TEST-001",
  "item_code_no": "ITEM-001"
}

Notes

  1. Asynchronous Processing: Invoice and credit note generation happens asynchronously. DMS should:

    • Accept the request immediately and return a success acknowledgment
    • Process the invoice/credit note in the background
    • Send complete details via webhook once processing is complete

  2. Activity Type to Item Code No Mapping:

    • DMS Team must provide Item Code No mapping for each predefined Activity Type
    • This mapping should be configured in DMS system
    • RE-Flow includes item_code_no in the request payload (determined by DMS based on activity_name mapping)
    • DMS uses Item Code No to determine HSN/SAC code and calculate GST (CGST/SGST/IGST percentages and amounts)
    • DMS returns item_code_no in the webhook response for verification

  3. Tax Calculation: DMS is responsible for:

    • Determining CGST/SGST/IGST percentages based on dealer location and activity type
    • Calculating tax amounts
    • Providing HSN/SAC codes

  4. Amount Validation: DMS should validate that credit note amount matches or is less than the original invoice amount.

  5. Invoice Dependency: Credit note generation requires a valid e-invoice to exist in DMS first.

  6. Error Handling: RE-Flow System handles DMS errors gracefully and allows manual entry if DMS is unavailable.

  7. Retry Logic: Consider implementing retry logic for transient DMS failures.

  8. Webhooks (Primary Method): DMS MUST send webhooks to notify RE-Flow System when invoice/credit note processing is complete. See DMS_WEBHOOK_API.md for webhook specifications. This is the primary method for status verification.

  9. Status Check API (Backup Method): If webhook delivery fails, RE-Flow can use the backup status check API to verify invoice/credit note generation status. See section "Backup: Status Check API" above.

  10. IRN Generation: DMS should generate IRN (Invoice Reference Number) from GST portal and include it in the webhook response.

  11. SAP Integration: For credit notes, DMS should generate SAP Credit Note Number and include it in the webhook response.

  12. Webhook URL Configuration: DMS must be configured with RE-Flow webhook URLs:

    • Invoice Webhook: POST /api/v1/webhooks/dms/invoice
    • Credit Note Webhook: POST /api/v1/webhooks/dms/credit-note
    • See DMS_WEBHOOK_API.md for complete webhook specifications

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 19, 2025
Version: 2.0

Changelog

Version 2.0 (December 19, 2025)

  • Added clear breakdown of inputs from RE-Flow vs DMS Team
  • Added predefined Activity Types list
  • Updated request/response structure to reflect asynchronous processing
  • Clarified that detailed responses come via webhook, not API response
  • Updated field names to match actual implementation (claim_amount instead of amount, activity_name, activity_description)
  • Added notes about Item Code No mapping requirement for DMS Team
  • Updated data mapping section with webhook fields

Version 1.0 (December 17, 2025)

  • Initial documentation