Criar uma nova venda

Descrição

Este endpoint permite registrar a venda de serviços, contratos ou aulas experimentais para prospects e membros. Ao realizar a solicitação, o sistema processa a transação, associando o prospect a um cliente (caso ainda não seja membro) e registrando o pagamento, que pode ser feito à vista ou parcelado. O fluxo também contempla a aplicação de descontos, a seleção da filial responsável e o gerenciamento completo das informações de pagamento.

🛂 A permissão no EVO que libera o acesso a este endpoint é o Vendas - Edição.

OBS. Disponível para uso com chave de acesso de filial e também com chave de acesso de ADM Geral.

Instruções complementares

Como realizar uma venda online via API

🚧 Atenção!
O totalInstallments do objeto cardData é valido apenas para o pagamento do tipo 1 (Cartão de crédito).
Inclua no Header da requisição o campo culture com o valor pt-BR. Esse parâmetro informa à API que as respostas devem ser retornadas em português do Brasil, garantindo que textos como mensagens, descrições e status venham em pt-BR.

Exemplo

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,
    ...
}'

📨 Parâmetros do Corpo da Requisição (Body Params)

Parâmetro	Tipo	Obrigatório	Descrição
`idBranch`	int32	Não	Identificador da filial onde a venda foi realizada. Se o sistema for multifilial, preencha com o ID da unidade específica. Caso contrário, será o valor gerado pelo token.
`idBranchToken`	string	Não	Token da filial, utilizado para identificar a unidade quando o sistema é multifilial.
`idMembership`	int32	Não	Identificador do contrato de adesão adquirido (se aplicável).
`membershipValue`	double	Não	Valor final do contrato.
`additionalMemberships`	arrayobject	Não	Lista de contratos adicionais opcionais que serão vendidos. Ver mais abaixo.
`idService`	int32	Não	Identificador do serviço ou aula experimental adquirida.
`serviceValue`	double	Não	Valor final do serviço.
`idProduct`	int32	Não	ID do produto relacionado à venda.
`productValue`	double	Não	Valor do produto relacionado à venda.
`productAmount`	int32	Não	Quantidade do produto relacionado à venda.
`memberData`	object	Sim	Dados do membro (se o cliente já for um membro). Contém o campo `idMember`.
`cardData`	object	Não	Dados do cartão de crédito, se a transação for realizada via cartão.
`idProspect`	int32	Não	Identificador do prospecto que está adquirindo o serviço.
`idProspectToken`	string	Não	Token do prospecto, utilizado para validar a transação e garantir que o prospecto seja convertido em membro após a compra.
`idMemberToken`	string	Não	Token do membro (se for um cliente registrado).
`voucher`	string	Não	Código do voucher de desconto, caso o cliente utilize um para obter um desconto.
`idVoucherToken`	int32	Não	Token do voucher de desconto (se aplicável).
`idCardMember`	int32	Não	Identificador do cartão de membro (se aplicável).
`idMemberCardToken`	string	Não	Token do cartão de membro (se aplicável).
`membershipStart`	string	Não	Data de início do contrato / da associação.
`totalInstallments`	int32	Sim	Número de parcelas para pagamento parcelado. Para pagamento à vista, será 0 ou 1.
`payment`	int32	Sim	Tipo de pagamento: 5 para parcelamento (com valor zerado para aulas experimentais) e 6 para pagamento à vista.
`sessionId`	string	Não	Identificador da sessão, utilizado para rastrear a transação durante o processo de venda.
`paymentData`	object	Não	Dados de pagamento aceitos quando o tipo de pagamento for externo `payment` = `16` ou `17`.

🧩 Estrutura do Objeto `additionalMemberships`

Parâmetro	Tipo	Obrigatório	Descrição
`idMembership`	int32	Sim	ID do contrato adicional opcional que será vendido. O adicional deve estar previamente vinculado como `Optional` ao contrato principal.
`membershipValue`	number (double)	Não	Valor final do contrato adicional informado pela integração. Quando informado, sobrescreve o valor padrão definido pelo EVO e não é multiplicado novamente pela vigência. Quando não informado, o EVO utiliza o valor padrão de venda aplicável ao vínculo.

🚧 OBS.
O campo additionalMemberships permite informar um ou mais contratos adicionais opcionais na mesma operação.
Somente contratos adicionais previamente vinculados como Optional ao contrato principal podem ser informados.
Contratos adicionais do tipo Fixed não devem ser enviados pela integração, pois são incluídos automaticamente quando o contrato principal é vendido.
Quando membershipValue não for informado, o EVO utilizará o valor padrão de venda do vínculo, conforme configurado no contrato e retornado no campo defaultSaleValue do endpoint GET /api/v3/membership.
Quando membershipValue for informado, o valor será considerado final para o adicional e não será multiplicado novamente pela vigência.
Quando additionalMemberships não for informado ou for enviado vazio, somente o contrato principal e seus adicionais Fixed serão vendidos. Adicionais Optional nunca são incluídos automaticamente.

