Use TM Forum as vocabulary and integration boundary.
Use our own canonical model for internal correctness.

Package
Bundle
Product
Offering
Plan
SKU
Service
Subscription
Asset
Contract
Order Item
Line Item
Provisioning Item
Fulfillment Item

External standard vocabulary is not a substitute for internal domain modelling.

{
  "@type": "ProductOffering",
  "@baseType": "CatalogEntity",
  "@schemaLocation": "https://..."
}

public class DomainEntity {
    String atType;
    String atBaseType;
    String atSchemaLocation;
    Map<String, Object> dynamicFields;
}

public final class ProductOffering {
    private final ProductOfferingId id;
    private final ProductSpecificationId productSpecificationId;
    private final OfferingLifecycleStatus status;
    private final List<CharacteristicDefinition> configurableCharacteristics;
    private final List<OfferingPriceRef> prices;
    private final List<EligibilityRuleRef> eligibilityRules;
}

GET /api/v1/product-offerings/{offeringId}

{
  "id": "po_broadband_1g",
  "name": "Broadband 1Gbps",
  "lifecycleStatus": "ACTIVE",
  "productSpecification": {
    "id": "ps_broadband_access",
    "name": "Broadband Access"
  },
  "characteristics": [
    {
      "code": "CONTRACT_TERM",
      "valueType": "STRING",
      "allowedValues": ["12M", "24M"],
      "required": true
    }
  ],
  "prices": [
    {
      "id": "pop_broadband_1g_mrc",
      "chargeType": "RECURRING",
      "recurrence": "MONTHLY",
      "amount": {
        "currency": "IDR",
        "value": "499000.00"
      }
    }
  ],
  "validFor": {
    "startDateTime": "2026-01-01T00:00:00Z",
    "endDateTime": null
  }
}

GET /api/v1/product-offerings/{offeringId}/configuration-model
GET /api/v1/product-offerings/{offeringId}/pricing-model
GET /api/v1/product-offerings/{offeringId}/decomposition-template

{
  "offeringId": "po_broadband_1g",
  "offeringVersion": 12,
  "catalogVersion": "2026.Q3",
  "lifecycleStatus": "ACTIVE"
}

{
  "productOfferingRef": {
    "id": "po_broadband_1g",
    "version": 12,
    "nameSnapshot": "Broadband 1Gbps"
  }
}

Quote and order must not depend on mutable live catalog for historical explanation.

Customer memilih produk -> cart -> eligibility check -> price estimate -> quote

Kita tidak membuat cart sebagai aggregate utama di awal.
Quote akan berfungsi sebagai configurable commercial workspace.

POST   /api/v1/quotes
GET    /api/v1/quotes/{quoteId}
PATCH  /api/v1/quotes/{quoteId}
POST   /api/v1/quotes/{quoteId}/items
PATCH  /api/v1/quotes/{quoteId}/items/{itemId}
DELETE /api/v1/quotes/{quoteId}/items/{itemId}
POST   /api/v1/quotes/{quoteId}/price
POST   /api/v1/quotes/{quoteId}/validate
POST   /api/v1/quotes/{quoteId}/submit
POST   /api/v1/quotes/{quoteId}/approve
POST   /api/v1/quotes/{quoteId}/reject
POST   /api/v1/quotes/{quoteId}/accept
POST   /api/v1/quotes/{quoteId}/convert-to-order

{
  "id": "quo_1001",
  "version": 7,
  "state": "PRICED",
  "stateCategory": "IN_PROGRESS",
  "validFor": {
    "startDateTime": "2026-07-02T00:00:00Z",
    "endDateTime": "2026-07-31T23:59:59Z"
  },
  "relatedParty": [
    {
      "role": "CUSTOMER",
      "id": "party_123",
      "name": "PT Example"
    }
  ],
  "billingAccount": {
    "id": "ba_456"
  },
  "quoteItem": [
    {
      "id": "qi_1",
      "action": "ADD",
      "productOffering": {
        "id": "po_broadband_1g",
        "version": 12,
        "name": "Broadband 1Gbps"
      },
      "configuration": {
        "configurationId": "cfg_1",
        "status": "VALID"
      },
      "price": {
        "oneTimeTotal": { "currency": "IDR", "value": "0.00" },
        "recurringTotal": { "currency": "IDR", "value": "499000.00" }
      }
    }
  ],
  "priceSummary": {
    "currency": "IDR",
    "oneTimeTotal": "0.00",
    "recurringTotal": "499000.00"
  }
}

