Estrutura da venda

Uma Venda (Sale) representa uma venda, contendo informações sobre o cliente, itens adquiridos, pagamento, entrega e histórico de estados. Cada venda pode gerar múltiplas Cobrânças (Payables) quando parcelada.

json

{
  "_id": "698b8a805eaf8de7c5af1cb9",
  "code": "LP-NNK26-MG463",
  "saleGroupCode": "LP-NNK26",
  "saleGroupId": "000000000000000000000001",
  "community": "test",
  "kind": "order",
  "currency": "BRL",
  "token": "dc1bb36a-62f1-4c94-bc7c-b05152ab3418",
  "checkoutId": "698b8a805eaf8de7c5af1cbb",
  "marketplaceId": null,
  "customerId": "698b8a805eaf8de7c5af1cbc",
  "embedded": null,
  "trackingUrl": "https://example.com/track/dc1bb36a",
  "requiresApproval": false,
  "approvedAt": "2026-02-12T20:45:01.549Z",
  "createdAt": "2026-02-10T19:44:01.198Z",
  "updatedAt": "2026-02-12T20:45:01.697Z",
  "confirmed": true,
  "confirmedAt": "2026-02-12T20:45:01.600Z",
  "completed": false,
  "completedAt": null,
  "failed": false,
  "failedAt": null,
  "failureReason": null,
  "canceled": false,
  "canceledAt": null,
  "refunded": false,
  "refundedAt": null,
  "canEditPaymentMethod": false,
  "sentEmailWithAllBankSlips": false,
  "hasPayableWithManualUpdate": false,
  "context": {
    "name": null,
    "alias": null,
    "entity": "698b8a805eaf8de7c5af1cb9",
    "kind": "order",
    "hash": "abc123def456"
  },
  "customer": {
    "name": "John Doe Silva",
    "email": "john@example.com",
    "phone": "(11) 91123-1233",
    "birth": "1990-05-15T00:00:00.000Z",
    "document": {
      "kind": "cpf",
      "value": "000.000.000-00"
    },
    "address": {
      "address": "Rua Exemplo",
      "number": "875",
      "address2": "Apto 101",
      "district": "Vila Nova",
      "city": "São Paulo",
      "state": "SP",
      "country": "BR",
      "code": "09510112",
      "createdAt": "2026-02-10T19:44:02.346Z",
      "updatedAt": "2026-02-10T19:44:02.346Z"
    },
    "stateLicense": null,
    "token": "3eef5671-a707-45ef-8c8a-d825e3ddd3d0"
  },
  "user": {
    "_id": "123456",
    "name": "John Doe",
    "alias": "johndoe",
    "accountId": "acc_123",
    "email": "john@example.com"
  },
  "coupon": null,
  "items": [],
  "discounts": [],
  "taxes": [],
  "payment": {
    "status": "pending",
    "statusTransitions": {
      "open": "2026-02-12T20:45:01.609Z"
    },
    "statusChangedAt": "2026-02-12T20:45:01.609Z",
    "tags": ["open"],
    "method": {
      "method": "credit_card",
      "key": "zoop:credit_card",
      "gateway": "zoop",
      "strategy": "installment",
      "installments": 5,
      "custom": false,
      "startAnchorAt": null,
      "sourceId": "698b8a805eaf8de7c5af1cce",
      "discounts": [],
      "taxes": [],
      "card": {
        "token": "CARD_TOKEN",
        "first_digits": "1234",
        "last_digits": "1111",
        "brand": "mastercard",
        "brandPretty": "Mastercard"
      },
      "multi_cards": [],
      "bank_slip": {
        "dueDays": 7,
        "lateFee": 0,
        "lateInterestRate": 0,
        "generateAllAtOnce": false
      },
      "pix": {
        "expiresInMinutes": 15
      }
    },
    "qrCode": null
  },
  "owned": {
    "items": { "amount": 20000, "currency": "BRL" },
    "discounts": { "amount": 0, "currency": "BRL" },
    "shipping": { "amount": 0, "currency": "BRL" },
    "taxes": { "amount": 0, "currency": "BRL" },
    "total": { "amount": 20000, "currency": "BRL" }
  },
  "recipients": [],
  "shipping": {
    "required": true,
    "method": null,
    "address": {
      "address": "Rua Exemplo",
      "number": "875",
      "address2": "Apto 101",
      "district": "Vila Nova",
      "city": "São Paulo",
      "state": "SP",
      "country": "BR",
      "createdAt": "2026-02-10T19:44:01.575Z",
      "updatedAt": "2026-02-10T19:44:01.575Z"
    }
  },
  "integration": {
    "status": "not_integrated",
    "statusChangedAt": "2026-02-10T19:44:01.235Z",
    "reason": null,
    "explanation": null,
    "metadata": {},
    "payload": {},
    "assignee": "DEFAULT_ASSIGNEE",
    "externalIdentifiers": []
  },
  "feedback": {
    "rate": null,
    "comment": null,
    "createdAt": null,
    "updatedAt": null
  },
  "device": {
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
    "colorDepth": 24,
    "ip": "192.168.1.1",
    "javaEnabled": false,
    "language": "pt-BR",
    "screenHeight": 1080,
    "screenWidth": 1920,
    "timeZoneOffSet": -180,
    "fingerprint": "abc123def456",
    "geoip": {
      "ip": "192.168.1.1",
      "country": "BR",
      "region": "SP",
      "city": "São Paulo",
      "ll": "-23.5505,-46.6333"
    }
  },
  "stepVerification": {
    "code": "123456",
    "validAt": "2026-02-13T19:44:01.198Z"
  },
  "externalFormAnswers": []
}

