openapi: 3.0.0
info:
  title: VTex Anti-fraud Provider Account Service Integration 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: Service Integration
  description: These endpoints must be developed to integrate with the Lastmile Pick and Pack Last Mile Protocol API.
paths:
  /create-service:
    post:
      tags:
      - Service Integration
      summary: VTex Create service
      description: "Creates a service with the information that VTEX will send to the carrier. To understand how to integrate with a carrier, check the [VTEX Pick and Pack Carriers Integration Protocol](https://developers.vtex.com/docs/guides/vtex-pick-and-pack) guide.\r\n\r\nThis endpoint must be developed by the carriers or brokers to integrate into the protocol.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [permissions](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3)."
      operationId: Createservice
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/Authorization'
      requestBody:
        content:
          application/json:
            example:
              orderId: SLR-29384924-01
              carrierId: servientrega-50461c9f3335
              seller: qaolimpica
              sender:
                name: Tabitha Sears
                phone: +57 2305781612
                email: tabitha_sears@fortean.brother
                city: Jenkinsville
                state: Northern Mariana Islands
                country: US
                address: 77 Sullivan Place, Jenkinsville, Northern Mariana Islands
                addressComplement: Flat 45
                number: '1029'
                reference: '3'
                location:
                  latitude: -75.269008
                  longitude: 137.499833
                pickupDate: '2024-04-25T18:06:41.202Z'
              receiver:
                name: Pansy Graves
                phone: +57 4240807147
                email: pansy_graves@zentime.moda
                city: Valle
                state: Marshall Islands
                country: Iceland
                neighborhood: Billings
                number: '9840'
                reference: 63 Billings Place, Valle, Marshall Islands
                addressComplement: Flat 45
                location:
                  latitude: -33.249891
                  longitude: -135.052901
                identification: '9541933267'
                deliveryDate: '2024-04-16T20:49:36.117Z'
                contactName: Savannah Porter
                deliveryWindow:
                  name: consectetur
                  initialDate: '2024-04-25T22:50:41.209Z'
                  finalDate: '2024-05-05T21:50:41.210Z'
              packages:
              - id: 6266df719ac55224b793ad36
                orderId: SLR-1221800709659-01
                envelope: Large
                description: Delicate package
                categories:
                - Cellphone
                - Technology
                dimensions:
                  width: '68'
                  height: '43'
                  length: '13'
                weight: '19'
                totalValue: 5616.01
                items:
                - id: 6266df71a19ebe35637e1f42
                  name: Tomatos
                  ean: '473390795673'
                  refId: '6266'
                  image: https://static9.depositphotos.com/1628352/1107/i/600/depositphotos_11071361-stock-photo-tomato.jpg
                  type: Food
                  price: 774230.01
                  weight: 4 kg
                  quantity: 4
                - id: 6266df71803601c3bc4e2d99
                  name: Tomatos
                  ean: '329949764612'
                  refId: '6266'
                  image: https://static9.depositphotos.com/1628352/1107/i/600/depositphotos_11071361-stock-photo-cellphone.jpg
                  type: Foods
                  price: 23162
                  weight: 14 kg
                  quantity: 9
              type: PICKUP_DELIVERY
              carrierServiceType: OTHERS
              comments: Delivery comments.
              paymentMethod: CASH_ON_DELIVERY
              orderValue: 8000
              settings:
              - label: Key secret
                value: keysecret-0122
                key: secrekey
              timezone:
                offset: 300
                value: America/Bogota
            schema:
              $ref: '#/components/schemas/CreateServiceBody'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseService'
        '400':
          description: Bad request
        '401':
          description: Required authentication
        '404':
          description: Resource not found
        '500':
          description: Internal error
      deprecated: false
      servers:
      - url: https://{store_endpoint}
        variables:
          your_endpoint:
            default: storeapi.com
            description: Server from the store.
