@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Orders API
@base https://apiexamples.vtexcommercestable.com.br
@version 1.0
@auth ApiKey X-VTEX-API-AppKey in header | ApiKey X-VTEX-API-AppToken in header | ApiKey VtexIdclientAutCookie in header
@common_fields {Accept: str=application/json, Content-Type: str=application/json}
@endpoints 36
@hint download_for_search
@toc api(36)

@endpoint GET /api/oms/pvt/orders/{orderId}
@required {orderId: str}
@returns(200) {orderId: str, sequence: str, marketplaceOrderId: str, marketplaceServicesEndpoint: str, sellerOrderId: str, origin: str, affiliateId: str, salesChannel: str, merchantName: str?, status: str, workflowIsInError: bool, statusDescription: str, value: int, creationDate: str, lastChange: str, orderGroup: str, followUpEmail: str, lastMessage: str?, hostname: str, isCompleted: bool, roundingError: int, orderFormId: str, allowCancellation: bool, allowEdition: bool, isCheckedIn: bool, authorizedDate: str?, invoicedDate: str?, cancelReason: str?, checkedInPickupPointId: str?, totals: [map], sellers: [map], clientPreferencesData: map{locale: str, optinNewsLetter: bool}, cancellationData: map?{RequestedByUser: bool?, RequestedBySystem: bool?, RequestedBySellerNotification: bool?, RequestedByPaymentNotification: bool?, Reason: str?, CancellationDate: str?}, taxData: map?{areTaxesDesignatedByMarketplace: bool, taxInfoCollection: [map]}, subscriptionData: map?{SubscriptionGroupId: str?, Subscriptions: [map]?}, itemMetadata: map{Items: [map]}, marketplace: map?{baseURL: str, isCertified: bool?, name: str}, storePreferencesData: map{countryCode: str, currencyCode: str, currencyFormatInfo: map{CurrencyDecimalDigits: int, CurrencyDecimalSeparator: str, CurrencyGroupSeparator: str, CurrencyGroupSize: int, StartsWithCurrencySymbol: bool}, currencyLocale: int, currencySymbol: str, timeZone: str}, customData: map?{customApps: [map]?, customFields: [map]}, commercialConditionData: str?, openTextField: map?, invoiceData: map?{address: map?{addressType: str?, receiverName: str?, addressId: str?, versionId: str?, entityId: str?, postalCode: str, city: str, state: str, country: str, street: str, number: str, neighborhood: str, complement: str?, reference: str?, geoCoordinates: [num], contactId: str?}, userPaymentInfo: map?{paymentMethods: [str]}, invoiceSubject: map?{id: str, email: str, firstName: str, lastName: str, phone: str}}, changesAttachment: map?{id: str, changesData: [map]}, callCenterOperatorData: map?{id: str, email: str, userName: str}, packageAttachment: map?{packages: [map]}, paymentData: map{giftCards: [map]?, transactions: [map]}, shippingData: map{id: str, address: map{addressType: str, receiverName: str, addressId: str, versionId: str?, entityId: str?, postalCode: str, city: str, state: str, country: str, street: str, number: str, neighborhood: str, complement: str, reference: str?, geoCoordinates: [num]}, logisticsInfo: [map], trackingHints: [map]?, selectedAddresses: [map], contactInformation: [map]}, ratesAndBenefitsData: map{id: str, rateAndBenefitsIdentifiers: [map]}, marketingData: map?{id: str, utmSource: str, utmPartner: str, utmMedium: str, utmCampaign: str, coupon: str, utmiCampaign: str, utmipage: str, utmiPart: str, marketingTags: [str]}, giftRegistryData: map?{giftRegistryId: str, giftRegistryType: str, giftRegistryTypeName: str, addressId: str, description: str}, clientProfileData: map{id: str, email: str, firstName: str, lastName: str, documentType: str, document: str, phone: str, corporateName: str?, tradeName: str?, corporateDocument: str?, stateInscription: str?, corporatePhone: str?, isCorporate: bool, userProfileId: str, userProfileVersion: str?, customerClass: str?, customerCode: str?}, items: [map], marketplaceItems: [str], authorizationPolicyData: [map]}

