Create a New Sale

Description

This endpoint allows you to register the sale of services, memberships, or experimental classes for prospects and members. When the request is made, the system processes the transaction, associating the prospect with a member (if the customer is not yet a member) and recording the payment, which can be made as a single payment or in installments. The flow also includes discounts, selection of the responsible branch, and complete payment information management.

🛂 The EVO permission that grants access to this endpoint is Vendas - Edição.

NOTE. Available for use with both Branch Access Keys and General Admin Access Keys.

Additional Instructions

How to perform an online sale through the API

🚧 Attention!
totalInstallments in the cardData object is valid only for payment type 1 (Credit Card).
Include the culture field in the request Header with the value pt-BR. This parameter tells the API that responses must be returned in Brazilian Portuguese, ensuring that texts such as messages, descriptions, and statuses are returned in pt-BR.

Example

curl --location --request POST 'https://evo-integracao-api.w12app.com.br/api/v2/sales' \
--header 'Content-Type: application/json-patch+json' \
--header 'Authorization: Basic Og==' \
--header 'culture: pt-BR' \ 👈👈👈
--data-raw '{
    "idBranch": 0,
    "idBranchToken": "string",
    "idMembership": 0,
    ...
}'

📨 Request Body Parameters

Parameter	Type	Required	Description
`idBranch`	int32	No	Identifier of the branch where the sale was made. If the system is multi-location, provide the ID of the specific branch. Otherwise, the value generated by the token will be used.
`idBranchToken`	string	No	Branch token, used to identify the location when the system is multi-location.
`idMembership`	int32	No	Identifier of the acquired membership, when applicable.
`membershipValue`	double	No	Final value of the membership.
`additionalMemberships`	arrayobject	No	List of optional add-on memberships to be sold. See below.
`idService`	int32	No	Identifier of the purchased service or experimental class.
`serviceValue`	double	No	Final value of the service.
`idProduct`	int32	No	ID of the product related to the sale.
`productValue`	double	No	Value of the product related to the sale.
`productAmount`	int32	No	Quantity of the product related to the sale.
`memberData`	object	Yes	Member data, if the customer is already a member. Contains the `idMember` field.
`cardData`	object	No	Credit card data, if the transaction is made by card.
`idProspect`	int32	No	Identifier of the prospect purchasing the service.
`idProspectToken`	string	No	Prospect token, used to validate the transaction and ensure that the prospect is converted into a member after the purchase.
`idMemberToken`	string	No	Member token, if the customer is already registered.
`voucher`	string	No	Discount voucher code, if the customer uses one to obtain a discount.
`idVoucherToken`	int32	No	Discount voucher token, when applicable.
`idCardMember`	int32	No	Member card identifier, when applicable.
`idMemberCardToken`	string	No	Member card token, when applicable.
`membershipStart`	string	No	Contract / membership start date.
`totalInstallments`	int32	Yes	Number of installments for installment payments. For a single payment, it will be 0 or 1.
`payment`	int32	Yes	Payment type: 5 for zero-value transactions, such as experimental classes, and 6 for single payments.
`sessionId`	string	No	Session identifier, used to track the transaction during the sale process.
`paymentData`	object	No	Payment data accepted when the payment type is external `payment = 16` or `17`.

🧩 `additionalMemberships` Object Structure

Parameter	Type	Required	Description
`idMembership`	int32	Yes	ID of the optional add-on membership to be sold. The add-on must already be linked as `Optional` to the main membership.
`membershipValue`	number (double)	No	Final value of the add-on membership provided by the integration. When provided, it overrides the default value defined by EVO and is not multiplied by the membership duration again. When omitted, EVO uses the default sale value applicable to the link.

🚧 NOTE
The additionalMemberships field allows one or more optional add-on memberships to be provided in the same operation.
Only add-on memberships previously linked as Optional to the main membership can be provided.
Add-on memberships of type Fixed must not be sent by the integration, as they are automatically included when the main membership is sold.
When membershipValue is not provided, EVO uses the default sale value of the link, according to the membership configuration and the defaultSaleValue field returned by the GET /api/v3/membership endpoint.
When membershipValue is provided, the value is considered final for the add-on and is not multiplied by the membership duration again.
When additionalMemberships is not provided or is sent empty, only the main membership and its Fixed add-ons will be sold. Optional add-ons are never included automatically.

🧩 `memberData` Object Structure

Parameter	Type	Required	Description
`idMember`	int32	Yes	Unique member identifier.
`document`	string	No	Member identification document, such as CPF or CNPJ.
`zipCode`	string	No	Postal code (ZIP code) of the member's address.
`address`	string	No	Member's address.
`number`	string	No	Member's address number.
`complement`	string	No	Address complement, such as apartment or block.
`neighborhood`	string	No	Member's neighborhood.
`city`	string	No	Member's city.
`idState`	int32	No	Identifier of the state where the member resides.

🧩 `cardData` Object Structure

Parameter	Type	Required	Description
`token`	string	No	Unique identifier for the card.
`temporaryToken`	string	No	Temporary token associated with the card, when applicable.
`branchToken`	string	No	Branch token used to identify a location when the system is multi-location.
`totalInstallments`	int32	No	Total number of installments for the payment, applicable to installment transactions.
`truncatedCardNumber`	string	No	Truncated card number, showing only the last 4 actual digits for security. (****1234)
`brand`	string	No	Card brand (e.g., Visa, MasterCard, etc.).
`cardHolderName`	string	No	Cardholder name.
`cardExpirationYear`	int32	No	Card expiration year.
`cardExpirationMonth`	int32	No	Card expiration month.

