Chatbot Delivery Change Contract

Logidav exposes POST /api/chatbot/delivery/change for menzzo-chatbot-backend. The endpoint returns stable JSON bodies so the chatbot can distinguish functional refusals from technical failures.

Request

{
  "increment_id": "100012345",
  "sale_product_id": 456789,
  "new_mode": "etage",
  "requested_by": "chatbot"
}

Required fields are increment_id, sale_product_id, and new_mode. Valid modes are classic, etage, etage_with_assembly, and retrait. Optional string fields include requested_by, tag, conversation_url, and conversation_link. requested_by is limited to 50 Unicode characters.

Success

Immediate changes return HTTP 200 with DELIVERY_CHANGE_UPDATED.

{
  "success": true,
  "code": "DELIVERY_CHANGE_UPDATED",
  "message": "Mode de livraison mis a jour.",
  "data": {
    "increment_id": "100012345",
    "sale_product_id": 456789,
    "new_mode": "etage"
  }
}

Paid changes return HTTP 200 with DELIVERY_CHANGE_PAYMENT_REQUIRED and data.payment_url.

Error Mapping

HTTP	Code	Meaning
400	DELIVERY_CHANGE_BAD_REQUEST	Malformed JSON or invalid request syntax
400	DELIVERY_CHANGE_INVALID_MODE	Unknown requested delivery mode
401	DELIVERY_CHANGE_UNAUTHORIZED	Missing API credentials
403	DELIVERY_CHANGE_FORBIDDEN	Invalid API credentials
404	DELIVERY_CHANGE_ORDER_NOT_FOUND	Order not found
404	DELIVERY_CHANGE_PRODUCT_NOT_FOUND	Product not found in order
409	DELIVERY_CHANGE_NOT_AVAILABLE	Business conflict
422	DELIVERY_CHANGE_VALIDATION_ERROR	Missing or invalid required data
422	DELIVERY_CHANGE_MODE_UNAVAILABLE	Requested mode unavailable for this order
422	DELIVERY_CHANGE_NOT_AVAILABLE	Unknown current mode, unconfigured store, or missing pricing data
500	DELIVERY_CHANGE_LOGIDAV_ERROR	Technical Logidav error

All error bodies include success, code, message, and details. Technical details are logged server-side and are not exposed in the response.

Client mapping and retry behavior

The current chatbot-backend client performs one request. It classifies timeouts, 502, 503, and 504 as retryable for caller handling; it does not automatically retry. Do not add blind retries until idempotency is established for this state-changing endpoint.

The current response mapper does not preserve two valid producer pairs: 400 with DELIVERY_CHANGE_INVALID_MODE, and 422 with DELIVERY_CHANGE_NOT_AVAILABLE. Until the consumer is corrected and verified, callers can receive a normalized fallback code instead of the producer code. This is a known integration gap, not part of the stable contract.

Symfony Wiring

The response contract is centralized in AppBundle\Services\Api\DeliveryChangeApiResponseFactory. Request validation is handled by AppBundle\Services\Api\DeliveryChangeRequestPayloadValidator, keeping DeliveryChangeController focused on orchestration.

EventBundle\EventSubscriber\ExceptionSubscriber is declared in src/EventBundle/Resources/config/services.yml and imported from app/config/config.yml through a direct resource path because EventBundle is service-scanned but not registered as a Symfony bundle in AppKernel.

Deployment checks

The producer contract was merged through Logidav PR #2512. Merge status does not prove deployment, corrected chatbot-backend mapping, or end-to-end acceptance.

Before deploying this contract:

• Confirm Jenkins is green for Logidav and chatbot-backend.
• Confirm chatbot-backend maps Logidav code and HTTP status without collapsing functional errors into generic 500.
• Confirm 401 responses preserve the WWW-Authenticate: Bearer header.
• Confirm requested_by validation protects the 50-character database column.