prestashop-bridge-v1（Prestashop 桥 v1）

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: GET
• endpoint: /v1/products/{id}
• sync: true
• scope: bridge:read
• params:

- id integer, required

• success: 200

get_order

• method: GET
• endpoint: /v1/orders/{id}
• sync: true
• scope: bridge:read
• params:

- id integer, required

• success: 200

get_job_status

• method: GET
• endpoint: /v1/jobs/{jobId}
• sync: true
• scope: bridge:read
• note: job status is read from MySQL, not from Redis
• success: 200

update_product

• method: POST
• endpoint: /v1/jobs/products/update
• sync: false
• scope: bridge:write
• idempotency: X-Request-ID required
• payload:

- product_id - updates.price_ht - updates.stock_delta - updates.seo - options.skip_reindex

• success: 202

import_products

• method: POST
• endpoint: /v1/jobs/products/import
• sync: false
• scope: bridge:write
• idempotency: request id required and stable batch_id
• payload:

- batch_id - items - options

• constraints:

- maximum 50 items - maximum payload size 10MB

• success: 202

update_order_status

• method: POST
• endpoint: /v1/jobs/orders/status
• sync: false
• scope: bridge:write
• idempotency: X-Request-ID required
• payload:

- order_id - new_status - notify_customer - tracking_number

• success: 202

Security

Required headers on protected routes

• Authorization: Bearer {jwt_rs256_token}
• X-Request-ID: {uuid_v4}
• X-Timestamp: {unix_seconds}
• X-Signature: {hmac_sha256_hex}
• Content-Type: application/json
• Accept: application/json

Compression

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

OAuth2

• flow: client_credentials
• token endpoint: /oauth/token
• JWT algorithm: RS256
• TTL: 3600
• scopes:

- bridge:read - bridge:write

HMAC

String to sign:

METHOD + "\ " + URI + "\ " + TIMESTAMP + "\ " + REQUEST_ID + "\ " + BODY_SHA256

Exact example:

• method: POST
• uri: /v1/jobs/products/update
• timestamp: 1710950400
• request id: f47ac10b-58cc-4372-a567-0e02b2c3d479
• body sha256: 37abd647733fbd18a3f11fb5a082fe59c62719d9fe833aec96b28ccea36b70ba
• signature: 448e251d1c71078b07a10baf4094fd2686bcebef97761c4729a921f71798554c

Response handling

• 200 OK: synchronous read success or completed idempotent replay.
• 202 Accepted: job accepted only. Always poll /v1/jobs/{jobId}.
• 400 Bad Request: schema validation failed.
• 401 Unauthorized: JWT missing, invalid, or expired.
• 403 Forbidden: invalid HMAC, invalid timestamp window, or insufficient scope.
• 409 Conflict: idempotency conflict or known failed replay.
• 422 Unprocessable Entity: valid JSON but impossible business transition.
• 429 Too Many Requests: wait for Retry-After.
• 500 Internal Server Error: unexpected server failure.
• 503 Service Unavailable: 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.