{
  "quoteItemId": "qi_1",
  "productOfferingSnapshot": {
    "id": "po_broadband_1g",
    "version": 12,
    "name": "Broadband 1Gbps"
  },
  "configurationSnapshot": {
    "characteristics": [
      { "code": "CONTRACT_TERM", "value": "24M" }
    ],
    "validationHash": "sha256:..."
  },
  "priceSnapshot": {
    "priceHash": "sha256:...",
    "charges": []
  }
}

POST /api/v1/orders
POST /api/v1/orders/from-quote
GET  /api/v1/orders/{orderId}
GET  /api/v1/orders/{orderId}/timeline
GET  /api/v1/orders/{orderId}/fulfillment-plan
POST /api/v1/orders/{orderId}/submit
POST /api/v1/orders/{orderId}/cancel
POST /api/v1/orders/{orderId}/amend
POST /api/v1/orders/{orderId}/hold
POST /api/v1/orders/{orderId}/resume

POST /api/v1/orders/from-quote
Idempotency-Key: idem_123
If-Match: "quote-version-7"

{
  "quoteId": "quo_1001",
  "requestedCompletionDate": "2026-08-01T00:00:00Z",
  "externalReference": {
    "system": "SALES_PORTAL",
    "id": "sp_9988"
  }
}

{
  "commandId": "cmd_2001",
  "orderId": "ord_3001",
  "status": "ACCEPTED",
  "statusUrl": "/api/v1/commands/cmd_2001"
}

Product Inventory ~= Installed Base / Asset View

GET /api/v1/customer-assets?customerId=party_123
GET /api/v1/customer-assets/{assetId}
GET /api/v1/customer-assets/{assetId}/timeline
GET /api/v1/customer-assets/{assetId}/eligible-actions

{
  "assetId": "ast_1001",
  "customerId": "party_123",
  "status": "ACTIVE",
  "productOffering": {
    "id": "po_broadband_1g",
    "name": "Broadband 1Gbps"
  },
  "characteristics": [
    { "code": "CONTRACT_TERM", "value": "24M" },
    { "code": "ACCESS_SPEED", "value": "1G" }
  ],
  "subscription": {
    "id": "sub_1001",
    "status": "ACTIVE",
    "startDate": "2026-01-01T00:00:00Z"
  }
}

Broadband 1Gbps + Static IP + Router Rental

- reserve access resource
- ship router
- configure CPE
- provision broadband service
- assign static IP
- activate billing trigger
- send notification

POST /internal/v1/technical-fulfillment-orders
GET  /internal/v1/technical-fulfillment-orders/{id}
POST /internal/v1/technical-fulfillment-orders/{id}/tasks/{taskId}/complete
POST /internal/v1/technical-fulfillment-orders/{id}/tasks/{taskId}/fail

{
  "relatedParty": [
    { "role": "CUSTOMER", "id": "party_123" },
    { "role": "SALES_AGENT", "id": "user_99" }
  ],
  "relatedOrder": [
    { "relationshipType": "AMENDS", "id": "ord_1000" }
  ]
}

Every relationship type must be enumerated and have domain meaning.

{ "relationshipType": "somehow_related" }

{
  "externalIdentifier": [
    {
      "system": "CRM",
      "type": "OPPORTUNITY_ID",
      "id": "opp_789"
    },
    {
      "system": "PARTNER_X",
      "type": "ORDER_ID",
      "id": "PX-2026-0001"
    }
  ]
}

Internal ID remains primary.
External ID is lookup/reference, not aggregate identity.
External ID uniqueness must be scoped by system + type.
External ID changes must be audited.

DRAFT
ACKNOWLEDGED
VALIDATED
DECOMPOSED
FULFILLING
PARTIALLY_COMPLETED
COMPLETED
FAILED
CANCELLING
CANCELLED
FALLOUT
CLOSED

