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.
`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.

🧩 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

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 Bodyapplication/json-patch+json

Exemplo

{
    "idBranch": 0,
    "idBranchToken": "string",
    "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"
}

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,
    "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",
    "typePayment": "string",
    "totalInstallments": 0,
    "payment": 1,
    "sessionId": "string"
}

🟠400Bad Request

/api/v2/sales

Criar uma nova venda#

Descrição#

Instruções complementares#

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

🧩 Estrutura do Objeto memberData#

🧩 Estrutura do Objeto cardData#

🔷 Enum de payment#