API reference

One API serves the four clients: the back-office, the reseller web, the reseller app and the delegate app. It is plain REST over HTTPS with JSON bodies, declared contract-first in packages/contracts (oRPC routes with Zod request/response schemas) and published as an OpenAPI 3.1 document. Flutter generates its Dart client from that document; the Next.js apps use the typed oRPC client. Nothing is implemented before it exists in the contract — see the API-contract workflow.

The domain hoco.dz is a placeholder until HOCO confirms the final domains (see the decision register).

Operation catalogueCopy Anchor Link

Every page lists its operations with method, path, access rule and the apps that call them, then details each operation: purpose, request (path, query, headers, body), response with a full JSON example, errors, business rules and the requirements it serves. Anchors follow the operation id: cart.checkout → /docs/srs/api/cart-and-checkout#cartcheckout.

Request conventionsCopy Anchor Link

Headers sent by every client

Bodies and fields. JSON, UTF-8, camelCase field names. Unknown fields are rejected (400 VALIDATION_FAILED). Omitted optional fields mean "unchanged" on PATCH; null means "clear".

Identifiers. UUIDv7 strings. For records that can be created offline (field prospects, unplanned visits, visit photos, visit reports, notes) the client generates the UUIDv7 id; the server upserts on it, so a replay never creates a duplicate. Human-readable business numbers are separate fields and always server-generated: REV-000123, CMD-2026-000158, FAC-2026-000123, BL-2026-000123, PAY-2026-000077, TRN-2026-000045, VIS-2026-001234, TKT-2026-000045, RET-2026-000012. Invitation codes are 8 characters (AB12CD34, displayed AB12-CD34).

Enums are UPPER_SNAKE_CASE strings exactly as in the lifecycles and statuses page; clients render the French label themselves (from their l10n files) — the API never sends display labels for enum values.

Money is an integer number of centimes of DZD: 249000 = 2 490,00 DA. Amounts are never floats. Percentages and VAT rates are basis points (1900 = 19 %).

Dates. Timestamps are ISO-8601 UTC strings (2026-11-03T08:12:00Z). Date-only fields are YYYY-MM-DD. "Today", tour days, objectives and reports use the business time zone Africa/Algiers (UTC+1, no DST).

Phones are E.164: +213555123456. The API normalises 0555 12 34 56, 00213… and +213… inputs; responses always return E.164.

Locations: { "lat": 35.6969, "lng": -0.6331, "accuracy": 12, "capturedAt": "2026-11-03T08:12:00Z" } — WGS84 degrees, accuracy in metres.

ResponsesCopy Anchor Link

Single resource: the object itself, no envelope.

Mobile and reseller lists use cursor pagination: ?limit=20&cursor=… (default 20, max 100).

{ "items": [], "nextCursor": "eyJ1IjoiMjAyNi0xMS0wM1QwODoxMjowMFoiLCJpIjoiMDE5MmY0In0" }

nextCursor is opaque and null on the last page.

Back-office tables use offset pagination with totals: ?page=1&pageSize=25&sort=createdAt&order=desc (pageSize max 200).

{ "items": [], "total": 312, "page": 1, "pageSize": 25 }

Filters are query parameters named after the field (status=SUBMITTED&status=PENDING for multi-values; from/to for date ranges; q for free-text search).

ErrorsCopy Anchor Link

Every error has an HTTP status and the same envelope:

{
  "error": {
    "code": "ORDER_MIN_AMOUNT_NOT_MET",
    "message": "Le montant minimum de commande est de 10 000,00 DA.",
    "details": { "minAmount": 1000000, "currentAmount": 845000 },
    "requestId": "req_01J9Z4K7M2"
  }
}

code is stable and documented; message is localised by Accept-Language and safe to show; details is structured data for the client (field errors, limits, conflicting state). Validation errors list fields:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Certains champs sont invalides.",
    "details": { "fields": [{ "path": "store.phone", "code": "INVALID_PHONE", "message": "Numéro invalide." }] },
    "requestId": "req_01J9Z4K7M3"
  }
}

The full code registry is on Errors.

Idempotency and offline replayCopy Anchor Link

Every mutating operation accepts an Idempotency-Key. It is required on cart.checkout, sync.batch, every delegate.* mutation and every operation marked Idempotency-Key in the tables.

• Same key + same body within 30 days → the original status and body are returned with Idempotent-Replayed: true. Nothing is executed twice.
• Same key + different body → 409 IDEMPOTENCY_KEY_REUSED.
• A request still in progress with the same key → 409 IDEMPOTENCY_IN_PROGRESS (retry after a second).

Actions recorded offline carry occurredAt — the device time of the action. The server stores both occurredAt and its own receivedAt, and refuses implausible values (more than 5 minutes in the future or older than 72 hours) with 422 OCCURRED_AT_OUT_OF_RANGE. The delegate app replays its queue through sync.batch — see the offline sync design.

Authentication and authorisationCopy Anchor Link

