Parties sub-module reference · Cluster ERP Wiki

This page lists the fields, routes, and rules of the parties sub-module in src/cluster_erp/modules/parties/parties/: the party card, the individual and organisation details, and the profile photo. The role model around the card is on party unification. Addresses, channels, and languages have their own pages.

Scope and source¶

Defined in: src/cluster_erp/modules/parties/parties/models.py (Party, Individual, OrganisationInfo), schemas.py, services.py (PartyService), routes.py, and metadata.py (PARTY_META, ADDRESS_META, CHANNEL_META).
Count: 3 tables (__tablename__ in models.py); 9 routes (@router. decorators in routes.py).

The metadata file of this sub-module also declares ADDRESS_META and CHANNEL_META (src/cluster_erp/modules/parties/parties/metadata.py:1181, src/cluster_erp/modules/parties/parties/metadata.py:1438); they are described on addresses and communication channels.

Party fields¶

Name	Type	Default	Meaning	Source
`code`	`String(20)`, unique	from sequence `party`	Yearly business key	`src/cluster_erp/modules/parties/parties/models.py:26`, `src/cluster_erp/modules/parties/parties/services.py:116`
`party_type`	`String(20)`	none	`individual` or `organisation`	`src/cluster_erp/modules/parties/parties/models.py:27`, `src/cluster_erp/modules/parties/parties/schemas.py:17-19`
`display_name`	`String(255)`	none	Name shown everywhere	`src/cluster_erp/modules/parties/parties/models.py:28`
`tax_id`, `tax_office`	`String(50)`, `String(255)`	none	Tax number and tax office	`src/cluster_erp/modules/parties/parties/models.py:29-30`
`notes`	`Text`	none	Free notes	`src/cluster_erp/modules/parties/parties/models.py:31`
`is_active`	bool	`True`	Active flag; the create payload's value is kept	`src/cluster_erp/modules/parties/parties/models.py:32`, `src/cluster_erp/modules/parties/parties/schemas.py:69-70`
`is_customer`, `is_supplier`, `is_employee`	bool	`False`	Role flags; see party unification	`src/cluster_erp/modules/parties/parties/models.py:33-35`
`photo_attachment_id`	FK to `core_attachments.id`	none	Profile photo; initials are shown without one	`src/cluster_erp/modules/parties/parties/models.py:36-42`
`extra`	JSONB	`{}`	Tenant-defined field values	`src/cluster_erp/modules/parties/parties/models.py:21-24`

Individual and organisation details¶

Entity	Fields	Rule	Source
`Individual`	`first_name`, `last_name` (required), `middle_name`, `title`, `date_of_birth`, `gender`	one live row per party (partial unique index)	`src/cluster_erp/modules/parties/parties/models.py:58-82`
`OrganisationInfo`	`legal_name` (required), `trade_name`, `registration_number`, `industry`	one live row per party (partial unique index)	`src/cluster_erp/modules/parties/parties/models.py:85-105`

National id, social security number, and blood group are not on the individual; the model comment states that they live on the employment record (src/cluster_erp/modules/parties/parties/models.py:78-79). Create writes the individual block only for an individual and the organisation block only for an organisation (src/cluster_erp/modules/parties/parties/services.py:130-136).

Routes¶

All paths are under /api/v1/parties.

Method and path	Purpose	Permission	Source
`GET /`	Page of parties; filters `search`, `party_type`, `role`, `active_only`, tenant fields `extra.<key>`	`party.read`	`src/cluster_erp/modules/parties/parties/routes.py:37-67`
`POST /`	Create a party, optionally with addresses and channels	`party.create`	`src/cluster_erp/modules/parties/parties/routes.py:70-85`
`GET /{party_id}`	Party with details, addresses, and channels	`party.read`	`src/cluster_erp/modules/parties/parties/routes.py:88-102`
`PUT /{party_id}`	Update	`party.update`	`src/cluster_erp/modules/parties/parties/routes.py:105-120`
`POST /bulk-delete`	Soft-delete several	`party.bulk_delete`	`src/cluster_erp/modules/parties/parties/routes.py:123-132`
`DELETE /{party_id}`	Soft-delete one	`party.delete`	`src/cluster_erp/modules/parties/parties/routes.py:135-144`
`GET /{party_id}/photo`	Photo bytes	`party.read`	`src/cluster_erp/modules/parties/parties/routes.py:161-184`
`POST /{party_id}/photo`	Upload or replace the photo	`party.update`	`src/cluster_erp/modules/parties/parties/routes.py:187-230`
`DELETE /{party_id}/photo`	Remove the photo	`party.update`	`src/cluster_erp/modules/parties/parties/routes.py:233-249`

The list returns items, total, total_capped, limit, and offset; the count stops at a deployment cap (src/cluster_erp/modules/parties/parties/routes.py:61-67, src/cluster_erp/modules/parties/parties/services.py:75-78). Read responses hide tenant-field values the caller may not see (src/cluster_erp/modules/parties/parties/routes.py:31-34, src/cluster_erp/modules/parties/parties/routes.py:82-85); see tenant fields. Guided creation and role enabling are server routes; see party unification.

Constraints and validation¶

display_name is at most 255 characters; tax id at most 50 (src/cluster_erp/modules/parties/parties/schemas.py:63-68).
Tenant-defined values are validated against their definitions on create and update (src/cluster_erp/modules/parties/parties/services.py:112-115, src/cluster_erp/modules/parties/parties/services.py:173-181).
The list is ordered by display name and eagerly loads the individual details (src/cluster_erp/modules/parties/parties/services.py:79-87).
A photo must be image/jpeg, image/png, image/webp, or image/gif, not empty, and at most 5 MB; it is stored with entity_type party_photo (src/cluster_erp/modules/parties/parties/routes.py:153-154, src/cluster_erp/modules/parties/parties/routes.py:196-225). See attachments, notes, and storage.
Completeness tiers on the card are Basic (type and name), Tax Information (tax id and office), and Complete (notes) (src/cluster_erp/modules/parties/parties/metadata.py:1156-1174).

Terms introduced¶

Term	Code identifier	Definition	Turkish term	Source
individual details	`Individual`	The person-specific fields of an individual party.	Bireysel bilgiler	`src/cluster_erp/modules/parties/parties/models.py:58`
organisation details	`OrganisationInfo`	The legal fields of an organisation party.	Kurumsal bilgiler	`src/cluster_erp/modules/parties/parties/models.py:85`

Verified against commit 92f8051 on 2026-11-13.