Crear una Nueva Venta

Descripción

Este endpoint permite registrar la venta de servicios, contratos o clases experimentales para prospectos y miembros. Al realizar la solicitud, el sistema procesa la transacción, asociando el prospecto a un miembro (si aún no es miembro) y registrando el pago, que puede realizarse al contado o en cuotas. El flujo también contempla la aplicación de descuentos, la selección de la sucursal responsable y la gestión completa de la información de pago.

🛂 El permiso de EVO que habilita el acceso a este endpoint es Vendas - Edição.

OBS. Disponible para su uso con clave de acceso de sucursal y también con clave de acceso de ADM General.

Instrucciones complementarias

Cómo realizar una venta online mediante la API

🚧 ¡Atención!
El totalInstallments del objeto cardData es válido únicamente para el pago de tipo 1 (Tarjeta de crédito).
Incluya en el Header de la solicitud el campo culture con el valor pt-BR. Este parámetro informa a la API que las respuestas deben devolverse en portugués de Brasil, garantizando que textos como mensajes, descripciones y estados se proporcionen en pt-BR.

Ejemplo

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 del Cuerpo de la Solicitud (Body Params)

Parámetro	Tipo	Obligatorio	Descripción
`idBranch`	int32	No	Identificador de la sucursal donde se realizó la venta. Si el sistema es multisucursal, informe el ID de la unidad específica. De lo contrario, será el valor generado por el token.
`idBranchToken`	string	No	Token de la sucursal, utilizado para identificar la unidad cuando el sistema es multisucursal.
`idMembership`	int32	No	Identificador del contrato adquirido, cuando corresponda.
`membershipValue`	double	No	Valor final del contrato.
`additionalMemberships`	arrayobject	No	Lista de contratos adicionales opcionales que se venderán. Ver más abajo.
`idService`	int32	No	Identificador del servicio o clase experimental adquirida.
`serviceValue`	double	No	Valor final del servicio.
`idProduct`	int32	No	ID del producto relacionado con la venta.
`productValue`	double	No	Valor del producto relacionado con la venta.
`productAmount`	int32	No	Cantidad del producto relacionado con la venta.
`memberData`	object	Sí	Datos del miembro, si el cliente ya es miembro. Contiene el campo `idMember`.
`cardData`	object	No	Datos de la tarjeta de crédito, si la transacción se realiza con tarjeta.
`idProspect`	int32	No	Identificador del prospecto que está adquiriendo el servicio.
`idProspectToken`	string	No	Token del prospecto, utilizado para validar la transacción y garantizar que el prospecto sea convertido en miembro después de la compra.
`idMemberToken`	string	No	Token del miembro, si se trata de un cliente registrado.
`voucher`	string	No	Código del voucher de descuento, cuando el cliente lo utilice para obtener un descuento.
`idVoucherToken`	int32	No	Token del voucher de descuento, cuando corresponda.
`idCardMember`	int32	No	Identificador de la tarjeta del miembro, cuando corresponda.
`idMemberCardToken`	string	No	Token de la tarjeta del miembro, cuando corresponda.
`membershipStart`	string	No	Fecha de inicio del contrato / de la membresía.
`totalInstallments`	int32	Sí	Número de cuotas para el pago a plazos. Para pagos al contado, será 0 o 1.
`payment`	int32	Sí	Tipo de pago: 5 para pagos con valor cero, como clases experimentales, y 6 para pago al contado.
`sessionId`	string	No	Identificador de la sesión, utilizado para rastrear la transacción durante el proceso de venta.
`paymentData`	object	No	Datos de pago aceptados cuando el tipo de pago sea externo `payment = 16` o `17`.

🧩 Estructura del Objeto `additionalMemberships`

Parámetro	Tipo	Obligatorio	Descripción
`idMembership`	int32	Sí	ID del contrato adicional opcional que se venderá. El adicional debe estar previamente vinculado como `Optional` al contrato principal.
`membershipValue`	number (double)	No	Valor final del contrato adicional informado por la integración. Cuando se informa, sobrescribe el valor predeterminado definido por EVO y no se multiplica nuevamente por la vigencia. Cuando no se informa, EVO utiliza el valor de venta predeterminado aplicable al vínculo.

🚧 OBS.
El campo additionalMemberships permite informar uno o más contratos adicionales opcionales en la misma operación.
Solo pueden informarse contratos adicionales previamente vinculados como Optional al contrato principal.
Los contratos adicionales de tipo Fixed no deben ser enviados por la integración, ya que se incluyen automáticamente cuando se vende el contrato principal.
Cuando membershipValue no se informa, EVO utilizará el valor de venta predeterminado del vínculo, según la configuración del contrato y el campo defaultSaleValue del endpoint GET /api/v3/membership.
Cuando membershipValue se informa, el valor se considerará final para el adicional y no se multiplicará nuevamente por la vigencia.
Cuando additionalMemberships no se informa o se envía vacío, solo se venderán el contrato principal y sus adicionales Fixed. Los adicionales Optional nunca se incluyen automáticamente.

