s.hajizadeh/esg

Fork 0

forked from Shared/esg

Files

s.hajizadeh 0aad5a34d2 parsian inquiries implemented

2026-06-13 12:59:15 +03:30

14 KiB

Raw Blame History

Environment Configuration Guide

This guide explains all environment variables used in the ESG Inquiry Gateway system.

Application Settings
Database Configuration
Authentication & Security
Provider Configuration
Inquiry Routing
Provider Behavior Examples

Application Settings

Basic Configuration

PORT=8085                    # HTTP server port
NODE_ENV=development         # Environment: development, production, test

OpenTelemetry (Optional)

OTEL_EXPORTER_OTLP_ENDPOINT=http://192.168.10.10:4318
OTEL_SERVICE_NAME=esg
OTEL_NODE_RESOURCE_DETECTORS=env,host,os

Database Configuration

MongoDB

MONGODB_URI=mongodb://localhost:27017/inquiry-gateway

Authentication & Security

API Authentication

API_KEY=your-secure-api-key-here              # API key for external clients
JWT_SECRET=change-me-use-long-random-string   # JWT signing secret
JWT_REFRESH_SECRET=change-me-refresh-secret   # JWT refresh token secret
JWT_ACCESS_EXPIRES_IN=15m                     # Access token lifetime
JWT_REFRESH_EXPIRES_IN=7d                     # Refresh token lifetime
JWT_ENABLED=true                              # Enable/disable JWT auth
BCRYPT_SALT_ROUNDS=12                         # Password hashing rounds

Rate Limiting

THROTTLE_TTL=60      # Time window in seconds
THROTTLE_LIMIT=100   # Max requests per window

Provider Configuration

Understanding Provider Architecture

The system has two types of components:

Providers (Inquiry Handlers): HAMTA, MOALLEM, TEJARATNOU
Authentication Services: AMITIS (used by HAMTA and MOALLEM)

AMITIS Authentication Service

AMITIS is not a provider - it's an authentication service that provides tokens for HAMTA and MOALLEM.

# AMITIS Configuration
AMITIS_BASE_URL=https://auth.services.centinsur.ir
AMITIS_LOGIN_PATH=/api/security/login
AMITIS_REFRESH_PATH=/api/security/RefreshToken
AMITIS_TOKEN_TIME_ZONE=Asia/Tehran
AMITIS_TIMEOUT=10000
AMITIS_ENABLED=true

Token Management:

Tokens refresh every 20 minutes
Tokens expire daily at 23:59:59 (Tehran time)
Automatic refresh with fallback to re-login

Provider Structure

Each provider has:

Global settings: ENABLED, TIMEOUT, MAX_RETRIES
Per-inquiry settings: URL, USERNAME, PASSWORD, AUTH_METHOD

Format: `PROVIDER_INQUIRY_FIELD`

Example:

HAMTA_REAL_ESTATE_URL=https://apigw.services.centinsur.ir/amlakeskanservice/amlakeskan/inquiry
HAMTA_REAL_ESTATE_USERNAME=AmlakEskanHamta
HAMTA_REAL_ESTATE_PASSWORD=r#Tk5!4bj
HAMTA_REAL_ESTATE_AUTH_METHOD=AMITIS

Authentication Methods

Each inquiry can use different authentication:

AMITIS: Token-based auth via AMITIS service
SOAP: Direct SOAP authentication (credentials in XML)
OAUTH2: OAuth2 flow (TejaratNou)
NONE: No authentication required

HAMTA Provider

# Global Settings
HAMTA_ENABLED=true
HAMTA_TIMEOUT=10000
HAMTA_MAX_RETRIES=3

# Person Inquiry (AMITIS auth)
HAMTA_PERSON_URL=https://api.hamta.example.com/api/inquiry/person
HAMTA_PERSON_USERNAME=pa6476
HAMTA_PERSON_PASSWORD=ciiws@sabt92
HAMTA_PERSON_AUTH_METHOD=AMITIS

# Real Estate Inquiry (AMITIS auth)
HAMTA_REAL_ESTATE_URL=https://apigw.services.centinsur.ir/amlakeskanservice/amlakeskan/inquiry
HAMTA_REAL_ESTATE_USERNAME=AmlakEskanHamta
HAMTA_REAL_ESTATE_PASSWORD=r#Tk5!4bj
HAMTA_REAL_ESTATE_AUTH_METHOD=AMITIS

# Shahkar Inquiry (SOAP auth - no AMITIS)
HAMTA_SHAHKAR_URL=http://reinsure.centinsur.ir/shahkarinqOut
HAMTA_SHAHKAR_USERNAME=Hamta.Shahkar
HAMTA_SHAHKAR_PASSWORD=Y^WzP!8R5Tz
HAMTA_SHAHKAR_AUTH_METHOD=SOAP

