s.hajizadeh/esg
1
0
Fork 0
forked from Shared/esg
Code Pull Requests Activity
Files
8af8c8d6df6cbeaafeb504fb4b8cbfbcbf38db72
esg/docs/API_DOCUMENTATION.md

15 KiB
Raw Blame History

API Documentation

Complete API reference for the ESG Inquiry Gateway with request/response examples.

Table of Contents

Base URL

Production: https://api.example.com
Development: http://localhost:8085

Authentication

All API requests require authentication using one of these methods:

1. API Key (Header)

X-API-Key: your-api-key-here

2. JWT Bearer Token

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Person Inquiry

Query person information using national code and birth date.

Endpoint

POST /api/inquiry/person

Request Headers

Content-Type: application/json
X-API-Key: your-api-key-here

Request Body

{
  "nationalCode": "0123456789",
  "birthDate": "1370/01/01"
}

Request Parameters

Field Type Required Description Example
nationalCode string Yes 10-digit national identification number "0123456789"
birthDate string Yes Birth date in Persian calendar (YYYY/MM/DD) "1370/01/01"

Success Response (200 OK)

{
  "success": true,
  "provider": "TEJARATNOU",
  "trackingCode": "a3e23be5-3128-4bb6-9424-9b62b41d6381",
  "message": "Person inquiry completed successfully",
  "data": {
    "nationalCode": "0123456789",
    "birthDate": "1370/01/01",
    "fullName": "علی احمدی",
    "raw": {
      "success": true,
      "data": {
        "fullName": "علی احمدی",
        "fatherName": "محمد",
        "birthPlace": "تهران"
      }
    }
  },
  "duration": 1250
}

Response Fields

Field Type Description
success boolean Whether the inquiry was successful
provider string Provider that handled the request (HAMTA, MOALLEM, TEJARATNOU)
trackingCode string Unique tracking code for this request
message string Human-readable status message
data object Inquiry result data
data.nationalCode string Queried national code
data.birthDate string Queried birth date
data.fullName string Person's full name (if found)
data.raw object Raw response from provider
duration number Request duration in milliseconds

cURL Example

curl -X POST https://api.example.com/api/inquiry/person \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key-here" \
  -d '{
    "nationalCode": "0123456789",
    "birthDate": "1370/01/01"
  }'

Swagger/OpenAPI Definition

/api/inquiry/person:
  post:
    summary: Person Inquiry
    description: Query person information using national code and birth date
    tags:
      - Inquiry
    security:
      - ApiKeyAuth: []
      - BearerAuth: []
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            required:
              - nationalCode
              - birthDate
            properties:
              nationalCode:
                type: string
                pattern: '^\d{10}$'
                description: 10-digit national identification number
                example: "0123456789"
              birthDate:
                type: string
                pattern: '^\d{4}/\d{2}/\d{2}$'
                description: Birth date in Persian calendar (YYYY/MM/DD)
                example: "1370/01/01"
    responses:
      '200':
        description: Successful inquiry
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PersonInquiryResponse'
      '400':
        description: Invalid request
      '401':
        description: Unauthorized
      '500':
        description: Server error

Real Estate Inquiry

Query real estate/property information.

Endpoint

POST /api/inquiry/real-estate

Request Body

{
  "nationalId": "5098961130",
  "postalCode": "1349689554"
}

Request Parameters

Field Type Required Description
nationalId string Yes National identification number
postalCode string Yes Property postal code

Success Response (200 OK)

{
  "success": true,
  "provider": "HAMTA",
  "trackingCode": "a3e23be5-3128-4bb6-9424-9b62b41d6381",
  "message": "Real estate inquiry completed successfully",
  "data": {
    "raw": {
      "Result": {
        "Result": false,
        "ErrorMessage": null,
        "ExternalServiceResponseDuration": 114.3783
      },
      "IsSucceed": true,
      "TrackingCode": "YTNlMjNiZTUtMzEyOC00YmI2LTk0MjQtOWI2MmI0MWQ2Mzgx"
    }
  },
  "duration": 1450
}

cURL Example

curl -X POST https://api.example.com/api/inquiry/real-estate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key-here" \
  -d '{
    "nationalId": "5098961130",
    "postalCode": "1349689554"
  }'

Shahkar Inquiry

Verify mobile number ownership.

Endpoint

POST /api/inquiry/shahkar

Request Body

{
  "nationalCode": "0123456789",
  "mobileNo": "09123456789"
}

Request Parameters