@endpoint GET /api/oms/pvt/orders/order-group/{orderGroup}
@required {orderGroup: str}
@returns(200)

@endpoint GET /api/oms/pvt/orders
@optional {orderBy: str, page: int, per_page: int, f_hasInputInvoice: bool, q: str, f_shippingEstimate: str, f_invoicedDate: str, f_creationDate: str, f_authorizedDate: str, f_UtmSource: str, f_sellerNames: str, f_callCenterOperatorName: str, f_salesChannel: str, salesChannelId: str, f_affiliateId: str, f_status: str, incompleteOrders: bool, f_paymentNames: str, f_RnB: str, searchField: str, f_isInstore: bool}
@returns(200)

@endpoint POST /api/oms/pvt/orders/{orderId}/start-handling
@required {orderId: str}
@returns(204)
@errors {401, 403, 404, 409, 429}

@endpoint POST /api/oms/pvt/orders/{orderId}/cancel
@required {orderId: str}
@optional {reason: str}
@returns(200) {date: str, orderId: str, receipt: str}
@errors {403, 404, 429}

@endpoint POST /api/oms/pvt/orders/{orderId}/changes
@required {orderId: str, requestId: str, reason: str, discountValue: int, incrementValue: int}
@optional {itemsRemoved: [map{id!: str, price!: int, quantity!: int}], itemsAdded: [map{id!: str, price!: int, quantity!: int}]}
@returns(200) {date: str, orderId: str, receipt: str}

@endpoint POST /api/oms/pvt/orders/{orderId}/interactions
@required {orderId: str, source: str, message: str}
@returns(200)

@endpoint POST /api/oms/pvt/orders/{orderId}/invoice
@required {orderId: str, type: str(Output/Input), issuanceDate: str, invoiceNumber: str, invoiceValue: str, items: [map{id!: str, price!: int, description: str, quantity!: int}]}
@optional {invoiceKey: str, invoiceUrl: str, embeddedInvoice: str, courier: str, trackingNumber: str, trackingUrl: str, dispatchedDate: str}
@returns(200) {date: str, orderId: str, receipt: str}

@endpoint PATCH /api/oms/pvt/orders/{orderId}/invoice/{invoiceNumber}
@required {orderId: str, invoiceNumber: str, trackingNumber: str, trackingUrl: str, dispatchedDate: str, courier: str}
@returns(200) {date: str, orderId: str, receipt: str}

@endpoint PUT /api/oms/pvt/orders/{orderId}/invoice/{invoiceNumber}/tracking
@required {orderId: str, invoiceNumber: str, isDelivered: bool, deliveredDate: str, events: [map{city!: str, state!: str, description!: str, date!: str}]}
@returns(200)

@endpoint GET /api/oms/pvt/orders/{orderId}/conversation-message
@required {orderId: str}
@returns(200)

@endpoint GET /api/oms/pvt/orders/{orderId}/payment-transaction
@required {orderId: str}
@returns(200) {status: str, isActive: bool, transactionId: str, merchantName: str, payments: [map]}

@endpoint POST /api/oms/pvt/orders/{orderId}/payments/{paymentId}/payment-notification
@required {orderId: str, paymentId: str}
@returns(200)
@errors {400, 403, 404, 429}

@endpoint GET /api/oms/pvt/feed/orders/status
@required {maxLot: str}
@returns(200)

@endpoint GET /api/orders/feed/config
@returns(200) {filter: map{type: str, status: [str], expression: str, disableSingleFire: bool}, queue: map{visibilityTimeoutInSeconds: int, MessageRetentionPeriodInSeconds: int}, quantity: int, approximateAgeOfOldestMessageInSeconds: num}

@endpoint POST /api/orders/feed/config
@required {filter: map{type!: str, status: [str], expression: str, disableSingleFire: bool}, queue: map{visibilityTimeoutInSeconds!: int, MessageRetentionPeriodInSeconds!: int}}
@returns(200)
@errors {403, 404, 429}

@endpoint DELETE /api/orders/feed/config
@returns(200)
@errors {400, 403, 404, 429}

@endpoint GET /api/orders/feed
@required {maxlot: str}
@returns(200)

@endpoint POST /api/orders/feed
@required {handles: [str]}
@returns(200)