# Sheba/Sayah Inquiry (AMITIS auth)
HAMTA_SHEBA_URL=https://api.hamta.example.com/api/inquiry/sheba
HAMTA_SHEBA_USERNAME=Hamta.sayah
HAMTA_SHEBA_PASSWORD=J$z07$bg
HAMTA_SHEBA_AUTH_METHOD=AMITIS

# Postal Code Inquiry (AMITIS auth)
HAMTA_POSTAL_CODE_URL=https://api.hamta.example.com/api/inquiry/postalCode
HAMTA_POSTAL_CODE_USERNAME=
HAMTA_POSTAL_CODE_PASSWORD=
HAMTA_POSTAL_CODE_AUTH_METHOD=AMITIS

# Legal Person Inquiry (AMITIS auth)
HAMTA_LEGAL_PERSON_URL=https://api.hamta.example.com/api/inquiry/legalPerson
HAMTA_LEGAL_PERSON_USERNAME=SabtAsnadHamta
HAMTA_LEGAL_PERSON_PASSWORD=HSY1f6?e@kSJ
HAMTA_LEGAL_PERSON_AUTH_METHOD=AMITIS

MOALLEM Provider

# Global Settings
MOALLEM_ENABLED=true
MOALLEM_TIMEOUT=10000
MOALLEM_MAX_RETRIES=2

# Person Inquiry (SOAP auth)
MOALLEM_PERSON_URL=http://reinsure.centinsur.ir/SabtV3Out
MOALLEM_PERSON_USERNAME=mo9635
MOALLEM_PERSON_PASSWORD=ciiws@sabt92
MOALLEM_PERSON_AUTH_METHOD=SOAP

# Postal Code Inquiry (AMITIS auth)
MOALLEM_POSTAL_CODE_URL=https://postalcode.services.centinsur.ir/api/cisb
MOALLEM_POSTAL_CODE_USERNAME=moallem.post
MOALLEM_POSTAL_CODE_PASSWORD=tBUCLGfVJH
MOALLEM_POSTAL_CODE_AUTH_METHOD=AMITIS

# Real Estate Inquiry (AMITIS auth)
MOALLEM_REAL_ESTATE_URL=https://api.moallem.example.com/api/inquiry/realEstate
MOALLEM_REAL_ESTATE_USERNAME=AmlakEskanMoalem
MOALLEM_REAL_ESTATE_PASSWORD=AEM@123456
MOALLEM_REAL_ESTATE_AUTH_METHOD=AMITIS

# Shahkar Inquiry (SOAP auth)
MOALLEM_SHAHKAR_URL=http://reinsure.centinsur.ir/shahkarinqOut
MOALLEM_SHAHKAR_USERNAME=ShkrMoalem1286
MOALLEM_SHAHKAR_PASSWORD=cuYYELt9
MOALLEM_SHAHKAR_AUTH_METHOD=SOAP

# Sheba/Sayah Inquiry (AMITIS auth)
MOALLEM_SHEBA_URL=https://sayah.services.centinsur.ir/api/Cisb/TatbighServiceAsync
MOALLEM_SHEBA_USERNAME=moallem.sayah
MOALLEM_SHEBA_PASSWORD=BUCLGfVJH7
MOALLEM_SHEBA_AUTH_METHOD=AMITIS

# Legal Person Inquiry (SOAP auth)
MOALLEM_LEGAL_PERSON_URL=http://reinsure.centinsur.ir/SabtV3Out
MOALLEM_LEGAL_PERSON_USERNAME=
MOALLEM_LEGAL_PERSON_PASSWORD=
MOALLEM_LEGAL_PERSON_AUTH_METHOD=SOAP

PARSIAN Provider

# Global Settings
PARSIAN_ENABLED=true
PARSIAN_TIMEOUT=10000
PARSIAN_MAX_RETRIES=2

# Shahkar Inquiry (X-PACKAGE-API-KEY header)
PARSIAN_SHAHKAR_URL=https://apigateway.parsianinsurance.com/shahkarinqOut
PARSIAN_SHAHKAR_API_KEY=your-package-api-key
PARSIAN_SHAHKAR_AUTH_METHOD=NONE

# Sheba/Sayah Inquiry (AMITIS auth)
PARSIAN_SHEBA_URL=https://sayah.services.centinsur.ir/api/Cisb/TatbighServiceAsync
PARSIAN_SHEBA_USERNAME=parsian.sayah
PARSIAN_SHEBA_PASSWORD=your-password
PARSIAN_SHEBA_AUTH_METHOD=AMITIS

