vignesh/documentverification
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
documentverification/CODEPLUS_API_DOCUMENTATION.md
vickytechkey 0291bd6195
All checks were successful
Deploy Beta (NATIVE) / deploy (push) Successful in 39s
Details
feat: add core verifier engine, serializers, tests, vendor client, and test portal template
2026-10-17 13:34:43 +05:30

619 lines
17 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Codeplus (apihub.services) Document Verification Engine Documentation
This document covers all active verification functions implemented in the **Multi-Vendor Verification Engine** using the **Codeplus** (`apihub.services`) adapter.
---
## 1. Architecture & Failover Waterfall
The verification engine provides seamless waterfall cascading across onboarded vendors:
- Every request is dispatched to the highest-priority active vendor.
- If the vendor encounters an error (e.g. HTTP 5xx, timeout, network failure, or API failure status), the engine logs the failure and automatically cascades to the next vendor.
- **Every attempt, raw vendor response, final normalized data, latency, and client response are permanently recorded in PostgreSQL.**
### Database Storage Architecture
1. **`VerificationTransaction` (`verifier_verificationtransaction`):**
- `reference_id`: Unique UUID generated for each client request.
- `document_type`: Type of document requested (`pan`, `bank_account`, `gstin`, etc.).
- `status`: Final outcome (`SUCCESS`, `FAILED`, `ERROR`).
- `successful_vendor`: Name of the vendor that resolved the verification (e.g. `codeplus`).
- `input_payload`: Masked, audit-safe input data.
- `final_data`: Normalized result payload.
- `response_payload`: Complete response payload returned to the client.
- `attempts_count`: Total number of vendors attempted in the waterfall.
- `total_latency_ms`: Total execution time in milliseconds.
- `created_at` / `updated_at`: Timestamps.
2. **`VendorAttemptLog` (`verifier_vendorattemptlog`):**
- `transaction`: Foreign key to `VerificationTransaction`.
- `attempt_number`: Sequential attempt sequence (`1`, `2`, ...).
- `vendor_name`: Vendor adapter invoked (`codeplus`).
- `status`: Vendor status (`SUCCESS`, `FAILED`, `ERROR`, `SKIPPED`).
- `is_success`: Boolean indicator.
- `data`: Extracted vendor data block.
- `raw_response`: Full unaltered JSON/HTTP response returned by the upstream API.
- `error_code` & `error_message`: Upstream failure codes and diagnostics.
- `latency_ms`: Execution latency for this specific vendor hit.
---
## 2. Global Authentication & Configuration
The Codeplus adapter uses the following headers for all upstream calls:
```http
X-Client-Api-ID: CAPI-YYR0YJIE0VMTDENY
X-Client-Api-Secret: s24Ts9wFsgl64mFzA61OqG0RDLRs2HFCpmOZBmqs
Content-Type: application/json
```
Environment variables configured in `docverify/settings.py` / `.env`:
- `CODEPLUS_BASE_URL`: `https://apihub.services`
- `CODEPLUS_CLIENT_API_ID`: `CAPI-YYR0YJIE0VMTDENY`
- `CODEPLUS_CLIENT_API_SECRET`: `s24Ts9wFsgl64mFzA61OqG0RDLRs2HFCpmOZBmqs`
---
## 3. Summary of Available Functions
| Function Name | Upstream Endpoint | Internal `document_type` | Description |
| :--- | :--- | :--- | :--- |
| **Pan Verification (v5 Recommended)** | `POST /v5/pan-verify` | `pan`, `pan_v5`, `pan_verify` | Full PAN holder details with name, DOB, gender, masked Aadhaar & address. |
| **Detailed PAN API** | `POST /v4/pan-detailed` | `pan_detailed` | Comprehensive PAN data including address, contact info, and profile. |
| **PAN Advanced API** | `POST /v4/pan-advanced` | `pan_advanced` | Standard government database verification for PAN validity and taxpayer status. |
| **Bank Verify (Penny Drop - v5)** | `POST /v5/bank-verify-pd` | `bank_verify_pd`, `bank_verify_v5`, `bank_account` | Verifies bank account using account number and IFSC via Penny Drop; returns validity and account holder name. |
| **Bank Verification (Full Details - v4)** | `POST /v4/bank-verify` | `bank_account` (with `mode: 'v4'`) | Penny drop routing for account holder name, MICR, IFSC, and branch details. |
| **Fetch GST By PAN** | `POST /v4/fetch-gst` | `gst_by_pan`, `fetch_gst` | Retrieves all registered GSTIN entities associated with a business PAN. |
| **Fetch MSME By PAN** | `POST /v4/msme-pan` | `msme`, `msme_by_pan`, `udyam` | Retrieves Udyam registration number and enterprise details linked to a PAN. |
| **GST Verification (v5)** | `POST /v5/gst-verify` | `gstin`, `gst`, `gst_verify` | Verifies single GSTIN and returns legal business name and active status. |
---
## 4. API Reference & Sample Requests
### Function 1: Pan Verification (v5 Recommended)
- **Engine Request:**
```bash
curl -X POST http://localhost:8092/api/verify/ \
-H "Content-Type: application/json" \
-d '{
"document_type": "pan",
"data": {
"pan": "ABCDE1234F"
}
}'
```
- **Direct Upstream cURL:**
```bash
curl --location 'https://apihub.services/v5/pan-verify' \
--header 'X-Client-Api-ID: CAPI-YYR0YJIE0VMTDENY' \
--header 'X-Client-Api-Secret: s24Ts9wFsgl64mFzA61OqG0RDLRs2HFCpmOZBmqs' \
--header 'Content-Type: application/json' \
--data '{"pan": "ABCDE1234F"}'
```
- **Sample Engine Response (HTTP 200):**
```json
{
"reference_id": "8a7c29e1-2244-48f1-9c6a-4933a1e94b21",
"is_success": true,
"status": "SUCCESS",
"document_type": "pan",
"successful_vendor": "codeplus",
"data": {
"document_type": "PAN",
"pan": "ABCDE1234F",
"pan_type": "Individual",
"full_name": "RAHUL KUMAR",
"first_name": "RAHUL",
"middle_name": null,
"last_name": "KUMAR",
"gender": "male",
"dob": "15/06/1995",
"aadhaar_number": "XXXXXXXX1234",
"aadhaar_linked": true,
"address_details": {
"building_name": "12/45",
"locality": "Central Area",
"street_name": "MG Road",
"pincode": "641001",
"city": "COIMBATORE",
"state": "Tamil Nadu",
"country": "India"
},
"service": "PAN_VERIFICATION",
"result_code": 101,
"client_ref_num": "REQ_1787136465034_demo12345",
"provider_transaction_id": "TXN_1787136465045_demo12345",
"transaction_id": "TXN_1787136465045_demo12345",
"request_id": "REQ_1787136465034_demo12345",
"timestamp": "2026-08-19T10:47:45.735Z"
},
"attempts_count": 1,
"attempts": [
{
"attempt_number": 1,
"vendor_name": "codeplus",
"is_success": true,
"status": "SUCCESS",
"latency_ms": 310.2
}
],
"error_message": null,
"total_latency_ms": 315.4
}
```
---
### Function 2: Detailed PAN API
- **Engine Request:**
```bash
curl -X POST http://localhost:8092/api/verify/ \
-H "Content-Type: application/json" \
-d '{
"document_type": "pan_detailed",
"data": {
"pan_number": "ABCDE1234F"
}
}'
```
- **Direct Upstream cURL:**
```bash
curl --location 'https://apihub.services/v4/pan-detailed' \
--header 'X-Client-Api-ID: CAPI-YYR0YJIE0VMTDENY' \
--header 'X-Client-Api-Secret: s24Ts9wFsgl64mFzA61OqG0RDLRs2HFCpmOZBmqs' \
--header 'Content-Type: application/json' \
--data '{"pan_number": "ABCDE1234F"}'
```
- **Sample Upstream Response:**
```json
{
"request_id": "7f3a1c92-5b84-4d21-a7e6-91c2f0d84b56",
"transaction_id": "b6e8d4a1-2c73-49f5-9a10-5f7c3e821d64",
"status": 200,
"data": {
"code": "1000",
"message": "Valid PAN.",
"pan_data": {
"document_type": "PAN",
"document_id": "ABCDE1234F",
"name": "RAHUL KUMAR",
"first_name": "RAHUL",
"last_name": "KUMAR",
"category": "P",
"date_of_birth": "1995-06-15",
"masked_aadhaar_number": "XXXXXXXX1234",
"address_data": {
"line_1": "12/45",
"line_2": "MG Road",
"street": "Central Area",
"city": "COIMBATORE",
"state": "TAMIL NADU",
"pincode": "641001"
},
"email": "ra******@example.com",
"phone": "98XXXXXX10",
"gender": "MALE",
"aadhaar_linked": true,
"taxpayer_profile": true
}
}
}
```
---
### Function 3: PAN Advanced API
- **Engine Request:**
```bash
curl -X POST http://localhost:8092/api/verify/ \
-H "Content-Type: application/json" \
-d '{
"document_type": "pan_advanced",
"data": {
"pan": "ABCDE1234F"
}
}'
```
- **Direct Upstream cURL:**
```bash
curl --location 'https://apihub.services/v4/pan-advanced' \
--header 'X-Client-Api-ID: CAPI-YYR0YJIE0VMTDENY' \
--header 'X-Client-Api-Secret: s24Ts9wFsgl64mFzA61OqG0RDLRs2HFCpmOZBmqs' \
--header 'Content-Type: application/json' \
--data '{"pan": "ABCDE1234F"}'
```
- **Sample Upstream Response:**
```json
{
"request_id": "8a42f1c7-63d9-4e15-b820-7c91a5d34628",
"transaction_id": "d5b73e91-2a46-4c08-9f61-83e2b7a51439",
"status": 200,
"data": {
"code": "1000",
"message": "Valid PAN.",
"pan_data": {
"document_type": "PAN",
"document_id": "ABCDE1234F",
"name": "RAHUL KUMAR",
"first_name": "RAHUL",
"last_name": "KUMAR",
"category": "P",
"category_type": "Individual",
"is_individual": true,
"individual_tax_compliance_status": "Operative",
"aadhaar_linked": true
}
}
}
```
---
### Function 4: Bank Verify (Penny Drop - v5 Recommended)
The Bank Account Verification – PD API verifies a bank account using the account number and IFSC code via automated penny drop routing. It checks whether the account is valid and active, and returns the account holder name and verified bank account details.
- **Engine Request:**
```bash
curl -X POST http://localhost:8092/api/verify/ \
-H "Content-Type: application/json" \
-d '{
"document_type": "bank_verify_pd",
"data": {
"account_number": "123456787270",
"ifsc": "UTIB0000373"
}
}'
```
*(Note: You can also use `document_type: "bank_account"`, which automatically defaults to v5 Penny Drop with fallback to v4).*
- **Direct Upstream cURL:**
```bash
curl --location 'https://apihub.services/v5/bank-verify-pd' \
--header 'X-Client-Api-ID: CAPI-YYR0YJIE0VMTDENY' \
--header 'X-Client-Api-Secret: your_client_api_secret' \
--header 'Content-Type: application/json' \
--data '{
"account_number": "123456787270",
"ifsc": "UTIB0000373"
}'
```
- **Client Input Parameters:**
| Parameter | Type | Description |
| :--- | :--- | :--- |
| `account_number` | String | Bank account number to be verified. |
| `ifsc` | String | 11-character IFSC code of the bank branch. |
- **Upstream Success Response (HTTP 200):**
```json
{
"status": "success",
"result": {
"failure_reason": null,
"account_number": "********7270",
"user": null,
"is_valid": true,
"account_holder_name": "MANOJ PRASAD",
"account_ifsc": "UTIB0000373",
"npci_error_code": null
},
"tranx_id": "9eeb9d58-04f8-4f8b-9608-99731850993f",
"timestamp": "2026-05-22T05:10:43.561554+00:00",
"chargeble": "true",
"user_consent": "true"
}
```
- **Engine Unified Response (HTTP 200):**
```json
{
"reference_id": "9eeb9d58-04f8-4f8b-9608-99731850993f",
"is_success": true,
"status": "SUCCESS",
"document_type": "bank_verify_pd",
"successful_vendor": "codeplus",
"data": {
"document_type": "BANK_ACCOUNT",
"verification_mode": "penny_drop_v5",
"account_number": "123456787270",
"masked_account_number": "********7270",
"ifsc": "UTIB0000373",
"account_ifsc": "UTIB0000373",
"beneficiary_name": "MANOJ PRASAD",
"account_holder_name": "MANOJ PRASAD",
"is_valid": true,
"account_exists": true,
"failure_reason": null,
"npci_error_code": null,
"tranx_id": "9eeb9d58-04f8-4f8b-9608-99731850993f",
"timestamp": "2026-05-22T05:10:43.561554+00:00",
"chargeble": "true",
"user_consent": "true"
},
"attempts_count": 1,
"attempts": [
{
"attempt_number": 1,
"vendor_name": "codeplus",
"is_success": true,
"status": "SUCCESS",
"latency_ms": 380.2
}
]
}
```
---
### Function 4B: Bank Verification (Full Details - v4 Legacy)
```bash
curl -X POST http://localhost:8092/api/verify/ \
-H "Content-Type: application/json" \
-d '{
"document_type": "bank_account",
"data": {
"account_number": "123456789012",
"ifsc": "HDFC0001234"
}
}'
```
- **Direct Upstream cURL:**
```bash
curl --location 'https://apihub.services/v4/bank-verify' \
--header 'X-Client-Api-ID: CAPI-YYR0YJIE0VMTDENY' \
--header 'X-Client-Api-Secret: s24Ts9wFsgl64mFzA61OqG0RDLRs2HFCpmOZBmqs' \
--header 'Content-Type: application/json' \
--data '{
"account_number": "123456789012",
"ifsc": "HDFC0001234"
}'
```
- **Sample Engine Response (HTTP 200):**
```json
{
"reference_id": "4b5d21a9-9941-4198-89c0-e74bf1a998bc",
"is_success": true,
"status": "SUCCESS",
"document_type": "bank_account",
"successful_vendor": "codeplus",
"data": {
"document_type": "BANK_ACCOUNT",
"account_number": "123456789012",
"ifsc": "HDFC0001234",
"beneficiary_name": "PRIYA SHARMA",
"micr": "641240002",
"bank_name": "HDFC BANK",
"branch": "MAIN BRANCH",
"city": "COIMBATORE",
"state": "TAMIL NADU",
"pincode": "641001",
"account_exists": true
},
"attempts_count": 1,
"attempts": [
{
"attempt_number": 1,
"vendor_name": "codeplus",
"is_success": true,
"status": "SUCCESS",
"latency_ms": 420.5
}
]
}
```
---
### Function 5: Fetch GST By PAN
- **Engine Request:**
```bash
curl -X POST http://localhost:8092/api/verify/ \
-H "Content-Type: application/json" \
-d '{
"document_type": "gst_by_pan",
"data": {
"pan": "ABCDE1234F"
}
}'
```
- **Direct Upstream cURL:**
```bash
curl --location 'https://apihub.services/v4/fetch-gst' \
--header 'X-Client-Api-ID: CAPI-YYR0YJIE0VMTDENY' \
--header 'X-Client-Api-Secret: s24Ts9wFsgl64mFzA61OqG0RDLRs2HFCpmOZBmqs' \
--header 'Content-Type: application/json' \
--data '{"pan": "ABCDE1234F"}'
```
- **Sample Upstream Response:**
```json
{
"request_id": "b27c9087-f061-4d38-b7aa-96498f8e667e",
"status": 200,
"data": {
"code": "1002",
"message": "Found 3 records",
"results": [
{
"document_type": "GSTIN",
"document_id": "20AXXXXXXXXXXX",
"status": "Active",
"state": "Jharkhand",
"state_code": "20"
},
{
"document_type": "GSTIN",
"document_id": "27AXXXXXXXXXXX",
"status": "Active",
"state": "Maharashtra",
"state_code": "27"
},
{
"document_type": "GSTIN",
"document_id": "29AXXXXXXXXXXX",
"status": "Active",
"state": "Karnataka",
"state_code": "29"
}
]
}
}
```
---
### Function 6: Fetch MSME By PAN
- **Engine Request:**
```bash
curl -X POST http://localhost:8092/api/verify/ \
-H "Content-Type: application/json" \
-d '{
"document_type": "msme",
"data": {
"pan": "ABCDE1234F",
"detailed_response": true
}
}'
```
- **Direct Upstream cURL:**
```bash
curl --location 'https://apihub.services/v4/msme-pan' \
--header 'X-Client-Api-ID: CAPI-YYR0YJIE0VMTDENY' \
--header 'X-Client-Api-Secret: s24Ts9wFsgl64mFzA61OqG0RDLRs2HFCpmOZBmqs' \
--header 'Content-Type: application/json' \
--data '{"pan": "ABCDE1234F", "detailed_response": true}'
```
- **Sample Engine Response (No Record Found):**
```json
{
"reference_id": "c19b38fa-0123-4567-89ab-cdef01234567",
"is_success": true,
"status": "SUCCESS",
"document_type": "msme",
"successful_vendor": "codeplus",
"data": {
"document_type": "MSME",
"pan": "ABCDE1234F",
"has_msme": false,
"code": "1011",
"message": "No record found.",
"udyam_data": {
"code": "1011",
"message": "No record found."
}
}
}
```
---
### Function 7: GST Verification (v5)
- **Engine Request:**
```bash
curl -X POST http://localhost:8092/api/verify/ \
-H "Content-Type: application/json" \
-d '{
"document_type": "gstin",
"data": {
"gst_number": "27ABCDE1234F1Z5"
}
}'
```
- **Direct Upstream cURL:**
```bash
curl --location 'https://apihub.services/v5/gst-verify' \
--header 'X-Client-Api-ID: CAPI-YYR0YJIE0VMTDENY' \
--header 'X-Client-Api-Secret: s24Ts9wFsgl64mFzA61OqG0RDLRs2HFCpmOZBmqs' \
--header 'Content-Type: application/json' \
--data '{"gst_number": "27ABCDE1234F1Z5"}'
```
- **Sample Engine Response (HTTP 200):**
```json
{
"reference_id": "5f6e7d8c-9b0a-1122-3344-556677889900",
"is_success": true,
"status": "SUCCESS",
"document_type": "gstin",
"successful_vendor": "codeplus",
"data": {
"document_type": "GSTIN",
"gst_number": "27ABCDE1234F1Z5",
"legal_name": "ABCDE PRIVATE LIMITED",
"registration_status": "ACTIVE",
"service": "GST_VERIFICATION",
"message": "GST verification completed"
},
"attempts_count": 1,
"attempts": [
{
"attempt_number": 1,
"vendor_name": "codeplus",
"is_success": true,
"status": "SUCCESS",
"latency_ms": 285.6
}
]
}
```
---
## 5. Transaction Audit API
Retrieve the complete historical audit log, raw responses, and latency for any transaction:
- **Endpoint:** `GET /api/transactions/<uuid:reference_id>/`
- **cURL:**
```bash
curl -X GET http://localhost:8092/api/transactions/8a7c29e1-2244-48f1-9c6a-4933a1e94b21/
```
- **Response:**
```json
{
"reference_id": "8a7c29e1-2244-48f1-9c6a-4933a1e94b21",
"document_type": "pan",
"status": "SUCCESS",
"successful_vendor": "codeplus",
"final_data": { ... },
"response_payload": { ... },
"attempts_count": 1,
"total_latency_ms": 315.4,
"created_at": "2026-10-15T19:58:00Z",
"attempts": [
{
"attempt_number": 1,
"vendor_name": "codeplus",
"status": "SUCCESS",
"is_success": true,
"error_code": null,
"error_message": null,
"latency_ms": 310.2,
"created_at": "2026-10-15T19:58:00Z"
}
]
}
```
Reference in a new issue View git blame Copy permalink