Updated API from documentation release

commercetools · Dec 2, 2024 · 72afd2e · 72afd2e
1 parent f4cb4be
commit 72afd2e
Show file tree

Hide file tree

Showing 41 changed files with 670 additions and 64 deletions.
diff --git a/api-specs/checkout/api.raml b/api-specs/checkout/api.raml
@@ -42,7 +42,40 @@ securedBy: [oauth_2_0]
 traits:
   secured_by_manage_payments:
     securedBy:
-      [oauth_2_0: { scopes: ['manage_checkout_payment_intents:{projectKey}'] }]
+      [
+        oauth_2_0:
+          {
+            scopes:
+              [
+                'manage_checkout_payment_intents:{projectKey}',
+                'manage_projects:{projectKey}',
+              ],
+          },
+      ]
+  secured_by_manage_transactions:
+    securedBy:
+      [
+        oauth_2_0:
+          {
+            scopes:
+              [
+                'manage_checkout_transactions:{projectKey}',
+                'manage_projects:{projectKey}',
+              ],
+          },
+      ]
+  secured_by_view_transactions:
+    securedBy:
+      [
+        oauth_2_0:
+          {
+            scopes:
+              [
+                'view_checkout_transactions:{projectKey}',
+                'manage_projects:{projectKey}',
+              ],
+          },
+      ]
 
 /{projectKey}:
   (annotations.methodName): withProjectKey
@@ -62,7 +95,7 @@ traits:
         is:
           - secured_by_manage_payments
         body:
-          type: Payment
+          type: PaymentIntent
           example: !include ./examples/payments/capturePayment.json
         description: |
           Specific Error Codes:
@@ -77,3 +110,72 @@ traits:
             description: The request was invalid.
             body:
               type: ErrorResponse
