Support & claims

This area covers the reseller's requests and claims and their handling by HOCO (cahier §2.1 « demandes SAV et réclamations », §5, §14.1), extended by the decisions of 17 Oct 2026: after-sales service is V1 and a regional WhatsApp support button is shown in both reseller apps (AUTHORING §1b.8, §1b.9). Apps: reseller app and web, back-office, API. Server module: support (tickets, after-sales claims, support regions), with orders for replacement orders and returns and billing for credit notes. Statuses are in the lifecycles page.

ID	Requirement	Release	Priority	Source	Apps
SUP-01	Reseller tickets: type, related order, message, attachments, conversation, statuses	V1	MUST	§2.1, §5, §14.1	RA · RW · API
SUP-02	Back-office ticket handling: assignment, internal notes, replies, statuses, notifications	V1	MUST	§2.1	BO · API
SUP-03	Support contacts and FAQ	V1	SHOULD	§5	RA · RW
SUP-04	After-sales service (SAV): a reseller opens a claim on an order (items, quantities, issue, photos); the back-office handles it from diagnosis to resolution (replacement, return, credit note, rejection)	V1	MUST	Team decision (17 Oct 2026), §2.1	API · BO · RA
SUP-05	Regional WhatsApp support: a fixed WhatsApp button in both reseller apps opens the support number of the user's region — declared region when signed in, device location otherwise	V1	MUST	Team decision (17 Oct 2026)	RA · RW · API · BO

SUP-01 — Reseller ticketsCopy Anchor Link

Statement — The system shall let a reseller open a ticket with a type, a subject, a message, an optional related order and attachments, follow the conversation and its status, and close it.

Rules