Field Type Required Description
nationalCode string Yes 10-digit national identification number
mobileNo string Yes Mobile number (11 digits starting with 09)

Success Response (200 OK)

{
  "success": true,
  "provider": "MOALLEM",
  "trackingCode": "b4f34cf6-4239-5cc7-a535-ac73c52e7492",
  "message": "Shahkar inquiry completed successfully",
  "data": {
    "raw": {
      "nationalCode": "0123456789",
      "mobileNo": "09123456789",
      "result": "MATCH",
      "soap": "<?xml version=\"1.0\" encoding=\"utf-8\"?>..."
    }
  },
  "duration": 890
}

Possible Results

Result Description
MATCH Mobile number belongs to the person
MISMATCH Mobile number does not belong to the person
NOT_FOUND No record found
ERROR Service error

cURL Example

curl -X POST https://api.example.com/api/inquiry/shahkar \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key-here" \
  -d '{
    "nationalCode": "0123456789",
    "mobileNo": "09123456789"
  }'

Postal Code Inquiry

Lookup address information by postal code.

Endpoint

POST /api/inquiry/postal-code

Request Body

{
  "postalCode": "1234567890"
}

Request Parameters

Field Type Required Description
postalCode string Yes 10-digit postal code

Success Response (200 OK)

{
  "success": true,
  "provider": "MOALLEM",
  "trackingCode": "c5g45dg7-5340-6dd8-b646-bd84d63f8503",
  "message": "Postal code inquiry completed successfully",
  "data": {
    "raw": {
      "province": "تهران",
      "city": "تهران",
      "district": "منطقه 1",
      "street": "خیابان ولیعصر",
      "alley": "کوچه شماره 5",
      "plaque": "123"
    }
  },
  "duration": 650
}

cURL Example

curl -X POST https://api.example.com/api/inquiry/postal-code \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key-here" \
  -d '{
    "postalCode": "1234567890"
  }'

Sheba Inquiry

Verify bank account (SHEBA/IBAN) information.

Endpoint

POST /api/inquiry/sheba

Request Body

{
  "accountOwnerType": "1",
  "nationalCode": "0123456789",
  "legalId": null,
  "sheba": "IR123456789012345678901234"
}

Request Parameters

Field Type Required Description
accountOwnerType string No Account owner type; defaults to "1" in providers
nationalCode string Yes Iranian national code (10 digits)
legalId string No Legal identifier when needed by the selected account owner type
sheba string Yes SHEBA/IBAN number (26 characters starting with IR)

Success Response (200 OK)

{
  "success": true,
  "provider": "MOALLEM",
  "trackingCode": "d6h56eh8-6451-7ee9-c757-ce95e74g9614",
  "message": "Sheba inquiry completed successfully",
  "data": {
    "raw": {
      "IsSucceed": true,
      "Result": {
        "accountOwner": "علی احمدی",
        "bankName": "بانک ملی ایران",
        "branchName": "شعبه مرکزی",
        "accountNumber": "1234567890",
        "isActive": true
      }
    }
  },
  "duration": 1120
}

cURL Example

curl -X POST https://api.example.com/api/inquiry/sheba \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key-here" \
  -d '{
    "accountOwnerType": "1",
    "nationalCode": "0123456789",
    "sheba": "IR123456789012345678901234"
  }'

Car Policy By Chassis

Endpoint

POST /api/inquiry/policyByChassis

Request Body

{
  "chassisNo": "NAAM01E15HK123456"
}

Car Policy By Plate

Endpoint

POST /api/inquiry/policyByPlate

Request Body

{
  "plk1": "12",
  "plk2": "ب",
  "plk3": "345",
  "plksrl": "67"
}

Car Policy By National Code

Endpoint

POST /api/inquiry/policyByNationalCode

Request Body

{
  "nationalCode": "0123456789"
}

Error Responses

400 Bad Request - Invalid Input

{
  "success": false,
  "provider": "GATEWAY",
  "trackingCode": "e7i67fi9-7562-8ff0-d868-df06f85h0725",
  "message": "Validation failed",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "nationalCode must be a 10-digit string"
  },
  "duration": 5
}

401 Unauthorized - Missing/Invalid API Key

{
  "statusCode": 401,
  "message": "Unauthorized",
  "error": "Unauthorized"
}

404 Not Found - Invalid Endpoint

{
  "statusCode": 404,
  "message": "Cannot POST /api/inquiry/invalid",
  "error": "Not Found"
}

429 Too Many Requests - Rate Limit Exceeded