ACKNOWLEDGED
IN_PROGRESS
COMPLETED
FAILED
CANCELLED

Store only final price total.

{
  "price": {
    "charges": [
      {
        "chargeType": "RECURRING",
        "recurrence": "MONTHLY",
        "baseAmount": { "currency": "IDR", "value": "599000.00" },
        "adjustments": [
          {
            "type": "PROMOTION",
            "code": "PROMO_100K_OFF",
            "amount": { "currency": "IDR", "value": "-100000.00" }
          }
        ],
        "finalAmount": { "currency": "IDR", "value": "499000.00" }
      }
    ],
    "explanationId": "pex_123",
    "priceHash": "sha256:..."
  }
}

{
  "configuration": {
    "status": "INVALID",
    "selectedCharacteristics": [
      { "code": "CONTRACT_TERM", "value": "12M" },
      { "code": "ROUTER_OPTION", "value": "PREMIUM_ROUTER" }
    ],
    "violations": [
      {
        "code": "INCOMPATIBLE_OPTION",
        "message": "Premium router requires contract term 24M.",
        "path": "/selectedCharacteristics/1"
      }
    ]
  }
}

GET  /api/v1/quotes/{quoteId}/approval-summary
GET  /api/v1/quotes/{quoteId}/approval-tasks
POST /api/v1/quotes/{quoteId}/approval-tasks/{taskId}/approve
POST /api/v1/quotes/{quoteId}/approval-tasks/{taskId}/reject
POST /api/v1/quotes/{quoteId}/approval-tasks/{taskId}/delegate

public record CreateQuoteCommand(
    CustomerRef customer,
    BillingAccountRef billingAccount,
    SalesChannelRef salesChannel,
    AgreementRef agreement,
    List<ExternalIdentifier> externalIdentifiers,
    Instant requestedValidUntil,
    ActorRef actor,
    RequestContext requestContext
) {}

public record AddQuoteItemCommand(
    QuoteId quoteId,
    ProductOfferingId offeringId,
    CatalogVersionRef catalogVersion,
    OrderAction action,
    Optional<AssetId> targetAssetId,
    List<SelectedCharacteristic> selectedCharacteristics,
    ActorRef actor,
    IdempotencyKey idempotencyKey
) {}

public record CreateOrderFromQuoteCommand(
    QuoteId quoteId,
    QuoteVersion expectedQuoteVersion,
    RequestedCompletionDate requestedCompletionDate,
    List<ExternalIdentifier> externalIdentifiers,
    ActorRef actor,
    IdempotencyKey idempotencyKey
) {}

/tmf/v5/productCatalogManagement/...
/tmf/v5/quoteManagement/...
/tmf/v5/productOrdering/...

/api/v1/product-offerings
/api/v1/quotes
/api/v1/orders

1. Do external partners require TMF conformance?
2. Do we need certification/interoperability?
3. Are downstream systems already TMF-based?
4. Is the domain telco-like enough?
5. Can our internal requirements fit without distortion?
6. Will conformance improve integration speed or create ceremony?

TMF-inspired internal canonical API.
Optional TMF-compatible adapter/facade later.

tags:
  - name: Product Offerings
    description: Published commercial offerings available for selection.
  - name: Configuration
    description: Product configuration models and validation operations.
  - name: Pricing
    description: Price simulation and quote pricing operations.
  - name: Quotes
    description: Commercial proposal lifecycle.
  - name: Quote Approvals
    description: Approval tasks and decisions related to quotes.
  - name: Orders
    description: Product order capture and lifecycle.
  - name: Fulfillment
    description: Fulfillment plan and operational task visibility.
  - name: Customer Assets
    description: Installed base and subscription-oriented views.

quote_table
order_item_table
product_json
misc

paths:
  /quotes/{quoteId}/submit:
    post:
      tags:
        - Quotes
      operationId: submitQuote
      summary: Submit a quote for approval or acceptance flow
      parameters:
        - name: quoteId
          in: path
          required: true
          schema:
            type: string
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
        - name: If-Match
          in: header
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitQuoteRequest'
      responses:
        '202':
          description: Quote submit command accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommandAcceptedResponse'
        '409':
          description: Invalid quote state or version conflict
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'

