VTex GiftCard Hub API — Transaction

naftiko: 1.0.0-alpha2
info:
  label: VTex GiftCard Hub API — Transaction
  description: 'VTex GiftCard Hub API — Transaction. 11 operations. Lead operation: VTex Create GiftCard in GiftCard Provider.
    Self-contained Naftiko capability covering one Vtex business surface.'
  tags:
  - Vtex
  - Transaction
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    VTEX_API_KEY: VTEX_API_KEY
capability:
  consumes:
  - type: http
    namespace: gift-card-hub-transaction
    baseUri: https://{accountName}.{environment}.com.br
    description: VTex GiftCard Hub API — Transaction business capability. Self-contained, no shared references.
    resources:
    - name: api-giftcardproviders-giftCardProviderId-giftcards
      path: /api/giftcardproviders/{giftCardProviderId}/giftcards
      operations:
      - name: creategiftcardingiftcardprovider
        method: POST
        description: VTex Create GiftCard in GiftCard Provider
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: Content-Type
          in: header
          type: string
          description: Type of the content being sent.
          required: true
        - name: Accept
          in: header
          type: string
          description: HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.
          required: true
        - name: giftCardProviderId
          in: path
          type: string
          description: Gift card provider identification.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: api-giftcardproviders-giftCardProviderId-giftcards-_search
      path: /api/giftcardproviders/{giftCardProviderId}/giftcards/_search
      operations:
      - name: getgiftcardfromgiftcardprovider
        method: POST
        description: VTex Get GiftCard from GiftCard Provider
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: Content-Type
          in: header
          type: string
          description: Type of the content being sent.
          required: true
        - name: Accept
          in: header
          type: string
          description: HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.
          required: true
        - name: REST-Range
          in: header
          type: string
          description: Pagination control. This query variable must follow the format `_resources={from}-{to}_`.
        - name: giftCardProviderId
          in: path
          type: string
          description: Gift card provider identification.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: api-giftcardproviders-giftCardProviderId-giftcards-giftCardId
      path: /api/giftcardproviders/{giftCardProviderId}/giftcards/{giftCardId}
      operations:
      - name: getgiftcardfromgiftcardproviderbyid
        method: GET
        description: VTex Get GiftCard from GiftCard Provider by ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: Content-Type
          in: header
          type: string
          description: Type of the content being sent.
          required: true
        - name: Accept
          in: header
          type: string
          description: HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.
          required: true
        - name: giftCardProviderId
          in: path
          type: string
          description: Gift card provider identification.
          required: true
        - name: giftCardId
          in: path
          type: string
          description: Gift card identification.
          required: true
    - name: api-giftcardproviders-giftCardProviderId-giftcards-giftCardId-transactions
      path: /api/giftcardproviders/{giftCardProviderId}/giftcards/{giftCardId}/transactions
      operations:
      - name: listallgiftcardtransactions
        method: GET
        description: VTex List All GiftCard Transactions
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: Content-Type
          in: header
          type: string
          description: Type of the content being sent.
          required: true
        - name: Accept
          in: header
          type: string
          description: HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.
          required: true
        - name: giftCardProviderId
          in: path
          type: string
          description: Gift card provider identification.
          required: true
        - name: giftCardId
          in: path
          type: string
          description: Gift card identification.
          required: true
      - name: creategiftcardtransaction
        method: POST
        description: VTex Create GiftCard Transaction
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: Content-Type
          in: header
          type: string
          description: Type of the content being sent.
          required: true
        - name: Accept
          in: header
          type: string
          description: HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.
          required: true
        - name: giftCardProviderId
          in: path
          type: string
          description: Gift card provider identification.
          required: true
        - name: giftCardId
          in: path
          type: string
          description: Gift card identification.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: api-giftcardproviders-giftCardProviderId-giftcards-giftCardId-transactions-tId-a
      path: /api/giftcardproviders/{giftCardProviderId}/giftcards/{giftCardId}/transactions/{tId}/authorization
      operations:
      - name: getgiftcardauthorizationtransaction
        method: GET
        description: VTex Get GiftCard Transaction Authorization
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: Content-Type
          in: header
          type: string
          description: Type of the content being sent.
          required: true
        - name: Accept
          in: header
          type: string
          description: HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.
          required: true
        - name: giftCardProviderId
          in: path
          type: string
          description: Gift card provider identification.
          required: true
        - name: giftCardId
          in: path
          type: string
          description: Gift card identification.
          required: true
        - name: tId
          in: path
          type: string
          description: Transaction ID generated by the provider. It is different from the `transactionId` generated by VTEX.
          required: true
    - name: api-giftcardproviders-giftCardProviderId-giftcards-giftCardId-transactions-tId-c
      path: /api/giftcardproviders/{giftCardProviderId}/giftcards/{giftCardId}/transactions/{tId}/cancellations
      operations:
      - name: listallgiftcardcancellationtransactions
        method: GET
        description: VTex List All GiftCard Transactions Cancellations
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: Content-Type
          in: header
          type: string
          description: Type of the content being sent.
          required: true
        - name: Accept
          in: header
          type: string
          description: HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.
          required: true
        - name: giftCardProviderId
          in: path
          type: string
          description: Gift card provider identification.
          required: true
        - name: giftCardId
          in: path
          type: string
          description: Gift card identification.
          required: true
        - name: tId
          in: path
          type: string
          description: Transaction ID generated by the provider. It is different from the `transactionId` generated by VTEX.
          required: true
      - name: creategiftcardcancellationtransaction
        method: POST
        description: VTex Cancel GiftCard Transaction
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: Content-Type
          in: header
          type: string
          description: Type of the content being sent.
          required: true
        - name: Accept
          in: header
          type: string
          description: HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.
          required: true
        - name: giftCardProviderId
          in: path
          type: string
          description: Gift card provider identification.
          required: true
        - name: giftCardId
          in: path
          type: string
          description: Gift card identification.
          required: true
        - name: tId
          in: path
          type: string
          description: Transaction ID generated by the provider. It is different from the `transactionId` generated by VTEX.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: api-giftcardproviders-giftCardProviderId-giftcards-giftCardId-transactions-tId-s
      path: /api/giftcardproviders/{giftCardProviderId}/giftcards/{giftCardId}/transactions/{tId}/settlements
      operations:
      - name: listallgiftcardsettlementtransactions
        method: GET
        description: VTex List All GiftCard Transactions Settlements
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: Content-Type
          in: header
          type: string
          description: Type of the content being sent.
          required: true
        - name: Accept
          in: header
          type: string
          description: HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.
          required: true
        - name: giftCardProviderId
          in: path
          type: string
          description: Gift card provider identification.
          required: true
        - name: giftCardId
          in: path
          type: string
          description: Gift card identification.
          required: true
        - name: tId
          in: path
          type: string
          description: Transaction ID generated by the provider. It is different from the `transactionId` generated by VTEX.
          required: true
      - name: creategiftcardsettlementtransaction
        method: POST
        description: VTex Settle GiftCard Transaction
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: Content-Type
          in: header
          type: string
          description: Type of the content being sent.
          required: true
        - name: Accept
          in: header
          type: string
          description: HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.
          required: true
        - name: giftCardProviderId
          in: path
          type: string
          description: Gift card provider identification.
          required: true
        - name: giftCardId
          in: path
          type: string
          description: Gift card identification.
          required: true
        - name: tId
          in: path
          type: string
          description: Transaction ID generated by the provider. It is different from the `transactionId` generated by VTEX.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: api-giftcardproviders-giftCardProviderId-giftcards-giftCardId-transactions-trans
      path: /api/giftcardproviders/{giftCardProviderId}/giftcards/{giftCardId}/transactions/{transactionId}
      operations:
      - name: getgiftcardtransactionbyid
        method: GET
        description: VTex Get GiftCard Transaction by ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: Content-Type
          in: header
          type: string
          description: Type of the content being sent.
          required: true
        - name: Accept
          in: header
          type: string
          description: HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.
          required: true
        - name: giftCardProviderId
          in: path
          type: string
          description: Gift card provider identification.
          required: true
        - name: giftCardId
          in: path
          type: string
          description: Gift card identification.
          required: true
        - name: transactionId
          in: path
          type: string
          description: Transaction identification.
          required: true
    authentication:
      type: apikey
      key: X-VTEX-API-AppKey
      value: '{{env.VTEX_API_KEY}}'
      placement: header
  exposes:
  - type: rest
    namespace: gift-card-hub-transaction-rest
    port: 8080
    description: REST adapter for VTex GiftCard Hub API — Transaction. One Spectral-compliant resource per consumed operation,
      prefixed with /v1.
    resources:
    - path: /v1/api/giftcardproviders/{giftcardproviderid}/giftcards
      name: api-giftcardproviders-giftcardproviderid-giftcards
      description: REST surface for api-giftcardproviders-giftCardProviderId-giftcards.
      operations:
      - method: POST
        name: creategiftcardingiftcardprovider
        description: VTex Create GiftCard in GiftCard Provider
        call: gift-card-hub-transaction.creategiftcardingiftcardprovider
        with:
          Content-Type: rest.Content-Type
          Accept: rest.Accept
          giftCardProviderId: rest.giftCardProviderId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/giftcardproviders/{giftcardproviderid}/giftcards/search
      name: api-giftcardproviders-giftcardproviderid-giftcards-search
      description: REST surface for api-giftcardproviders-giftCardProviderId-giftcards-_search.
      operations:
      - method: POST
        name: getgiftcardfromgiftcardprovider
        description: VTex Get GiftCard from GiftCard Provider
        call: gift-card-hub-transaction.getgiftcardfromgiftcardprovider
        with:
          Content-Type: rest.Content-Type
          Accept: rest.Accept
          REST-Range: rest.REST-Range
          giftCardProviderId: rest.giftCardProviderId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/giftcardproviders/{giftcardproviderid}/giftcards/{giftcardid}
      name: api-giftcardproviders-giftcardproviderid-giftcards-giftcardid
      description: REST surface for api-giftcardproviders-giftCardProviderId-giftcards-giftCardId.
      operations:
      - method: GET
        name: getgiftcardfromgiftcardproviderbyid
        description: VTex Get GiftCard from GiftCard Provider by ID
        call: gift-card-hub-transaction.getgiftcardfromgiftcardproviderbyid
        with:
          Content-Type: rest.Content-Type
          Accept: rest.Accept
          giftCardProviderId: rest.giftCardProviderId
          giftCardId: rest.giftCardId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/giftcardproviders/{giftcardproviderid}/giftcards/{giftcardid}/transactions
      name: api-giftcardproviders-giftcardproviderid-giftcards-giftcardid-transactions
      description: REST surface for api-giftcardproviders-giftCardProviderId-giftcards-giftCardId-transactions.
      operations:
      - method: GET
        name: listallgiftcardtransactions
        description: VTex List All GiftCard Transactions
        call: gift-card-hub-transaction.listallgiftcardtransactions
        with:
          Content-Type: rest.Content-Type
          Accept: rest.Accept
          giftCardProviderId: rest.giftCardProviderId
          giftCardId: rest.giftCardId
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: creategiftcardtransaction
        description: VTex Create GiftCard Transaction
        call: gift-card-hub-transaction.creategiftcardtransaction
        with:
          Content-Type: rest.Content-Type
          Accept: rest.Accept
          giftCardProviderId: rest.giftCardProviderId
          giftCardId: rest.giftCardId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/giftcardproviders/{giftcardproviderid}/giftcards/{giftcardid}/transactions/{tid}/authorization
      name: api-giftcardproviders-giftcardproviderid-giftcards-giftcardid-transactions-tid-a
      description: REST surface for api-giftcardproviders-giftCardProviderId-giftcards-giftCardId-transactions-tId-a.
      operations:
      - method: GET
        name: getgiftcardauthorizationtransaction
        description: VTex Get GiftCard Transaction Authorization
        call: gift-card-hub-transaction.getgiftcardauthorizationtransaction
        with:
          Content-Type: rest.Content-Type
          Accept: rest.Accept
          giftCardProviderId: rest.giftCardProviderId
          giftCardId: rest.giftCardId
          tId: rest.tId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/giftcardproviders/{giftcardproviderid}/giftcards/{giftcardid}/transactions/{tid}/cancellations
      name: api-giftcardproviders-giftcardproviderid-giftcards-giftcardid-transactions-tid-c
      description: REST surface for api-giftcardproviders-giftCardProviderId-giftcards-giftCardId-transactions-tId-c.
      operations:
      - method: GET
        name: listallgiftcardcancellationtransactions
        description: VTex List All GiftCard Transactions Cancellations
        call: gift-card-hub-transaction.listallgiftcardcancellationtransactions
        with:
          Content-Type: rest.Content-Type
          Accept: rest.Accept
          giftCardProviderId: rest.giftCardProviderId
          giftCardId: rest.giftCardId
          tId: rest.tId
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: creategiftcardcancellationtransaction
        description: VTex Cancel GiftCard Transaction
        call: gift-card-hub-transaction.creategiftcardcancellationtransaction
        with:
          Content-Type: rest.Content-Type
          Accept: rest.Accept
          giftCardProviderId: rest.giftCardProviderId
          giftCardId: rest.giftCardId
          tId: rest.tId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/giftcardproviders/{giftcardproviderid}/giftcards/{giftcardid}/transactions/{tid}/settlements
      name: api-giftcardproviders-giftcardproviderid-giftcards-giftcardid-transactions-tid-s
      description: REST surface for api-giftcardproviders-giftCardProviderId-giftcards-giftCardId-transactions-tId-s.
      operations:
      - method: GET
        name: listallgiftcardsettlementtransactions
        description: VTex List All GiftCard Transactions Settlements
        call: gift-card-hub-transaction.listallgiftcardsettlementtransactions
        with:
          Content-Type: rest.Content-Type
          Accept: rest.Accept
          giftCardProviderId: rest.giftCardProviderId
          giftCardId: rest.giftCardId
          tId: rest.tId
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: creategiftcardsettlementtransaction
        description: VTex Settle GiftCard Transaction
        call: gift-card-hub-transaction.creategiftcardsettlementtransaction
        with:
          Content-Type: rest.Content-Type
          Accept: rest.Accept
          giftCardProviderId: rest.giftCardProviderId
          giftCardId: rest.giftCardId
          tId: rest.tId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/giftcardproviders/{giftcardproviderid}/giftcards/{giftcardid}/transactions/{transactionid}
      name: api-giftcardproviders-giftcardproviderid-giftcards-giftcardid-transactions-trans
      description: REST surface for api-giftcardproviders-giftCardProviderId-giftcards-giftCardId-transactions-trans.
      operations:
      - method: GET
        name: getgiftcardtransactionbyid
        description: VTex Get GiftCard Transaction by ID
        call: gift-card-hub-transaction.getgiftcardtransactionbyid
        with:
          Content-Type: rest.Content-Type
          Accept: rest.Accept
          giftCardProviderId: rest.giftCardProviderId
          giftCardId: rest.giftCardId
          transactionId: rest.transactionId
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: gift-card-hub-transaction-mcp
    port: 9090
    transport: http
    description: MCP adapter for VTex GiftCard Hub API — Transaction. One tool per consumed operation, routed inline through
      this capability's consumes block.
    tools:
    - name: vtex-create-giftcard-giftcard-provider
      description: VTex Create GiftCard in GiftCard Provider
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: gift-card-hub-transaction.creategiftcardingiftcardprovider
      with:
        Content-Type: tools.Content-Type
        Accept: tools.Accept
        giftCardProviderId: tools.giftCardProviderId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: vtex-get-giftcard-giftcard-provider
      description: VTex Get GiftCard from GiftCard Provider
      hints:
        readOnly: true
        destructive: false
        idempotent: false
      call: gift-card-hub-transaction.getgiftcardfromgiftcardprovider
      with:
        Content-Type: tools.Content-Type
        Accept: tools.Accept
        REST-Range: tools.REST-Range
        giftCardProviderId: tools.giftCardProviderId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: vtex-get-giftcard-giftcard-provider-2
      description: VTex Get GiftCard from GiftCard Provider by ID
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: gift-card-hub-transaction.getgiftcardfromgiftcardproviderbyid
      with:
        Content-Type: tools.Content-Type
        Accept: tools.Accept
        giftCardProviderId: tools.giftCardProviderId
        giftCardId: tools.giftCardId
      outputParameters:
      - type: object
        mapping: $.
    - name: vtex-list-all-giftcard-transactions
      description: VTex List All GiftCard Transactions
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: gift-card-hub-transaction.listallgiftcardtransactions
      with:
        Content-Type: tools.Content-Type
        Accept: tools.Accept
        giftCardProviderId: tools.giftCardProviderId
        giftCardId: tools.giftCardId
      outputParameters:
      - type: object
        mapping: $.
    - name: vtex-create-giftcard-transaction
      description: VTex Create GiftCard Transaction
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: gift-card-hub-transaction.creategiftcardtransaction
      with:
        Content-Type: tools.Content-Type
        Accept: tools.Accept
        giftCardProviderId: tools.giftCardProviderId
        giftCardId: tools.giftCardId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: vtex-get-giftcard-transaction-authorization
      description: VTex Get GiftCard Transaction Authorization
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: gift-card-hub-transaction.getgiftcardauthorizationtransaction
      with:
        Content-Type: tools.Content-Type
        Accept: tools.Accept
        giftCardProviderId: tools.giftCardProviderId
        giftCardId: tools.giftCardId
        tId: tools.tId
      outputParameters:
      - type: object
        mapping: $.
    - name: vtex-list-all-giftcard-transactions-2
      description: VTex List All GiftCard Transactions Cancellations
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: gift-card-hub-transaction.listallgiftcardcancellationtransactions
      with:
        Content-Type: tools.Content-Type
        Accept: tools.Accept
        giftCardProviderId: tools.giftCardProviderId
        giftCardId: tools.giftCardId
        tId: tools.tId
      outputParameters:
      - type: object
        mapping: $.
    - name: vtex-cancel-giftcard-transaction
      description: VTex Cancel GiftCard Transaction
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: gift-card-hub-transaction.creategiftcardcancellationtransaction
      with:
        Content-Type: tools.Content-Type
        Accept: tools.Accept
        giftCardProviderId: tools.giftCardProviderId
        giftCardId: tools.giftCardId
        tId: tools.tId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: vtex-list-all-giftcard-transactions-3
      description: VTex List All GiftCard Transactions Settlements
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: gift-card-hub-transaction.listallgiftcardsettlementtransactions
      with:
        Content-Type: tools.Content-Type
        Accept: tools.Accept
        giftCardProviderId: tools.giftCardProviderId
        giftCardId: tools.giftCardId
        tId: tools.tId
      outputParameters:
      - type: object
        mapping: $.
    - name: vtex-settle-giftcard-transaction
      description: VTex Settle GiftCard Transaction
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: gift-card-hub-transaction.creategiftcardsettlementtransaction
      with:
        Content-Type: tools.Content-Type
        Accept: tools.Accept
        giftCardProviderId: tools.giftCardProviderId
        giftCardId: tools.giftCardId
        tId: tools.tId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: vtex-get-giftcard-transaction-id
      description: VTex Get GiftCard Transaction by ID
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: gift-card-hub-transaction.getgiftcardtransactionbyid
      with:
        Content-Type: tools.Content-Type
        Accept: tools.Accept
        giftCardProviderId: tools.giftCardProviderId
        giftCardId: tools.giftCardId
        transactionId: tools.transactionId
      outputParameters:
      - type: object
        mapping: $.