Campos principais

Campo	Tipo	Descrição
`_id`	`string`	ID único da venda no formato ObjectId
`code`	`string`	Código legível único da venda. Ex: `LP-NNK26-MG463`
`saleGroupCode`	`string \| null`	Código do grupo de vendas. Ex: `LP-NNK26`. Caso não agrupada, `null`
`saleGroupId`	`string \| null`	ID do grupo de vendas ao qual esta venda pertence. Caso não agrupada, `null`
`community`	`string`	Comunidade (tenant) onde a venda foi realizada
`kind`	`string`	Tipo da venda. Valores possíveis: `order`, `recurrence`, `subscription`, `commission`, `gift`, `voucher`
`currency`	`string`	Moeda da transação no formato ISO 4217. Ex: `BRL`, `USD`
`token`	`string`	Token único de acesso público para a venda (UUID v4)
`checkoutId`	`string \| null`	ID do checkout associado. Caso não vinculado, `null`
`customerId`	`string \| null`	ID do cliente. Caso não vinculado, `null`
`marketplaceId`	`string \| null`	ID do marketplace de origem. Caso não aplicável, `null`
`embedded`	`object \| null`	Dados do checkout embutido (origem do checkout). Caso não aplicável, `null`
`trackingUrl`	`string \| null`	URL pública para rastreamento e acompanhamento da venda. Caso não gerada, `null`
`requiresApproval`	`boolean`	Indica se a venda requer aprovação manual antes de prosseguir
`approvedAt`	`string (ISO 8601) \| null`	Data e hora da aprovação. Caso não aprovada, `null`
`createdAt`	`string (ISO 8601)`	Data e hora de criação da venda
`updatedAt`	`string (ISO 8601)`	Data e hora da última atualização
`confirmed`	`boolean`	Indica se o pagamento foi confirmado pelo gateway
`confirmedAt`	`string (ISO 8601) \| null`	Data e hora da confirmação. Caso não confirmada, `null`
`completed`	`boolean`	Indica se a venda foi finalizada com sucesso
`completedAt`	`string (ISO 8601) \| null`	Data e hora da conclusão. Caso não concluída, `null`
`failed`	`boolean`	Indica se o pagamento falhou
`failedAt`	`string (ISO 8601) \| null`	Data e hora da falha. Caso não falhou, `null`
`failureReason`	`string \| null`	Descrição do motivo da falha (ex: "Cartão recusado"). Caso não falhou, `null`
`canceled`	`boolean`	Indica se a venda foi cancelada
`canceledAt`	`string (ISO 8601) \| null`	Data e hora do cancelamento. Caso não cancelada, `null`
`refunded`	`boolean`	Indica se a venda teve reembolso
`refundedAt`	`string (ISO 8601) \| null`	Data e hora do reembolso. Caso não reembolsada, `null`
`canEditPaymentMethod`	`boolean`	Indica se o método de pagamento pode ser alterado
`sentEmailWithAllBankSlips`	`boolean`	Indica se email com todos os boletos foi enviado
`hasPayableWithManualUpdate`	`boolean`	Indica se há parcelas com atualização manual (bloqueia cobranças automáticas)
`coupon`	`object \| null`	Cupom de desconto aplicado. Caso não houver, `null`
`externalFormAnswers`	`array`	Respostas de formulários externos vinculados à venda
`discounts`	`array`	Lista de descontos aplicados à venda
`taxes`	`array`	Lista de impostos aplicados à venda

