VTEX Order Hook API

openapi: 3.0.0
info:
  title: VTex Anti-fraud Provider Account Order Hook API
  description: ">ℹ️ Onboarding guide\r\n>\r\n> Check the new [Payments onboarding guide](https://developers.vtex.com/docs/guides/payments-overview). We created this guide to improve the onboarding experience for developers at VTEX. It assembles all documentation on our Developer Portal about Payments and is organized by focusing on the developer's journey.\r\n\r\nThe Anti-fraud Provider Protocol is a set of definitions to help you integrate your anti-fraud service API into VTEX platform.\r\n\r\nTo achieve this, you need to implement a web API (REST) following the specifications described in this documentation.\r\n\r\n>⚠️ You can also access our [template on GitHub](https://github.com/vtex-apps/antifraud-provider-example) to help you quickly develop your anti-fraud connector using the Anti-fraud Provider Protocol and VTEX IO.\r\n\r\nTo learn more about the Anti-fraud Provider Protocol, check our [developer guide](https://developers.vtex.com/docs/guides/how-the-integration-protocol-between-vtex-and-antifraud-companies-works).\r\n\r\n## Anti-fraud Provider API Index\r\n\r\n### Anti-fraud  Flow\r\n\r\n- `POST` [Send Anti-fraud Pre-Analysis Data (optional)](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#post-/pre-analysis)\r\n- `POST` [Send Anti-fraud Data](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#post-/transactions)\r\n- `PUT` [Update Anti-fraud Transactions (optional)](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#put-/transactions/-transactionId-)\r\n- `GET` [List Anti-fraud Provider Manifest](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/manifest)\r\n- `GET` [Get Anti-fraud Status](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/transactions/-transactions.id-)\r\n- `DELETE` [Stop Anti-fraud Analysis (optional)](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#delete-/transactions/-transactions.Id-)\r\n\r\n### OAuth Flow\r\n\r\n1. `POST` [Retrieve Token](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#post-/authorization/token)\r\n2. `GET` [Redirect](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/redirect)\r\n3. `GET` [Return to VTEX](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/authorizationCode)\r\n4. `GET` [Get Credentials](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/authorization/credentials)"
  version: '1.0'
servers:
- url: https://{providerApiEndpoint}
  description: Anti-fraud provider endpoint URL.
  variables:
    providerApiEndpoint:
      description: Anti-fraud provider endpoint URL.
      default: '{providerApiEndpoint}'
tags:
- name: Order Hook
paths:
  /api/orders/hook/config:
    get:
      tags:
      - Order Hook
      summary: VTex Get hook configuration
      description: "Retrieves a given hook's configuration details. Learn more with the [orders hook guide](https://developers.vtex.com/vtex-rest-api/docs/orders-feed#hook). \r\n\r\n> \U0001F4D8 Onboarding guide \r\n>\r\n> Check the new [Orders onboarding guide](https://developers.vtex.com/vtex-rest-api/docs/orders-overview). We created this guide to improve the onboarding experience for developers at VTEX. It assembles all documentation on our Developer Portal about Orders and is organized by focusing on the developer's journey.\r\n\r\n"
      operationId: GetHookConfiguration
      parameters:
      - name: Content-Type
        in: header
        description: Type of the content being sent.
        required: true
        style: simple
        schema:
          type: string
          default: application/json
      - name: Accept
        in: header
        description: HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.
        required: true
        style: simple
        schema:
          type: string
          default: application/json
      - name: clientEmail
        in: query
        description: Customer email.
        required: false
        style: form
        explode: true
        schema:
          type: string
          example: customer@mail.com
      - name: page
        in: query
        description: Page number for result pagination.
        required: false
        style: form
        explode: true
        schema:
          type: string
          example: '10'
      - name: per_page
        in: query
        description: Page quantity for result pagination.
        required: false
        style: form
        explode: true
        schema:
          type: string
          example: '15'
      responses:
        '200':
          description: OK
          headers: {}
      deprecated: false
    post:
      tags:
      - Order Hook
      summary: VTex Create or update hook configuration
      description: "Configures filtering rules applied to orders hook. Learn more with the [orders hook guide](https://developers.vtex.com/vtex-rest-api/docs/orders-feed#hook).\n\r\n\rThere are two types of filtering that can be used: \n\r\n\r - `FromWorkflow`: filters orders by status.\n\r\n\r - `FromOrders`: uses JSONata expressions to filter orders according to any property in the orders JSON document.\n\r\n\r This enables stores to filter delivered orders and orders in which products have been added or removed, for example.\n\r\n\rTo learn more, access the [JSONata documentation](https://docs.jsonata.org/overview.html) and test filtering JSONata expressions with our [expressions API](https://developers.vtex.com/docs/api-reference/orders-api#post-/api/orders/expressions/jsonata)."
      operationId: HookConfiguration
      parameters:
      - name: Content-Type
        in: header
        description: Type of the content being sent.
        required: true
        style: simple
        schema:
          type: string
          default: application/json
      - name: Accept
        in: header
        description: HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.
        required: true
        style: simple
        schema:
          type: string
          default: application/json
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HookConfigurationRequest'
            example:
              filter:
                type: FromOrders
                expression: value > 100
                disableSingleFire: false
              hook:
                url: https://endpoint.example/path
                headers:
                  key: value
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HookConfiguration'
              example:
                Domain: Fulfillment
                OrderId: v52277740atmc-01
                State: ready-for-handling
                LastState: window-to-cancel
                LastChange: '2019-08-14T17:11:39.2550122Z'
                CurrentChange: '2019-08-14T17:12:48.0965893Z'
                Origin:
                  Account: automacaoqa
                  Key: vtexappkey-appvtex
      deprecated: false
    delete:
      tags:
      - Order Hook
      summary: VTex Delete hook configuration
      description: "Deletes a given hook configuration.\n\r\n\rLearn more with the [orders hook guide](https://developers.vtex.com/vtex-rest-api/docs/orders-feed#hook)."
      operationId: DeleteHookConfiguration
      parameters:
      - name: Accept
        in: header
        description: HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.
        required: true
        style: simple
        schema:
          type: string
          default: application/json
      - name: Content-Type
        in: header
        description: Type of the content being sent.
        required: true
        style: simple
        schema:
          type: string
          default: application/json
      responses:
        '200':
          description: Success
        '403':
          description: The credentials are not enabled to access the service
        '404':
          description: Value not found
        '429':
          description: Too many requests
      deprecated: false
