Integrations
Every external service and platform the ecosystem depends on — maps, device location, push, real-time streams, SMS, email, WhatsApp, file storage, carriers, ERP and accounting, the stock system and the app stores — with purpose, release, data exchanged, configuration, failure modes, costs to validate and the decision each depends on.
Cahier §11 lists the integrations « à confirmer » — cartography, push notifications, WhatsApp, SMS and email, delivery, ERP and accounting, stock, file storage — and adds: « Les frais, comptes, abonnements, limites d'API et délais de validation imposés par les fournisseurs externes doivent être identifiés séparément et validés par le client » (INT-07). This page is that inventory. Each section ends with what HOCO has to validate and the decision it depends on in the decision register.
Design rule. Every external provider sits behind an adapter interface in the server's integrations module, with a development simulator (SRV-08): the business modules call sms.send, push.send, email.send, geo.reverse, storage.presignPut… never a vendor SDK. Changing provider means a new adapter and new environment variables, not changes across modules. Every outbound call has a timeout, a retry policy for transient errors and a circuit breaker; failures are logged with the provider's message id and never with personal content (logging).
Overview
| Integration | Purpose | Release | Owner (build · account) | Depends on |
|---|---|---|---|---|
| Maps | Delegate maps and navigation, back-office maps, geocoding | V1 | Imad, Anis · HOCO billing | D-14 |
| Device location | Check-in, tour sampling, support region of a guest | V1 | Imad, Anis | D-06, D-07, D-24 |
| Push (FCM) | Notifications to the two Flutter apps | V1 | Imad, Anis · HOCO Firebase | D-25 |
| Real-time streams (SSE) | Live order status for resellers, live back-office | V1 | Anis, Imad | D-15 (proxy and hosting) |
| SMS | One-time codes and critical messages | V1 | Anis · HOCO contract | D-13 |
| Staff emails, digests, invoices | V1 | Anis · HOCO domain | D-12 | |
| V1 links: invitations, regional support, sharing · V2 automated messages | V1 / V2 | Imad, Anis · HOCO numbers | D-36 | |
| File storage | Photos, documents, proofs, generated PDFs, backups | V1 | Anis · HOCO | D-15 |
| Delivery carriers | V1 structured manual · V2 shipment API | V1 / V2 | Anis · HOCO contracts | D-08 |
| ERP and accounting | V1 file exports · V2 API | V1 / V2 | Anis · HOCO | D-34, D-21 |
| Stock system | V1 import · V2 synchronisation | V1 / V2 | Anis · HOCO | D-34, D-31 |
| App stores | Distribution of the two apps | V1 | Imad · HOCO accounts | D-10, D-25 |
A practical constraint applies to several of them: Google Cloud, Firebase billing, Mapbox, Apple, the Google Play registration and Meta all need an internationally accepted payment card and, for organization accounts, a D-U-N-S number. HOCO should start these steps at the cadrage.
Maps
Cahier §11 « Google Maps, Mapbox ou service équivalent pour adresses, itinéraires et géocodage »; INT-01, GEO-04, FLD-07.
Uses. Delegate app: tour map and mini-map (DA-06, DA-08), prospects map (DA-13), GPS capture at sign-up. Back-office: resellers map (BO-10), zone editor (BO-19), live map (BO-06), tour trail (BO-23). Server: reverse geocoding of a captured point to suggest wilaya and commune (COULD). Turn-by-turn navigation is handed to the phone's navigation app (Google Maps or Waze intent) — no routing API cost.
| Criterion | Google Maps Platform | Mapbox |
|---|---|---|
| Coverage in Algeria | Dense road network including small communes; rich points of interest and business listings | OpenStreetMap-based; good in large cities, thinner in rural communes; fewer points of interest |
| Geocoding of Algerian addresses | The strongest available; informal addresses (« à côté de la poste ») still resolve to the right commune | Weaker on street-level Algerian addresses; reverse geocoding to commune acceptable |
| Flutter SDK | google_maps_flutter — first-party plugin, already in the planned stack | mapbox_maps_flutter — official plugin; a second map stack to learn |
| Back-office (web) | Maps JavaScript API | Mapbox GL JS |
| Pricing model (as published in 2025 — re-check at decision time) | Pay-as-you-go per SKU with a monthly free allowance per SKU; native mobile SDK map loads are free | Free tiers per product (mobile monthly active users, web map loads, geocoding requests), then per-unit pricing |
| Expected HOCO volume | Mobile maps free; back-office map loads and geocoding around or under the free allowances at generalisation | Within free tiers at generalisation |
| Offline behaviour | SDK caches recently viewed tiles; list view and distances work offline | Offline packs available (more control, more work) |
Recommendation — decision D-14: Google Maps Platform, with distances computed on device and server by haversine (no routing API in V1) and external navigation for directions.
| Field | Value |
|---|---|
| Release | V1 |
| Data exchanged | Map tiles to the device; store coordinates sent to the geocoding API (reverse geocoding of business locations only — never the delegate's tracking points) |
| Configuration | GOOGLE_MAPS_SERVER_KEY (server, restricted to the Geocoding API and the server IP) · NEXT_PUBLIC_GOOGLE_MAPS_BROWSER_KEY (back-office, restricted by HTTP referrer) · Android key per flavor in the manifest placeholders (restricted by package name and signing certificate SHA-1) · iOS key if D-10 |
| Failure modes and fallbacks | Tiles unavailable or offline → the delegate keeps the ordered list, distances and the « Arrivé » check-in (GPS needs no network); geocoding fails or quota reached → manual wilaya and commune pickers, which are mandatory anyway; key revoked → blank map, list view still works; alert on error rate |
| Costs and quotas for HOCO to validate | Billing account and payment card; monthly budget alert (for example at 20 and 50 USD); key restrictions |
| Owner | Imad (mobile setup, MOB-10), Anis (server and back-office, DSH-08); HOCO owns the billing account |
Device location
Not a paid service, but a platform dependency with privacy rules (SEC-07, cross-cutting privacy).
| Use | App | Precision | When | Stored |
|---|---|---|---|---|
| Check-in at a point of sale | DA | High, accuracy ≤ 100 m required | On « Arrivé » | Yes — with the visit |
| Tour sampling | DA | Balanced, every 5 min or 200 m | Only while the tour is IN_PROGRESS (foreground service, D-24) | Yes — 90 days |
| GPS capture of a new point of sale | DA | High | On the sign-up form | Yes — on the reseller |
| Support region of a guest | RA, RW | Low (about 5 km is enough) | Only when a guest taps the WhatsApp button and no wilaya is known | No — used once to resolve the region |
Region detection (SUP-05) for the WhatsApp button, implemented by support.whatsapp:
- Signed in → the wilaya of the reseller's account → its support region.
- Guest, location allowed → the app reads a coarse position (
geolocatorwith low accuracy and a 5-second timeout on mobile; the browser Geolocation API on the reseller web, HTTPS only) and sendslatandlng; the server finds the nearest commune centroid, hence the wilaya and the region; the coordinates are not stored or logged. - Guest, location refused, unavailable or timed out → a wilaya picker; the choice is remembered on the device.
- Still nothing (picker dismissed) → the default region's number.
Assumption — the commune reference data carries centroid coordinates; their source (official list or an open geographic dataset) is checked in SRV-10. IP-based geolocation is not used (imprecise in Algeria and another provider).
| Field | Value |
|---|---|
| Release | V1 |
| Platform services | Android fused location (Google Play services) through geolocator; browser Geolocation API |
| Failure modes and fallbacks | GPS off → DA-28 state with a shortcut to settings; poor accuracy → « Précision insuffisante », retry; mock location → refused at check-in (422 GPS_MOCK_LOCATION); permission refused by a guest → wilaya picker |
| Risk | Phones without Google Play services (some recent models of certain brands): no fused location, no FCM, no Google Maps. The reseller app still works (live updates while open, inbox); the delegate app should run on approved phones with Google Play services (Assumption, to agree with HOCO) |
| Owner | Imad (MOB-10, MDA-12, MRA-08); Anis (server resolution) |
Push notifications — FCM
Cahier §11 « Firebase Cloud Messaging ou service équivalent »; INT-02, NOT-02. What is sent and when is in the notifications matrix.
| Field | Value |
|---|---|
| Release | V1 |
| Projects | One Firebase project per flavor — hoco-dev, hoco-staging, hoco-prod — each holding both Android apps (reseller and delegate, with the flavor's application id suffix, see the mobile guide); separate projects keep test pushes away from production devices |
| Server SDK | firebase-admin for Node, FCM HTTP v1 API with a service account (the legacy API no longer exists); batched sending for announcements and promotions |
| Token lifecycle | The app obtains the token after sign-in and registers it with me.devices.register (Device: device id, platform, app version, token, last seen); re-registers on token refresh and at least every 30 days at app start; auth.logout unregisters it; the server deletes a token on FCM UNREGISTERED or invalid-token errors and prunes tokens inactive for 60 days; one device carries one signed-in user at a time |
| Data exchanged | Device token; notification title and body; data payload (notificationId, eventKey, route, entityId). Push content transits through Google: no codes, passwords, quantities or personal data beyond the store name |
| Configuration | FCM_PROJECT_ID, FCM_SERVICE_ACCOUNT_JSON (base64, server secret) · google-services.json per flavor in the mobile build (injected by CI) · APNs key uploaded to Firebase if iOS |
| Failure modes and fallbacks | FCM outage or quota → retries with backoff within the TTL, then dropped; the inbox row exists and the app refreshes its badge on resume — no SMS fallback. Aggressive battery savers delay delivery: the delegate app asks to be excluded from battery optimisation. Runbook push outage in operations |
| Costs and quotas for HOCO to validate | No per-message charge; Firebase project ownership (D-25) |
| Owner | Imad (MOB-08), Anis (SRV-08); HOCO owns the projects |
Real-time streams — SSE
Server-Sent Events are served by our own API, but they depend on the proxy and hosting chain and on client behaviour, so they are specified here (ORD-15, SYN-07, SRV-26).
| Stream | Operation | Clients | Authentication | Events |
|---|---|---|---|---|
| Per user | events.stream — GET /v1/events | Reseller app and web while open; delegate app while open | Mobile: Authorization: Bearer on a streaming HTTP request; web: the session cookie (the browser EventSource cannot set headers) | The caller's own order.status_changed, order.modified, assisted_order.awaiting_confirmation, ticket.replied, return.status_changed, notification.created |
| Back-office | admin.events.stream — GET /v1/admin/events | Back-office pages | Session cookie | Permission-filtered operations events (orders, visits, tours, positions, stock alerts, pending accounts, returns, claims) |
id: 0192f5a3-1c2d-7e40-8b11-6a7d9e2f3c04
event: order.status_changed
data: {"orderId":"0192f4b8-7c1e-7a10-9f00-5b6d2c8e1a01","number":"CMD-2026-000158","status":"SHIPPED","at":"2026-11-03T08:12:00Z"}
: heartbeat| Rule | Value |
|---|---|
| Event id | The outbox event id (UUIDv7, ordered); the client resumes with Last-Event-ID |
| Replay window | 5 minutes of events kept per stream in Redis (SSE_REPLAY_WINDOW_SECONDS=300); older gaps → the client reloads its screen |
| Heartbeat | A comment line every 25 seconds (SSE_HEARTBEAT_SECONDS=25), below proxy idle timeouts |
| Fan-out | Redis pub/sub, so any API replica can serve any user's stream (stateless API, NFR-3.2) |
| Proxy | Response buffering off and long read timeouts on the stream routes (Traefik in Dokploy, and any CDN in front); HTTP/2 to avoid the six-connections-per-domain limit of HTTP/1.1 in browsers |
| Mobile lifecycle | The app opens the stream in the foreground and closes it in the background (battery); pushes cover a closed or background app; reconnect with exponential backoff from 1 to 30 seconds with jitter |
| Payload | Identifiers and the new state only; the client refetches details with its own session — no data the reseller could not read through the API |
| Field | Value |
|---|---|
| Release | V1 |
| Failure modes and fallbacks | Redis down → no live updates (screens refresh on navigation and resume); notifications and inbox unaffected; alert on SSE connection drops and Redis health |
| Costs | Infrastructure only — about 600 concurrent connections at the generalisation peak (sizing) |
| Owner | Anis (server, back-office, reseller web), Imad (MRA-10, MRA-05) |
SMS
Cahier §11 « SMS / Email : OTP, invitations, confirmations et relances »; INT-03, NOT-03, AUTH-07. OTP is on the sign-up and password-reset paths: without SMS, no reseller can sign up.
What is sent. One-time codes and the short critical whitelist (assisted order to confirm, account approved or suspended, password changed, delegate invitation). Invitation shares by SMS are not sent by the server: the delegate app opens the phone's SMS composer with a prefilled text (sms: intent), so it costs HOCO nothing and comes from the delegate's own number (IVT-02).
Provider requirements — evaluation checklist (decision D-13). Candidates are the A2P offers of the three Algerian mobile operators (Mobilis, Djezzy, Ooredoo), Algerian SMS aggregators, or international messaging platforms with Algerian delivery; each is scored on:
| # | Requirement | Pass criterion |
|---|---|---|
| 1 | Alphanumeric sender ID HOCO | Registered and approved on all three networks; approval delay stated in writing |
| 2 | Coverage | Delivery to Mobilis, Djezzy and Ooredoo numbers, number portability handled |
| 3 | API | HTTPS REST with API key, JSON, client reference id, Unicode (UCS-2) and concatenated messages supported; sandbox |
| 4 | Delivery reports | Per-message status (delivered, failed, expired) by signed webhook or polling, with error codes |
| 5 | OTP route | Transactional priority route; p95 delivery under 30 seconds; no night-time throttling |
| 6 | Throughput | At least 10 messages per second sustained |
| 7 | Pricing | Price per segment per network, invoiced in DZD if possible; prepaid balance with a low-balance alert or API |
| 8 | Service | Uptime commitment, status page, support in French with an escalation contact |
| 9 | Data protection | Where messages and logs are stored, retention of message content, data-protection terms (processors) |
| 10 | Test numbers | An allow-list or test mode for non-production environments |
OTP template (GSM-7, one segment): « HOCO : votre code d'inscription est 123456. Il expire dans 5 minutes. Ne le partagez avec personne. » — optionally followed by the 11-character app hash of the Android SMS Retriever API for automatic filling (copy).
| Field | Value |
|---|---|
| Release | V1 |
| Data exchanged | Destination phone (E.164), message text, sender ID; back: provider message id and delivery status |
| Configuration | SMS_PROVIDER (simulator in local and staging by default) · SMS_API_URL · SMS_API_KEY · SMS_SENDER_ID=HOCO · SMS_DLR_WEBHOOK_SECRET · SMS_ALLOWLIST (non-production: only listed numbers receive real messages) · optional SMS_FALLBACK_* for a secondary route |
| Failure modes and fallbacks | Transport errors retried 3 times in 2 minutes for OTP; circuit breaker opens after repeated failures and switches to the secondary route if configured; the user can request a new code after 60 seconds; delivery-rate alert below 90 % over an hour; runbook SMS outage in operations |
| Costs and quotas for HOCO to validate | Unit price per segment and network; sender-ID registration fee and delay; volume estimate in the notifications matrix (≈ 2 000–4 000 SMS in the launch month, then ≈ 500–1 000 per month — Assumption); accents outside GSM-7 and Arabic double the segments |
| Owner | Anis (adapter, SRV-08); HOCO signs the contract and the sender-ID paperwork |
INT-04. Volume is small: staff invitations and password resets, the 08:00 staff digest, export and import results, invoices to resellers who gave an address, security alerts to staff.
| Field | Value |
|---|---|
| Release | V1 |
| Provider | Any SMTP or transactional email service — for example Amazon SES, Postmark, Brevo or Mailgun — or HOCO's own Google Workspace or Microsoft 365 relay; Mailpit locally (OPS-01) |
| Sender | HOCO <notifications@hoco.dz> on a dedicated sending subdomain (for example mail.hoco.dz) so its reputation is separate from HOCO's office mail; Reply-To the support address |
| DNS | SPF v=spf1 include:<provider> -all on the sending domain · DKIM 2048-bit keys published as the provider instructs · DMARC _dmarc.hoco.dz starting at p=none with aggregate reports, moved to p=quarantine after two to four weeks of clean reports · a custom bounce (Return-Path) domain aligned with the sender |
| Data exchanged | Recipient address, subject, body (no passwords except the one-time temporary password of a staff invitation, valid 72 hours) |
| Configuration | SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASSWORD (or the provider's API key) · EMAIL_FROM · EMAIL_REPLY_TO · EMAIL_BOUNCE_WEBHOOK_SECRET |
| Failure modes and fallbacks | 5 retries over an hour; hard bounce → address flagged; no other fallback (the inbox holds the notification) |
| Costs for HOCO to validate | A free or entry tier is enough (under 3 000 emails per month); DNS access for the records |
| Owner | Anis; HOCO provides DNS access (D-12) |
Cahier §11 « Partage de liens et, en option, API WhatsApp Business pour messages automatisés »; §8 lists WhatsApp among notification channels; V2 for automated messages (NOT-08).
V1 — click-to-chat links
All V1 uses are links opened by the user; the server sends nothing on WhatsApp.
| Use | Where | Number | Prefilled text (French) |
|---|---|---|---|
| Regional support button | Fixed button in the reseller app and web, also for guests (SUP-05, RA-32, RW-14) | The support region's number returned by support.whatsapp (region detection) | Signed in: Bonjour HOCO, ici {{storeName}} ({{resellerNumber}}). From a product: adds Produit : {{productName}} (réf. {{sku}}). Guest: Bonjour HOCO, je souhaite des informations sur vos produits. |
| Invitation share | Delegate app DA-16 | The prospect's WhatsApp number, or none (the delegate picks a contact) | Bonjour {{ownerFirstName}}, voici votre invitation HOCO : https://app.hoco.dz/i/{{code}} (code {{codeDisplay}}). |
| Product share | Product detail (RA, RW) | None | Product name and its public product link |
Link format. https://wa.me/<number>?text=<encoded> with the number in international format without +, spaces, dashes or the national leading zero (0550 12 34 56 → 213550123456); https://wa.me/?text=<encoded> lets the user choose the contact.
Encoding rules. Encode the whole text with Uri.encodeComponent (Dart) or encodeURIComponent (JavaScript): UTF-8 percent-encoding, space → %20 (never +), line break → %0A, & → %26, # → %23, ? → %3F, é → %C3%A9. Keep the text under about 1 000 characters. Example — the invitation text above becomes Bonjour%20Karim%2C%20voici%20votre%20invitation%20HOCO%20%3A%20https%3A%2F%2Fapp.hoco.dz%2Fi%2FAB12CD34%20(code%20AB12-CD34).
Opening. Mobile: url_launcher with LaunchMode.externalApplication; when WhatsApp is not installed, wa.me opens in the browser and offers the install. Web: a normal link in a new tab (WhatsApp Web or the desktop app). Outside the region's hours the button still opens WhatsApp and the sheet shows the hours (« Réponse de 8h30 à 17h00, du dimanche au jeudi », values from BO-70).
| Field | Value |
|---|---|
| Release | V1 |
| Data exchanged | None with Meta from our systems; the user's WhatsApp sends the message |
| Configuration | Regions, numbers and hours in SupportRegion and SupportRegionWilaya (ADM-08), edited on BO-70; a default region |
| Failure modes and fallbacks | No region resolved → default number; number not on WhatsApp → the support phone number of support.contacts is shown as an alternative |
| Costs for HOCO to validate | One phone and WhatsApp Business app account per regional number (the app is free); staffing of each number during the published hours (D-36) |
| Owner | Imad (MRA-08, MDA-08), Anis (support.whatsapp, SRV-24, WEB-05) |
V2 — WhatsApp Business Platform
Automated messages (order confirmed or shipped, assisted order to confirm, payment reminders) through Meta's WhatsApp Business Platform (SRV-34).
| Topic | Requirement |
|---|---|
| Account | Meta Business account verified with HOCO's legal documents; a dedicated phone number not used in the WhatsApp app (or migrated); display name approved |
| Templates | Every business-initiated message is a template approved by Meta in a category (utility for order updates and reminders, authentication for codes, marketing for promotions); French and Arabic versions approved separately |
| Consent | Business-initiated messages only to resellers who opted in, with the date recorded; opt-out honoured |
| Messaging limits | New numbers start with a low daily limit of unique recipients that rises with verification and quality rating |
| Webhooks | Delivery statuses (sent, delivered, read, failed) and inbound messages to a signed webhook; inbound replies routed to the support region's agents or a ticket |
| Costs | Per delivered template message, by category and country, on Meta's rate card — re-checked before V2 is committed; marketing costs the most |
| Option | Authentication templates could replace part of the SMS OTP volume — to compare with SMS prices in V2 |
File storage
Cahier §11 « Cloud ou serveur sécurisé pour photos, factures et documents »; INT-05, SEC-04.
Decided (18 Oct 2026): MinIO on the VPS, used through the S3 API. The other options stay listed for reference.
| Option | Notes |
|---|---|
| MinIO on the production server — chosen | Cheapest; same failure domain as the server — backups must go elsewhere |
| Managed S3-compatible storage (for example Backblaze B2, Hetzner, OVHcloud or Scaleway object storage, AWS S3) | Durable, no disks to manage |
| Algerian hosting provider's storage | If D-15 requires data in Algeria; check S3 compatibility, signed URLs and lifecycle rules |
Buckets per environment
| Bucket | Content (FilePurpose) | Access |
|---|---|---|
hoco-<env>-public | PRODUCT_IMAGE, BRAND_LOGO, BANNER_IMAGE | Public read through the CDN (cdn.hoco.dz); immutable file names (file id + size), Cache-Control: public, max-age=31536000, immutable |
hoco-<env>-private | Store photos and documents, visit photos, payment and delivery proofs, ticket and after-sales attachments, avatars, generated documents (invoices, delivery notes, credit notes, exports), import files | No public access; 10-minute signed PUT for uploads, 5-minute signed GET after an access check; versioning on |
hoco-<env>-backups | Encrypted database dumps and WAL archives | Separate credentials, ideally another provider or account; object lock if available |
Key layout: <purpose>/<yyyy>/<mm>/<fileId>.<ext>, derived sizes <fileId>_w320.webp, _w640, _w1280.
Lifecycle rules: abort incomplete multipart uploads after 1 day; a job deletes objects of uploads never completed after 24 hours; exports deleted after 7 days, import files after 90 days; non-current versions expire after 30 days; backups per the 7 daily, 4 weekly, 12 monthly rule; other categories per the retention table.
| Field | Value |
|---|---|
| Release | V1 |
| Configuration | S3_ENDPOINT, S3_REGION, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, S3_BUCKET_PUBLIC, S3_BUCKET_PRIVATE, CDN_PUBLIC_BASE_URL; BACKUP_S3_* with separate credentials; bucket CORS allowing PUT with Content-Type from the web apps' origins |
| Failure modes and fallbacks | Storage unavailable → uploads fail and are retried; the delegate app keeps photos in its offline queue (MOB-11); downloads show a placeholder; generated documents are regenerated on demand |
| Costs for HOCO to validate | Storage per GB-month (about 70–100 GB per year at generalisation), egress for the public bucket, request charges |
| Owner | Anis (SRV-07, OPS-02) |
Delivery carriers
Cahier §4.4 « Affectation du transporteur et suivi de livraison »; §11 « Connexion aux agences disposant d'une API ; sinon gestion manuelle structurée »; DLV-02, DLV-04, DLV-05. Several Algerian delivery companies expose REST APIs; which ones HOCO uses is D-08.
V1 — structured manual. Carrier records (name, DeliveryMode OWN_FLEET or CARRIER, tracking URL template such as https://carrier.example/track/{trackingNumber}, contact, API-capable flag) on BO-43; on shipping the delivery manager enters the carrier and tracking number, or the driver's name and phone for the own fleet; proof of delivery (photo, recipient name) on BO-42. The reseller sees the carrier, tracking number and link live on RA-22.
V2 — shipment API (SRV-34).
| Our data | Carrier field | Mapping note |
|---|---|---|
Address.recipientName, Address.phone | Recipient name, phone | E.164 → national 0XXXXXXXXX if required |
Address.wilayaCode, communeName | Wilaya code (01–58), commune | A mapping table per carrier: commune spellings differ |
Address.addressLine, landmark | Address | — |
Order.number | Reference | CMD-YYYY-NNNNNN |
Totals.totalTtc when CASH_ON_DELIVERY | Amount to collect | Centimes → dinars |
| Package count, weight | Parcels, weight | Recorded at READY |
| Delivery mode | Home or stop-desk | — |
| Carrier events | DeliveryStatus | picked up → SHIPPED; delivered → DELIVERED; failed attempt → FAILED; returned → RETURNED |
| Cash settlement report | Payment (CASH_ON_DELIVERY) | Reconciled by finance |
| Field | Value |
|---|---|
| Release | V1 manual · V2 API |
| Failure modes and fallbacks (V2) | API down → shipment creation queued, manual entry still possible; missed webhook → polling job every 2 hours for shipped orders; webhooks verified by signature and processed idempotently by carrier event id |
| Costs for HOCO to validate | Carrier tariffs per parcel and COD fees (commercial); API access terms |
| Owner | Anis (SRV-17 V1, SRV-34 V2); HOCO's delivery manager for carrier contracts |
ERP and accounting
Cahier §4.7 « Exports comptables et rapports financiers »; §11 « Import, export ou API selon le système existant du client »; INT-06, FIN-09.
| Release | What |
|---|---|
| V1 | Exports of invoices, credit notes and payments as XLSX or CSV (ANA-05) with stable columns: date, document number (FAC-, credit note, PAY-), reseller number (REV-), customer type, HT per VAT rate, VAT, stamp duty, TTC, payment method, allocation; initial import of products and resellers from HOCO's files (D-31) |
| V2 | Accounting journal export in the format HOCO's accountant expects, then an API or scheduled file exchange with the ERP (SRV-32) |
| Field | Value |
|---|---|
| Data exchanged | Financial documents and reseller identifiers (RC, NIF, NIS, AI where required) |
| Failure modes | Export job failure → retried, then FAILED with a notification; V2 sync errors listed for finance with retry |
| To validate with HOCO | The ERP or accounting software in use, its import formats, which system is master for customers and prices (D-34), the legal mentions (D-21) |
| Owner | Anis; HOCO's finance manager and accountant |
Stock system
Cahier §11 « Synchronisation avec le système de stock existant si disponible »; STK-09 (V2).
| Release | What |
|---|---|
| V1 | Initial stock import per warehouse (ADM-06, SRV-27); from go-live the platform records receipts, adjustments, inventories, reservations, shipments and the automatic restocks of cancellations and return receptions — the platform is the stock master unless D-34 decides otherwise |
| V2 | API synchronisation with HOCO's stock system (SRV-37): direction per data (levels pulled or movements pushed), frequency, conflict rule (the system that owns a movement wins) |
| Field | Value |
|---|---|
| Failure modes | Import errors reported row by row before apply (dry-run); V2: sync lag alert, last successful sync shown on the stock dashboard |
| To validate with HOCO | Whether a stock system exists and stays in use after go-live, its API or export capabilities |
| Owner | Anis; HOCO's stock manager |
App stores
Google Play is the V1 channel (NFR-04); the App Store only if D-10 decides iOS. Both are platforms with review rules that can delay a release, so store readiness is a planned task (MOB-14).
| Constraint | Google Play | App Store (if iOS) |
|---|---|---|
| Account | Organization developer account in HOCO's name (D-U-N-S number, identity verification, one-time fee); new personal accounts must run a closed test with a minimum number of testers for 14 days before production — another reason for an organization account | Apple Developer Program organization enrollment (D-U-N-S, annual fee) |
| Tracks and distribution | Internal testing (team), closed testing (pilot users by email list), production with staged rollout | TestFlight, then App Store |
| Location | The delegate app's foreground service of type location needs the foreground-service declaration (with a video) in Play Console; ACCESS_BACKGROUND_LOCATION would need a separate declaration and stricter review (D-24); a prominent in-app disclosure before the permission prompt (DA-04) | Usage description strings; background mode only if needed |
| Data safety | Data safety form: location (delegate app), name, phone, email, photos and files, financial info (payment proofs), device identifiers (push token), crash logs; encryption in transit; how to request deletion | Privacy nutrition labels with the same content |
| Account deletion | Apps that let users create an account must offer an in-app path and a web page to request deletion — the reseller app needs both (data subject requests) | In-app account deletion required |
| Privacy policy | Public URL required (location, camera) — published before closed testing (D-11) | Same |
| Target API level | targetSdk at the level Google Play requires for new apps and updates at submission time | Recent Xcode and SDK |
| Review access | Demo credentials for reviewers (a test reseller and a test delegate on production with a demo tour) | Demo account |
| Review time | Usually hours to a few days; the first submission and sensitive permissions take longer — plan at least a week of margin before the pilot | Usually a day or two |
| App Links | https://app.hoco.dz/.well-known/assetlinks.json lists the Play app-signing and upload certificate fingerprints so invitation links open the reseller app (IVT-04) | apple-app-site-association for universal links |
| Install referrer | The Play Install Referrer API carries the invitation code from the store link to the first open (MRA-09) | No equivalent — the code is typed or carried by the universal link |
| Field | Value |
|---|---|
| Configuration | Play App Signing (Google holds the app-signing key), the upload keystore and its passwords as CI secrets of hoco-mobile, a Play service account for CI uploads limited to release management |
| Costs and delays for HOCO to validate | Registration fees, D-U-N-S lookup delay, review delays, HOCO's ownership of the accounts (D-25) |
| Owner | Imad (MOB-14, MOB-16); Akram for store assets (DQA-01); HOCO owns the accounts |
Offline sync design
The server side of offline sync for the delegate app: what works offline, client ids, idempotency, occurredAt rules, batch replay, the conflict catalogue, the delta feed and its tombstones, photos, location pings, security, observability and test scenarios.
Deployment and operations
Environments, the delivery pipeline, infrastructure sizing, domains, secrets, backups and restore, monitoring and alerts, the initial data import, training, the go-live checklist, the pilot, the maintenance and support model, and the runbook index.