`context`

Informações sobre o contexto da loja onde a venda foi realizada.

json

{
  "name": null,
  "alias": null,
  "entity": "698b8a805eaf8de7c5af1cb9",
  "kind": "order",
  "hash": "abc123def456"
}

Campo	Tipo	Descrição
`name`	`string \| null`	Nome da loja. Caso não configurado, `null`
`alias`	`string \| null`	Alias da loja. Caso não configurado, `null`
`entity`	`string`	Identificador da entidade (channel) da loja
`kind`	`string`	Tipo do contexto da venda
`hash`	`string`	Hash computado do contexto da venda

`customer`

Dados do cliente que realizou a compra.

json

{
  "name": "John Doe Silva",
  "email": "john@example.com",
  "phone": "(11) 91123-1233",
  "birth": "1990-05-15T00:00:00.000Z",
  "document": {
    "kind": "cpf",
    "value": "000.000.000-00"
  },
  "address": {
    "address": "Rua Exemplo",
    "number": "875",
    "address2": "Apto 101",
    "district": "Vila Nova",
    "city": "São Paulo",
    "state": "SP",
    "country": "BR",
    "code": "09510112",
    "createdAt": "2026-02-10T19:44:02.346Z",
    "updatedAt": "2026-02-10T19:44:02.346Z"
  },
  "stateLicense": null,
  "token": "3eef5671-a707-45ef-8c8a-d825e3ddd3d0"
}

Campo	Tipo	Descrição
`name`	`string`	Nome completo do cliente (mínimo 2 palavras com 2+ caracteres cada)
`email`	`string`	Endereço de e-mail do cliente (validado)
`phone`	`string \| null`	Número de telefone do cliente. Caso não informado, `null`
`birth`	`string (ISO 8601) \| null`	Data de nascimento do cliente (apenas data, sem hora). Caso não informado, `null`
`token`	`string \| null`	Token de pagamento. Caso não informado, `null`
`document.kind`	`string`	Tipo do documento. Valores possíveis: `cpf`, `cnpj`
`document.value`	`string`	Número do documento
`stateLicense`	`string \| null`	Inscrição estadual (apenas para CNPJ). Caso não informado, `null`
`address.address`	`string \| null`	Logradouro. Caso não informado, `null`
`address.number`	`string \| null`	Número. Caso não informado, `null`
`address.address2`	`string \| null`	Complemento (apto, sala, etc). Caso não informado, `null`
`address.district`	`string \| null`	Bairro. Caso não informado, `null`
`address.city`	`string \| null`	Cidade. Caso não informado, `null`
`address.state`	`string \| null`	Estado (UF). Caso não informado, `null`
`address.country`	`string`	País no formato ISO 3166-1 alpha-2. Ex: `BR`
`address.code`	`string \| null`	CEP/Código postal. Caso não informado, `null`
`address.createdAt`	`string (ISO 8601)`	Data de criação do endereço
`address.updatedAt`	`string (ISO 8601)`	Data da última atualização do endereço

`user`

Dados do usuário autenticado que completou a compra (apenas quando aplicável).

json

{
  "_id": "123456",
  "name": "John Doe",
  "alias": "johndoe",
  "accountId": "acc_123",
  "email": "john@example.com"
}

Campo	Tipo	Descrição
`_id`	`string`	ID do usuário
`name`	`string`	Nome completo do usuário
`alias`	`string`	Alias/username do usuário
`accountId`	`string`	ID da conta associada
`email`	`string`	Email do usuário

Nota: Este objeto só está presente quando um usuário autenticado completou a compra. Para compras de visitantes, este campo é null.

`items`

Lista de produtos adquiridos na venda. Note que a estrutura do objeto items é diferente da estrutura do objeto Item do catálogo. Um exemplo: o objeto aqui contém itemKind, enquanto o objeto Item tem campos adicionais.

json

