esg/docs/API_DOCUMENTATION.md

# 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