@axova/shared 1.0.0 → 1.0.2

package/src/schemas/store/ethiopian_business_api.md.resolved

@@ -1,212 +0,0 @@
-# Ethiopian Business Registration API Documentation
-
-## Overview
-
-The Ethiopian Business Registration API allows store creation and validation using Ethiopian Tax Identification Numbers (TIN). It integrates with the Ethiopian government's e-trade system to automatically fetch and populate business details.
-
-**Base URL**: `/api/stores`
-
-## Authentication
-
-All endpoints require authentication unless specified otherwise.
-- Headers: `X-User-ID: <user_id>`
-- Or authenticated session cookies
-
----
-
-## 1. Validate TIN
-
-Validates an Ethiopian TIN and fetches associated business data, including license status.
-
-- **Endpoint**: `POST /validate-tin`
-- **Auth Required**: No (Publicly accessible for check)
-
-### Request Body
-
-```json
-{
-  "tinNumber": "0069967578"
-}
-```
-
-### Response (200 OK)
-
-```json
-{
-  "success": true,
-  "message": "TIN validated successfully",
-  "data": {
-    "valid": true,
-    "tin": "0069967578",
-    "businessData": {
-      "businessName": "COSHILD TRADING PLC",
-      "businessNameAmh": "ኮሸልድ ትሬዲንግ ሃላ የተ የግ ማህበር",
-      "registrationNumber": "BL/AA/2/0022869/2013",
-      "registrationDate": "2021-03-15T00:00:00.000Z",
-      "paidUpCapital": 16000000,
-      "legalCondition": "Private Limited Company",
-      "tradeNames": ["COSHILD TRADING"]
-    },
-    "licenseStatus": {
-      "hasValidLicense": true,
-      "allLicensesExpired": false,
-      "totalLicenses": 1,
-      "activeLicenses": 1,
-      "expiredLicenses": 0,
-      "licensesExpiringSoon": 0
-    },
-    "licenses": [
-      {
-        "licenseNumber": "BL/AA/14/609/4908051/2013",
-        "tradeName": "COSHILD TRADING",
-        "isActive": true,
-        "isExpired": false,
-        "daysUntilExpiry": 145,
-        "renewedTo": "2026-07-07T00:00:00.000Z",
-        "subGroups": [
-          {
-            "code": 46900,
-            "description": "Non-specialized wholesale trade"
-          }
-        ]
-      }
-    ],
-    "associates": [
-      {
-        "name": "ABEBE KEBEDE",
-        "position": "MANAGER",
-        "mobilePhone": "0911234567"
-      }
-    ],
-    "warnings": []
-  }
-}
-```
-
----
-
-## 2. Create Store from TIN
-
-Creates a new store populated with data fetched from the TIN.
-
-- **Endpoint**: `POST /from-tin`
-- **Auth Required**: Yes
-
-### Conditional Validation
-
-The requirement for location fields depends on `businessType`:
-
-| Field | Starter (`starter`) | Business Owner (`business_owner`) |
-|-------|---------------------|-----------------------------------|
-| `region` | Optional | **Required** |
-| `subcity` | Optional | **Required** |
-| `woreda` | Optional | **Required** |
-| `houseNumber` | Optional | **Required** |
-
-### Request Body (Business Owner Example)
-
-```json
-{
-  "tinNumber": "0069967578",
-  "businessType": "business_owner",
-  "storeName": "My Store Name", 
-  "subdomain": "mystore123",
-  "region": "Addis Ababa",
-  "subcity": "Bole",
-  "woreda": "03",
-  "houseNumber": "123",
-  "organization": {
-    "name": "My Org"
-  }
-}
-```
-
-### Request Body (Starter Example)
-
-```json
-{
-  "tinNumber": "0069967578",
-  "businessType": "starter",
-  "storeName": "My Starter Store",
-  "subdomain": "starterstore",
-  "organization": {
-    "name": "My Starter Org"
-  }
-}
-```
-
-### Response (201 Created)
-
-```json
-{
-  "success": true,
-  "message": "Store created successfully from TIN",
-  "data": {
-    "storeId": "store_cl...",
-    "storeUrl": "mystore123.myaxova.store",
-    "subdomain": "mystore123",
-    "ethiopianBusinessData": {
-      "tin": "0069967578",
-      "businessType": "business_owner",
-      "legalBusinessName": "COSHILD TRADING PLC",
-      "location": {
-        "region": "Addis Ababa",
-        "subcity": "Bole",
-        "woreda": "03",
-        "houseNumber": "123"
-      },
-      "hasValidLicense": true
-    }
-  }
-}
-```
-
----
-
-## 3. Get TIN Data (Read Only)
-
-Fetches raw TIN data without creating a store.
-
-- **Endpoint**: `GET /tin/:tinNumber`
-- **Auth Required**: No (Public)
-
-### Response
-
-Returns the same data structure as `data.businessData` in the Validate TIN endpoint, plus full license and associate details.
-
----
-
-## Error Codes
-
-| Code | Message | Description |
-|------|---------|-------------|
-| 400 | Invalid TIN format | TIN must be exactly 10 digits |
-| 400 | Missing required fields | Missing TIN, businessType, etc. |
-| 400 | For business_owner type... | Missing required location fields for business owner |
-| 409 | Subdomain is already taken | The requested subdomain is invalid |
-| 404 | etrade API request failed | TIN not found in government database |
-| 500 | Failed to fetch TIN data | External API error or timeout |
-
-## Database Schema
-
-### `stores` Table Extensions
-
-| Column | Type | Description |
-|--------|------|-------------|
-| `tin_number` | varchar(50) | Ethiopian TIN |
-| `business_type` | varchar(20) | 'starter' or 'business_owner' |
-| `region` | varchar(100) | Region (e.g., Addis Ababa) |
-| `subcity` | varchar(100) | Subcity (e.g., Bole) |
-| `woreda` | varchar(100) | Woreda/District |
-| `house_number` | varchar(50) | House number |
-| `trade_names` | jsonb | Array of registered trade names |
-
-### `store_business_details` Table Extensions
-
-| Column | Type | Description |
-|--------|------|-------------|
-| `legal_business_name_amh` | varchar(255) | Business name in Amharic |
-| `registration_date` | timestamp | Initial registration date |
-| `paid_up_capital` | numeric(15,2) | Capital in ETB |
-| `license_details` | jsonb | Full license history and status |
-| `associate_info` | jsonb | Manager and associate details |