{
  "itemId": "5be99fd8dd405c6c7acfc0c4",
  "itemKind": "product",
  "name": "My at once product",
  "sku": "my-once-product-0001",
  "alias": "my-once-product",
  "caption": "Branco | 1kg",
  "quantity": 2,
  "maxQuantity": null,
  "variantId": "0001",
  "channelId": "698b8a805eaf8de7c5af1cb9",
  "inventoryId": "698b8a805eaf8de7c5af1d7e",
  "custom": false,
  "shippable": true,
  "sole": false,
  "requiresApproval": false,
  "isPriceVisible": true,
  "isRecurring": false,
  "startAnchorAt": null,
  "recurrentCycles": null,
  "linkingGroup": null,
  "schoolName": null,
  "tab": null,
  "plan": null,
  "forms": null,
  "observations": [],
  "attributes": [
    { "id": "000000000000000000000001", "value": "Branco" },
    { "id": "000000000000000000000002", "value": "1kg" }
  ],
  "package": {
    "width": 5,
    "depth": 5,
    "height": 5,
    "weight": 0.2
  },
  "price": {
    "amount": 10000,
    "currency": "BRL"
  },
  "subtotal": {
    "amount": 20000,
    "currency": "BRL"
  },
  "media": {
    "url": "https://cdn.exemplo.com/imagem.png",
    "path": "/community/uploads/.../imagem.png",
    "mime": "image/png",
    "width": 456,
    "height": 783,
    "size": 379264,
    "name": "imagem.png",
    "orientation": null
  }
}

Campo	Tipo	Descrição
`itemId`	`string`	Identificador do produto no catálogo
`itemKind`	`string`	Tipo do item (discriminator). Valores: `product`, `recurrence`, `gift`
`name`	`string`	Nome do item
`sku`	`string`	Código SKU do item
`alias`	`string`	Alias do item
`caption`	`string`	Descrição curta do item, frequentemente com os atributos selecionados. Ex: `Branco \| 1kg`
`quantity`	`integer`	Quantidade adquirida
`maxQuantity`	`integer \| null`	Quantidade máxima permitida por compra. Caso não limitado, `null`
`variantId`	`string`	Identificador da variante do produto selecionada
`channelId`	`string`	Identificador do canal de venda
`inventoryId`	`string \| null`	Identificador do registro de estoque associado. Caso não aplicável, `null`
`custom`	`boolean`	Indica se o item foi personalizado pelo cliente
`shippable`	`boolean`	Indica se o item requer envio físico
`sole`	`boolean`	Indica se o item é vendido de forma exclusiva/individual
`requiresApproval`	`boolean`	Indica se a entrega do item requer aprovação manual
`isPriceVisible`	`boolean`	Indica se o preço é exibido publicamente no catálogo
`isRecurring`	`boolean`	Indica se o item possui cobrança recorrente
`startAnchorAt`	`string (ISO 8601) \| null`	Data de início da recorrência, quando aplicável. Caso contrário, `null`
`recurrentCycles`	`integer \| null`	Número de ciclos de recorrência. Caso não aplicável, `null`
`linkingGroup`	`string \| null`	Grupo de vinculação do item (para itens vinculados). Caso não aplicável, `null`
`schoolName`	`string \| null`	Nome da instituição vinculada, quando aplicável. Caso contrário, `null`
`tab`	`object \| null`	Aba/categoria de categorização do item no catálogo. Caso não houver, `null`
`plan`	`object \| null`	Dados do plano de recorrência vinculado. Caso não houver, `null`
`forms`	`object \| null`	Respostas de formulários vinculados ao item. Caso não houver, `null`
`observations`	`array`	Lista de observações registradas para o item
`attributes`	`array`	Lista de atributos selecionados para o item (como cor e tamanho). Cada elemento contém `id` e `value`
`price.amount`	`integer`	Valor unitário em centavos. Ex: 10000 = R$ 100,00
`price.currency`	`string`	Moeda no formato ISO 4217
`subtotal.amount`	`integer`	Valor total do item em centavos (`price × quantity`)
`subtotal.currency`	`string`	Moeda no formato ISO 4217
`package.width`	`number`	Largura em centímetros
`package.depth`	`number`	Profundidade em centímetros
`package.height`	`number`	Altura em centímetros
`package.weight`	`number`	Peso em quilogramas
`media.url`	`string`	URL pública da imagem do item
`media.path`	`string`	Caminho interno da imagem
`media.mime`	`string`	Tipo MIME da imagem. Ex: `image/png`, `image/jpeg`
`media.width`	`integer`	Largura da imagem em pixels
`media.height`	`integer`	Altura da imagem em pixels
`media.size`	`integer`	Tamanho do arquivo em bytes
`media.name`	`string`	Nome do arquivo da imagem
`media.orientation`	`string \| null`	Orientação da imagem. Caso não informada, `null`

`payment`

Informações sobre o pagamento da venda.

json