• Sessions are opaque tokens (Better Auth). Mobile stores the token in secure storage and sends it as a bearer token; the web apps rely on the httpOnly cookie. Reseller and delegate sessions last 30 days and slide with activity; back-office sessions last 7 days and slide (decision pending).
• Permissions are checked on every operation: back-office operations require a permission key <module>.<action> (shown in the Access column); reseller operations are scoped to the caller's own reseller (self); delegate operations to the delegate's zones and assigned resellers (delegate). See the permissions matrix.
• Guests. Operations marked optional in the Access column (catalog, facets, product pages, promotions, banners, the WhatsApp support number, app config, reference data) also answer without a session. Guests never receive prices (price: null, priceLocked: true), cannot use favorites or the cart, and never see stock quantities — nobody outside the back-office does.
• Customer type. A reseller's price for every variant is the variant's price for the reseller's customerType (SUPER_GROS, DEMI_GROS or DETAIL), declared at sign-up and confirmed at validation; promotions apply on top.
• Account status gates everything: SUSPENDED and DISABLED accounts get 403 ACCOUNT_SUSPENDED on any call; PENDING_VALIDATION resellers see the catalog with their prices but get 403 ACCOUNT_PENDING_VALIDATION on checkout.
• Orders are confirmed by people. cart.checkout always creates an order in SUBMITTED; only a back-office user with orders.validate moves it to VALIDATED.

Live eventsCopy Anchor Link

Two Server-Sent Events streams push changes as they happen (text/event-stream, heartbeat every 25 s, resume with Last-Event-ID):

Every event that matters to a user is also delivered as a notification (push + in-app inbox), so nothing depends on the stream being connected.

Shared schemasCopy Anchor Link

These shapes are reused across pages. Field names and types are binding for every operation that returns them.

type Money = number;            // integer centimes of DZD
type BasisPoints = number;      // 1900 = 19 %
type Uuid = string;             // UUIDv7
type Iso = string;              // ISO-8601 UTC timestamp

interface GeoPoint { lat: number; lng: number; accuracy?: number; capturedAt?: Iso }

interface Price {               // a unit price, always both values
  ht: Money;
  ttc: Money;
  vatRate: BasisPoints;
}

interface Totals {
  subtotalHt: Money;            // Σ line HT before discounts
  discountTotal: Money;         // Σ discounts, HT
  deliveryFee: Money;           // HT; 0 = "Offerts"
  vatTotal: Money;
  totalTtc: Money;              // subtotalHt − discountTotal + deliveryFee + vatTotal
  currency: "DZD";
}

interface FileRef {
  id: Uuid;
  url: string;                  // public CDN URL, or a signed URL valid 5 minutes for private files
  thumbnailUrl?: string;
  mimeType: string;
  size: number;                 // bytes
  purpose: string;              // FilePurpose
}

interface UserSummary { id: Uuid; displayName: string; avatarUrl?: string }

interface Address {
  id: Uuid;
  label?: string;               // "Magasin", "Dépôt"
  recipientName: string;
  phone: string;                // E.164
  wilayaCode: string;           // "31"
  wilayaName: string;
  communeId: Uuid;
  communeName: string;
  addressLine: string;
  landmark?: string;
  location?: GeoPoint;
  isDefault: boolean;
}

interface ResellerSummary {
  id: Uuid;
  number: string;               // REV-000123
  storeName: string;
  ownerName: string;
  phone: string;
  wilayaCode: string;
  communeName: string;
  status: string;               // ResellerStatus
  location?: GeoPoint;
}

type CustomerType = "SUPER_GROS" | "DEMI_GROS" | "DETAIL";

interface ProductCard {
  id: Uuid;
  name: string;
  brand: { id: Uuid; name: string };
  category: { id: Uuid; name: string; parentId: Uuid | null };   // sub-category when parentId is set
  imageUrl?: string;
  defaultVariantId: Uuid;
  price: Price | null;          // the caller's price (their customer type's price); null for guests
  priceLocked: boolean;         // true for guests — show "Créez un compte pour voir les prix"
  recommendedPrice?: Money;     // prix conseillé (TTC)
  availability: "IN_STOCK" | "OUT_OF_STOCK";   // never a quantity
  promotion?: { id: Uuid; label: string; price: Price | null };
  isNew: boolean;
  isFavorite: boolean;          // always false for guests
}

interface Issue {               // a non-blocking or blocking problem attached to a cart/order
  code: string;                 // e.g. PRICE_CHANGED, STOCK_INSUFFICIENT
  severity: "BLOCKING" | "WARNING";
  lineId?: Uuid;
  message: string;
  details?: Record<string, unknown>;
}

interface StatusChange {
  from: string | null;
  to: string;
  at: Iso;
  actor: UserSummary | null;    // null = system
  reason?: string;
}

Versioning and change policyCopy Anchor Link

• The version is in the path (/v1). Additive changes (new optional fields, new operations, new enum values announced in advance) stay in v1.
• Breaking changes need a new operation or /v2; the old one is marked deprecated (Deprecation and Sunset headers) and kept for at least two mobile releases.
• Clients must ignore unknown response fields and treat unknown enum values gracefully (generic label, no crash).
• Every contract change is listed in the changelog of the API-contract workflow and announced to Imad before merge.

Rate limitsCopy Anchor Link

Limits answer 429 RATE_LIMITED with Retry-After.