🔷 `payment` Enum

Code	Payment Type	Description
null	LinkCheckout	If the `payment` value is null, it is treated as LinkCheckout.
`1`	Credit Card	Payment made by credit card. (The card token must be generated using Evo Pay)
`2`	Boleto	Payment made by bank slip.
`3`	Sale Credits	Payment made using sales credits.
`4`	Transfer	Payment made by bank transfer.
`5`	ValorZerado	Used for zero-value transactions, such as experimental classes.
`6`	LinkCheckout	Payment made through a checkout link (externally generated).
`7`	Pix	Payment made through Pix.
`13`	Transferência	Payment made by bank transfer.
`14`	Cash	Payment made in cash.
`15`	GiftCard	Payment made by gift card.
`16`	ExternalCreditCard	Payment made by external credit card.
`17`	ExternalDebitCard	Payment made by external debit card.

🧩 `paymentData` Object Structure

Parameter	Type	Required	Description
`tid`	string	No	Transaction identifier.
`nsu`	string	No	Transaction NSU.
`authorization`	string	No	Authorization code.
`brand`	string	No	Card brand (e.g., Visa, MasterCard, etc.).
`acquirer`	string	No	Acquirer responsible for the transaction.

Scenario: Selling only add-ons to an existing member

When the member already has an eligible main membership, it is possible to sell one or more optional add-on memberships without selling a new main membership.

In this scenario, idMembership identifies the first add-on membership and the additionalMemberships field can be used to provide the other add-ons in the same operation.

{
  "idBranch": 1,
  "idMembership": 200,
  "membershipValue": 45.00,
  "memberData": {
    "idMember": 123
  },
  "payment": 14,
  "additionalMemberships": [
    {
      "idMembership": 201,
      "membershipValue": 30.00
    }
  ]
}

🚧 NOTE
This operation is available only for members.
Each add-on must have an eligible main membership that already belongs to the member.
When different add-ons are eligible for different main memberships owned by the member, each add-on will be linked to its corresponding eligible main membership.

Request

Authorization

Basic Auth

Send your HTTP requests with an

Authorization

header that contains the word Basic followed by a space and a base64-encoded string username:password

Example:

Authorization: Basic *****************

Query Params

Body Params

application/json-patch+json

Example

{
    "idBranch": 0,
    "idBranchToken": "string",
    "idMembership": 0,
    "membershipValue": 0,
    "additionalMemberships": [
        {
            "idMembership": 0,
            "membershipValue": 0
        }
    ],
    "idService": 0,
    "serviceValue": 0,
    "idProduct": 0,
    "productValue": 0,
    "productAmount": 0,
    "memberData": {
        "idMember": 0,
        "document": "string",
        "zipCode": "string",
        "address": "string",
        "number": "string",
        "complement": "string",
        "neighborhood": "string",
        "city": "string",
        "idState": 0
    },
    "cardData": {
        "token": "string",
        "temporaryToken": "string",
        "branchToken": "string",
        "totalInstallments": 0,
        "truncatedCardNumber": "string",
        "brand": "string",
        "cardHolderName": "string",
        "cardExpirationYear": 0,
        "cardExpirationMonth": 0
    },
    "idProspect": 0,
    "idProspectToken": "string",
    "idMemberToken": "string",
    "voucher": "string",
    "idCartToken": "string",
    "idCardMember": 0,
    "idMemberCardToken": "string",
    "membershipStart": "string",
    "totalInstallments": 0,
    "payment": 1,
    "sessionId": "string",
    "paymentData": {
        "tid": "string",
        "nsu": "string",
        "authorization": "string",
        "brand": "string",
        "acquirer": "string"
    }
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200OK

application/json

Success

Body

Example

{
    "idBranch": 0,
    "idBranchToken": "string",
    "idMembership": 0,
    "membershipValue": 0,
    "additionalMemberships": [
        {
            "idMembership": 0,
            "membershipValue": 0
        }
    ],
    "idService": 0,
    "serviceValue": 0,
    "idProduct": 0,
    "productValue": 0,
    "productAmount": 0,
    "memberData": {
        "idMember": 0,
        "document": "string",
        "zipCode": "string",
        "address": "string",
        "number": "string",
        "complement": "string",
        "neighborhood": "string",
        "city": "string",
        "idState": 0
    },
    "cardData": {
        "token": "string",
        "temporaryToken": "string",
        "branchToken": "string",
        "totalInstallments": 0,
        "truncatedCardNumber": "string",
        "brand": "string",
        "cardHolderName": "string",
        "cardExpirationYear": 0,
        "cardExpirationMonth": 0
    },
    "idProspect": 0,
    "idProspectToken": "string",
    "idMemberToken": "string",
    "voucher": "string",
    "idCartToken": "string",
    "idCardMember": 0,
    "idMemberCardToken": "string",
    "membershipStart": "string",
    "totalInstallments": 0,
    "payment": 1,
    "sessionId": "string",
    "paymentData": {
        "tid": "string",
        "nsu": "string",
        "authorization": "string",
        "brand": "string",
        "acquirer": "string"
    }
}

🟠400Bad Request

Create a new sale

Create a New Sale#

Description#

Additional Instructions#

📨 Request Body Parameters#

🧩 additionalMemberships Object Structure#

🧩 memberData Object Structure#

🧩 cardData Object Structure#

🔷 payment Enum#

🧩 paymentData Object Structure#

Scenario: Selling only add-ons to an existing member#