{
  "status": "pending",
  "statusTransitions": {
    "open": "2026-02-12T20:45:01.609Z"
  },
  "statusChangedAt": "2026-02-12T20:45:01.609Z",
  "tags": ["open"],
  "method": {
    "method": "credit_card",
    "key": "zoop:credit_card",
    "gateway": "zoop",
    "strategy": "installment",
    "installments": 5,
    "custom": false,
    "startAnchorAt": null,
    "sourceId": "698b8a805eaf8de7c5af1cce",
    "discounts": [],
    "taxes": [],
    "card": {
      "token": "CARD_TOKEN",
      "first_digits": "1234",
      "last_digits": "1111",
      "brand": "mastercard",
      "brandPretty": "Mastercard"
    },
    "multi_cards": [],
    "bank_slip": {
      "dueDays": 7,
      "lateFee": 0,
      "lateInterestRate": 0,
      "generateAllAtOnce": false
    },
    "pix": {
      "expiresInMinutes": 15
    }
  },
  "qrCode": null
}

Campo	Tipo	Descrição
`status`	`string`	Status atual do pagamento. Valores possíveis: `open`, `pending`, `paid`, `released`, `late`, `expired`, `failed`, `canceled`, `refunded`, `chargeback`, `in_protest`, `waiting_approval`, `gifted`, `voucher`
`statusTransitions`	`object`	Histórico de timestamps de cada status atingido
`statusChangedAt`	`string (ISO 8601)`	Data e hora da última mudança de status
`tags`	`array<string>`	Tags descritivas do status atual
`method.method`	`string`	Forma de pagamento. Valores possíveis: `credit_card`, `bank_slip`, `pix`, `multi_card`, `gift`, `voucher`, `bolepix`
`method.key`	`string`	Chave composta que identifica o gateway e o método. Ex: `zoop:credit_card`
`method.gateway`	`string`	Gateway de pagamento. Valores: `barte`, `zoop`, `pagarme`, `maxipago`, `bempaggo`, `getnet`, `vindi`
`method.strategy`	`string`	Estratégia de cobrança. Valores possíveis: `installment`, `recurrence`
`method.installments`	`integer`	Número de parcelas (1-36)
`method.custom`	`boolean`	Indica se o método de pagamento foi customizado
`method.startAnchorAt`	`string (ISO 8601) \| null`	Data âncora de início das cobranças. Caso não aplicável, `null`
`method.sourceId`	`string \| null`	Identificador da fonte de pagamento. Caso não vinculado, `null`
`method.discounts`	`array`	Descontos aplicados ao método de pagamento
`method.taxes`	`array`	Taxas aplicadas ao método de pagamento
`method.card`	`object`	Objeto com dados do cartão (apenas para `credit_card`)
`method.card.token`	`string \| null`	Token do cartão no gateway. Caso não tokenizado, `null`
`method.card.first_digits`	`string`	Primeiros dígitos do cartão
`method.card.last_digits`	`string`	Últimos dígitos do cartão (máx 6 caracteres)
`method.card.brand`	`string`	Bandeira do cartão. Ex: `mastercard`, `visa`, `amex`
`method.card.brandPretty`	`string`	Bandeira formatada para exibição. Ex: `Mastercard`
`method.multi_cards`	`array<object>`	Lista de cartões quando o pagamento é dividido entre múltiplos cartões (mesma estrutura de `card`)
`method.bank_slip`	`object`	Objeto com dados do boleto (apenas para `bank_slip`)
`method.bank_slip.dueDays`	`integer`	Prazo de vencimento em dias corridos
`method.bank_slip.lateFee`	`number`	Percentual de multa por atraso
`method.bank_slip.lateInterestRate`	`number`	Percentual de juros por atraso ao mês
`method.bank_slip.generateAllAtOnce`	`boolean`	Indica se todos os boletos parcelados são gerados de uma vez
`method.pix`	`object`	Objeto com dados do PIX (apenas para `pix`)
`method.pix.expiresInMinutes`	`integer`	Minutos até expiração do PIX (padrão: 15)
`qrCode`	`string \| null`	String do QR Code (para PIX). Caso não gerado, `null`

`owned`

Resumo dos valores da venda sob responsabilidade do vendedor.

json

{
  "items": { "amount": 20000, "currency": "BRL" },
  "discounts": { "amount": 0, "currency": "BRL" },
  "shipping": { "amount": 0, "currency": "BRL" },
  "taxes": { "amount": 0, "currency": "BRL" },
  "total": { "amount": 20000, "currency": "BRL" }
}

Campo	Tipo	Descrição
`items`	`object`	Valor total dos itens antes de descontos
`discounts`	`object`	Total de descontos aplicados
`shipping`	`object`	Custo de envio
`taxes`	`object`	Total de impostos
`total`	`object`	Valor final da venda (`items - discounts + shipping + taxes`)

