📘 User Guide

1. Document Purpose

This guide provides business, functional and technical context to help API consumers understand and integrate the Asset Contracts API. It complements the OpenAPI specification and is part of the mandatory documentation set for each version (Major.Minor.Patch).

2. Target Audience

Profile	Role
Product Owner	Understand the business scope and value of the API
Developer	Implement and integrate the API
QA / Architect	Validate expected behaviors and technical compliance
Customer Connect API (CCA)	Support API consumers during onboarding and integration

3. API Overview

3.1 Business Context

The API manages the contracts that govern the use of digital assets (images, videos and other media). It lets a source system publish contract data (brands, territories, media channels, validity period) and lets applications retrieve it, so that they can check which assets can be used, where and until when.

Usage context: asset rights management and consultation of selectable contracts.

3.2 Main Features

List of supported operations:

• List and search contracts, with filters and pagination.
• Retrieve the detail of a contract by its number.
• Create or update a contract (upsert).
• Check the health of the service.

3.3 Known Limitations

• Contracts cannot be deleted through the API.
• An update is applied only if the incoming date_updated is more recent than the stored one.
• Query parameters not defined in the specification are rejected.
• Lists in the payload (brands, geographical_scope, allowed_media_formats) are limited to 50 values.

4. Access & Security

4.1 Access Requirements

Requirement	Provided by Accor	Consumer Action Required
Client ID / credentials to obtain a token	✅	🔲 Request via onboarding
Access to the API in the Developer Hub	✅	🔲 Subscribe to the API

4.2 Authentication & Headers

Auth method: OAuth 2.0 / JWT bearer token, issued by the identity provider of the environment.

Required headers:

• Authorization: Bearer <access_token>
• Content-Type: application/json (for POST requests)

5. API Behavior

5.1 Traceability & Telemetry

Each contract carries source_system, interface_version, date_updated and api_call_timestamp, which identify the sender and the moment of the call. Keep these values accurate: they are used to trace changes and to decide whether an update is applied.

5.2 Health Check

GET /ecom/v1/asset/healthcheck returns the status of the service (UP) and a timestamp.

6. Endpoints

/ecom/v1/asset/contracts (GET)

Description

Return a paginated list of selectable contracts.

Request Rules

Optional: contractId (contains), status (repeatable), recordType, limit (default 20), offset (default 0).

Response Behavior

Returns 200 with items, total, limit and offset. Returns 400 if a query parameter is invalid.

/ecom/v1/asset/contracts/{contract_number} (GET)

Description

Return the full contract identified by its number.

Request Rules

Mandatory: contract_number (path parameter).

Response Behavior

Returns 404 if no contract is found for the given number.

/ecom/v1/asset/contracts (POST)

Description

Create a contract, or update it when the incoming payload is more recent.

Request Rules

Mandatory: contract_number, interface_version, source_system, date_updated, api_call_timestamp.

Response Behavior

Returns 201 when the contract is created, 200 when it is updated, and 400 if the payload is invalid.

7. Usage Examples

🔍 List contracts

GET /ecom/v1/asset/contracts?status=Approved&limit=2&offset=0

{
  "items": [
    {
      "contract_number": "CT-000123",
      "contract_type": "Photographer",
      "contract_sub_category": "Buyout",
      "wfstate": "Approved",
      "company_name": "Studio Example",
      "contract_start_date": "2025-01-01",
      "contract_end_date": "2027-12-31",
      "source_system": "SALESFORCE",
      "date_updated": "2025-06-12T09:30:00Z",
      "record_type": "Contract"
    }
  ],
  "total": 1,
  "limit": 2,
  "offset": 0
}

🔍 Get a contract

GET /ecom/v1/asset/contracts/CT-000123

{
  "contract_number": "CT-000123",
  "interface_version": "1.0",
  "source_system": "SALESFORCE",
  "record_type": "Contract",
  "contract_type": "Photographer",
  "contract_sub_category": "Buyout",
  "wfstate": "Approved",
  "company_name": "Studio Example",
  "contract_start_date": "2025-01-01",
  "contract_end_date": "2027-12-31",
  "brands": ["Sofitel", "Novotel"],
  "geographical_scope": ["FR", "DE"],
  "allowed_media_formats": ["Digital", "Print"],
  "date_updated": "2025-06-12T09:30:00Z",
  "api_call_timestamp": "2025-06-12T09:30:05Z"
}

✏️ Create or update a contract

POST /ecom/v1/asset/contracts
Content-Type: application/json

{
  "contract_number": "CT-000123",
  "interface_version": "1.0",
  "source_system": "SALESFORCE",
  "contract_start_date": "2025-01-01",
  "contract_end_date": "2027-12-31",
  "brands": ["Sofitel", "Novotel"],
  "date_updated": "2025-06-12T09:30:00Z",
  "api_call_timestamp": "2025-06-12T09:30:05Z"
}

8. Error Codes

HTTP Code	Error Code	Description	Recommended Action
400	INVALID_INPUT	Invalid or missing fields	Check input data
401	UNAUTHORIZED	Invalid or expired token	Refresh or re-authenticate
404	NOT_FOUND	Entity does not exist	Check the contract number
500	INTERNAL_ERROR	Unexpected backend issue	Retry or escalate