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

575 lines
20 KiB
Markdown
Raw Permalink Blame History

# DMS Webhook API Documentation
## Overview
This document describes the webhook endpoints that DMS (Document Management System) will call to notify the RE Workflow System after processing invoice and credit note generation requests.
---
## Table of Contents
1. [Webhook Overview](#1-webhook-overview)
2. [Authentication](#2-authentication)
3. [Invoice Webhook](#3-invoice-webhook)
4. [Credit Note Webhook](#4-credit-note-webhook)
5. [Payload Specifications](#5-payload-specifications)
6. [Error Handling](#6-error-handling)
7. [Testing](#7-testing)
---
## 1. Webhook Overview
### 1.1 Purpose
After RE Workflow System pushes invoice/credit note generation requests to DMS, DMS processes them and sends webhook callbacks with the generated document details, tax information, and other metadata.
### 1.2 Webhook Flow
```
┌─────────────────┐ ┌─────────────────┐
│ RE Workflow │ │ DMS System │
│ System │ │ │
└────────┬────────┘ └────────┬────────┘
│ │
│ POST /api/invoices/generate │
│ { request_number, dealer_code, ... }│
├─────────────────────────────────────►│
│ │
│ │ Process Invoice
│ │ Generate Document
│ │ Calculate GST
│ │
│ │ POST /api/v1/webhooks/dms/invoice
│ │ { document_no, irn_no, ... }
│◄─────────────────────────────────────┤
│ │
│ Update Invoice Record │
│ Store IRN, GST Details, etc. │
│ │
```
---
## 2. Authentication
### 2.1 Webhook Signature
DMS must include a signature in the request header for security validation:
**Header:**
```
X-DMS-Signature: <HMAC-SHA256-signature>
```
**Signature Generation:**
1. Create HMAC-SHA256 hash of the request body (JSON string)
2. Use the shared secret key (`DMS_WEBHOOK_SECRET`)
3. Send the hex-encoded signature in the `X-DMS-Signature` header
**Example:**
```javascript
const crypto = require('crypto');
const body = JSON.stringify(payload);
const signature = crypto
.createHmac('sha256', DMS_WEBHOOK_SECRET)
.update(body)
.digest('hex');
// Send in header: X-DMS-Signature: <signature>
```
### 2.2 Environment Variable
Configure the webhook secret in RE Workflow System:
```env
DMS_WEBHOOK_SECRET=your_shared_secret_key_here
```
**Note:** If `DMS_WEBHOOK_SECRET` is not configured, signature validation is skipped (development mode only).
---
## 3. Invoice Webhook
### 3.1 Endpoint
**URL:** `POST /api/v1/webhooks/dms/invoice`
**Base URL Examples:**
- Development: `http://localhost:5000/api/v1/webhooks/dms/invoice`
- UAT: `https://reflow-uat.royalenfield.com/api/v1/webhooks/dms/invoice`
- Production: `https://reflow.royalenfield.com/api/v1/webhooks/dms/invoice`
### 3.2 Request Headers
```http
Content-Type: application/json
X-DMS-Signature: <HMAC-SHA256-signature>
User-Agent: DMS-Webhook-Client/1.0
```
### 3.3 Request Payload
```json
{
"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 Campaign",
"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"
}
```
### 3.4 Payload Field Descriptions
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `request_number` | string | ✅ Yes | Original request number from RE Workflow System (e.g., "REQ-2025-12-0001") |
| `document_no` | string | ✅ Yes | Generated invoice/document number from DMS |
| `document_type` | string | ✅ Yes | Type of document: "E-INVOICE" or "INVOICE" |
| `document_date` | string (ISO 8601) | ✅ Yes | Date when invoice was generated |
| `dealer_code` | string | ✅ Yes | Dealer code (should match original request) |
| `dealer_name` | string | ✅ Yes | Dealer name (should match original request) |
| `activity_name` | string | ✅ Yes | Activity name from original request |
| `activity_description` | string | ✅ Yes | Activity description from original request |
| `claim_amount` | number | ✅ Yes | Original claim amount (before tax) |
| `io_number` | string | No | Internal Order number (if provided in original request) |
| `item_code_no` | string | ✅ Yes | Item code number (provided by DMS team based on activity list) |
| `hsn_sac_code` | string | ✅ Yes | HSN/SAC code for the invoice |
| `cgst_percentage` | number | ✅ Yes | CGST percentage (e.g., 9.0 for 9%) |
| `sgst_percentage` | number | ✅ Yes | SGST percentage (e.g., 9.0 for 9%) |
| `igst_percentage` | number | ✅ Yes | IGST percentage (0.0 for intra-state, >0 for inter-state) |
| `cgst_amount` | number | ✅ Yes | CGST amount in INR |
| `sgst_amount` | number | ✅ Yes | SGST amount in INR |
| `igst_amount` | number | ✅ Yes | IGST amount in INR |
| `total_amount` | number | ✅ Yes | Total invoice amount (claim_amount + all taxes) |
| `irn_no` | string | No | Invoice Reference Number (IRN) from GST portal (if generated) |
| `invoice_file_path` | string | ✅ Yes | URL or path to the generated invoice PDF/document file |
| `error_message` | string | No | Error message if invoice generation failed |
| `timestamp` | string (ISO 8601) | ✅ Yes | Timestamp when webhook is sent |
### 3.5 Success Response
**Status Code:** `200 OK`
```json
{
"success": true,
"message": "Invoice webhook processed successfully",
"data": {
"message": "Invoice webhook processed successfully",
"invoiceNumber": "EINV-2025-001234",
"requestNumber": "REQ-2025-12-0001"
}
}
```
### 3.6 Error Response
**Status Code:** `400 Bad Request` or `500 Internal Server Error`
```json
{
"success": false,
"message": "Failed to process invoice webhook",
"error": "Request not found: REQ-2025-12-0001"
}
```
---
## 4. Credit Note Webhook
### 4.1 Endpoint
**URL:** `POST /api/v1/webhooks/dms/credit-note`
**Base URL Examples:**
- Development: `http://localhost:5000/api/v1/webhooks/dms/credit-note`
- UAT: `https://reflow-uat.royalenfield.com/api/v1/webhooks/dms/credit-note`
- Production: `https://reflow.royalenfield.com/api/v1/webhooks/dms/credit-note`
### 4.2 Request Headers
```http
Content-Type: application/json
X-DMS-Signature: <HMAC-SHA256-signature>
User-Agent: DMS-Webhook-Client/1.0
```
### 4.3 Request Payload
```json
{
"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 Campaign",
"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"
}
```
### 4.4 Payload Field Descriptions
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `request_number` | string | ✅ Yes | Original request number from RE Workflow System |
| `document_no` | string | ✅ Yes | Generated credit note number from DMS |
| `document_type` | string | ✅ Yes | Type of document: "CREDIT_NOTE" |
| `document_date` | string (ISO 8601) | ✅ Yes | Date when credit note was generated |
| `dealer_code` | string | ✅ Yes | Dealer code (should match original request) |
| `dealer_name` | string | ✅ Yes | Dealer name (should match original request) |
| `activity_name` | string | ✅ Yes | Activity name from original request |
| `activity_description` | string | ✅ Yes | Activity description from original request |
| `claim_amount` | string | ✅ Yes | Original claim amount (before tax) |
| `io_number` | string | No | Internal Order number (if provided) |
| `item_code_no` | string | ✅ Yes | Item code number (provided by DMS team) |
| `hsn_sac_code` | string | ✅ Yes | HSN/SAC code for the credit note |
| `cgst_percentage` | number | ✅ Yes | CGST percentage |
| `sgst_percentage` | number | ✅ Yes | SGST percentage |
| `igst_percentage` | number | ✅ Yes | IGST percentage |
| `cgst_amount` | number | ✅ Yes | CGST amount in INR |
| `sgst_amount` | number | ✅ Yes | SGST amount in INR |
| `igst_amount` | number | ✅ Yes | IGST amount in INR |
| `total_amount` | number | ✅ Yes | Total credit note amount (claim_amount + all taxes) |
| `credit_type` | string | ✅ Yes | Type of credit: "GST" or "Commercial Credit" |
| `irn_no` | string | No | Invoice Reference Number (IRN) for credit note (if generated) |
| `sap_credit_note_no` | string | ✅ Yes | SAP Credit Note Number (generated by SAP system) |
| `credit_note_file_path` | string | ✅ Yes | URL or path to the generated credit note PDF/document file |
| `error_message` | string | No | Error message if credit note generation failed |
| `timestamp` | string (ISO 8601) | ✅ Yes | Timestamp when webhook is sent |
### 4.5 Success Response
**Status Code:** `200 OK`
```json
{
"success": true,
"message": "Credit note webhook processed successfully",
"data": {
"message": "Credit note webhook processed successfully",
"creditNoteNumber": "CN-2025-001234",
"requestNumber": "REQ-2025-12-0001"
}
}
```
### 4.6 Error Response
**Status Code:** `400 Bad Request` or `500 Internal Server Error`
```json
{
"success": false,
"message": "Failed to process credit note webhook",
"error": "Credit note record not found for request: REQ-2025-12-0001"
}
```
---
## 5. Payload Specifications
### 5.1 Data Mapping: RE Workflow → DMS
When RE Workflow System sends data to DMS, it includes:
| RE Workflow Field | DMS Receives | Notes |
|-------------------|--------------|-------|
| `requestNumber` | `request_number` | Direct mapping |
| `dealerCode` | `dealer_code` | Direct mapping |
| `dealerName` | `dealer_name` | Direct mapping |
| `activityName` | `activity_name` | From claim details |
| `activityDescription` | `activity_description` | From claim details |
| `claimAmount` | `claim_amount` | Total claim amount |
| `ioNumber` | `io_number` | If available |
### 5.2 Data Mapping: DMS → RE Workflow
When DMS sends webhook, RE Workflow System stores:
| DMS Webhook Field | RE Workflow Database Field | Table |
|-------------------|---------------------------|-------|
| `document_no` | `invoice_number` / `credit_note_number` | `claim_invoices` / `claim_credit_notes` |
| `document_date` | `invoice_date` / `credit_note_date` | `claim_invoices` / `claim_credit_notes` |
| `total_amount` | `invoice_amount` / `credit_note_amount` | `claim_invoices` / `claim_credit_notes` |
| `invoice_file_path` | `invoice_file_path` | `claim_invoices` |
| `credit_note_file_path` | `credit_note_file_path` | `claim_credit_notes` |
| `irn_no` | Stored in `description` field | Both tables |
| `sap_credit_note_no` | `sap_document_number` | `claim_credit_notes` |
| `item_code_no` | Stored in `description` field | Both tables |
| `hsn_sac_code` | Stored in `description` field | Both tables |
| GST amounts | Stored in `description` field | Both tables |
| `credit_type` | Stored in `description` field | `claim_credit_notes` |
### 5.3 GST Calculation Logic
**Intra-State (Same State):**
- CGST: Applied (e.g., 9%)
- SGST: Applied (e.g., 9%)
- IGST: 0%
**Inter-State (Different State):**
- CGST: 0%
- SGST: 0%
- IGST: Applied (e.g., 18%)
**Total Amount Calculation:**
```
total_amount = claim_amount + cgst_amount + sgst_amount + igst_amount
```
---
## 6. Error Handling
### 6.1 Common Error Scenarios
| Error | Status Code | Description | Solution |
|-------|-------------|-------------|----------|
| Invalid Signature | 401 | Webhook signature validation failed | Check `DMS_WEBHOOK_SECRET` and signature generation |
| Missing Required Field | 400 | Required field is missing in payload | Ensure all required fields are included |
| Request Not Found | 400 | Request number doesn't exist in system | Verify request number matches original request |
| Invoice Not Found | 400 | Invoice record not found for request | Ensure invoice was created before webhook |
| Credit Note Not Found | 400 | Credit note record not found for request | Ensure credit note was created before webhook |
| Database Error | 500 | Internal database error | Check database connection and logs |
### 6.2 Retry Logic
DMS should implement retry logic for failed webhook deliveries:
- **Initial Retry:** After 1 minute
- **Second Retry:** After 5 minutes
- **Third Retry:** After 15 minutes
- **Final Retry:** After 1 hour
**Maximum Retries:** 4 attempts
**Retry Conditions:**
- HTTP 5xx errors (server errors)
- Network timeouts
- Connection failures
**Do NOT Retry:**
- HTTP 400 errors (client errors - invalid payload)
- HTTP 401 errors (authentication errors)
### 6.3 Idempotency
Webhooks should be idempotent. If DMS sends the same webhook multiple times:
- RE Workflow System will update the record with the latest data
- No duplicate records will be created
- Status will be updated to reflect the latest state
---
## 7. Testing
### 7.1 Test Invoice Webhook
```bash
curl -X POST "http://localhost:5000/api/v1/webhooks/dms/invoice" \
-H "Content-Type: application/json" \
-H "X-DMS-Signature: <calculated-signature>" \
-d '{
"request_number": "REQ-2025-12-0001",
"document_no": "EINV-TEST-001",
"document_type": "E-INVOICE",
"document_date": "2025-12-17T10:30:00.000Z",
"dealer_code": "DLR001",
"dealer_name": "Test Dealer",
"activity_name": "Test Activity",
"activity_description": "Test Description",
"claim_amount": 100000.00,
"io_number": "IO-TEST-001",
"item_code_no": "ITEM-001",
"hsn_sac_code": "998314",
"cgst_percentage": 9.0,
"sgst_percentage": 9.0,
"igst_percentage": 0.0,
"cgst_amount": 9000.00,
"sgst_amount": 9000.00,
"igst_amount": 0.00,
"total_amount": 118000.00,
"irn_no": "IRN123456789012345678901234567890123456789012345678901234567890",
"invoice_file_path": "https://dms.example.com/invoices/EINV-TEST-001.pdf",
"timestamp": "2025-12-17T10:30:00.000Z"
}'
```
### 7.2 Test Credit Note Webhook
```bash
curl -X POST "http://localhost:5000/api/v1/webhooks/dms/credit-note" \
-H "Content-Type: application/json" \
-H "X-DMS-Signature: <calculated-signature>" \
-d '{
"request_number": "REQ-2025-12-0001",
"document_no": "CN-TEST-001",
"document_type": "CREDIT_NOTE",
"document_date": "2025-12-17T11:00:00.000Z",
"dealer_code": "DLR001",
"dealer_name": "Test Dealer",
"activity_name": "Test Activity",
"activity_description": "Test Description",
"claim_amount": 100000.00,
"io_number": "IO-TEST-001",
"item_code_no": "ITEM-001",
"hsn_sac_code": "998314",
"cgst_percentage": 9.0,
"sgst_percentage": 9.0,
"igst_percentage": 0.0,
"cgst_amount": 9000.00,
"sgst_amount": 9000.00,
"igst_amount": 0.00,
"total_amount": 118000.00,
"credit_type": "GST",
"irn_no": "IRN987654321098765432109876543210987654321098765432109876543210",
"sap_credit_note_no": "SAP-CN-TEST-001",
"credit_note_file_path": "https://dms.example.com/credit-notes/CN-TEST-001.pdf",
"timestamp": "2025-12-17T11:00:00.000Z"
}'
```
### 7.3 Signature Calculation (Node.js Example)
```javascript
const crypto = require('crypto');
function calculateSignature(payload, secret) {
const body = JSON.stringify(payload);
return crypto
.createHmac('sha256', secret)
.update(body)
.digest('hex');
}
const payload = { /* webhook payload */ };
const secret = process.env.DMS_WEBHOOK_SECRET;
const signature = calculateSignature(payload, secret);
// Use in header: X-DMS-Signature: <signature>
```
---
## 8. Integration Checklist
### 8.1 DMS Team Checklist
- [ ] Configure webhook URLs in DMS system
- [ ] Set up `DMS_WEBHOOK_SECRET` (shared secret)
- [ ] Implement signature generation (HMAC-SHA256)
- [ ] Test webhook delivery to RE Workflow endpoints
- [ ] Implement retry logic for failed deliveries
- [ ] Set up monitoring/alerting for webhook failures
- [ ] Document webhook payload structure
- [ ] Coordinate with RE Workflow team for testing
### 8.2 RE Workflow Team Checklist
- [ ] Configure `DMS_WEBHOOK_SECRET` in environment variables
- [ ] Deploy webhook endpoints to UAT/Production
- [ ] Test webhook endpoints with sample payloads
- [ ] Verify database updates after webhook processing
- [ ] Set up monitoring/alerting for webhook failures
- [ ] Document webhook endpoints for DMS team
- [ ] Coordinate with DMS team for integration testing
---
## 9. Support & Troubleshooting
### 9.1 Logs
RE Workflow System logs webhook processing:
- **Success:** `[DMSWebhook] Invoice webhook processed successfully`
- **Error:** `[DMSWebhook] Error processing invoice webhook: <error>`
- **Validation:** `[DMSWebhook] Invalid webhook signature`
### 9.2 Common Issues
**Issue: Webhook signature validation fails**
- Verify `DMS_WEBHOOK_SECRET` matches in both systems
- Check signature calculation method (HMAC-SHA256)
- Ensure request body is JSON stringified correctly
**Issue: Request not found**
- Verify `request_number` matches the original request
- Check if request exists in RE Workflow database
- Ensure request was created before webhook is sent
**Issue: Invoice/Credit Note record not found**
- Verify invoice/credit note was created in RE Workflow
- Check if webhook is sent before record creation
- Review workflow step sequence
---
## 10. Environment Configuration
### 10.1 Environment Variables
Add to RE Workflow System `.env` file:
```env
# DMS Webhook Configuration
DMS_WEBHOOK_SECRET=your_shared_secret_key_here
```
### 10.2 Webhook URLs by Environment
| Environment | Invoice Webhook URL | Credit Note Webhook URL |
|-------------|---------------------|-------------------------|
| Development | `http://localhost:5000/api/v1/webhooks/dms/invoice` | `http://localhost:5000/api/v1/webhooks/dms/credit-note` |
| UAT | `https://reflow-uat.royalenfield.com/api/v1/webhooks/dms/invoice` | `https://reflow-uat.royalenfield.com/api/v1/webhooks/dms/credit-note` |
| Production | `https://reflow.royalenfield.com/api/v1/webhooks/dms/invoice` | `https://reflow.royalenfield.com/api/v1/webhooks/dms/credit-note` |
---
**Document Version:** 1.0
**Last Updated:** December 2024
**Maintained By:** RE Workflow Development Team
Reference in New Issue View Git Blame Copy Permalink