Todos os campos acima seguem o padrão: amount (valor em centavos) e currency (moeda no formato ISO 4217).

`recipients`

Lista de destinatários dos valores da venda. Cada entrada representa um recebedor, como o vendedor ou a plataforma.

json

{
  "sourceId": "698b8a805eaf8de7c5af1cce",
  "items": { "amount": 4000, "currency": "BRL" },
  "discounts": { "amount": 0, "currency": "BRL" },
  "taxes": { "amount": 0, "currency": "BRL" },
  "shipping": { "amount": 0, "currency": "BRL" },
  "total": { "amount": 4000, "currency": "BRL" },
  "options": {},
  "itemsInfo": []
}

Campo	Tipo	Descrição
`sourceId`	`string`	Identificador do recebedor
`items`	`object`	Valor dos itens atribuído a este recebedor
`discounts`	`object`	Descontos aplicados sobre o valor deste recebedor
`taxes`	`object`	Impostos atribuídos a este recebedor
`shipping`	`object`	Custo de frete atribuído a este recebedor
`total`	`object`	Valor total a ser recebido
`options`	`object`	Opções de split específicas do recebedor
`itemsInfo`	`array`	Informações detalhadas dos itens atribuídos a este recebedor

Todos os campos de valor seguem o padrão: amount (centavos) e currency (ISO 4217).

`shipping`

Informações sobre a entrega da venda.

json

{
  "required": true,
  "method": null,
  "address": {
    "address": "Rua Exemplo",
    "number": "875",
    "address2": "Apto 101",
    "district": "Vila Nova",
    "city": "São Paulo",
    "state": "SP",
    "country": "BR",
    "createdAt": "2026-02-10T19:44:01.575Z",
    "updatedAt": "2026-02-10T19:44:01.575Z"
  }
}

Campo	Tipo	Descrição
`required`	`boolean`	Indica se a entrega física é necessária para esta venda
`method`	`object \| null`	Método de entrega selecionado. Caso não definido, `null`
`address.address`	`string \| null`	Logradouro de entrega. Caso não informado, `null`
`address.number`	`string \| null`	Número. Caso não informado, `null`
`address.address2`	`string \| null`	Complemento. Caso não informado, `null`
`address.district`	`string \| null`	Bairro. Caso não informado, `null`
`address.city`	`string \| null`	Cidade. Caso não informado, `null`
`address.state`	`string \| null`	Estado (UF). Caso não informado, `null`
`address.country`	`string`	País no formato ISO 3166-1 alpha-2. Ex: `BR`
`address.createdAt`	`string (ISO 8601)`	Data de criação do endereço de entrega
`address.updatedAt`	`string (ISO 8601)`	Data da última atualização do endereço de entrega

`integration`

Status da integração da venda com sistemas externos.

json

{
  "status": "not_integrated",
  "statusChangedAt": "2026-02-10T19:44:01.235Z",
  "reason": null,
  "explanation": null,
  "metadata": {},
  "payload": {},
  "assignee": "DEFAULT_ASSIGNEE",
  "externalIdentifiers": []
}

Campo	Tipo	Descrição
`status`	`string`	Status da integração. Valores possíveis: `not_integrated`, `pending`, `integrated`, `approved`, `received`, `failed`, `ignored`, `invoiced`
`statusChangedAt`	`string (ISO 8601)`	Data e hora da última alteração de status
`reason`	`string \| null`	Motivo da integração/falha
`explanation`	`string \| null`	Explicação adicional sobre o status
`metadata`	`object`	Dados adicionais e metadados da integração
`payload`	`object`	Carga da integração com informações completas
`assignee`	`string \| null`	Responsável pela integração. Ex: `DEFAULT_ASSIGNEE`
`externalIdentifiers`	`array<string>`	Identificadores da venda em sistemas externos

`embedded`

Dados do checkout embutido (quando a venda é originária de um checkout embutido).

json

{
  "source": "comunicados",
  "entityId": "entity-123",
  "userId": "user-456"
}

Campo	Tipo	Descrição
`source`	`string`	Origem do checkout embutido. Valor: `comunicados`
`entityId`	`string`	ID da entidade de origem
`userId`	`string`	ID do usuário que criou o checkout

`externalFormAnswers`

Respostas de formulários externos vinculados à venda.

json

[
  {
    "externalId": "ext-form-001",
    "externalValue": "valor-resposta",
    "externalAlias": "alias-opcional",
    "formAnswerId": "form-ans-123"
  }
]