# Car policy inquiry by chassis (SOAP auth)
PARSIAN_POLICY_BY_CHASSIS_URL=http://reinsure.centinsur.ir/CarAllPlcysV4
PARSIAN_POLICY_BY_CHASSIS_USERNAME=pa6476
PARSIAN_POLICY_BY_CHASSIS_PASSWORD=your-password
PARSIAN_POLICY_BY_CHASSIS_AUTH_METHOD=SOAP

# Car policy inquiry by national plate (SOAP auth)
PARSIAN_POLICY_BY_PLATE_URL=http://reinsure.centinsur.ir/CarAllPlcysV4
PARSIAN_POLICY_BY_PLATE_USERNAME=pa6476
PARSIAN_POLICY_BY_PLATE_PASSWORD=your-password
PARSIAN_POLICY_BY_PLATE_AUTH_METHOD=SOAP

# Car policy inquiry by national code (SOAP auth)
PARSIAN_POLICY_BY_NATIONAL_CODE_URL=http://reinsure.centinsur.ir/CarAllPlcysV4
PARSIAN_POLICY_BY_NATIONAL_CODE_USERNAME=pa6476
PARSIAN_POLICY_BY_NATIONAL_CODE_PASSWORD=your-password
PARSIAN_POLICY_BY_NATIONAL_CODE_AUTH_METHOD=SOAP

TEJARATNOU Provider

# Global Settings
TEJARATNOU_ENABLED=true
TEJARATNOU_TIMEOUT=15000
TEJARATNOU_MAX_RETRIES=2

# OAuth2 Authentication
TEJARATNOU_AUTH_URL=https://accounts.tejaratnoins.ir
TEJARATNOU_CLIENT_ID=api-gateway
TEJARATNOU_CLIENT_SECRET=hkld@ork123T
TEJARATNOU_USERNAME=thirdparty-silcogroup
TEJARATNOU_PASSWORD=FDHG87sdf787l764iuo

# Person Inquiry
TEJARATNOU_PERSON_URL=https://gateway.tejaratnoins.ir/api/inquiry/person
TEJARATNOU_PERSON_AUTH_METHOD=OAUTH2

Inquiry Routing

Routing determines which provider handles each inquiry type and whether to use fallbacks.

Format

{INQUIRY_TYPE}_DEFAULT_PROVIDER=PROVIDER_NAME
{INQUIRY_TYPE}_FALLBACK_ENABLED=true|false
{INQUIRY_TYPE}_FALLBACK_PROVIDERS=PROVIDER1,PROVIDER2

Available Inquiry Types

PERSON - Person/Civil registration inquiry
REAL_ESTATE - Real estate/property inquiry
SHAHKAR - Mobile number verification
POSTAL_CODE - Postal code lookup
SHEBA - Bank account verification
LEGAL_PERSON - Legal entity inquiry
CAR_PLATE - Vehicle plate inquiry

Example Configurations

Person Inquiry (Single Provider)

PERSON_DEFAULT_PROVIDER=TEJARATNOU
PERSON_FALLBACK_ENABLED=false
PERSON_FALLBACK_PROVIDERS=

Behavior: Only TEJARATNOU is used. If it fails, request fails.

Person Inquiry (With Fallback)

PERSON_DEFAULT_PROVIDER=TEJARATNOU
PERSON_FALLBACK_ENABLED=true
PERSON_FALLBACK_PROVIDERS=HAMTA,MOALLEM

Behavior:

Try TEJARATNOU first
If fails, try HAMTA
If fails, try MOALLEM
If all fail, return error

Real Estate Inquiry

REAL_ESTATE_DEFAULT_PROVIDER=HAMTA
REAL_ESTATE_FALLBACK_ENABLED=false
REAL_ESTATE_FALLBACK_PROVIDERS=

Shahkar Inquiry

SHAHKAR_DEFAULT_PROVIDER=PARSIAN
SHAHKAR_FALLBACK_ENABLED=false
SHAHKAR_FALLBACK_PROVIDERS=

Sheba/Sayah Inquiry

SHEBA_DEFAULT_PROVIDER=PARSIAN
SHEBA_FALLBACK_ENABLED=false
SHEBA_FALLBACK_PROVIDERS=

Provider Behavior Examples

Scenario 1: All Providers Enabled

HAMTA_ENABLED=true
MOALLEM_ENABLED=true
TEJARATNOU_ENABLED=true

PERSON_DEFAULT_PROVIDER=TEJARATNOU
PERSON_FALLBACK_ENABLED=false

Result: Only TEJARATNOU is used for person inquiries, even though others are enabled.

Scenario 2: Default Provider Disabled

HAMTA_ENABLED=false
MOALLEM_ENABLED=true
TEJARATNOU_ENABLED=true

PERSON_DEFAULT_PROVIDER=HAMTA
PERSON_FALLBACK_ENABLED=true
PERSON_FALLBACK_PROVIDERS=TEJARATNOU,MOALLEM