+  /transactions:
+    post:
+      is:
+        - secured_by_manage_transactions
+      body:
+        type: TransactionDraft
+        example: !include ./examples/transactions/transactionDraft.json
+      description: |
+        Creates a Transaction on Checkout. Specific Error Codes:
+        - [InvalidInput](ctp:checkout:type:InvalidInputError)
+        - [ResourceNotFound](ctp:checkout:type:ResourceNotFoundError)
+        - [ConnectorFailed](ctp:checkout:type:ConnectorFailedError)
+        - [PaymentFailure](ctp:checkout:type:PaymentFailureError)
+        - [RequiredField](ctp:checkout:type:RequiredFieldError)
+      responses:
+        201:
+          body:
+            type: Transaction
+            example: !include ../checkout/examples/transactions/transaction.json
+        400:
+          description: The request was invalid.
+          body:
+            type: ErrorResponse
+    /{id}:
+      (annotations.methodName): withId
+      uriParameters:
+        id:
+          type: string
+          description: |
+            `id` of the [Transaction](/transactions-api#transaction).
+      get:
+        is:
+          - secured_by_view_transactions
+        description: |
+          Returns a Transaction with a given `id`. Specific Error Codes:
+          - [ResourceNotFound](ctp:checkout:type:ResourceNotFoundError)
+          - [GeneralError](ctp:checkout:type:GeneralError)
+        responses:
+          200:
+            body:
+              type: Transaction
+              example: !include ../checkout/examples/transactions/transaction.json
+          400:
+            description: The request was invalid.
+            body:
+              type: ErrorResponse
+    /key={key}:
+      (annotations.methodName): withKey
+      uriParameters:
+        key:
+          type: string
+          description: |
+            `key` of the [Transaction](/transactions-api#transaction).
+      get:
+        is:
+          - secured_by_view_transactions
+        description: |
+          Returns a Transaction with a given `key`. Specific Error Codes:
+          - [ResourceNotFound](ctp:checkout:type:ResourceNotFoundError)
+          - [GeneralError](ctp:checkout:type:GeneralError)
+        responses:
+          200:
+            body:
+              type: Transaction
+              example: !include ../checkout/examples/transactions/transaction.json
+          400:
+            description: The request was invalid.
+            body:
+              type: ErrorResponse
diff --git a/api-specs/checkout/examples/transactions/transaction.json b/api-specs/checkout/examples/transactions/transaction.json
@@ -0,0 +1,42 @@
+{
+    "id" : "6d95b6c6-5ef0-4091-8478-b26077ca2b2f",
+    "version" : 1,
+    "key": "transaction-key",
+    "application" : {
+      "typeId": "application",
+      "id": "a84d4fe7-ae82-4c3f-8c6c-435e54204fdd" 
+    },
+    "cart": {
+      "typeId": "cart",
+      "id": "a0e60229-441c-44b0-952b-981a67cbd8c4" 
+    },
+    "order": {
+      "typeId": "order",
+      "id": "39ccda28-47f9-41bf-8dde-e1d720c19000" 
+    },
+    "transactionItems": [
+      {
+        "paymentIntegration": {
+          "typeId": "payment-integration",
+          "id": "4c24762b-87df-4bd3-898a-bafed913a9ca"
+        },
+        "amount": {
+          "centAmount": 1000,
+          "currencyCode": "EUR"
+        },
+        "payment": {
+          "typeId": "payment",
+          "id": "d1fec278-22c2-4a1d-8190-8f1e8af5ccfb"
+        }
+      }
+    ],
+    "transactionStatus": {
+      "state": "Failed", 
+      "errors": [{
+        "code": "PaymentRejected",
+        "message": "Payment d1fec278-22c2-4a1d-8190-8f1e8af5ccfb has been rejected."
+      }]
+    },
+    "createdAt": "1970-01-01T00:00:00.001Z",
+    "lastModifiedAt": "1970-01-01T00:00:00.001Z"
+  }
diff --git a/api-specs/checkout/examples/transactions/transactionDraft.json b/api-specs/checkout/examples/transactions/transactionDraft.json
@@ -0,0 +1,23 @@
+{
+    "key": "transaction-key",
+    "application" : {
+      "typeId": "application",
+      "id": "a84d4fe7-ae82-4c3f-8c6c-435e54204fdd" 
+    },
+    "cart": {
+      "typeId": "cart",
+      "id": "a0e60229-441c-44b0-952b-981a67cbd8c4" 
+    },
+    "transactionItems": [
+      {
+        "paymentIntegration": {
+          "typeId": "payment-integration",
+          "id": "4c24762b-87df-4bd3-898a-bafed913a9ca"
+        },
+        "amount": {
+          "centAmount": 1000,
+          "currencyCode": "EUR"
+        }
+      }
+    ]
+  }
diff --git a/api-specs/checkout/types/applications/ApplicationReference.raml b/api-specs/checkout/types/applications/ApplicationReference.raml
@@ -0,0 +1,12 @@
+#%RAML 1.0 DataType
+(annotations.package): Application
+type: Reference
+displayName: ApplicationReference
+discriminatorValue: application
+description: |
+  Reference to an [Application](/payment-connectors-applications#applications).
+properties:
+  id:
+    type: string
+    description: |
+      Unique identifier of the referenced Application.
diff --git a/api-specs/checkout/types/applications/ApplicationResourceIdentifier.raml b/api-specs/checkout/types/applications/ApplicationResourceIdentifier.raml
@@ -0,0 +1,16 @@
+#%RAML 1.0 DataType
+(annotations.package): Application
+type: ResourceIdentifier
+displayName: ApplicationResourceIdentifier
+discriminatorValue: application
+description: |
+  Resource identifier to an [Application](/payment-connectors-applications#applications). Either `id` or `key` is required. If both are set, an [InvalidJsonInput](/errors#invalidjsoninput) error is returned.
+properties:
+  id?:
+    type: string
+    description: |
+      Unique identifier of the referenced Application. Required if `key` is absent.
+  key?:
+    type: string
+    description: |
+      User-defined unique identifier of the referenced Application. Required if `id` is absent.
diff --git a/api-specs/checkout/types/coco/CartReference.raml b/api-specs/checkout/types/coco/CartReference.raml
@@ -0,0 +1,12 @@
+#%RAML 1.0 DataType
+(annotations.package): Cart
+type: Reference
+displayName: CartReference
+discriminatorValue: cart
+description: |
+  Reference to a [Cart](/../api/projects/carts).
+properties:
+  id:
+    type: string
+    description: |
+      Unique identifier of the referenced [Cart](/../api/projects/carts).
diff --git a/api-specs/checkout/types/coco/CartResourceIdentifier.raml b/api-specs/checkout/types/coco/CartResourceIdentifier.raml
@@ -0,0 +1,16 @@
+#%RAML 1.0 DataType
+(annotations.package): Cart
+type: ResourceIdentifier
+displayName: CartResourceIdentifier
+discriminatorValue: cart
+description: |
+  Resource identifier to a [Cart](/../api/projects/carts). Either `id` or `key` is required. If both are set, an [InvalidJsonInput](/errors#invalidjsoninput) error is returned.
+properties:
+  id?:
+    type: string
+    description: |
+      Unique identifier of the referenced [Cart](/../api/projects/carts). Required if `key` is absent.
+  key?:
+    type: string
+    description: |
+      User-defined unique identifier of the referenced [Cart](/../api/projects/carts). Required if `id` is absent.
diff --git a/api-specs/checkout/types/coco/OrderReference.raml b/api-specs/checkout/types/coco/OrderReference.raml
@@ -0,0 +1,12 @@
+#%RAML 1.0 DataType
+(annotations.package): Cart
+type: Reference
+displayName: OrderReference
+discriminatorValue: order
+description: |
+  Reference to an [Order](/../api/projects/orders).
+properties:
+  id:
+    type: string
+    description: |
+      Unique identifier of the referenced [Order](/../api/projects/orders).
diff --git a/api-specs/checkout/types/coco/OrderResourceIdentifier.raml b/api-specs/checkout/types/coco/OrderResourceIdentifier.raml
@@ -0,0 +1,16 @@
+#%RAML 1.0 DataType
+(annotations.package): Order
+type: ResourceIdentifier
+displayName: OrderResourceIdentifier
+discriminatorValue: order
+description: |
+  Resource identifier to an [Order](/../api/projects/orders). Either `id` or `key` is required. If both are set, an [InvalidJsonInput](/errors#invalidjsoninput) error is returned.
+properties:
+  id?:
+    type: string
+    description: |
+      Unique identifier of the referenced [Order](/../api/projects/orders). Required if `key` is absent.
+  key?:
+    type: string
+    description: |
+      User-defined unique identifier of the referenced [Order](/../api/projects/orders). Required if `id` is absent.
diff --git a/api-specs/checkout/types/coco/PaymentReference.raml b/api-specs/checkout/types/coco/PaymentReference.raml
@@ -0,0 +1,12 @@
+#%RAML 1.0 DataType
+(annotations.package): Payment
+type: Reference
+displayName: PaymentReference
+discriminatorValue: payment
+description: |
+  Reference to a [Payment](/../api/projects/payments).
+properties:
+  id:
+    type: string
+    description: |
+      Unique identifier of the referenced [Payment](/../api/projects/payments).
diff --git a/api-specs/checkout/types/coco/PaymentResourceIdentifier.raml b/api-specs/checkout/types/coco/PaymentResourceIdentifier.raml
@@ -0,0 +1,16 @@
+#%RAML 1.0 DataType
+(annotations.package): Payment
+type: ResourceIdentifier
+displayName: PaymentResourceIdentifier
+discriminatorValue: payment
+description: |
+  Resource identifier to a [Payment](/../api/projects/payments). Either `id` or `key` is required. If both are set, an [InvalidJsonInput](/errors#invalidjsoninput) error is returned.
+properties:
+  id?:
+    type: string
+    description: |
+      Unique identifier of the referenced [Payment](/../api/projects/payments). Required if `key` is absent.
+  key?:
+    type: string
+    description: |
+      User-defined unique identifier of the referenced [Payment](/../api/projects/payments). Required if `id` is absent.
diff --git a/api-specs/checkout/types/coco/Reference.raml b/api-specs/checkout/types/coco/Reference.raml
@@ -0,0 +1,16 @@
+#%RAML 1.0 DataType
+(annotations.package): Common
+displayName: Reference
+type: object
+discriminator: typeId
+description: |
+  A Reference represents a loose reference to another resource in the same Project identified by its `id`. The `typeId` indicates the type of the referenced resource. Each resource type has its corresponding Reference type, like [ChannelReference](ctp:api:type:ChannelReference).  A referenced resource can be embedded through [Reference Expansion](/general-concepts#reference-expansion). The expanded reference is the value of an additional `obj` field then.
+properties:
+  typeId:
+    type: ReferenceTypeId
+    description: |
+      Type of referenced resource.
+  id:
+    type: string
+    description: |
+      Unique ID of the referenced resource.
diff --git a/api-specs/checkout/types/coco/ReferenceTypeId.raml b/api-specs/checkout/types/coco/ReferenceTypeId.raml
@@ -0,0 +1,23 @@
+#%RAML 1.0 DataType
+(annotations.package): Common
+displayName: ReferenceTypeId
+type: string
+description: |
+  Type of resource the value should reference. Supported resource type identifiers are:
+enum:
+  - cart
+  - order
+  - payment
+  - application
+  - payment-integration
+(annotations.enumDescriptions):
+  cart: |
+    References a [Cart](/../api/projects/carts#cart).
+  order: |
+    References an [Order](/../api/projects/orders#order).
+  payment: |
+    References a [Payment](/../api/projects/payments#payment).
+  application: |
+    References an [Application](/payment-connectors-applications#applications).
+  payment-integration: |
+    References a [Payment Integration](/payment-connectors-applications#payment-integrations).
diff --git a/api-specs/checkout/types/coco/ResourceIdentifier.raml b/api-specs/checkout/types/coco/ResourceIdentifier.raml
@@ -0,0 +1,22 @@
+#%RAML 1.0 DataType
+(annotations.package): Common
+displayName: ResourceIdentifier
+type: object
+discriminator: typeId
+description: |
+  Draft type to create a [Reference](ctp:api:type:Reference) or a [KeyReference](ctp:api:type:KeyReference) to a resource. Provide either the `id` or (wherever supported) the `key` of the resource to reference, but depending on the API endpoint the response returns either a Reference or a KeyReference. For example, the field `parent` of a [CategoryDraft](ctp:api:type:CategoryDraft) takes a ResourceIdentifier for its value while the value of the corresponding field of a [Category](ctp:api:type:Category) is a Reference.
+
+  Each resource type has its corresponding ResourceIdentifier, like [ChannelResourceIdentifier](ctp:api:type:ChannelResourceIdentifier).
+properties:
+  typeId?:
+    type: ReferenceTypeId
+    description: |
+      Type of referenced resource. If given, it must match the expected [ReferenceTypeId](/../api/types#ctp:api:type:ReferenceTypeId) of the referenced resource.
+  id?:
+    type: string
+    description: |
+      Unique identifier of the referenced resource. Required if `key` is absent.
+  key?:
+    type: string
+    description: |
+      User-defined unique identifier of the referenced resource. Required if `id` is absent.