Campo	Tipo	Descrição
`externalId`	`string`	ID do formulário externo
`externalValue`	`string`	Valor da resposta no sistema externo
`externalAlias`	`string \| null`	Alias da resposta (opcional)
`formAnswerId`	`string`	ID da resposta de formulário vinculada

`feedback`

Avaliação do cliente sobre a venda.

json

{
  "rate": null,
  "comment": null,
  "createdAt": null,
  "updatedAt": null
}

Campo	Tipo	Descrição
`rate`	`integer (1-5) \| null`	Nota atribuída pelo cliente (1-5). Caso não avaliado, `null`
`comment`	`string \| null`	Comentário do cliente. Caso não avaliado, `null`
`createdAt`	`string (ISO 8601) \| null`	Data de criação da avaliação. Caso não avaliado, `null`
`updatedAt`	`string (ISO 8601) \| null`	Data da última atualização da avaliação. Caso não avaliado, `null`

`device`

Informações sobre o dispositivo usado para completar a compra (para detecção de fraude).

json

{
  "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
  "colorDepth": 24,
  "ip": "192.168.1.1",
  "javaEnabled": false,
  "language": "pt-BR",
  "screenHeight": 1080,
  "screenWidth": 1920,
  "timeZoneOffSet": -180,
  "fingerprint": "abc123def456",
  "geoip": {
    "ip": "192.168.1.1",
    "country": "BR",
    "region": "SP",
    "city": "São Paulo",
    "ll": "-23.5505,-46.6333"
  }
}

Campo	Tipo	Descrição
`userAgent`	`string`	User Agent do navegador
`colorDepth`	`integer`	Profundidade de cor do dispositivo
`ip`	`string`	Endereço IP do cliente
`javaEnabled`	`boolean`	Se Java está habilitado no navegador
`language`	`string`	Idioma do navegador (ex: `pt-BR`)
`screenHeight`	`integer`	Altura da tela em pixels
`screenWidth`	`integer`	Largura da tela em pixels
`timeZoneOffSet`	`integer`	Offset do timezone em minutos
`fingerprint`	`string \| null`	Hash de fingerprinting do dispositivo
`geoip.ip`	`string`	IP resolvido
`geoip.country`	`string`	País (ISO 3166-1 alpha-2)
`geoip.region`	`string`	Região/Estado
`geoip.city`	`string`	Cidade
`geoip.ll`	`string`	Coordenadas latitude,longitude

`stepVerification`

Dados de verificação de etapa (código OTP para confirmação adicional).

json

{
  "code": "123456",
  "validAt": "2026-02-13T19:44:01.198Z"
}

Campo	Tipo	Descrição
`code`	`string \| null`	Código de verificação da etapa (6 dígitos). Caso não gerado, `null`
`validAt`	`string (ISO 8601) \| null`	Data e hora de validade do código. Caso não gerado, `null`

Ciclo de Vida e Estados

Estados de Pagamento

O status do pagamento segue uma máquina de estados:

open → pending → (paid → released | failed | canceled | expired)
     ↘ refunded ↙
     ↘ chargeback ↙
     ↘ in_protest ↙

Estado	Descrição
`open`	Pagamento aberto, aguardando processamento
`pending`	Pagamento em processamento
`paid`	Pagamento confirmado pelo gateway
`released`	Pagamento liberado/liquidado
`failed`	Pagamento falhou
`expired`	Pagamento expirou
`canceled`	Pagamento cancelado
`refunded`	Pagamento reembolsado
`chargeback`	Disputa/chargeback iniciado
`in_protest`	Em protesto (boleto)
`late`	Pagamento em atraso
`up_to_date`	Pagamento em dia
`waiting_approval`	Aguardando aprovação manual
`gifted`	Presente/cupom (sem cobrança)
`voucher`	Voucher/vale (sem cobrança)
`partially_paid`	Pagamento foi parcialmente pago
`partially_refunded`	Pagamento foi parcialmente reembolsado

Bandeiras de Estado (State Flags)

Além do status de pagamento, a venda possui bandeiras de estado independentes:

Flag	Relacionado	Significado
`confirmed`	`confirmedAt`	Pagamento confirmado pelo gateway
`completed`	`completedAt`	Venda finalizada com sucesso
`failed`	`failedAt`, `failureReason`	Pagamento falhou
`canceled`	`canceledAt`	Venda cancelada
`refunded`	`refundedAt`	Reembolso processado
`requiresApproval`	`approvedAt`	Aguardando aprovação

Ciclo Típico de Uma Compra