1. Fields: TicketType (AFTER_SALES, ORDER_ISSUE, DELIVERY_ISSUE, BILLING, QUESTION, OTHER), subject (5 to 120 characters), message (10 to 2 000 characters), related order (required for ORDER_ISSUE, DELIVERY_ISSUE and AFTER_SALES; must be the reseller's own, else 404 NOT_FOUND), up to 5 attachments (TICKET_ATTACHMENT, JPEG/PNG/PDF, ≤ 10 MB each). AFTER_SALES adds the fields of SUP-04.
2. Number TKT-2026-000045 at creation; statuses OPEN, IN_PROGRESS, WAITING_RESELLER, RESOLVED, REJECTED, CLOSED with the French labels of enums.json.
3. The reseller sees only public messages, never internal notes; replies are allowed until CLOSED (409 TICKET_TRANSITION_NOT_ALLOWED after); a reply to WAITING_RESELLER, RESOLVED or REJECTED moves the ticket back to IN_PROGRESS.
4. The reseller may close a ticket at any time with an optional 1–5 rating; tickets RESOLVED, REJECTED or WAITING_RESELLER without reply close automatically after support.autoCloseDays (7), with a reminder at half the delay.
5. Agent replies and status changes reach the open app live (ticket.replied on events.stream) and as push plus inbox notification.
6. Accounts PENDING_VALIDATION may open QUESTION tickets (e.g. about their validation).

Acceptance criteria

• A reseller opens a DELIVERY_ISSUE ticket on order CMD-2026-000158 with a photo; it gets a TKT-… number and appears in the back-office queue.
• A reply by the agent shows in the open conversation within 5 seconds and as a push when the app is closed.
• A reply to a CLOSED ticket → 409 TICKET_TRANSITION_NOT_ALLOWED; referencing another reseller's order → 404 NOT_FOUND.

Data — Ticket, TicketMessage, TicketItem, File, Order, Notification.

Interfaces

• Screens: RA-32 Support · RA-33 New ticket / after-sales claim · RA-34 Ticket conversation · RW-14 Support
• Endpoints: tickets.list · tickets.create · tickets.get · tickets.reply · tickets.close

SUP-02 — Back-office ticket handlingCopy Anchor Link

Statement — The system shall let support staff triage, assign, answer and close tickets, with internal notes and notifications.

Rules

1. Queue (BO-55): filters by status, type, assignee, priority, reseller, wilaya, delegate, age; default sort oldest unanswered first; unassigned and overdue tickets highlighted.
2. Detail (BO-56): conversation, internal notes (never visible to the reseller), related order and its timeline, reseller summary, attachments through signed URLs.
3. Actions with support.update: assign to a staff user, set priority (normal, high, urgent — assumption: the priority enum is not yet in enums.json), reply (optionally as a question → WAITING_RESELLER), resolve a non-SAV ticket; SAV resolutions need support.validate (SUP-04).
4. First public reply or assignment moves OPEN → IN_PROGRESS and records the first-response time; target: first response within 1 working day (support KPI).
5. Notifications: new ticket → in-app to support staff; assignment → in-app and email to the assignee; reseller reply → assignee.
6. Each ticket appears on the reseller's timeline (Interaction CLAIM) and in the order's history when linked. All actions are audited.

Acceptance criteria

• Assigning a ticket moves it to IN_PROGRESS, notifies the assignee and records the first-response time.
• An internal note never appears in tickets.get for the reseller.
• A user without support.update gets 403 PERMISSION_DENIED on reply.

Data — Ticket, TicketMessage, Interaction, Notification, AuditLog.

Interfaces

• Screens: BO-55 Tickets list · BO-56 Ticket detail
• Endpoints: admin.tickets.list · admin.tickets.get · admin.tickets.reply · admin.tickets.update

SUP-03 — Support contacts and FAQCopy Anchor Link

Statement — The reseller apps shall show HOCO's support phone, hours and a FAQ.

Rules

1. support.contacts returns the support phone (opened with tel:), opening hours and FAQ entries (question, answer, category, order) in the caller's language with French fallback; WhatsApp support is the regional button of SUP-05.
2. Assumption — FAQ entries and the support phone are business settings edited in BO-64 (no dedicated screen in the inventory).
3. Outside hours the screen shows « Service fermé — réponse dès l'ouverture » and still allows a ticket.

Acceptance criteria

• The support screen shows the phone, hours and at least the FAQ entries configured; tapping the phone opens the dialer.

Data — Setting.

Interfaces

• Screens: RA-32 Support
• Endpoints: support.contacts

SUP-04 — After-sales service (SAV) claimsCopy Anchor Link

Statement — The system shall let a reseller open an after-sales claim on items of a delivered order, and let the back-office handle it from diagnosis to a resolution: replacement, return, credit note, repair or rejection.

Rules

1. A claim is a ticket of type AFTER_SALES on one order in status DELIVERED, opened within the after-sales window (afterSales.windowDays, default 30, or the product warranty — D-35) else 422 AFTER_SALES_WINDOW_CLOSED.

2. It lists one or more claimed lines (TicketItem) with quantity ≤ delivered − already claimed or returned, an AfterSalesIssue (DEFECTIVE, DAMAGED, WRONG_ITEM, MISSING_ITEM, NOT_AS_DESCRIBED, OTHER), a description, and at least one photo.

3. Diagnosis: the agent may ask for more evidence (WAITING_RESELLER).

4. Resolution with support.validate (admin.tickets.resolve), AfterSalesResolution:

   Resolution	Effect
   REPLACEMENT	a free replacement order is created in SUBMITTED and waits for confirmation like any order (ORD-14)
   RETURN	a return is created in APPROVED; its reception re-enters accepted quantities into stock and issues a credit note (ORD-13)
   CREDIT_NOTE	a credit note without physical return, amount ≤ claimed lines at order prices (FIN-08)
   REPAIR	repair note and expected date
   REJECTED	reason required (out of warranty, misuse, outside the window) → status REJECTED; the reseller may contest once

5. Generated orders, returns and credit notes carry the ticket id and are linked both ways (BO-56, BO-69). Every resolution notifies the reseller (push, inbox, live event) and is audited.

6. Returns can also be requested directly on a delivered order (RA-40, returns.create).

Acceptance criteria

• A reseller claims 2 of 10 delivered chargers as DEFECTIVE with a photo; the claim gets a TKT-… number; resolving with REPLACEMENT creates a free order for 2 chargers in SUBMITTED linked to the ticket.
• Resolving with RETURN creates an APPROVED return; after reception, a RETURN stock movement and a credit note exist.
• Claiming 11 of 10 delivered units → 400 VALIDATION_FAILED; a claim 60 days after delivery (window 30) → 422 AFTER_SALES_WINDOW_CLOSED; resolving without support.validate → 403 PERMISSION_DENIED; REJECTED without reason → 400 VALIDATION_FAILED.

Data — Ticket, TicketItem, TicketMessage, Order, OrderItem, ReturnRequest, ReturnItem, CreditNote, StockMovement, File, AuditLog.

Interfaces

• Screens: RA-32 Support · RA-33 New ticket / after-sales claim · RA-40 Return request · BO-56 Ticket detail · BO-69 Returns & after-sales claims · RW-14 Support
• Endpoints: admin.tickets.resolve — related: tickets.create, returns.create

Notes / open points — Windows, warranty rules and the treatment of defective units are D-35.

SUP-05 — Regional WhatsApp supportCopy Anchor Link

Statement — Both reseller apps shall show a fixed WhatsApp button that opens the support number of the user's support region.

Rules

1. The button is visible on every main screen of RA and RW, for guests too (guest mode, AUTH-10).
2. Region resolution by support.whatsapp, in this order: signed in → the region of the wilaya declared on the reseller's account; guest with location permission → device position → nearest commune centroid → wilaya → region (lat/lng parameters; the position is not stored); otherwise the wilaya chosen in a picker (wilayaCode); otherwise support.defaultWhatsappNumber.
3. Response: E.164 number, https://wa.me/213… link with a pre-filled text (« Bonjour, je suis Magasin El Wafa (REV-000123)… » when signed in), region name and hours; outside hours the button still opens WhatsApp and the screen shows the hours.
4. Regions, their wilayas, numbers and hours are managed in BO-70 (ADM-08).

Acceptance criteria

• A reseller whose wilaya is Oran (region Ouest) gets the Ouest number; a guest located in Constantine gets the Est number; a guest refusing location picks a wilaya and gets its region's number.
• With no region covering the wilaya, the default number is returned.

Data — SupportRegion, SupportRegionWilaya, Wilaya, Commune, Reseller, Setting.

Interfaces

• Screens: RA-09 Home · RA-32 Support · RW-14 Support · BO-70 Support regions & WhatsApp numbers
• Endpoints: support.whatsapp · admin.supportRegions.crud

Notes / open points — Number of regions and their numbers: D-36 (default: one national number at launch).