{
  "statusCode": 429,
  "message": "ThrottlerException: Too Many Requests"
}

500 Internal Server Error - No Providers Available

{
  "success": false,
  "provider": "GATEWAY",
  "trackingCode": "f8j78gj0-8673-9gg1-e979-eg17g96i1836",
  "message": "No enabled providers configured for PERSON",
  "error": {
    "code": "NO_PROVIDERS",
    "message": "No enabled providers configured for PERSON"
  },
  "duration": 2
}

500 Internal Server Error - Provider Service Unavailable

{
  "success": false,
  "provider": "GATEWAY",
  "trackingCode": "g9k89hk1-9784-0hh2-f080-fh28h07j2947",
  "message": "TEJARATNOU service is not available",
  "error": {
    "code": "PROVIDER_SERVICE_NOT_AVAILABLE",
    "message": "TEJARATNOU service is not available",
    "providerMessage": "Connection timeout",
    "providerCode": "ETIMEDOUT"
  },
  "duration": 10500
}

500 Internal Server Error - All Providers Failed

{
  "success": false,
  "provider": "GATEWAY",
  "trackingCode": "h0l90il2-0895-1ii3-g191-gi39i18k3058",
  "message": "TEJARATNOU failed: timeout; HAMTA failed: auth error; MOALLEM failed: network error",
  "error": {
    "code": "ALL_PROVIDERS_FAILED",
    "message": "TEJARATNOU failed: timeout; HAMTA failed: auth error; MOALLEM failed: network error",
    "providerMessage": "Connection timeout",
    "providerCode": "ETIMEDOUT"
  },
  "duration": 25000
}

Error Codes Reference

Code Description HTTP Status
VALIDATION_ERROR Invalid request parameters 400
NO_PROVIDERS No providers configured for inquiry type 500
PROVIDER_SERVICE_NOT_AVAILABLE Single provider failed 500
ALL_PROVIDERS_FAILED All configured providers failed 500
PROVIDER_ERROR Generic provider error 500
TIMEOUT Request timeout 500
NETWORK_ERROR Network connectivity issue 500
AUTH_ERROR Authentication failed 500
UNSUPPORTED_INQUIRY Inquiry type not supported 400

Rate Limiting

The API implements rate limiting to prevent abuse:

  • Default Limit: 100 requests per minute per API key
  • Window: 60 seconds (sliding window)
  • Response Header: X-RateLimit-Remaining shows remaining requests

When rate limit is exceeded:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1609459200

Response Time SLA

Inquiry Type Target Response Time Timeout
Person < 2 seconds 10 seconds
Real Estate < 3 seconds 10 seconds
Shahkar < 1.5 seconds 10 seconds
Postal Code < 1 second 10 seconds
Sheba < 2 seconds 10 seconds

Best Practices

1. Always Include Tracking Code

Store the trackingCode from responses for troubleshooting and support requests.

2. Handle Errors Gracefully

Implement retry logic with exponential backoff for transient errors (5xx).

3. Validate Input Client-Side

Validate national codes, postal codes, and mobile numbers before sending requests.

4. Use Appropriate Timeouts

Set client-side timeouts slightly higher than API timeouts (e.g., 12 seconds).

5. Monitor Rate Limits

Track X-RateLimit-Remaining header and implement client-side throttling.

6. Log All Requests

Log request/response pairs with tracking codes for audit and debugging.

7. Secure API Keys

  • Never expose API keys in client-side code
  • Rotate keys regularly
  • Use environment variables
  • Implement key rotation without downtime

Postman Collection

Import this collection to test all endpoints:

{
  "info": {
    "name": "ESG Inquiry Gateway",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "item": [
    {
      "name": "Person Inquiry",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Content-Type",
            "value": "application/json"
          },
          {
            "key": "X-API-Key",
            "value": "{{api_key}}"
          }
        ],
        "body": {
          "mode": "raw",
          "raw": "{\n  \"nationalCode\": \"0123456789\",\n  \"birthDate\": \"1370/01/01\"\n}"
        },
        "url": {
          "raw": "{{base_url}}/api/inquiry/person",
          "host": ["{{base_url}}"],
          "path": ["api", "inquiry", "person"]
        }
      }
    }
  ],
  "variable": [
    {
      "key": "base_url",
      "value": "http://localhost:8085"
    },
    {
      "key": "api_key",
      "value": "your-api-key-here"
    }
  ]
}

Support

For API support:

View Git Blame Copy Permalink