Criação: Venda criada com payment.status = open
Processamento: Status muda para pending
Confirmação: Gateway confirma → confirmed = true, confirmedAt = now()
Sucesso: Status muda para paid → completed = true, completedAt = now()
Liquidação: Status muda para released

Ciclo de Falha

Criação: Venda criada com payment.status = open
Processamento: Status muda para pending
Falha: Gateway recusa → failed = true, failedAt = now(), failureReason = "Cartão recusado"

Validações

Nome do Cliente

✓ Mínimo 2 palavras
✓ Cada palavra com mínimo 2 caracteres
✓ Regex: (\S{2,}\s)(\S{2,}\s?)+
✗ "João" = falha (1 palavra)
✗ "Jo Silva" = falha (1º palavra < 2 chars)
✓ "John Doe Silva" = ok

Email

✓ Validação de email padrão
✓ Trimmed e lowercase
✗ Email inválido resulta em erro

StateLicense

✓ Apenas para documents.kind = 'cnpj'
✓ Validação específica de inscrição estadual
✗ Se document.kind = 'cpf' e stateLicense informado = erro

StepVerification.code

✓ Exatamente 6 dígitos/caracteres
✓ Obrigatório quando step verification é criado
✗ Menos de 6 ou mais de 6 caracteres = erro

Installments

✓ Inteiro
✓ Mínimo: 1
✓ Máximo: 36
✗ Decimais não são permitidos
✗ < 1 ou > 36 = erro

Relacionamentos

Venda (1) ← → Cobrança (N)

Uma Venda pode gerar múltiplas Cobrânças (uma por parcela)
Cada Cobrança referencia exatamente uma Venda
Relacionamento via saleId em Payable

Venda ← Checkout (1:1)

Um Checkout resulta em exatamente uma Venda
Relacionamento via checkoutId
Checkout é efêmero, Venda é permanente

Venda ← SaleGroup (N:1)

Múltiplas Vendas podem pertencer a um SaleGroup
Permite agrupar vendas relacionadas
Relacionamento via saleGroupId

Venda ← Customer (N:1)

Um Customer pode ter múltiplas Vendas
Relacionamento via customerId
Customer é o perfil persistente

Venda ← LineItem (1:N)

Uma Venda contém múltiplos LineItems (produtos comprados)
LineItem é snapshot da venda, não Item do catálogo
Relacionamento direto no array items

Comparação: Venda vs Cobrança vs Checkout

Aspecto	Venda	Cobrança	Checkout
Escopo	Venda completa	Parcela individual	Sessão de compra
Duração	Permanente	Até liquidação	Efêmera
Relação	1 por checkout	N por venda	1 por venda
Status	Múltiplos flags	Status único	Aberto/Fechado
Histórico	Completo	Por parcela	Não persistido
Cliente	Snapshot completo	Referência	Incompleto

Referência

Cobranças

Entregas

Formulários

Inventários

Itens

Kits

Vendas

Guia

Referência

Estrutura da venda ​

Campos principais ​

context ​

customer ​

user ​

items ​

payment ​

owned ​

recipients ​

shipping ​

integration ​

embedded ​

externalFormAnswers ​

feedback ​

device ​

stepVerification ​

Ciclo de Vida e Estados ​

Estados de Pagamento ​

Bandeiras de Estado (State Flags) ​

Ciclo Típico de Uma Compra ​

Ciclo de Falha ​

Validações ​

Nome do Cliente ​

Email ​

StateLicense ​

StepVerification.code ​

Installments ​

Relacionamentos ​

Venda (1) ← → Cobrança (N) ​

Venda ← Checkout (1:1) ​

Venda ← SaleGroup (N:1) ​

Venda ← Customer (N:1) ​

Venda ← LineItem (1:N) ​

Comparação: Venda vs Cobrança vs Checkout ​

Estrutura da venda

Campos principais

`context`

`customer`

`user`

`items`

`payment`

`owned`

`recipients`

`shipping`

`integration`

`embedded`

`externalFormAnswers`

`feedback`

`device`

`stepVerification`

Ciclo de Vida e Estados

Estados de Pagamento

Bandeiras de Estado (State Flags)

Ciclo Típico de Uma Compra

Ciclo de Falha

Validações

Nome do Cliente

Email

StateLicense

StepVerification.code

Installments

Relacionamentos

Venda (1) ← → Cobrança (N)

Venda ← Checkout (1:1)

Venda ← SaleGroup (N:1)

Venda ← Customer (N:1)

Venda ← LineItem (1:N)

Comparação: Venda vs Cobrança vs Checkout