Unit-service requests

Once a shopper owns a unit they enter the Pre-Delivery owner area — the same post-purchase suite that lets them refer a buyer and request resale assistance. This page covers the third outbound thing they can do there: raise a unit-service request against a unit they own — for example ask for a site visit, flag a complaint, request an account statement, or start a handover. Every one of these is the unit_service variant of App\Models\UserRequest (app/Models/UserRequest.php:11), tagged with UserRequestsEnums::UNIT_SERVICE (value unit_service, app/Enums/UserRequestsEnums.php:11). The authoritative record lives in the CRM; the portal keeps only a thin user_requests mirror.

unit_service is one of four UserRequest variants — and the only one keyed by a service code

unit_service is one of the four UserRequestsEnums values (app/Enums/UserRequestsEnums.php:10-13); the sibling Referrals & resell assistance page covers referral and unit_resale. What makes unit_service different is that the owner must also pick a service code — one of the 14 CR_* cases in UnitServiceRequestCodeEnum (app/Enums/UnitServiceRequestCodeEnum.php:10-23). That code is what tells the CRM which kind of service the owner is asking for. Unlike the referral path (which rides the shared leads endpoint), unit-service has its own dedicated, logged-in endpoint.

The whole trip, in one diagram

sequenceDiagram
actor OW as Owner (Shopper)
participant SPA as Pre-Delivery SPA
participant API as Backend (Laravel)
participant MW as crms-middleware
participant CRM as CRM
participant DB as Portal DB
OW->>SPA: Pick a service code (CR_SiteVisit, CR_Complaint, one of 14) and fill details
SPA->>API: POST units customer-requests (authed) with service_slug
Note over API: validate service_slug is a UnitServiceRequestCodeEnum name
API->>API: map the slug name to the CRM service_code value
API->>MW: POST /customer-requests with country header from the unit
MW->>CRM: Create customer request keyed on unit_source_id
CRM-->>API: 200
API->>DB: SaveUserRequest writes UserRequest request_type = unit_service
Note over DB: service_type stores the uppercased slug name not the CRM value
API-->>SPA: 200 mapped response

Unit-service request — owner picks a CR_* code, CRM records, portal mirrors as unit_service

The shape matches the sibling flows: submit to the CRM first, then — only on an HTTP 200 — write the local UserRequest mirror. If the CRM call is non-200, no local row is written and the request never appears in the portal’s owner list or analytics (CustomerRequestController.php:48).

The flow, step by step

1. Route. POST units/{publishedUnitShopper}/customer-requests → CustomerRequestController@submitUnitService (routes/api/shopper.php:136-139). This route sits inside the auth:sanctum + ability:ACCESS_SHOPPER_API group (routes/api/shopper.php:93-96), so the owner must be logged in — there is no token-optional path here (contrast the referral POST leads endpoint, which is outside the authed group).

2. Validation. SubmitUnitServiceRequest (app/Http/Requests/CustomerRequest/SubmitUnitServiceRequest.php:14-27) requires customer_source_id and service_slug. The service_slug is constrained to Rule::in(UnitServiceRequestCodeEnum::names()) (:22) — the names of the enum, e.g. CR_SITEVISIT. Every other field is nullable: preferred_time_of_contact (a ContactTime), preferred_way_of_contact (a CommunicationMethod), request_details, change_contact_details, sign_contract_place, sign_contract_requested_option (a ContractRequestedOption), and sign_contract_visit_date_and_time. prepareForValidation() uppercases the incoming slug first — strtoupper($this->service_slug) (:29-34) — so the SPA can send CR_SiteVisit or cr_sitevisit and it still matches the uppercase enum name CR_SITEVISIT.

3. Controller. submitUnitService (app/Http/Controllers/Api/Shopper/CustomerRequestController.php:32-62) reads $shopper = Auth::user(), calls the CRM action, maps the response, and only if the mapped status is 200 (:48) calls SaveUserRequest with request_type = UserRequestsEnums::UNIT_SERVICE->value (:54). A non-200 returns the mapped error and writes nothing locally (:61).

4. CRM submit (Action). SubmitUnitService::handle (app/Actions/CustomerRequests/SubmitUnitService.php:18-33) resolves the country header from the unit itself — $unit->project->destination->country->slug (:20) — so unit-service is multi-country, unlike the Egypt-pinned EOI flow. prepareRequestData (:35-42) sets unit_source_id = $unit->source_id, translates the slug to the CRM code with service_code = UnitServiceRequestCodeEnum::array()[$data['service_slug']] (:38), drops the raw service_slug key, then POSTs to {crms-middleware}/customer-requests via CrmMiddlewareClient::postWithAuthentication (:24-32).

5. Local mirror (on 200 only). formatUserRequestData (CustomerRequestController.php:97-107) builds the row: user_type = Shopper::class, user_id = $shopper->id, request_type = unit_service, service_type = $requestData['service_slug'] (the uppercased name), unit_type_id = $unit->unit_type_id, and the unit’s destination_slug for the pivot. SaveUserRequest::handle (app/Actions/UserRequest/SaveUserRequest.php:12-21) stamps created_at_dm, creates the UserRequest, and syncs the destinations pivot.

How the slug becomes a CRM service_code

UnitServiceRequestCodeEnum::array() is array_combine(names(), values()) (app/Traits/EnumToArray.php:17-20) — so it is keyed by the uppercase enum name and returns the mixed-case CRM value. The lookup array()[$data['service_slug']] (SubmitUnitService.php:38) therefore turns the validated slug CR_SITEVISIT into the CRM service_code CR_SiteVisit. The CRM receives the mixed-case value; the local mirror keeps the uppercase name (see Gotchas).

