VTex Checkout API — Cart Attachments

naftiko: 1.0.0-alpha2
info:
  label: VTex Checkout API — Cart Attachments
  description: 'VTex Checkout API — Cart Attachments. 7 operations. Lead operation: VTex Add client preferences. Self-contained
    Naftiko capability covering one Vtex business surface.'
  tags:
  - Vtex
  - Cart Attachments
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    VTEX_API_KEY: VTEX_API_KEY
capability:
  consumes:
  - type: http
    namespace: checkout-cart-attachments
    baseUri: https://{accountName}.{environment}.com.br
    description: VTex Checkout API — Cart Attachments business capability. Self-contained, no shared references.
    resources:
    - name: api-checkout-pub-orderForm-orderFormId-attachments-clientPreferencesData
      path: /api/checkout/pub/orderForm/{orderFormId}/attachments/clientPreferencesData
      operations:
      - name: addclientpreferences
        method: POST
        description: VTex Add client preferences
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: orderFormId
          in: path
          type: string
          description: ID of the orderForm that will receive client profile information.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: api-checkout-pub-orderForm-orderFormId-attachments-clientProfileData
      path: /api/checkout/pub/orderForm/{orderFormId}/attachments/clientProfileData
      operations:
      - name: addclientprofile
        method: POST
        description: VTex Add client profile
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: orderFormId
          in: path
          type: string
          description: ID of the orderForm that will receive client profile information.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: api-checkout-pub-orderForm-orderFormId-attachments-marketingData
      path: /api/checkout/pub/orderForm/{orderFormId}/attachments/marketingData
      operations:
      - name: addmarketingdata
        method: POST
        description: VTex Add marketing data
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: orderFormId
          in: path
          type: string
          description: ID of the orderForm that will receive client profile information.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: api-checkout-pub-orderForm-orderFormId-attachments-merchantContextData
      path: /api/checkout/pub/orderForm/{orderFormId}/attachments/merchantContextData
      operations:
      - name: addmerchantcontextdata
        method: POST
        description: VTex Add merchant context data
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: orderFormId
          in: path
          type: string
          description: ID of the orderForm that will receive the relevant information added by the merchant.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: api-checkout-pub-orderForm-orderFormId-attachments-paymentData
      path: /api/checkout/pub/orderForm/{orderFormId}/attachments/paymentData
      operations:
      - name: addpaymentdata
        method: POST
        description: VTex Add payment data
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: orderFormId
          in: path
          type: string
          description: ID of the orderForm that will receive client profile information.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: api-checkout-pub-orderForm-orderFormId-attachments-shippingData
      path: /api/checkout/pub/orderForm/{orderFormId}/attachments/shippingData
      operations:
      - name: addshippingaddress
        method: POST
        description: VTex Add shipping address and select delivery option
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: orderFormId
          in: path
          type: string
          description: ID of the orderForm that will receive client profile information.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: api-checkout-pub-profiles
      path: /api/checkout/pub/profiles
      operations:
      - name: getclientprofilebyemail
        method: GET
        description: VTex Get client profile by email
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: email
          in: query
          type: string
          description: Client's email address to be searched.
          required: true
        - name: ensureComplete
          in: query
          type: boolean
          description: Indicates whether the returned profiles must be complete or not.
    authentication:
      type: apikey
      key: X-VTEX-API-AppKey
      value: '{{env.VTEX_API_KEY}}'
      placement: header
  exposes:
  - type: rest
    namespace: checkout-cart-attachments-rest
    port: 8080
    description: REST adapter for VTex Checkout API — Cart Attachments. One Spectral-compliant resource per consumed operation,
      prefixed with /v1.
    resources:
    - path: /v1/api/checkout/pub/orderform/{orderformid}/attachments/clientpreferencesdata
      name: api-checkout-pub-orderform-orderformid-attachments-clientpreferencesdata
      description: REST surface for api-checkout-pub-orderForm-orderFormId-attachments-clientPreferencesData.
      operations:
      - method: POST
        name: addclientpreferences
        description: VTex Add client preferences
        call: checkout-cart-attachments.addclientpreferences
        with:
          orderFormId: rest.orderFormId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/checkout/pub/orderform/{orderformid}/attachments/clientprofiledata
      name: api-checkout-pub-orderform-orderformid-attachments-clientprofiledata
      description: REST surface for api-checkout-pub-orderForm-orderFormId-attachments-clientProfileData.
      operations:
      - method: POST
        name: addclientprofile
        description: VTex Add client profile
        call: checkout-cart-attachments.addclientprofile
        with:
          orderFormId: rest.orderFormId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/checkout/pub/orderform/{orderformid}/attachments/marketingdata
      name: api-checkout-pub-orderform-orderformid-attachments-marketingdata
      description: REST surface for api-checkout-pub-orderForm-orderFormId-attachments-marketingData.
      operations:
      - method: POST
        name: addmarketingdata
        description: VTex Add marketing data
        call: checkout-cart-attachments.addmarketingdata
        with:
          orderFormId: rest.orderFormId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/checkout/pub/orderform/{orderformid}/attachments/merchantcontextdata
      name: api-checkout-pub-orderform-orderformid-attachments-merchantcontextdata
      description: REST surface for api-checkout-pub-orderForm-orderFormId-attachments-merchantContextData.
      operations:
      - method: POST
        name: addmerchantcontextdata
        description: VTex Add merchant context data
        call: checkout-cart-attachments.addmerchantcontextdata
        with:
          orderFormId: rest.orderFormId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/checkout/pub/orderform/{orderformid}/attachments/paymentdata
      name: api-checkout-pub-orderform-orderformid-attachments-paymentdata
      description: REST surface for api-checkout-pub-orderForm-orderFormId-attachments-paymentData.
      operations:
      - method: POST
        name: addpaymentdata
        description: VTex Add payment data
        call: checkout-cart-attachments.addpaymentdata
        with:
          orderFormId: rest.orderFormId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/checkout/pub/orderform/{orderformid}/attachments/shippingdata
      name: api-checkout-pub-orderform-orderformid-attachments-shippingdata
      description: REST surface for api-checkout-pub-orderForm-orderFormId-attachments-shippingData.
      operations:
      - method: POST
        name: addshippingaddress
        description: VTex Add shipping address and select delivery option
        call: checkout-cart-attachments.addshippingaddress
        with:
          orderFormId: rest.orderFormId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/checkout/pub/profiles
      name: api-checkout-pub-profiles
      description: REST surface for api-checkout-pub-profiles.
      operations:
      - method: GET
        name: getclientprofilebyemail
        description: VTex Get client profile by email
        call: checkout-cart-attachments.getclientprofilebyemail
        with:
          email: rest.email
          ensureComplete: rest.ensureComplete
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: checkout-cart-attachments-mcp
    port: 9090
    transport: http
    description: MCP adapter for VTex Checkout API — Cart Attachments. One tool per consumed operation, routed inline through
      this capability's consumes block.
    tools:
    - name: vtex-add-client-preferences
      description: VTex Add client preferences
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: checkout-cart-attachments.addclientpreferences
      with:
        orderFormId: tools.orderFormId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: vtex-add-client-profile
      description: VTex Add client profile
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: checkout-cart-attachments.addclientprofile
      with:
        orderFormId: tools.orderFormId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: vtex-add-marketing-data
      description: VTex Add marketing data
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: checkout-cart-attachments.addmarketingdata
      with:
        orderFormId: tools.orderFormId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: vtex-add-merchant-context-data
      description: VTex Add merchant context data
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: checkout-cart-attachments.addmerchantcontextdata
      with:
        orderFormId: tools.orderFormId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: vtex-add-payment-data
      description: VTex Add payment data
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: checkout-cart-attachments.addpaymentdata
      with:
        orderFormId: tools.orderFormId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: vtex-add-shipping-address-and
      description: VTex Add shipping address and select delivery option
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: checkout-cart-attachments.addshippingaddress
      with:
        orderFormId: tools.orderFormId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: vtex-get-client-profile-email
      description: VTex Get client profile by email
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: checkout-cart-attachments.getclientprofilebyemail
      with:
        email: tools.email
        ensureComplete: tools.ensureComplete
      outputParameters:
      - type: object
        mapping: $.