components:
  schemas:
    HookConfiguration:
      title: HookConfiguration
      required:
      - Domain
      - OrderId
      - State
      - LastState
      - LastChange
      - CurrentChange
      - Origin
      type: object
      properties:
        Domain:
          type: string
        OrderId:
          type: string
        State:
          type: string
        LastState:
          type: string
        LastChange:
          type: string
        CurrentChange:
          type: string
        Origin:
          $ref: '#/components/schemas/Origin2'
      example:
        Domain: Fulfillment
        OrderId: v52277740atmc-01
        State: ready-for-handling
        LastState: window-to-cancel
        LastChange: '2019-08-14T17:11:39.2550122Z'
        CurrentChange: '2019-08-14T17:12:48.0965893Z'
        Origin:
          Account: automacaoqa
          Key: vtexappkey-appvtex
    HookConfigurationRequest:
      title: HookConfigurationRequest
      required:
      - filter
      - hook
      type: object
      properties:
        filter:
          $ref: '#/components/schemas/HookFilter'
        hook:
          $ref: '#/components/schemas/Hook'
      example:
        filter:
          type: FromWorkflow
          status:
          - order-completed
          - handling
          - ready-for-handling
          - waiting-ffmt-authorization
          - cancel
        hook:
          url: https://endpoint.example/path
          headers:
            key: value
    HookFilter:
      title: Filter
      required:
      - type
      type: object
      properties:
        type:
          type: string
          description: "Determines what orders appear in the hook and how they are filtered. As shown in the examples above, there are two ways:\r\n\r\n - `FromWorkflow`: the hook will receive order updates only when there is a change or update in the [order status](https://help.vtex.com/en/tutorial/order-flow-and-status--tutorials_196). You must send at least one value for the `status` field to determine by which status the orders will be filtered.\r\n\r\n - `FromOrders`: the hook will receive order updates when there is a change in the order. In this case, orders can be filtered by any property, according to JSONata expressions passed in the `expression` field. You must send the request with values for the `expression` and `disableSingleFire` fields."
          example: FromWorkflow
        status:
          type: array
          items:
            type: string
          description: List of order statuses that should be included in the hook. This should only be used in case `type` is `FromWorkflow`.
        expression:
          type: string
          description: JSONata query expression that defines what conditions must be met for an order to be included in the hook. This should only be used in case `type` is `FromOrders`.
        disableSingleFire:
          type: boolean
          description: Sets a limit to how many times a specific order shows on the hook, after it first meets filtering conditions. Using the `FromOrders` type configuration with JSONata filtering expressions might cause orders to appear more than once on a feed, whenever changes are made to that order. If this field is `false` orders will appear in the hook only once. Send this field if you want to filter `FromOrders`.
          example: false
    Headers:
      title: Headers
      required:
      - key
      type: object
      properties:
        key:
          type: string
      example:
        key: value
    Origin2:
      title: Origin2
      required:
      - Account
      - Key
      type: object
      properties:
        Account:
          type: string
        Key:
          type: string
      example:
        Account: automacaoqa
        Key: vtexappkey-appvtex
    Hook:
      title: Hook
      required:
      - url
      - headers
      type: object
      properties:
        url:
          type: string
        headers:
          $ref: '#/components/schemas/Headers'
      example:
        url: https://endpoint.example/path
        headers:
          key: value
  securitySchemes:
    VtexIdclientAutCookie:
      type: apiKey
      in: header
      name: VtexIdclientAutCookie
      description: '[User token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens), valid for 24 hours.'