The 14 service codes

UnitServiceRequestCodeEnum (string-backed, app/Enums/UnitServiceRequestCodeEnum.php:7-24) defines exactly 14 codes. The enum name (uppercase) is what the SPA sends as service_slug and what the local mirror stores in service_type; the value is the mixed-case service_code sent to the CRM. The meanings below are read from the case names.

CRM service_code (value)	Enum case (service_slug / service_type)	What the owner is asking for
CR_BouncedPayment	CR_BOUNCEDPAYMENT	A bounced / failed installment payment
CR_Cancellation	CR_CANCELLATION	Cancel a contract or unit
CR_ChangeContactDetails	CR_CHANGECONTACTDETAILS	Update the owner’s contact details
CR_ChangeOfOwnership	CR_CHANGEOFOWNERSHIP	Transfer ownership of the unit
CR_HandoverReq	CR_HANDOVERREQ	Start / request the unit handover
CR_Complaint	CR_COMPLAINT	Raise a complaint
CR_FinancialClearance	CR_FINANCIALCLEARANCE	A financial-clearance letter
CR_FinancialReq	CR_FINANCIALREQ	A general financial request
CR_SiteVisit	CR_SITEVISIT	Book a site visit
CR_ModificationReq	CR_MODIFICATIONREQ	A unit-modification request
CR_General	CR_GENERAL	A general / uncategorized request
CR_AddonInterest	CR_ADDONINTEREST	Interest in a unit add-on
CR_SignContract	CR_SIGNCONTRACT	Arrange to sign a contract
CR_AccountStatement	CR_ACCOUNTSTATEMENT	An account statement

Where the owner sees their requests back

The owner’s submitted requests are read straight from the CRM, not the local mirror: GET user/customer-requests → CustomerRequestController@index → GetByCustomerSourceId, which GETs {crms-middleware}/customer-requests and maps the result (CustomerRequestController.php:22-30; app/Actions/CustomerRequests/GetByCustomerSourceId.php:16-33). The local user_requests row exists only to power the shopper-admin analytics count GET analytics/unit-services/count-per-service-type, which filters request_type = unit_service and groups by service_type (app/Http/Controllers/Api/ShopperAdmin/UserRequestController.php:24-32).

Gotchas

The local service_type is the UPPERCASE name, not the CRM service_code

The CRM is sent the mixed-case value CR_SiteVisit (SubmitUnitService.php:38), but the local mirror stores service_type = $requestData['service_slug'] — the uppercased name CR_SITEVISIT (CustomerRequestController.php:102). So the same request is labelled two different strings on the two sides. Any reporting or reconciliation that joins the portal service_type against the CRM service_code must normalize case (or map name → value through UnitServiceRequestCodeEnum) — a literal string match will never line up.

No local row unless the CRM returns 200

The mirror is written only inside the if ($mappedResponse->getStatusCode() == 200) guard (CustomerRequestController.php:48). A CRM outage means the owner may still get a mapped error back, but nothing lands in user_requests — so the request is invisible to the shopper-admin count-per-service-type analytics even though the owner tried to submit it. Because the owner reads their list back from the CRM directly (not the mirror), a request that reached the CRM but failed to mirror will still show in their list yet be missing from portal analytics.

unit_service is always authed — no orphan rows

Because POST units/{publishedUnitShopper}/customer-requests sits inside the auth:sanctum + ability:ACCESS_SHOPPER_API group (routes/api/shopper.php:93-96,136-139), Auth::user() is always a real Shopper, so user_id is never null. This is the opposite of the referral path, where POST leads is outside the authed group and an owner-less (user_id = null) row is possible.

The mirror is deliberately thin — the CR detail fields never persist locally

UserRequest’s $fillable is only seven columns — user_id, user_type, unit_type_id, request_type, service_type, created_at_dm, country_code (app/Models/UserRequest.php:15-23). Everything else the form collects — request_details, change_contact_details, preferred_time_of_contact, preferred_way_of_contact, and the three sign_contract_* fields — is sent to the CRM but dropped by mass-assignment on the local write. The portal row cannot reconstruct the request; only the CRM can.

country_code is left null on the unit-service mirror

formatUserRequestData sets unit_type_id and the destination_slug pivot but never sets country_code (CustomerRequestController.php:97-107) — even though the action already resolved the unit’s country slug for the CRM country header (SubmitUnitService.php:20). So unit_service rows carry a populated destination pivot but a null country_code, an asymmetry worth remembering when querying user_requests across request_type.

Where to go next

Referrals & resell assistanceThe sibling Pre-Delivery owner requests — the referral and unit_resale UserRequest variants that share this page's CRM-mirror shape.

Shopper buys a unitThe purchase that puts a shopper into the Pre-Delivery owner area in the first place.

Submitting an EOIAnother CRM-mirrored request flow — agent-initiated and client-paid, with its own local mirror.

Verified, not guessed

Every claim here is traced to a file and line in the current backend (routes/api/shopper.php, CustomerRequestController, SubmitUnitService, SaveUserRequest, SubmitUnitServiceRequest, and the UnitServiceRequestCodeEnum / UserRequestsEnums enums) and cross-checked against docs-site/_inventory/backend-api.md and data-model.md. The 14 CR_* codes, the slug-to-service_code mapping, the 200-only mirror guard, and the uppercase-name-vs-CRM-value mismatch are all read from source.