s.hajizadeh/esg
1
0
Fork 0
forked from Shared/esg
Code Pull Requests Activity

initial commit

Browse Source
This commit is contained in:
Soheil Hajizadeh
2026-06-09 14:07:37 +03:30
parent 30ac533800
commit 996a4fcda7
121 changed files with 20557 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

628
docs/API_DOCUMENTATION.md Normal file
View File

@@ -0,0 +1,628 @@
# API Documentation
Complete API reference for the ESG Inquiry Gateway with request/response examples.
## Table of Contents
- [Authentication](#authentication)
- [Person Inquiry](#person-inquiry)
- [Real Estate Inquiry](#real-estate-inquiry)
- [Shahkar Inquiry](#shahkar-inquiry)
- [Postal Code Inquiry](#postal-code-inquiry)
- [Sheba Inquiry](#sheba-inquiry)
- [Error Responses](#error-responses)
## 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)
```http
X-API-Key: your-api-key-here
```
### 2. JWT Bearer Token
```http
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```
## Person Inquiry
Query person information using national code and birth date.
### Endpoint
```
POST /api/inquiry/person
```
### Request Headers
```http
Content-Type: application/json
X-API-Key: your-api-key-here
```
### Request Body
```json
{
"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)
```json
{
"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
```bash
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
```yaml
/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
```json
{
"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)
```json
{
"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
```bash
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
```json
{
"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)
```json
{
"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
```bash
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
```json
{
"postalCode": "1234567890"
}
```
### Request Parameters
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| postalCode | string | Yes | 10-digit postal code |
### Success Response (200 OK)
```json
{
"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
```bash
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
```json
{
"accountOwnerType": "REAL",
"nationalId": "0123456789",
"shebaId": "IR123456789012345678901234"
}
```
### Request Parameters
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| accountOwnerType | string | Yes | Account owner type: "REAL" (person) or "LEGAL" (company) |
| nationalId | string | Conditional | Required if accountOwnerType is "REAL" |
| legalId | string | Conditional | Required if accountOwnerType is "LEGAL" |
| shebaId | string | Yes | SHEBA/IBAN number (26 characters starting with IR) |
### Success Response (200 OK)
```json
{
"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
```bash
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": "REAL",
"nationalId": "0123456789",
"shebaId": "IR123456789012345678901234"
}'
```
## Error Responses
### 400 Bad Request - Invalid Input
```json
{
"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
```json
{
"statusCode": 401,
"message": "Unauthorized",
"error": "Unauthorized"
}
```
### 404 Not Found - Invalid Endpoint
```json
{
"statusCode": 404,
"message": "Cannot POST /api/inquiry/invalid",
"error": "Not Found"
}
```
### 429 Too Many Requests - Rate Limit Exceeded
```json
{
"statusCode": 429,
"message": "ThrottlerException: Too Many Requests"
}
```
### 500 Internal Server Error - No Providers Available
```json
{
"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
```json
{
"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
```json
{
"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
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:
```json
{
"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:
- **Documentation**: https://docs.example.com
- **Status Page**: https://status.example.com
- **Support Email**: support@example.com
- **Emergency**: +98-21-1234-5678