components:
  schemas:
    Dimensions:
      required:
      - height
      - length
      - width
      type: object
      properties:
        height:
          type: string
          description: Package height in centimeters.
        length:
          type: string
          description: Package length in centimeters.
        width:
          type: string
          description: Package width in centimeters.
      example:
        height: '5'
        length: '11'
        width: '7'
    ResponseService:
      type: object
      required:
      - status
      - serviceId
      - shippingPrice
      - metaData
      - shippingEstimatedDate
      - labels
      properties:
        status:
          type: string
          example: PENDING
          description: Status of the service.
          enum:
          - PENDING
          - ASSIGNED
          - PICKED
          - ON_ROUTE
          - INCIDENT
          - RETURNED
          - DELIVERED
          - CANCELED
          - ON_HOLD
        serviceId:
          type: string
          example: ASDF23324KDSF2
          description: Service ID.
        shippingPrice:
          type: number
          example: 20000.09
          description: Service shipping price.
        metaData:
          type: object
          properties:
            '{keyValue}':
              description: Carrier additional information.
              type: string
          example:
            anyKey: anyValue
        shippingEstimatedDate:
          type: string
          example: '2024-05-29T22:36:37.589Z'
          description: Shipping estimated date in [UTC time format](https://learn.microsoft.com/en-us/rest/api/storageservices/formatting-datetime-values), as in `YYYY-MM-DDThh:mm:ssZ`.
        labels:
          type: array
          items:
            $ref: '#/components/schemas/Label'
          description: Shipping labels, there may be more than one per order due to breakage in packages.
    Item:
      title: Item
      required:
      - id
      - name
      - ean
      - quantity
      - price
      - refId
      - image
      - type
      - weight
      type: object
      properties:
        id:
          type: string
          description: Product ID.
        name:
          type: string
          description: Product name.
        ean:
          type: string
          description: Unique SKU identification code (barcode). Up to 13 numerical characters.
        quantity:
          type: integer
          format: int32
          description: Quantity of units of the product.
        price:
          type: integer
          format: int32
          description: Product price in cents.
        refId:
          type: string
          description: Product reference ID.
        image:
          type: string
          description: SKU image.
        type:
          type: string
          description: Item type.
        weight:
          type: string
          description: Product weight in grams.
      example:
        id: '184'
        name: Chicken
        ean: EAN354
        quantity: 8
        price: 669
        refId: '314'
        image: https://picsum.photos/seed/YtoZ9/128/480
        type: other
        weight: '6'
    CreateServiceBody:
      type: object
      properties:
        orderId:
          type: string
          description: Order ID.
        carrierId:
          type: string
          description: Carrier ID.
        seller:
          type: string
          description: Identifier representing the seller associated with the order.
        sender:
          description: Sender personal information.
          type: object
          properties:
            name:
              description: Sender name.
              type: string
            phone:
              description: Sender phone number.
              type: string
            email:
              description: Sender email.
              type: string
            city:
              description: Sender city of residence.
              type: string
            state:
              description: Sender state of residence.
              type: string
            country:
              description: Sender country of residence.
              type: string
            address:
              description: Sender address.
              type: string
            addressComplement:
              description: Sender address complement, as apartment number.
              type: string
            number:
              description: Sender residence number.
              type: string
            reference:
              description: Reference to the sender's address to facilitate localization.
              type: string
            location:
              description: Object containing specific latitude and longitude of the sender's address.
              type: object
              properties:
                latitude:
                  description: Sender address' latitude.
                  type: number
                longitude:
                  description: Sender address' longitude.
                  type: number
            pickupDate:
              description: Package pickup date in [UTC time format](https://learn.microsoft.com/en-us/rest/api/storageservices/formatting-datetime-values), as in `YYYY-MM-DDThh:mm:ssZ`.
              type: string
        receiver:
          description: Receiver personal information.
          type: object
          properties:
            name:
              description: Receiver name.
              type: string
            phone:
              description: Receiver phone number.
              type: string
            email:
              description: Receiver email.
              type: string
            city:
              description: Receiver city of residence.
              type: string
            state:
              description: Receiver state of residence.
              type: string
            country:
              description: Receiver country of residence.
              type: string
            address:
              description: Receiver address.
              type: string
            addressComplement:
              description: Receiver address complement, as apartment number.
              type: string
            number:
              description: Receiver residence number.
              type: string
            reference:
              description: Reference to the receiver's address to facilitate localization.
              type: string
            location:
              description: Object containing specific latitude and longitude of the receiver's address.
              type: object
              properties:
                latitude:
                  description: Receiver address' latitude.
                  type: number
                longitude:
                  description: Receiver address' longitude.
                  type: number
            identification:
              description: Receiver identification code.
              type: string
            deliveryDate:
              description: Delivery estimated date in [UTC time format](https://learn.microsoft.com/en-us/rest/api/storageservices/formatting-datetime-values), as in `YYYY-MM-DDThh:mm:ssZ`.
              type: string
            contactName:
              description: Receiver contact name.
              type: string
            deliveryWindow:
              description: Object containing information about package delivery window.
              type: object
              properties:
                name:
                  description: Carrier name.
                  type: string
                initialDate:
                  description: Delivery initial date in [UTC time format](https://learn.microsoft.com/en-us/rest/api/storageservices/formatting-datetime-values), as in `YYYY-MM-DDThh:mm:ssZ`.
                  type: string
                finalDate:
                  description: Delivery final date in [UTC time format](https://learn.microsoft.com/en-us/rest/api/storageservices/formatting-datetime-values), as in `YYYY-MM-DDThh:mm:ssZ`.
                  type: string
        packages:
          type: array
          items:
            $ref: '#/components/schemas/Package'
          description: Array containing information about all order's packages.
        carrierServiceType:
          type: string
          description: Carrier service type. The `carrierServiceType` value is not limited to these specific values. It will be defined by the carrier integrating with the Pick and Pack Last Mile Protocol API.
          enum:
          - BROKER
          - PICKUP_IN_STORE
          - NATIONAL
          - INTERNATIONAL
          - EXPRESS
          - SPECIALIZED
          - OTHERS
        type:
          type: string
          description: Order's type of delivery, `Delivery` or [`Pickup`](https://help.vtex.com/en/tutorial/pickup-points--2fljn6wLjn8M4lJHA6HP3R).
        paymentMethod:
          type: string
          description: Payment method.
        comments:
          type: string
          description: Comments.
        orderValue:
          type: integer
          description: Total value of the order.
        settings:
          description: Array of objects with additional custom fields defined by the carrier.
          type: array
          items:
            description: Object containing information about a custom field.
            type: object
            properties:
              label:
                description: Custom field description.
                type: string
              value:
                description: Custom field value.
                type: string
              key:
                description: Custom field key.
                type: string
        timezone:
          $ref: '#/components/schemas/Timezone'
    Package:
      required:
      - id
      - orderId
      - envelope
      - dimensions
      - weight
      - totalValue
      - items
      - categories
      - description
      type: object
      description: Package information.
      properties:
        id:
          type: string
          description: Package ID.
        orderId:
          type: string
          description: Order ID.
        envelope:
          type: string
          description: Name of the envelope used.
        dimensions:
          $ref: '#/components/schemas/Dimensions'
          description: Package dimensions.
        weight:
          type: string
          description: Package weight in grams.
        totalValue:
          type: integer
          format: int32
          description: Total value of the order.
        items:
          type: array
          items:
            $ref: '#/components/schemas/Item'
            description: Product general information.
          description: Array containing information about the order's products.
        categories:
          type: array
          items:
            type: string
            description: Category name.
          description: Array of categories.
        description:
          type: string
          description: Package description.
      example:
        id: a46e5bc1-8959-459f-a094-b6e699f7214c
        orderId: 46369545534253-01
        envelope: Foam or Plastic Containers
        dimensions:
          height: '5'
          length: '11'
          width: '7'
        weight: '48'
        totalValue: 5352
        items:
        - id: '184'
          name: Chicken
          ean: EAN354
          quantity: 8
          price: 669
          refId: '314'
          image: https://picsum.photos/seed/YtoZ9/128/480
          type: other
          weight: '6'
        categories:
        - Movies
        - Garden
        - Books
        description: Unde deserunt libero cupiditate illum.
    Timezone:
      required:
      - offset
      - value
      - label
      type: object
      description: Time zone information.
      properties:
        offset:
          type: integer
          format: int32
          description: Time zone offset.
        value:
          type: string
          description: Time zone.
        label:
          type: string
          nullable: true
          description: Label.
      example:
        offset: 300
        value: America/Bogota
        label: null
    Label:
      required:
      - id
      - name
      - url
      - type
      type: object
      properties:
        id:
          type: string
          description: Label ID.
        name:
          type: string
          description: Name of the label.
        url:
          type: string
          description: Label URL.
        type:
          type: string
          description: Label's type of file.
      example:
        id: 78c83922-d658-48bf-89d5-0658a6a94e27
        name: Shipping label
        url: https://sandbox-download.postmen.com/label/2024-03-09/258a26a4-45ae-49eb-b64d-929d3b81f46d-1709947994279763.pdf
        type: PDF
  parameters:
    Accept:
      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
        example: application/json
    Content-Type:
      name: Content-Type
      in: header
      description: Type of the content being sent.
      required: true
      style: simple
      schema:
        type: string
        example: application/json
    Authorization:
      name: Authorization
      in: header
      description: Authentication JWT. JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information as a JSON object between parties.
      required: true
      style: simple
      schema:
        type: string
        example: '{token}'
  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.'