Result:

HAMTA is skipped (disabled)
TEJARATNOU is tried first (first enabled fallback)
MOALLEM is tried if TEJARATNOU fails

Scenario 3: No Providers Available

HAMTA_ENABLED=false
MOALLEM_ENABLED=false
TEJARATNOU_ENABLED=false

PERSON_DEFAULT_PROVIDER=TEJARATNOU

Result: API returns error:

{
  "success": false,
  "provider": "GATEWAY",
  "message": "No enabled providers configured for PERSON",
  "error": {
    "code": "NO_PROVIDERS",
    "message": "No enabled providers configured for PERSON"
  }
}

Scenario 4: All Providers Fail

HAMTA_ENABLED=true
MOALLEM_ENABLED=true
TEJARATNOU_ENABLED=true

PERSON_DEFAULT_PROVIDER=TEJARATNOU
PERSON_FALLBACK_ENABLED=true
PERSON_FALLBACK_PROVIDERS=HAMTA,MOALLEM

Result: If all three providers fail, API returns:

{
  "success": false,
  "provider": "GATEWAY",
  "message": "TEJARATNOU failed: timeout; HAMTA failed: auth error; MOALLEM failed: network error",
  "error": {
    "code": "ALL_PROVIDERS_FAILED",
    "message": "Combined error messages from all providers"
  }
}

Production Recommendations

High Availability Setup

# Enable all providers
HAMTA_ENABLED=true
MOALLEM_ENABLED=true
TEJARATNOU_ENABLED=true

# Use fallbacks for critical inquiries
PERSON_DEFAULT_PROVIDER=TEJARATNOU
PERSON_FALLBACK_ENABLED=true
PERSON_FALLBACK_PROVIDERS=HAMTA,MOALLEM

REAL_ESTATE_DEFAULT_PROVIDER=HAMTA
REAL_ESTATE_FALLBACK_ENABLED=true
REAL_ESTATE_FALLBACK_PROVIDERS=MOALLEM

Performance-Optimized Setup

# Enable only primary providers
HAMTA_ENABLED=true
MOALLEM_ENABLED=false
TEJARATNOU_ENABLED=true

# No fallbacks for faster response
PERSON_DEFAULT_PROVIDER=TEJARATNOU
PERSON_FALLBACK_ENABLED=false

REAL_ESTATE_DEFAULT_PROVIDER=HAMTA
REAL_ESTATE_FALLBACK_ENABLED=false

Cost-Optimized Setup

# Enable only necessary providers
HAMTA_ENABLED=true
MOALLEM_ENABLED=false
TEJARATNOU_ENABLED=false

# Single provider per inquiry type
PERSON_DEFAULT_PROVIDER=HAMTA
PERSON_FALLBACK_ENABLED=false

REAL_ESTATE_DEFAULT_PROVIDER=HAMTA
REAL_ESTATE_FALLBACK_ENABLED=false

Security Best Practices

Never commit .env to git - Use .env.example as template
Rotate credentials regularly - Update passwords every 90 days
Use strong secrets - Generate random strings for JWT secrets
Limit API key distribution - One key per client application
Enable rate limiting - Protect against abuse
Monitor failed authentications - Alert on repeated failures
Use HTTPS in production - Never send credentials over HTTP

Troubleshooting

Provider Not Working

Check if provider is enabled: {PROVIDER}_ENABLED=true
Verify credentials are correct
Check if inquiry type is configured for that provider
Verify network connectivity to provider URL
Check logs for authentication errors

No Providers Available Error

Verify at least one provider is enabled
Check {INQUIRY}_DEFAULT_PROVIDER is set correctly
Ensure the default provider supports the inquiry type
Verify provider credentials are configured

Authentication Failures

Check AMITIS service is enabled and reachable
Verify credentials in {PROVIDER}_{INQUIRY}_USERNAME/PASSWORD
Check if tokens are expiring (should auto-refresh)
Verify system time is correct (affects token expiration)

Performance Issues

Reduce MAX_RETRIES for faster failures
Decrease TIMEOUT values
Disable fallbacks if not needed
Enable only required providers
Check network latency to provider services

Migration from Old Format

Old Format (Deprecated)

AMITIS_HAMTA_PERSON_USERNAME=pa6476
AMITIS_HAMTA_PERSON_PASSWORD=ciiws@sabt92

New Format (Current)

HAMTA_PERSON_USERNAME=pa6476
HAMTA_PERSON_PASSWORD=ciiws@sabt92
HAMTA_PERSON_AUTH_METHOD=AMITIS

Key Changes:

Removed AMITIS_ prefix from provider credentials
Added AUTH_METHOD to specify authentication type
Added per-inquiry URL configuration
AMITIS is now a separate authentication service, not a provider

14 KiB Raw Blame History