turash/docs/api/organizations.md

# Organizations API

Complete API documentation for organization management endpoints.

## Organization Object

```json
{
  "id": "uuid-string",
  "name": "Organization Name",
  "subtype": "business",
  "sector": "Manufacturing",
  "description": "Detailed company description",
  "logoUrl": "https://api.turash.com/static/images/logos/uuid.jpg",
  "galleryImages": [
    "https://api.turash.com/static/images/gallery/uuid1.jpg",
    "https://api.turash.com/static/images/gallery/uuid2.jpg"
  ],
  "website": "https://company.com",
  "address": "123 Industrial Street, City, Country",
  "latitude": 55.7558,
  "longitude": 37.6176,
  "legalForm": "LLC",
  "primaryContactEmail": "contact@company.com",
  "primaryContactPhone": "+7-495-123-45-67",
  "industrialSector": "C20",
  "companySize": 150,
  "yearsOperation": 10,
  "supplyChainRole": "manufacturer",
  "certifications": ["ISO9001", "ISO14001"],
  "businessFocus": ["sustainability", "innovation"],
  "strategicVision": "Vision statement",
  "driversBarriers": "Key drivers and barriers",
  "readinessMaturity": 4,
  "trustScore": 0.85,
  "technicalExpertise": ["process_optimization", "waste_management"],
  "availableTechnology": ["heat_recovery", "recycling"],
  "managementSystems": ["ERP", "MES"],
  "sellsProducts": [
    {
      "name": "Industrial Waste Product",
      "category": "Waste Materials",
      "description": "Recyclable industrial waste",
      "quantity": 1000,
      "unit": "kg/month",
      "pricePerUnit": 0.50,
      "quality": {
        "purity": "95%",
        "contamination": ["heavy_metals", "organic_compounds"]
      }
    }
  ],
  "offersServices": [
    {
      "name": "Waste Treatment Service",
      "category": "Environmental Services",
      "description": "Industrial waste treatment",
      "capacity": 5000,
      "unit": "kg/day",
      "pricing": {
        "basePrice": 1000,
        "currency": "EUR",
        "billingCycle": "monthly",
        "volumePricingTiers": [
          {
            "minVolume": 0,
            "maxVolume": 1000,
            "pricePerUnit": 0.20,
            "discountPct": 0
          },
          {
            "minVolume": 1000,
            "pricePerUnit": 0.15,
            "discountPct": 25
          }
        ]
      }
    }
  ],
  "needsServices": [
    {
      "category": "Transportation",
      "description": "Need logistics support for waste transport",
      "urgency": "high",
      "budget": {
        "minAmount": 5000,
        "maxAmount": 15000,
        "currency": "EUR",
        "frequency": "monthly"
      }
    }
  ],
  "yearBuilt": "1995",
  "builderOwner": "Original Construction Company",
  "architect": "Architect Name",
  "originalPurpose": "Manufacturing facility",
  "currentUse": "Chemical manufacturing",
  "style": "Industrial",
  "materials": "Steel and concrete",
  "storeys": 3,
  "heritageStatus": "Not protected",
  "verified": true,
  "notes": "Additional notes",
  "sources": ["Company website", "Industry database"],
  "trustNetwork": ["partner-org-uuid"],
  "existingSymbioticRelationships": ["supplier-uuid"],
  "createdAt": "2025-01-01T00:00:00Z",
  "updatedAt": "2025-01-15T10:30:00Z"
}
```

## Organization Subtypes

- `business`: Commercial companies and enterprises
- `facility`: Industrial facilities and plants
- `cultural`: Cultural institutions and venues
- `religious`: Religious organizations
- `government`: Government entities and agencies
- `educational`: Schools, universities, research institutions
- `healthcare`: Hospitals, clinics, medical facilities
- `infrastructure`: Utility providers, transportation
- `other`: Other organization types

## Legal Forms

- `LLC`: Limited Liability Company
- `corporation`: Corporation
- `partnership`: Partnership
- `sole_proprietorship`: Sole Proprietorship
- `GmbH`: German GmbH
- `UG`: German UG (haftungsbeschränkt)
- `AG`: German AG (Aktiengesellschaft)

## Supply Chain Roles

- `manufacturer`: Produces goods
- `supplier`: Supplies materials/components
- `distributor`: Distributes products
- `consumer`: Consumes products/services

## API Endpoints

### List Organizations

```http
GET /api/v1/organizations
```

**Query Parameters:**
- `limit` (int, optional): Maximum results (default: 50, max: 100)
- `offset` (int, optional): Pagination offset (default: 0)
- `sector` (string, optional): Filter by sector
- `subtype` (string, optional): Filter by organization subtype
- `verified` (boolean, optional): Filter by verification status
- `min_trust_score` (float, optional): Minimum trust score (0.0-1.0)
- `max_distance_km` (float, optional): Filter by distance from coordinates
- `lat` (float, optional): Latitude for distance filtering
- `lng` (float, optional): Longitude for distance filtering