🧩 Estructura del Objeto `memberData`

Parámetro	Tipo	Obligatorio	Descripción
`idMember`	int32	Sí	Identificador único del miembro.
`document`	string	No	Documento de identificación del miembro, como CPF o CNPJ.
`zipCode`	string	No	Código postal (CEP) de la dirección del miembro.
`address`	string	No	Dirección del miembro.
`number`	string	No	Número de la dirección del miembro.
`complement`	string	No	Complemento de la dirección del miembro, como apartamento o bloque.
`neighborhood`	string	No	Barrio del miembro.
`city`	string	No	Ciudad del miembro.
`idState`	int32	No	Identificador del estado donde reside el miembro.

🧩 Estructura del Objeto `cardData`

Parámetro	Tipo	Obligatorio	Descripción
`token`	string	No	Identificador único de la tarjeta.
`temporaryToken`	string	No	Token temporal asociado a la tarjeta, cuando corresponda.
`branchToken`	string	No	Token de la sucursal para identificar una unidad cuando el sistema es multisucursal.
`totalInstallments`	int32	No	Número total de cuotas del pago, aplicable a transacciones a plazos.
`truncatedCardNumber`	string	No	Número de tarjeta truncado, mostrando únicamente los últimos 4 dígitos reales por seguridad. (****1234)
`brand`	string	No	Marca de la tarjeta (ejemplo: Visa, MasterCard, etc.).
`cardHolderName`	string	No	Nombre del titular de la tarjeta.
`cardExpirationYear`	int32	No	Año de vencimiento de la tarjeta.
`cardExpirationMonth`	int32	No	Mes de vencimiento de la tarjeta.

🔷 Enum de `payment`

Código	Tipo de Pago	Descripción
null	LinkCheckout	Cuando el valor de `payment` es nulo, se trata como LinkCheckout.
`1`	Credit Card	Pago realizado con tarjeta de crédito. (Es necesario generar el token de la tarjeta mediante Evo Pay)
`2`	Boleto	Pago realizado mediante boleto bancario.
`3`	Sale Credits	Pago realizado mediante créditos de ventas.
`4`	Transfer	Pago realizado mediante transferencia bancaria.
`5`	ValorZerado	Utilizado para transacciones con valor cero, como clases experimentales.
`6`	LinkCheckout	Pago realizado mediante enlace de checkout (generado externamente).
`7`	Pix	Pago realizado mediante Pix.
`13`	Transferência	Pago realizado mediante transferencia bancaria.
`14`	Cash	Pago realizado en efectivo.
`15`	GiftCard	Pago realizado mediante tarjeta de regalo.
`16`	ExternalCreditCard	Pago realizado mediante tarjeta de crédito externa.
`17`	ExternalDebitCard	Pago realizado mediante tarjeta de débito externa.

🧩 Estructura del Objeto `paymentData`

Parámetro	Tipo	Obligatorio	Descripción
`tid`	string	No	Identificador de la transacción.
`nsu`	string	No	NSU de la transacción.
`authorization`	string	No	Código de autorización.
`brand`	string	No	Marca de la tarjeta (ejemplo: Visa, MasterCard, etc.).
`acquirer`	string	No	Adquirente responsable de la transacción.

Escenario de venta únicamente de adicionales para un miembro existente

Cuando el miembro ya posee un contrato principal elegible, es posible realizar la venta de uno o más contratos adicionales opcionales sin vender un nuevo contrato principal.

En este escenario, idMembership identifica el primer contrato adicional y el campo additionalMemberships puede utilizarse para informar los demás adicionales de la misma operación.

{
  "idBranch": 1,
  "idMembership": 200, // Primer contrato adicional de la venta
  "membershipValue": 45.00,
  "memberData": {
    "idMember": 123
  },
  "payment": 14,
  "additionalMemberships": [
    {
      "idMembership": 201, // Segundo contrato adicional de la venta
      "membershipValue": 30.00
    }
  ]
}

🚧 OBS.
Esta operación está disponible únicamente para miembros.
Cada adicional debe tener un contrato principal elegible que ya pertenezca al miembro.
Cuando diferentes adicionales sean elegibles para diferentes contratos principales del miembro, cada adicional se vinculará al contrato principal elegible correspondiente.

Solicitud

Autorización

Envía tus solicitudes HTTP con un encabezado

Authorization

que contenga la palabra Basic seguida de un espacio y una cadena codificada en base64 username:password

Ejemplo:

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

Parámetros de consulta

Parámetros del Body

application/json-patch+json

Ejemplo

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

Ejemplos de solicitud

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Respuestas

🟢200OK

application/json

Success

Body

Ejemplo

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

Crear una Nueva Venta#

Descripción#

Instrucciones complementarias#

📨 Parámetros del Cuerpo de la Solicitud (Body Params)#

🧩 Estructura del Objeto additionalMemberships#

🧩 Estructura del Objeto memberData#

🧩 Estructura del Objeto cardData#

🔷 Enum de payment#

🧩 Estructura del Objeto paymentData#

Escenario de venta únicamente de adicionales para un miembro existente#