PrestaShop Bridge V1

PrestaShop Bridge V1 is a secure operational contract for AI agents and Python handlers that need to interact with a PrestaShop 9 store through a stable interface. It standardizes OAuth2 authentication, HMAC request signing, rate limiting, asynchronous writes, idempotency, and durable job polling.

Operating model

• - Reads are synchronous.
• Writes are asynchronous.
• Redis is used only for Messenger transport and temporary HTTP idempotency cache.
• MySQL is the source of truth for job status, business idempotency, and failed jobs.
• A 202 Accepted response means only that a job was accepted for processing. It never means business success.

Capabilities

get_product

• - method: INLINECODE1
• endpoint: INLINECODE2
• sync: INLINECODE3
• scope: INLINECODE4
• params:

• - success: INLINECODE6

get_order

• - method: INLINECODE7
• endpoint: INLINECODE8
• sync: INLINECODE9
• scope: INLINECODE10
• params:

• - success: INLINECODE12

getjobstatus

• - method: INLINECODE13
• endpoint: INLINECODE14
• sync: INLINECODE15
• scope: INLINECODE16
• note: job status is read from MySQL, not from Redis
• success: INLINECODE17

update_product

• - method: INLINECODE18
• endpoint: INLINECODE19
• sync: INLINECODE20
• scope: INLINECODE21
• idempotency: X-Request-ID required
• payload:

• - success: INLINECODE28

import_products

• - method: INLINECODE29
• endpoint: INLINECODE30
• sync: INLINECODE31
• scope: INLINECODE32
• idempotency: request id required and stable INLINECODE33
• payload:

• - constraints:

• - success: INLINECODE39

updateorderstatus

• - method: INLINECODE40
• endpoint: INLINECODE41
• sync: INLINECODE42
• scope: INLINECODE43
• idempotency: X-Request-ID required
• payload:

• - success: INLINECODE49

Security

Required headers on protected routes

• - INLINECODE50
• INLINECODE51
• INLINECODE52
• INLINECODE53
• INLINECODE54
• INLINECODE55

Compression

• - gzip recommended above 1024 bytes
• gzip required above 32768 bytes

OAuth2

• - flow: INLINECODE58
• token endpoint: INLINECODE59
• JWT algorithm: INLINECODE60
• TTL: INLINECODE61
• scopes:

HMAC

INLINECODE64

Exact example:

• - method: INLINECODE65
• uri: INLINECODE66
• timestamp: INLINECODE67
• request id: INLINECODE68
• body sha256: INLINECODE69
• signature: INLINECODE70

Response handling

• - 200 OK: synchronous read success or completed idempotent replay.
• INLINECODE72: job accepted only. Always poll /v1/jobs/{jobId}.
• INLINECODE74: schema validation failed.
• INLINECODE75: JWT missing, invalid, or expired.
• INLINECODE76: invalid HMAC, invalid timestamp window, or insufficient scope.
• INLINECODE77: idempotency conflict or known failed replay.
• INLINECODE78: valid JSON but impossible business transition.
• INLINECODE79: wait for Retry-After.
• INLINECODE81: unexpected server failure.
• INLINECODE82: service degraded or Redis unavailable.

Absolute refusal rules

• - Never report business success immediately after a 202.
• Never modify TTC price directly. Only HT price may be changed.
• Never delete a product that has associated orders.
• Never access the database or filesystem directly.
• Never send payloads larger than 10MB.
• Never perform heavy writes synchronously.
• Never reuse an X-Request-ID for a different business intention within 24 hours.

Pre-deployment checks

• - Verify JWT issuance and validation with RS256 only.
• Verify the exact HMAC example in examples.http.
• Verify schema validation for all request bodies.
• Verify Redis-backed idempotency replay behavior.
• Verify MySQL-backed job polling after Redis restart.
• Verify idempotent handlers under at-least-once delivery.