🧩 Estrutura do Objeto `memberData`

Parâmetro	Tipo	Obrigatório	Descrição
`idMember`	int32	Sim	Identificador único do membro.
`document`	string	Não	Documento de identificação do membro, como CPF ou CNPJ.
`zipCode`	string	Não	Código postal (CEP) do endereço do membro.
`address`	string	Não	Endereço do membro.
`number`	string	Não	Número do endereço do membro.
`complement`	string	Não	Complemento do endereço do membro, como apartamento ou bloco.
`neighborhood`	string	Não	Bairro do membro.
`city`	string	Não	Cidade do membro.
`idState`	int32	Não	Identificador do estado onde o membro reside.

🧩 Estrutura do Objeto `cardData`

Parâmetro	Tipo	Obrigatório	Descrição
`token`	string	Não	Identificador único para o cartão.
`temporaryToken`	string	Não	Token temporário associado ao cartão, se aplicável.
`branchToken`	string	Não	Token da filial para identificar uma unidade quando o sistema é multifilial.
`totalInstallments`	int32	Não	Número total de parcelas no pagamento, aplicável em transações parceladas.
`truncatedCardNumber`	string	Não	Número do cartão truncado, mostrando apenas os ultimos 4 números reais para segurança. (****1234)
`brand`	string	Não	Marca do cartão (exemplo: Visa, MasterCard, etc.).
`cardHolderName`	string	Não	Nome do titular do cartão.
`cardExpirationYear`	int32	Não	Ano de expiração do cartão.
`cardExpirationMonth`	int32	Não	Mês de expiração do cartão.

🔷 Enum de `payment`

Código	Tipo de Pagamento	Descrição
null	LinkCheckout	Caso o valor de `payment` seja nulo, é tratado como LinkCheckout.
`1`	Credit Card	Pagamento realizado com cartão de crédito. (É preciso gerar o token do cartão usando Evo Pay)
`2`	Boleto	Pagamento realizado via boleto bancário.
`3`	Sale Credits	Pagamento realizado com créditos de vendas.
`4`	Transfer	Pagamento realizado por transferência bancária.
`5`	ValorZerado	Utilizado para transações com valor zerado, como aulas experimentais.
`6`	LinkCheckout	Pagamento realizado via link de checkout (gerado externamente).
`7`	Pix	Pagamento realizado via Pix.
`13`	Transferência	Pagamento realizado via transferência bancaria.
`14`	Cash	Pagamento realizado em dinheiro.
`15`	GiftCard	Pagamento realizado via vale-presente.
`16`	ExternalCreditCard	Pagamento realizado via cartão de crédito externo.
`17`	ExternalDebitCard	Pagamento realizado via cartão de débito externo.

🧩 Estrutura do Objeto `paymentData`

Parâmetro	Tipo	Obrigatório	Descrição
`tid`	string	Não	Identificador da transação.
`nsu`	string	Não	NSU da transação.
`authorization`	string	Não	Código de autorização.
`brand`	string	Não	Marca do cartão (exemplo: Visa, MasterCard, etc.).
`acquirer`	string	Não	Adquirente responsável pela transação.

Cenário de venda somente de adicionais para um membro existente

Quando o membro já possuir um contrato principal elegível, é possível realizar a venda de um ou mais contratos adicionais opcionais sem vender um novo contrato principal.

Nesse cenário, o idMembership identifica o primeiro contrato adicional e o campo additionalMemberships pode ser utilizado para informar os demais adicionais da mesma operação.

{
  "idBranch": 1,
  "idMembership": 200, // Primeiro contrato adicional da venda
  "membershipValue": 45.00,
  "memberData": {
    "idMember": 123
  },
  "payment": 14,
  "additionalMemberships": [
    {
      "idMembership": 201, // Segundo contrato adicional da venda
      "membershipValue": 30.00
    }
  ]
}

🚧 OBS.
Essa operação está disponível somente para membros.
Cada adicional deve possuir um contrato principal elegível já pertencente ao membro.
Quando diferentes adicionais forem elegíveis para diferentes contratos principais do membro, cada adicional será vinculado ao respectivo contrato principal elegível.

Requisição

Authorization

Basic Auth

Envie suas requisições HTTP com um cabeçalho

Authorization

que contenha a palavra Basic seguida por um espaço e uma string codificada em base64 username:password

Exemplo:

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

Parâmetros de Consulta

Parâmetros Body

application/json-patch+json

Exemplo

{
    "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"
    }
}

Exemplos de Requisição

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Respostas

🟢200OK

application/json

Success

Body

Exemplo

{
    "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

Criar uma nova venda#

Descrição#

Instruções complementares#

📨 Parâmetros do Corpo da Requisição (Body Params)#

🧩 Estrutura do Objeto additionalMemberships#

🧩 Estrutura do Objeto memberData#

🧩 Estrutura do Objeto cardData#

🔷 Enum de payment#

🧩 Estrutura do Objeto paymentData#

Cenário de venda somente de adicionais para um membro existente#