External integrations

This area covers the external services the ecosystem depends on (cahier §2 Services externes, §11). Each provider sits behind an adapter in the server module integrations (and files, notifications), with a simulator in local and staging environments. The technical details (keys, quotas, webhooks, store declarations) are in integrations. All provider accounts belong to HOCO (D-25).

ID	Requirement	Release	Priority	Source	Apps
INT-01	Maps provider (Google Maps or Mapbox) for maps, routes and geocoding	V1	MUST	§11	DA · BO · API
INT-02	Firebase Cloud Messaging	V1	MUST	§11	API · RA · DA
INT-03	SMS gateway for OTP, invitations, confirmations and reminders	V1	MUST	§11	API
INT-04	Transactional email	V1	MUST	§11	API
INT-05	S3-compatible file storage for photos, invoices and documents	V1	MUST	§11	API
INT-06	ERP / accounting import-export (files in V1, API in V2)	V2	SHOULD	§11	API
INT-07	External costs, quotas and approval delays of every provider identified and validated by the client	V1	MUST	§11	OPS

INT-01 — Maps providerCopy Anchor Link

Statement — The system shall use one maps provider for maps, routes and geocoding in the delegate app and the back-office.

Rules

1. Default: Google Maps Platform — Maps SDK for Android (delegate app), Maps JavaScript API (BO-06, BO-10, BO-19, BO-22, BO-23, BO-25), Routes for the next destination's ETA, Geocoding (optional, GEO-04). Mapbox is the alternative (D-14).
2. Keys per environment and app, restricted by Android package and certificate or by HTTP referrer; budget alerts at 50 / 90 % of the monthly budget.
3. Calls are economised: ETA only for the next stop, at most every 2 minutes or 500 m; distances in lists are computed locally (Haversine); offline the apps fall back to straight-line distance.

Acceptance criteria

• The delegate map and the back-office live map render on staging with restricted keys; a key used from another package is refused by the provider.

Data — none stored beyond coordinates.

Interfaces — SDKs (no HOCO endpoint).

INT-02 — Firebase Cloud MessagingCopy Anchor Link

Statement — Push notifications shall be delivered through FCM.

Rules

1. One Firebase project per flavor (dev, staging, prod); the server calls the FCM HTTP v1 API with a service account kept in secrets; per-device tokens (no topics).
2. Tokens invalidated by FCM are removed; iOS needs an APNs key only if iOS is decided (D-10).

Acceptance criteria

• A staging event delivers a push to a staging build and not to a production build.

Data — Device, NotificationDelivery.

Interfaces — FCM HTTP v1.

INT-03 — SMS gatewayCopy Anchor Link

Statement — The system shall send SMS (OTP, confirmations, reminders and, if enabled, invitations) through an SMS gateway.

Rules

1. Provider to choose (D-13); adapter interface send(to, text, purpose) with delivery reports when the provider offers them; sender id HOCO registered with the operators (allow several weeks).
2. OTP limits of the platform apply (1 per 60 s, 5 per hour per phone); 3 retries on transient errors; failures visible in the delivery log; a dev simulator logs messages instead of sending them.

Acceptance criteria

• An OTP is received on Mobilis, Djezzy and Ooredoo numbers within 30 seconds in pre-production.

Data — NotificationDelivery, Verification.

Interfaces — provider API.

INT-04 — Transactional emailCopy Anchor Link

Statement — The system shall send transactional email through an SMTP or API provider.

Rules

1. SPF, DKIM and DMARC configured on the sending domain (D-12); bounces and complaints recorded; Mailpit in local development.
2. Uses: staff invitations and resets, export ready, ticket assignment, documents to resellers who gave an email.

Acceptance criteria

• A staff invitation reaches a Gmail inbox (not spam) with DKIM pass.

Data — NotificationDelivery.

Interfaces — provider API or SMTP.

INT-05 — S3-compatible file storageCopy Anchor Link

Statement — Photos, invoices and documents shall be stored in S3-compatible object storage.

Rules

1. Two buckets: public (product images, brand logos, banners — behind a CDN) and private (store photos and documents, visit photos, payment and delivery proofs, ticket attachments, generated PDFs, imports, exports). MinIO locally; production provider per D-15.
2. Upload: files.createUpload returns a pre-signed PUT URL valid 10 minutes; files.completeUpload checks size and type per FilePurpose, strips EXIF and creates thumbnails; private reads through 5-minute signed GET URLs (SEC-04).
3. Lifecycle: uploads never completed are deleted after 24 h; exports after exports.retentionDays; private bucket encrypted at rest and backed up (SEC-05).

Acceptance criteria

• A 6 MB visit photo is refused at completion (limit 5 MB); a private file URL stops working after 5 minutes.

Data — File.

Interfaces

• Endpoints: files.createUpload · files.completeUpload

INT-06 — ERP / accounting import-export (V2)Copy Anchor Link

Statement — The system should exchange invoices, payments and credit notes with HOCO's accounting or ERP system.

Rules

1. V1 provides file exports of the back-office lists (ANA-05); V2 adds the accounting export format or API agreed once HOCO's system is identified (D-34).

Acceptance criteria

• A monthly accounting export imports into HOCO's accounting software without manual edits.

Data — Invoice, Payment, CreditNote, ExportJob.

Interfaces — none in V1.

INT-07 — Provider costs, quotas and delays validated by HOCOCopy Anchor Link

Statement — The costs, accounts, subscriptions, API limits and approval delays of every external provider shall be identified separately and validated by HOCO.

Rules

1. A provider register lists, per provider (maps, FCM, SMS, email, storage and hosting, Google Play, Apple if decided, WhatsApp Business in V2): account owner (HOCO), pricing model and estimate for the pilot and generalisation volumes, quotas, approval delays (Play developer verification, SMS sender id, Apple review) and the decision id.
2. Accounts with long approval delays are opened during cadrage so they do not delay the January go-live of the three-month frame.
3. HOCO signs off the register at the cadrage workshop (PRJ-03); changes are re-validated.

Acceptance criteria

• The register is signed before the go-live and every production provider account is in HOCO's name.

Data — none (project document).

Interfaces — none.