VTEX Fulfillment API

openapi: 3.2.0
info:
  title: VTex Checkout Fulfillment API
  description: '>ℹ️ Check the new Checkout onboarding guide.'
  contact: {}
  version: '1.0'
servers:
- url: https://{accountName}.{environment}.com.br
  description: VTEX server URL.
  variables:
    accountName:
      description: Name of the VTEX account. Used as part of the URL
      default: apiexamples
    environment:
      description: Environment to use. Used as part of the URL.
      enum:
      - vtexcommercestable
      default: vtexcommercestable
security:
- appKey: []
  appToken: []
- VtexIdclientAutCookie: []
tags:
- name: Fulfillment
paths:
  /api/checkout/pub/pickup-points:
    get:
      tags:
      - Fulfillment
      summary: VTex List pickup points by location
      description: 'Retrieves information on pickup points close to a given location determined by geocoordinates or postal code.


        The pickup points returned are not necessarily all active ones. Make sure to validate the information consumed by integrations.


        ## Permissions


        This endpoint does not require permissions.'
      operationId: ListPickupPpointsByLocation
      security: []
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      - name: geoCoordinates
        in: query
        description: Geocoordinates (first longitude, then latitude) around which to search for pickup points. If you use this type of search, do not pass postal and country codes.
        required: false
        style: form
        schema:
          type: array
          example:
          - -47.924747467041016
          - -15.832582473754883
          items:
            description: Geocoordinate.
            type: number
            example: -47.924747467041016
      - name: postalCode
        in: query
        description: Postal code around which to search for pickup points. If you use this type of search, make sure to pass a `countryCode` and do not pass `geoCoordinates`.
        required: false
        style: form
        schema:
          type: string
          example: '1234000'
      - name: countryCode
        in: query
        description: Three letter country code refering to the `postalCode` field. Pass the country code only if you are searching pickup points by postal code.
        required: false
        style: form
        schema:
          type: string
          example: BRA
      responses:
        '200':
          description: OK
          content:
            application/json:
              example:
                paging:
                  page: 1
                  pageSize: 30
                  total: 1
                  pages: 1
                items:
                - distance: 0.8469786518616546
                  pickupPoint:
                    friendlyName: physical-store-02
                    address:
                      addressType: pickup
                      receiverName: null
                      addressId: physical-store-02
                      isDisposable: true
                      postalCode: 23450-070
                      city: Rio de Janeiro
                      state: RJ
                      country: BRA
                      street: Praia de Botafogo
                      number: '132'
                      neighborhood: Botafogo
                      complement: Apto 101
                      reference: null
                      geoCoordinates:
                      - -47.924747467041016
                      - -15.832582473754883
                    additionalInfo: null
                    id: 02_Physical
                    businessHours:
                    - DayOfWeek: 0
                      OpeningTime: 00:00:00
                      ClosingTime: '23:59:00'
                    - DayOfWeek: 1
                      OpeningTime: 00:00:00
                      ClosingTime: '23:59:00'
                    - DayOfWeek: 2
                      OpeningTime: 00:00:00
                      ClosingTime: '23:59:00'
                    - DayOfWeek: 3
                      OpeningTime: 00:00:00
                      ClosingTime: '23:59:00'
                    - DayOfWeek: 4
                      OpeningTime: 00:00:00
                      ClosingTime: '23:50:00'
                    - DayOfWeek: 5
                      OpeningTime: 00:00:00
                      ClosingTime: '23:59:00'
                    - DayOfWeek: 6
                      OpeningTime: 00:00:00
                      ClosingTime: '23:59:00'
              schema:
                type: object
                properties:
                  paging:
                    description: Paging.
                    type: object
                    properties:
                      page:
                        description: Page number.
                        type: integer
                      pageSize:
                        description: Page size.
                        type: integer
                      total:
                        description: Total pages.
                        type: integer
                      pages:
                        description: Pages.
                        type: integer
                  items:
                    description: Items.
                    type: array
                    items:
                      description: Item information.
                      type: object
                      properties:
                        distance:
                          description: Distance.
                          type: integer
                        pickupPoint:
                          description: Pickup point.
                          type: object
                          properties:
                            friendlyName:
                              description: Friendly name.
                              type: string
                            address:
                              description: Address.
                              type: object
                              properties:
                                addressType:
                                  description: Address type.
                                  type: string
                                receiverName:
                                  description: Receiver name.
                                  type: string
                                addressId:
                                  description: Address ID.
                                  type:
                                  - string
                                  - 'null'
                                isDisposable:
                                  description: Is disposable.
                                  type: boolean
                                postalCode:
                                  description: Postal code.
                                  type: string
                                city:
                                  description: City.
                                  type: string
                                state:
                                  description: State.
                                  type: string
                                country:
                                  description: Country.
                                  type: string
                                street:
                                  description: Street.
                                  type: string
                                number:
                                  description: Number.
                                  type: string
                                neighborhood:
                                  description: Neighborhood.
                                  type: string
                                complement:
                                  description: Complement.
                                  type: string
                                reference:
                                  description: Racao.
                                  type: string
                                geoCoordinates:
                                  description: Geo coordinates.
                                  type: array
                                  items:
                                    description: Geo coordinate.
                                    type: integer
                            additionalInfo:
                              description: Additional info.
                              type: string
                            id:
                              description: ID.
                              type: string
                            businessHours:
                              description: Array with business hours.
                              type: array
                              items:
                                description: Business hours.
                                type: object
                                properties:
                                  DayOfWeek:
                                    description: Day of week.
                                    type: integer
                                  OpeningTime:
                                    description: Opening time.
                                    type: string
                                  ClosingTime:
                                    description: Closing time.
                                    type: string
  /api/checkout/pub/postal-code/{countryCode}/{postalCode}:
    get:
      tags:
      - Fulfillment
      summary: VTex Get address by postal code
      description: 'Retrieves address information for a given postal code and country.


        This request can be used to implement auto complete functionality when a customer needs to fill in an address.


        ## Permissions


        This endpoint does not require permissions.'
      operationId: GetAddressByPostalCode
      security: []
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      - name: countryCode
        in: path
        description: Three letter country code refering to the `postalCode` field.
        required: true
        style: simple
        schema:
          type: string
          example: BRA
      - name: postalCode
        in: path
        description: Postal code.
        required: true
        style: simple
        schema:
          type: string
          example: '1234000'
      responses:
        '200':
          description: OK
          content:
            application/json:
              example:
                postalCode: '12345000'
                city: Rio de Janeiro
                state: RJ
                country: BRA
                street: My street
                number: '34'
                neighborhood: My neighborhood
                complement: Apto 101
                reference: Reference
                geoCoordinates: []
              schema:
                description: Address.
                type: object
                properties:
                  postalCode:
                    description: Postal code.
                    type: string
                  city:
                    description: City.
                    type: string
                  state:
                    description: State.
                    type: string
                  country:
                    description: Country.
                    type: string
                  street:
                    description: Street.
                    type: string
                  number:
                    description: Number.
                    type: string
                  neighborhood:
                    description: Neighborhood.
                    type: string
                  complement:
                    description: Complement.
                    type: string
                  reference:
                    description: Reference.
                    type: string
                  geoCoordinates:
                    description: Geo coordinates.
                    type: array
                    items:
                      description: Geo coordinate.
                      type: integer
components:
  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
        default: application/json
    Content-Type:
      name: Content-Type
      in: header
      description: Type of the content being sent.
      required: true
      style: simple
      schema:
        type: string
        default: application/json
  securitySchemes:
    appKey:
      type: apiKey
      in: header
      name: X-VTEX-API-AppKey
      description: Unique identifier of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys).
    appToken:
      type: apiKey
      in: header
      name: X-VTEX-API-AppToken
      description: Secret token of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys).
    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.'