Re_Backend/docs/DMS_INTEGRATION_API.md

# DMS Integration API Documentation

## Overview

This document describes the data exchange between the Royal Enfield Workflow System 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

---

## 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:**
```http
Authorization: Bearer {DMS_API_KEY}
Content-Type: application/json
```

**Request Body:**
```json
{
  "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):**
```json
{
  "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):**
```json
{
  "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

```bash
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:**
```http
Authorization: Bearer {DMS_API_KEY}
Content-Type: application/json
```

**Request Body:**
```json
{
  "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):**
```json
{
  "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):**
```json
{
  "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

```bash
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:

```env
# 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 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:**
```json
{
  "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:**
```json
{
  "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

1. **Idempotency**: Both APIs should be idempotent - calling them multiple times with the same data should not create duplicates.

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

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

4. **Error Handling**: RE Workflow System handles DMS errors gracefully and allows manual entry if DMS is unavailable.

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

6. **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