Engage / API v1
Vendas

Criar venda

Registra uma nova venda associada a um cliente e a uma lista de itens.

POST/v1/sales

Cria uma venda vinculada a um cliente existente e calcula o total a partir dos itens enviados. O cliente e todos os produtos referenciados precisam pertencer à mesma conta da chave de API. O servidor calcula totalAmount e items[].totalPrice; você não envia esses valores.

Obrigatório

customerId, saleDate e items são obrigatórios. O array de items precisa ter pelo menos um item.

Exemplo mínimo

json
{
  "customerId": "c3a1b2d4-9f5e-4a8b-9c0d-1e2f3a4b5c6d",
  "saleDate": "2026-04-25T15:00:00.000Z",
  "items": [
    {
      "productId": "f7e8d9c0-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
      "quantity": 1,
      "unitPrice": 49.9
    }
  ]
}

Exemplo completo

json
{
  "customerId": "c3a1b2d4-9f5e-4a8b-9c0d-1e2f3a4b5c6d",
  "saleDate": "2026-04-25T15:00:00.000Z",
  "items": [
    {
      "productId": "f7e8d9c0-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
      "quantity": 2,
      "unitPrice": 49.9
    },
    {
      "productId": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "quantity": 1,
      "unitPrice": 199.0
    }
  ],
  "customFields": {
    "channel": "online",
    "campaign": "summer-sale"
  }
}

Parâmetros do body

  • customerIdstring (uuid)obrigatório
    ID do cliente da venda. Deve existir na sua conta. Caso contrário, retorna 404 Cliente não encontrado.
  • saleDatestring (ISO 8601)obrigatório
    Data e hora em que a venda aconteceu. Aceita o formato ISO 8601 (ex.: 2026-04-25T15:00:00.000Z).
  • itemsarrayobrigatório
    Lista de itens vendidos. Pelo menos um item é obrigatório.
  • items[].productIdstring (uuid)obrigatório
    ID do produto vendido. Deve pertencer à sua conta. Produtos desconhecidos retornam 400 Produto(s) inválido(s).
  • items[].quantitynumberobrigatório
    Quantidade vendida. Mínimo 1.
  • items[].unitPricenumberobrigatório
    Preço unitário praticado nesta venda. Mínimo 0. Pode ser diferente do preço cadastrado no produto.
  • customFieldsobjectopcional
    Mapa { <nome do campo>: valor } com os campos customizados da entidade Venda. Chaves desconhecidas retornam 400 Bad Request. Veja campos customizados.

Campos da resposta

  • idstring (uuid)opcional
    Identificador único gerado pelo Engage.
  • customerIdstringopcional
    ID do cliente enviado.
  • totalAmountnumberopcional
    Soma calculada de quantity × unitPrice de todos os itens.
  • saleDatestring (ISO 8601)opcional
    Data e hora enviada.
  • itemsarrayopcional
    Itens enviados, com productName resolvido e totalPrice calculado.
  • createdAtstring (ISO 8601)opcional
    Data e hora em que a venda foi registrada.

Possíveis erros

  • 400
    Produto(s) inválido(s): <ids>Algum productId enviado em items não pertence à sua conta.
  • 400
    Unknown custom fields: <nomes>Alguma chave do customFields não corresponde a um campo cadastrado para a entidade Venda.
  • 400
    ValidaçãoBody inválido: customerId/saleDate ausentes, items vazio, quantity < 1, unitPrice < 0, formato de data incorreto, etc.
  • 401
    Invalid API keyHeader x-api-key ausente, inválido ou revogado.
  • 404
    Cliente não encontradoO customerId enviado não pertence à sua conta.