baya-monorepo/archive/docs/integration/domains/partner-center.md

partner-center — nursing companies

Client seam client/src/services/partnerCenter/ · USE_PARTNER_MOCK = true (mock is primary) · 9 server ops Last verified: 2026-07-30 against commit d3ec723 and swagger.v1.json (2026-07-29).

Nursing companies («مراکز») that sponsor nurses onto the platform. The domain with the widest gap between what the client wants and what the server serves — 6 of its client calls are phantom.

Endpoints

Method	Path	Verdict
GET	/api/v1/admin/partner-centers	wired · paginated
POST	/api/v1/admin/partner-centers	wired
GET	/api/v1/admin/partner-centers/{id}	wired
PATCH	/api/v1/admin/partner-centers/{id}	wired
POST	/api/v1/admin/partner-centers/{id}/set-active	wired — REQ-032's delivered half
POST	/api/v1/admin/partner-centers/{id}/sponsor-nurse	wired
POST	/api/v1/admin/partner-centers/{id}/verify	wired
GET	/api/v1/centers/{id}/dashboard	unwired — the client wants centers/me/* splits instead
GET	/api/v1/internal/bookings/{bookingId}/center	unwired — the MoR resolver, server-internal

The seven admin/partner-centers routes are DynamicPermission + sensitive; centers is [Authorize]; internal/bookings is DynamicPermission.

This domain owns three of the four route-shape exceptions in the API: hyphens (partner-centers, set-active, sponsor-nurse), a nested admin/ segment, and an internal/ namespace. It also has one of only two PATCH verbs. See index.md.

Phantom — 6

Client call	REQ	Note
GET /api/v1/centers/me	REQ-032	The portal's own-center read
GET /api/v1/centers/me/nurses	REQ-032	Split read — the server serves one aggregate instead
GET /api/v1/centers/me/bookings	REQ-032	Split read
GET /api/v1/centers/me/bookings/{id}	REQ-064	Partner-scoped booking detail
GET /api/v1/centers/me/settlement	REQ-033	Per-booking commission invoices
GET /api/v1/admin/partner-centers/{id}/nurses	REQ-032	The admin-side sponsored-nurse list

The shape mismatch is the point. The server serves one aggregate, GET centers/{id}/dashboard → CenterDashboardDto with sponsoredNurses inline. The portal wants /me plus paginated splits — it cannot page an inline array, and it does not know its own center id without REQ-038. Until REQ-032 lands, the portal is mock-only.

Merchant of record

The one business rule that changes where money goes:

• isMerchantOfRecord = true → the center is the seller. It invoices the customer, holds the commercial relationship, and Balinyaar's cut is a commission against the center.
• isMerchantOfRecord = false → the nurse is the seller and the center is a sponsor only.

GET internal/bookings/{bookingId}/center is the MoR resolver the invoice pipeline calls to decide which entity issues the invoice — which is why InvoiceDto.issuingEntityType exists. See payment.md. commissionRate on the center is a per-center override of the platform default, snapshotted at compute time like every other rate.

Shape rules the JSON does not express

• The settlement IBAN is write-then-masked. settlementIbanMasked is the only form on every read model; the full value never comes back after the write that set it. Same pattern as nurse.md.
• verify is a licence check behind a seam. ILicenseVerificationService checks the eNamad code and the MoH establishment permit; by default it returns NeedsManualReview, so verify records a human admin decision. Seams:LicenseVerification:AutoApprove makes the mock return Valid to test the auto-approve path. A real eNamad/MoH registry adapter ignores the knob.
• technicalDirectorNurseUserId links to a real verified nurse, not a free-text name — Iranian regulation requires a named technical director («مدیر فنی») with a valid licence.
• set-active is suspend/activate, not delete. A suspended center's sponsored nurses and past bookings stay resolvable.
• sponsoredNurseCount is denormalised onto both the list item and the detail so the queue needs no per-row count.
• legalEntityType and mohEstablishmentPermitNo are the regulatory identity; enamadCode is the e-commerce trust seal. All three are distinct and none substitutes for another.

Enums

Vocabulary	Values
CenterOnboardingState	draft pending_verification verified suspended
MoadianStatus (on the center's invoices)	pending submitted registered failed

MoadianStatus is shared with payment.md — it is the سامانه مودیان submission state, and it is the same vocabulary on both sides.

CenterOnboardingState is the client's model of the center's position in onboarding. On the wire the server carries the facts it is derived from — isActive and verifiedAt on both PartnerCenterListItemDto and PartnerCenterDetailDto — not the state string itself. Derive, do not expect a field.

Open REQs

REQ	Status	Effect
REQ-032	partially delivered	set-active landed. The /me split reads and the IBAN write-then-masked flow are deferred → 5 phantom routes. The main reason this seam is mocked
REQ-033	partially delivered	totalIrr is on InvoiceDto; the per-booking commission invoice list is deferred → 1 phantom
REQ-064	open	No partner-scoped booking detail → 1 phantom
REQ-038	open	/me carries no signal that the caller administers a center, so the portal cannot auto-route or discover its own center id. See auth.md