{
  "relatedParty": [
    { "role": "customer", "id": "party_123" },
    { "role": "salesAgent", "id": "usr_99" }
  ],
  "billingAccount": { "id": "ba_456" },
  "externalIdentifier": [
    { "owner": "CRM", "id": "opp_123" }
  ],
  "validFor": {
    "endDateTime": "2026-08-01T00:00:00Z"
  }
}

{
  "customer": { "id": "party_123" },
  "actor": { "id": "usr_99", "type": "SALES_AGENT" },
  "billingAccount": { "id": "ba_456" },
  "externalIdentifiers": [
    { "system": "CRM", "type": "OPPORTUNITY_ID", "id": "opp_123" }
  ],
  "requestedValidUntil": "2026-08-01T00:00:00Z"
}

{
  "code": "QUOTE_INVALID_STATE_TRANSITION",
  "status": 409,
  "detail": "Quote cannot move from ACCEPTED to SUBMITTED."
}

{
  "code": "INVALID_TRANSITION",
  "reason": "The requested operation is not allowed for the current quote state.",
  "message": "Quote cannot be submitted because it has already been accepted."
}

internalErrorId -> externalResponseId -> audit record

test-fixtures/
  tmf-like/
    quote-create/
      valid-minimal.json
      valid-with-external-id.json
      invalid-multiple-customer.json
      invalid-unsupported-party-role.json
    product-order/
      order-from-quote.json
      amend-existing-asset.json

Partner sends ProductOrderItem.action = modify, but no target asset reference.

No one knows which relationship drives behavior.

Enumerate relationship types and map each to explicit domain meaning.

Promote stable business-critical field into explicit contract.
Use extension only for non-core partner metadata.

{ "state": "COMPLETED" }

Expose command endpoints, not arbitrary state patching.

Use ProductOfferingRef for catalog.
Use Asset/ProductInventoryRef for installed base.

1. TMF vocabulary is allowed; TMF cargo-cult is not.
2. External API DTO is not domain model.
3. All external payloads map to canonical commands.
4. Quote item stores offering/configuration/price snapshots.
5. Order item action is explicit.
6. Installed asset is separate from product offering.
7. Relationship types are enumerated and behavior-relevant.
8. External identifiers are scoped references, not primary keys.
9. State mapping must preserve internal detail.
10. Approval, pricing, configuration, and fulfillment need first-class APIs, not generic patching.
11. TMF-compatible facade may exist, but canonical service remains internally consistent.
12. Mapping code must be tested and audited.

# ADR-018: TM Forum Inspired API Mapping

## Status
Accepted

## Context
The CPQ/OMS platform must support enterprise commerce concepts such as product catalog, quote, product order, product inventory, service fulfillment, related party, billing account, and agreement references. TM Forum Open APIs provide useful industry vocabulary, but the platform also requires CPQ-specific configuration, pricing explainability, approval policy, orchestration, and operational repair models.

## Decision
Use TM Forum Open APIs as vocabulary and integration inspiration, not as internal domain model. Build canonical internal APIs and domain commands. Add TMF-compatible facade or partner adapters only at the edge where required.

## Consequences
Internal models remain precise and invariant-driven. External integrations can still align with industry vocabulary. Mapping layers become critical production components and require contract tests, golden payloads, error mapping, and audit traceability.

1. Catalog API inspired by TMF620 vocabulary.
2. Quote API inspired by TMF648 but extended for CPQ configuration/pricing/approval.
3. Order API inspired by TMF622 but extended for decomposition and fulfillment visibility.
4. Customer Asset API inspired by product inventory concepts.
5. Internal fulfillment API inspired by service ordering concepts.
6. Anti-corruption layer for external TMF-like payloads.
7. Canonical command model for application services.
8. Explicit mapping tests and golden payloads.

External vocabulary for interoperability.
Internal canonical model for correctness.
Explicit mapping for safety.
State machines for lifecycle control.
Snapshots for commercial defensibility.
Events for integration.
Audit for accountability.