@endpoint GET /api/orders/hook/config
@optional {clientEmail: str, page: str, per_page: str}
@returns(200)

@endpoint POST /api/orders/hook/config
@required {filter: map{type!: str, status: [str], expression: str, disableSingleFire: bool}, hook: map{url!: str, headers!: map}}
@returns(200) {Domain: str, OrderId: str, State: str, LastState: str, LastChange: str, CurrentChange: str, Origin: map{Account: str, Key: str}}

@endpoint DELETE /api/orders/hook/config
@returns(200)
@errors {403, 404, 429}

@endpoint GET /api/orders/pvt/document/{orderId}/change-summary
@required {orderId: str}
@returns(200) {original: [map], added: [map], removed: [map], replaced: [map], manualDiscountValueAggregated: int, manualIncrementValueAggregated: int, totalChangeValueAggregated: int, totals: any, lastChange: str}
@errors {401, 403, 404}

@endpoint GET /api/oms/user/orders
@optional {clientEmail: str, page: str, per_page: str, text: str, status: str, creation_date: str, purchase_agent_id: str, my_pending_approvals: bool}
@returns(200) {list: [map], facets: [str], paging: map{total: int, pages: int, currentPage: int, perPage: int}, stats: map{stats: map{totalValue: map{Count: int, Max: int, Mean: int, Min: int, Missing: int, StdDev: int, Sum: int, SumOfSquares: int, Facets: map}, totalItems: map{Count: int, Max: int, Mean: int, Min: int, Missing: int, StdDev: int, Sum: int, SumOfSquares: int, Facets: map}}}}

@endpoint GET /api/oms/user/orders/{orderId}
@required {orderId: str}
@optional {clientEmail: str, text: str, status: str, creation_date: str, purchase_agent_id: str, my_pending_approvals: bool}
@returns(200) {orderId: str, sequence: str, marketplaceOrderId: str, marketplaceServicesEndpoint: str, sellerOrderId: str, origin: str, affiliateId: str, salesChannel: str, merchantName: str, status: str, statusDescription: str, value: int, creationDate: str, lastChange: str, orderGroup: str, totals: [map], items: [map], marketplaceItems: [str], clientProfileData: map{id: str, email: str, firstName: str, lastName: str, documentType: str, document: str, phone: str, corporateName: str?, tradeName: str?, corporateDocument: str?, stateInscription: str?, corporatePhone: str?, isCorporate: bool, userProfileId: str, customerClass: str?}, giftRegistryData: str?, marketingData: map{id: str, utmSource: str, utmPartner: str, utmMedium: str, utmCampaign: str, coupon: str, utmiCampaign: str, utmipage: str, utmiPart: str, marketingTags: [str]}, ratesAndBenefitsData: map{id: str, rateAndBenefitsIdentifiers: [str]}, shippingData: map{id: str, address: map{addressType: str, receiverName: str, addressId: str, versionId: str?, entityId: str?, postalCode: str, city: str, state: str, country: str, street: str, number: str, neighborhood: str, complement: str, reference: str?, geoCoordinates: [num]}, logisticsInfo: [map], trackingHints: str?, selectedAddresses: [map]}, paymentData: map{giftCards: [str], transactions: [map]}, packageAttachment: map{packages: [str]}, sellers: [map], callCenterOperatorData: str?, followUpEmail: str, lastMessage: str?, hostname: str, invoiceData: map?, changesAttachment: map{id: str, changesData: [map]}, openTextField: str?, roundingError: int, orderFormId: str, commercialConditionData: str?, isCompleted: bool, customData: str?, storePreferencesData: map{countryCode: str, currencyCode: str, currencyFormatInfo: map{CurrencyDecimalDigits: int, CurrencyDecimalSeparator: str, CurrencyGroupSeparator: str, CurrencyGroupSize: int, StartsWithCurrencySymbol: bool}, currencyLocale: int, currencySymbol: str, timeZone: str}, allowCancellation: bool, allowEdition: bool, isCheckedIn: bool, marketplace: map{baseURL: str, isCertified: str?, name: str}, authorizedDate: str, invoicedDate: str?, cancelReason: str?, itemMetadata: map{Items: [map]}, subscriptionData: map?{SubscriptionGroupId: str, Subscriptions: [map]?}, taxData: map{areTaxesDesignatedByMarketplace: bool, taxInfoCollection: [map]}, checkedInPickupPointId: str, cancellationData: map{RequestedByUser: bool, RequestedBySystem: bool, RequestedBySellerNotification: bool, RequestedByPaymentNotification: bool, Reason: str, CancellationDate: str}, clientPreferencesData: map{locale: str, optinNewsLetter: bool}}

