vignesh/documentverification
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
documentverification/CODEPLUS_API_DOCUMENTATION.md
vickytechkey 1ff0bd9f93
All checks were successful
Deploy Beta (NATIVE) / deploy (push) Successful in 29s
Details
feat: add verification models, serializers, views, and core engine tests for multi-vendor document validation
2026-10-15 20:03:19 +05:30

14 KiB
Raw Blame History

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:

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 Verification (Full Details) POST /v4/bank-verify bank_account 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:
curl -X POST http://localhost:8092/api/verify/ \
  -H "Content-Type: application/json" \
  -d '{
    "document_type": "pan",
    "data": {
      "pan": "ABCDE1234F"
    }
  }'
  • Direct Upstream cURL:
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):
{
  "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:
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:
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:
{
  "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:
curl -X POST http://localhost:8092/api/verify/ \
  -H "Content-Type: application/json" \
  -d '{
    "document_type": "pan_advanced",
    "data": {
      "pan": "ABCDE1234F"
    }
  }'
  • Direct Upstream cURL:
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:
{
  "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 Verification (Full Details)

  • Engine Request:
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:
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):
{
  "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:
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:
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:
{
  "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:
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:
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):
{
  "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:
curl -X POST http://localhost:8092/api/verify/ \
  -H "Content-Type: application/json" \
  -d '{
    "document_type": "gstin",
    "data": {
      "gst_number": "27ABCDE1234F1Z5"
    }
  }'
  • Direct Upstream cURL:
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):
{
  "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:

curl -X GET http://localhost:8092/api/transactions/8a7c29e1-2244-48f1-9c6a-4933a1e94b21/
  • Response:
{
  "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"
    }
  ]
}