**Response:**
```json
{
  "data": [Organization],
  "pagination": {
    "total": 1250,
    "limit": 50,
    "offset": 0,
    "hasMore": true
  }
}
```

### Get Organization by ID

```http
GET /api/v1/organizations/{id}
```

**Response:** Single Organization object

### Search Organizations

```http
GET /api/v1/organizations/search
```

**Query Parameters:**
- `q` (string, required): Search query (searches name, description, sector)
- `sector` (string, optional): Filter by sector
- `subtype` (string, optional): Filter by subtype
- `limit` (int, optional): Maximum results (default: 20)

**Response:** Array of matching Organization objects

### Search Suggestions

```http
GET /api/v1/organizations/suggestions
```

**Query Parameters:**
- `q` (string, required): Partial search query
- `limit` (int, optional): Maximum suggestions (default: 10)

**Response:**
```json
{
  "data": [
    {
      "id": "uuid",
      "name": "Organization Name",
      "sector": "Manufacturing",
      "subtype": "business"
    }
  ]
}
```

### Get Sector Statistics

```http
GET /api/v1/organizations/sectors/stats
```

**Response:**
```json
{
  "data": {
    "totalOrganizations": 1250,
    "sectors": {
      "Manufacturing": {
        "count": 450,
        "percentage": 36.0,
        "subtypes": {
          "business": 380,
          "facility": 70
        }
      }
    },
    "subtypes": {
      "business": 980,
      "facility": 200,
      "cultural": 50,
      "other": 20
    }
  }
}
```

### Get Similar Organizations

```http
GET /api/v1/organizations/{id}/similar
```

**Query Parameters:**
- `limit` (int, optional): Maximum results (default: 10)

**Response:** Array of similar Organization objects

### Get Organization Proposals

```http
GET /api/v1/organizations/{id}/proposals
```

**Response:** Array of proposal objects related to the organization

### Get Organization Resources

```http
GET /api/v1/organizations/{id}/resources
```

**Response:** Array of resource flow objects associated with the organization

### Get Direct Matches

```http
GET /api/v1/organizations/{id}/matching/direct
```

**Response:** Array of direct matching opportunities

## Create Organization

```http
POST /api/v1/organizations
```

**Request Body:** Complete Organization object (see schema above)

**Required Fields:**
- `name`
- `sector`
- `subtype`

**Response:** Created Organization object

## Update Organization

```http
PUT /api/v1/organizations/{id}
```

**Request Body:** Partial Organization object (only fields to update)

**Response:** Updated Organization object

## Delete Organization

```http
DELETE /api/v1/organizations/{id}
```

**Response:**
```json
{
  "message": "Organization deleted successfully"
}
```

## Image Upload Endpoints

### Upload Logo

```http
POST /api/v1/organizations/{id}/logo
```

**Content-Type:** `multipart/form-data`

**Form Fields:**
- `image` (file, required): Image file (JPEG, PNG, max 5MB)

**Response:**
```json
{
  "data": {
    "url": "https://api.turash.com/static/images/logos/uuid.jpg",
    "path": "/logos/uuid.jpg"
  },
  "message": "Logo uploaded successfully"
}
```

### Upload Gallery Image

```http
POST /api/v1/organizations/{id}/gallery
```

**Content-Type:** `multipart/form-data`

**Form Fields:**
- `image` (file, required): Image file (JPEG, PNG, max 10MB)

**Response:**
```json
{
  "data": {
    "url": "https://api.turash.com/static/images/gallery/uuid.jpg",
    "galleryImages": ["url1", "url2", "url3"]
  },
  "message": "Gallery image uploaded successfully"
}
```

### Delete Gallery Image

```http
DELETE /api/v1/organizations/{id}/gallery?url={imageUrl}
```

**Query Parameters:**
- `url` (string, required): Full URL of image to delete

**Response:**
```json
{
  "data": {
    "galleryImages": ["url1", "url2"]
  },
  "message": "Gallery image deleted successfully"
}
```

## Data Validation Rules

### Organization Name
- Required
- 2-200 characters
- Unique across all organizations

### Geographic Coordinates
- `latitude`: -90.0 to 90.0
- `longitude`: -180.0 to 180.0

### Trust Score
- Range: 0.0 to 1.0
- Represents reliability and reputation

### Readiness Maturity
- Range: 1 to 5
- 1: Unaware of industrial symbiosis
- 5: Actively engaged in multiple symbiotic relationships

### Company Size
- Must be positive integer
- Represents number of employees

### Years of Operation
- Must be non-negative integer

## Error Responses

### Validation Errors
```json
{
  "error": "Validation failed",
  "details": {
    "name": "Name is required",
    "latitude": "Latitude must be between -90 and 90"
  }
}
```

### Not Found
```json
{
  "error": "Organization not found"
}
```

### Unauthorized
```json
{
  "error": "Authentication required"
}
```