@endpoint POST /api/orders/expressions/jsonata
@required {Expression: str, Document: str}
@returns(200)

@endpoint GET /api/checkout/pvt/configuration/window-to-change-seller
@returns(200)

@endpoint POST /api/checkout/pvt/configuration/window-to-change-seller
@required {waitingTime: int}
@returns(201)

@endpoint PATCH /api/order-system/orders/{changeOrderId}/changes
@required {accountName: str, changeOrderId: str, reason: str}
@optional {replace: [map{from!: map, to!: map}]}
@returns(202) {requestId: str, workflowId: str, reason: str, manualDiscountValue: int, manualIncrementValue: int, totalChangeValue: int, totals: [str], add: [str]?, remove: [str]?, replace: [map]?, date: str, origin: map{account: str, orderId: str, component: str}, settings: map{customPaymentSystemsAllowed: [str]}}

@endpoint GET /api/order-system/orders/{changeOrderId}/changes
@required {an: str, changeOrderId: str}
@returns(200) {requests: [map], actions: [map]}

@endpoint GET /api/order-system/orders/{changeOrderId}/changes/{changeRequestId}
@required {an: str, changeOrderId: str, changeRequestId: str}
@returns(200) {requestId: str, workflowId: str, status: str, inProgress: bool, reason: str, manualDiscountValue: int, manualIncrementValue: int, totalChangeValue: int, totals: [map], add: [str]?, remove: [str]?, replace: [map], date: str, origin: map{account: str, orderId: str, component: str}, settings: map{customPaymentSystemsAllowed: [str]}}

@endpoint POST /api/order-system/orders/{changeOrderId}/changes/preview
@required {an: str, changeOrderId: str, reason: str, replace: [map{from!: map, to!: map}]}
@returns(200) {reason: str, manualDiscountValue: int, manualIncrementValue: int, totalChangeValue: int, totals: [map], add: [str]?, remove: [str]?, replace: [map], date: str, origin: map{account: str, orderId: str, component: str}, settings: map{customPaymentSystemsAllowed: [str]}}

@endpoint POST /api/order-system/orders/{changeOrderId}/changes/{changeRequestId}/retry
@required {an: str, changeOrderId: str, changeRequestId: str, reason: str}
@optional {replace: [map{from!: map, to!: map}]}
@returns(204)

@endpoint POST /api/order-system/orders/{changeOrderId}/changes/{changeRequestId}/cancel
@required {an: str, changeOrderId: str, changeRequestId: str, reason: str}
@returns(200)

@endpoint PUT /api/order-system/orders/changes/settings
@required {an: str}
@optional {paymentConfiguration: map{customPaymentSystemsAllowed: [str]}, rolloutConfiguration: map{enableApi: bool, enableAdminOrders: map, enableMyOrders: map}, pipelineConfiguration: map{enableTaxHubRecalculation: bool, compensateShippingChanges: bool}}
@returns(200) {paymentConfiguration: map{customPaymentSystemsAllowed: [str]}, rolloutConfiguration: map{usingDefaultBehavior: bool, enableApi: bool, enableAdminOrders: map{enabledWorkspaces: [str]}, enableMyOrders: map{enabledWorkspaces: [str]}}, pipelineConfiguration: map{enableTaxHubRecalculation: bool, compensateShippingChanges: bool}}

@endpoint GET /api/order-system/orders/changes/settings
@required {an: str}
@returns(200) {paymentConfiguration: map{customPaymentSystemsAllowed: [str]}, rolloutConfiguration: map{usingDefaultBehavior: bool, enableApi: bool, enableAdminOrders: map{enabledWorkspaces: [str]}, enableMyOrders: map{enabledWorkspaces: [str]}}, pipelineConfiguration: map{enableTaxHubRecalculation: bool, compensateShippingChanges: bool}}

@end