Pular para o conteúdo

Atualizar uma venda

PATCH
/sales/{id}
 
curl --request PATCH \
  --url https://dattacrm.com.br/api/v1/sales/0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "status": "paid", "value": 1, "currency": "example", "productId": "example", "productName": "example", "paymentType": "example", "adId": "example", "occurredAt": "2026-10-19T12:00:00.000Z", "buyer": { "name": "example", "email": "example", "phone": "example" }, "utm": { "source": "example", "medium": "example", "campaign": "example", "term": "example", "content": "example" }, "mirror": { "grossValue": 1, "buyerTaxes": 1, "installmentFee": 1, "processingFee": 1, "streamingFee": 1, "otherFees": 1, "producerNetValue": 1, "coproducerValue": 1, "affiliateValue": 1, "affiliateName": "example", "offerCode": "example", "offerName": "example", "couponCode": "example", "installments": 1, "payoutCurrency": "example", "approvedAt": "2026-10-19T12:00:00.000Z" }, "addTags": [ "example" ], "removeTags": [ "example" ] }'

Altera campos de uma venda da conta (de qualquer origem, inclusive de um gateway integrado) pelo identificador do CRM: status, valor, moeda, produto, forma de pagamento, anúncio (adId), data, comprador, UTMs e espelho do gateway. As tags mudam por addTags (acrescenta) e removeTags (tira), como no update_lead; tags não existe no PATCH e responde 400. Só os campos enviados mudam; o resto fica como está, e o payload original guardado na venda nunca é substituído. O PATCH é uma correção: os campos enviados valem sempre, sem a guarda de ordem dos eventos. Quando o status muda, a mudança é registrada como evento outro; reenviar o mesmo status, ou alterar só outros campos, não grava evento. Na mudança de status saem os eventos sale.<status> (webhooks e automações); alterar os outros campos não gera evento. Só a venda paga conta no limite do plano: passar uma venda para paga acima dele responde 409 plan_limit e nada é gravado. Responde 404 quando a venda não existe ou pertence a outra conta e 400 quando o corpo não tem nenhum campo.

Authorizations

Seção intitulada “Authorizations ”

Parameters

Seção intitulada “ Parameters ”

Path Parameters

Seção intitulada “Path Parameters ”
id
required

Identificador da venda no CRM.

string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
Example 
0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f

Identificador da venda no CRM.

Request Body required

Seção intitulada “Request Body required ”
Media type application/json

Campos da venda a alterar. O que não vem no corpo não muda (buyer, utm e mirror chave a chave; as tags mudam por addTags e removeTags). gateway e transactionId não entram: identificam a venda. Exige pelo menos um campo.

object
status

Situação da venda: paid (paga), pending (aguardando pagamento), refunded (reembolsada), chargeback, canceled (cancelada) ou abandoned (carrinho abandonado).

string
Allowed values: paid pending refunded chargeback canceled abandoned
value

Valor da venda, na moeda de currency (zero a 9999999999.99).

number
<= 9999999999.99
currency

Moeda da venda: código ISO de 3 letras (ex.: BRL, USD).

string
/^[A-Z]{3}$/
productId

Identificador do produto (até 200 caracteres).

string
>= 1 characters <= 200 characters
productName

Nome do produto (até 200 caracteres).

string
>= 1 characters <= 200 characters
paymentType

Forma de pagamento, ex.: pix, credit_card, boleto (até 60 caracteres).

string
>= 1 characters <= 60 characters
adId

Identificador do anúncio que gerou a venda (até 200 caracteres).

string
>= 1 characters <= 200 characters
occurredAt

Data da venda (do pedido), em ISO 8601 com fuso.

string format: date-time
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$/
Example 
2026-10-19T12:00:00.000Z
buyer

Comprador. Com e-mail ou telefone, a venda se liga ao lead (criado se não existir); a venda nova sem os dois fica sem lead, e a existente mantém o comprador gravado.

object
name

Nome do comprador (até 120 caracteres).

string
>= 1 characters <= 120 characters
email

E-mail do comprador; cria ou encontra o lead por ele. Formato inválido é gravado como chegou.

string
>= 1 characters <= 254 characters
phone

Telefone do comprador, em qualquer formato (até 64 caracteres); cria ou encontra o lead por ele. Fora de 8 a 15 dígitos é gravado como veio e não encontra o lead de ninguém.

string
<= 64 characters
utm

UTMs da venda. Na venda nova sem UTM, valem as do lead do comprador; na existente, só as enviadas mudam.

object
source

Utm_source.

string
<= 255 characters
medium

Utm_medium.

string
<= 255 characters
campaign

Utm_campaign.

string
<= 255 characters
term

Utm_term.

string
<= 255 characters
content

Utm_content.

string
<= 255 characters
mirror

Espelho do painel do gateway (opcional): taxas, líquido do produtor, comissões, oferta, cupom e parcelas. Só as chaves enviadas mudam; as outras ficam como estão.

object
grossValue

Valor bruto cobrado do comprador (zero a 9999999999.99).

number
<= 9999999999.99
buyerTaxes

Impostos pagos pelo comprador (zero a 9999999999.99).

number
<= 9999999999.99
installmentFee

Juros do parcelamento (zero a 9999999999.99).

number
<= 9999999999.99
processingFee

Taxa de processamento do gateway (zero a 9999999999.99).

number
<= 9999999999.99
streamingFee

Taxa de streaming ou entrega (zero a 9999999999.99).

number
<= 9999999999.99
otherFees

Outras taxas (zero a 9999999999.99).

number
<= 9999999999.99
producerNetValue

Valor líquido do produtor (zero a 9999999999.99).

number
<= 9999999999.99
coproducerValue

Comissão do coprodutor (zero a 9999999999.99).

number
<= 9999999999.99
affiliateValue

Comissão do afiliado (zero a 9999999999.99).

number
<= 9999999999.99
affiliateName

Nome do afiliado (até 200 caracteres).

string
>= 1 characters <= 200 characters
offerCode

Código da oferta no gateway (até 200 caracteres).

string
>= 1 characters <= 200 characters
offerName

Nome da oferta (até 200 caracteres).

string
>= 1 characters <= 200 characters
couponCode

Cupom de desconto usado (até 200 caracteres).

string
>= 1 characters <= 200 characters
installments

Número de parcelas (0 a 1000).

integer
<= 1000
payoutCurrency

Moeda do repasse ao produtor (código ISO de 3 letras).

string
/^[A-Z]{3}$/
approvedAt

Quando o pagamento foi aprovado, em ISO 8601.

string format: date-time
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$/
Example 
2026-10-19T12:00:00.000Z
addTags

Tags a acrescentar à venda, pelo nome (até 30). Tag nova entra no catálogo de tags de venda. Tag automática é ignorada: o CRM a põe e tira pela regra dela.

Array<string>
<= 30 items
removeTags

Tags a remover da venda, pelo nome (até 30), sem diferenciar maiúsculas. Tag que a venda não tem e tag automática são ignoradas.

Array<string>
<= 30 items

Responses

Seção intitulada “ Responses ”

200

Seção intitulada “200 ”

Sucesso.

Media type application/json
object
data
required

A venda depois da alteração.

object
sale
required

Venda (de um gateway ou registrada pela API) no formato público.

object
id
required

Identificador da venda no CRM.

string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
gateway
required

Origem da venda: api para as registradas pela API, ou o gateway (hotmart, kiwify…).

string
transactionId
required

Identificador da transação no gateway (ou no seu sistema).

string
status
required

Situação: paid, pending, refunded, chargeback, canceled ou abandoned. other aparece só em venda de gateway com status desconhecido.

string
Allowed values: paid pending refunded chargeback canceled abandoned other
value
required

Valor da venda, na moeda de currency.

number
currency
required

Moeda da venda (código ISO de 3 letras, ex.: BRL).

string
productId
required

Identificador do produto, ou null.

string | null
productName
required

Nome do produto, ou null.

string | null
paymentType
required

Forma de pagamento (pix, cartão, boleto…), ou null.

string | null
buyer
required

Comprador, como veio na venda.

object
name
required

Nome do comprador, ou null.

string | null
email
required

E-mail do comprador, ou null.

string | null
phone
required

Telefone do comprador, ou null.

string | null
tags
required

Tags da venda, pelo nome (catálogo de tags de venda, separado do das tags de lead). Veja list_sale_tags.

Array<string>
leadId
required
Any of:

Identificador único (UUID).

string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
occurredAt
required
Any of:

Data e hora em ISO 8601, com fuso.

string format: date-time
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$/
utm
required

UTMs da venda; sem UTM na venda, valem as do lead.

object
source
required

Utm_source.

string | null
medium
required

Utm_medium.

string | null
campaign
required

Utm_campaign.

string | null
term
required

Utm_term.

string | null
content
required

Utm_content.

string | null
mirror
required

Espelho do painel do gateway: taxas, líquido do produtor, comissões, oferta e parcelas.

object
grossValue
required

Valor bruto cobrado do comprador, ou null.

number | null
buyerTaxes
required

Impostos pagos pelo comprador, ou null.

number | null
installmentFee
required

Juros do parcelamento, ou null.

number | null
processingFee
required

Taxa de processamento do gateway, ou null.

number | null
streamingFee
required

Taxa de streaming ou entrega, ou null.

number | null
otherFees
required

Outras taxas, ou null.

number | null
producerNetValue
required

Valor líquido do produtor, ou null.

number | null
coproducerValue
required

Comissão do coprodutor, ou null.

number | null
affiliateValue
required

Comissão do afiliado, ou null.

number | null
affiliateName
required

Nome do afiliado, ou null.

string | null
offerCode
required

Código da oferta no gateway, ou null.

string | null
offerName
required

Nome da oferta, ou null.

string | null
couponCode
required

Cupom de desconto usado, ou null.

string | null
installments
required
Any of:
integer
>= -9007199254740991 <= 9007199254740991
payoutCurrency
required

Moeda do repasse ao produtor, ou null.

string | null
approvedAt
required
Any of:

Data e hora em ISO 8601, com fuso.

string format: date-time
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$/
createdAt
required

Quando a venda entrou no CRM.

string format: date-time
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$/
updatedAt
required

Quando a venda foi alterada pela última vez.

string format: date-time
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$/
Example 
{
  "data": {
    "sale": {
      "id": "0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f",
      "status": "paid",
      "leadId": "0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f",
      "occurredAt": "2026-10-19T12:00:00.000Z",
      "mirror": {
        "approvedAt": "2026-10-19T12:00:00.000Z"
      },
      "createdAt": "2026-10-19T12:00:00.000Z",
      "updatedAt": "2026-10-19T12:00:00.000Z"
    }
  }
}

Headers

Seção intitulada “Headers ”
X-Request-Id
string

Identificador da requisição, para suporte.

X-RateLimit-Limit
integer

Máximo de requisições por janela de 60 segundos para esta chave.

X-RateLimit-Remaining
integer

Requisições restantes na janela atual.

X-RateLimit-Reset
integer

Fim da janela atual, em milissegundos desde a época Unix (epoch ms).

400

Seção intitulada “400 ”

Dados inválidos na requisição (validation_error), lead novo sem lista (list_required), campo que mudou de lugar (field_moved) ou chave enviada na URL (api_key_in_url).

Media type application/json

Formato de erro da API.

object
error
required
object
code
required

Código estável do erro, ex.: validation_error.

string
message
required

Mensagem legível em português.

string
details

Detalhes extras, ex.: lista de campos inválidos.

requestId
required

Identificador da requisição, para suporte.

string
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

Seção intitulada “Headers ”
X-Request-Id
string

Identificador da requisição, para suporte.

401

Seção intitulada “401 ”

Chave ausente, inválida (invalid_api_key), vencida (api_key_expired) ou revogada (api_key_revoked).

Media type application/json

Formato de erro da API.

object
error
required
object
code
required

Código estável do erro, ex.: validation_error.

string
message
required

Mensagem legível em português.

string
details

Detalhes extras, ex.: lista de campos inválidos.

requestId
required

Identificador da requisição, para suporte.

string
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

Seção intitulada “Headers ”
X-Request-Id
string

Identificador da requisição, para suporte.

403

Seção intitulada “403 ”

A chave é somente leitura e a operação grava dados (insufficient_scope).

Media type application/json

Formato de erro da API.

object
error
required
object
code
required

Código estável do erro, ex.: validation_error.

string
message
required

Mensagem legível em português.

string
details

Detalhes extras, ex.: lista de campos inválidos.

requestId
required

Identificador da requisição, para suporte.

string
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

Seção intitulada “Headers ”
X-Request-Id
string

Identificador da requisição, para suporte.

404

Seção intitulada “404 ”

Recurso não encontrado (not_found).

Media type application/json

Formato de erro da API.

object
error
required
object
code
required

Código estável do erro, ex.: validation_error.

string
message
required

Mensagem legível em português.

string
details

Detalhes extras, ex.: lista de campos inválidos.

requestId
required

Identificador da requisição, para suporte.

string
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

Seção intitulada “Headers ”
X-Request-Id
string

Identificador da requisição, para suporte.

409

Seção intitulada “409 ”

Conflito com o estado atual (conflict), contato oculto, cujo negócio não muda (lead_hidden), ou limite do plano atingido (plan_limit).

Media type application/json

Formato de erro da API.

object
error
required
object
code
required

Código estável do erro, ex.: validation_error.

string
message
required

Mensagem legível em português.

string
details

Detalhes extras, ex.: lista de campos inválidos.

requestId
required

Identificador da requisição, para suporte.

string
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

Seção intitulada “Headers ”
X-Request-Id
string

Identificador da requisição, para suporte.

413

Seção intitulada “413 ”

O corpo da requisição passa de 256 KB (payload_too_large).

Media type application/json

Formato de erro da API.

object
error
required
object
code
required

Código estável do erro, ex.: validation_error.

string
message
required

Mensagem legível em português.

string
details

Detalhes extras, ex.: lista de campos inválidos.

requestId
required

Identificador da requisição, para suporte.

string
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

Seção intitulada “Headers ”
X-Request-Id
string

Identificador da requisição, para suporte.

429

Seção intitulada “429 ”

Limite de requisições atingido (rate_limited). Aguarde Retry-After segundos.

Media type application/json

Formato de erro da API.

object
error
required
object
code
required

Código estável do erro, ex.: validation_error.

string
message
required

Mensagem legível em português.

string
details

Detalhes extras, ex.: lista de campos inválidos.

requestId
required

Identificador da requisição, para suporte.

string
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

Seção intitulada “Headers ”
X-Request-Id
string

Identificador da requisição, para suporte.

X-RateLimit-Limit
integer

Máximo de requisições por janela de 60 segundos para esta chave.

X-RateLimit-Remaining
integer

Requisições restantes na janela atual.

X-RateLimit-Reset
integer

Fim da janela atual, em milissegundos desde a época Unix (epoch ms).

Retry-After
integer

Segundos até poder tentar de novo.

500

Seção intitulada “500 ”

Erro interno (internal_error). Informe o requestId ao suporte.

Media type application/json

Formato de erro da API.

object
error
required
object
code
required

Código estável do erro, ex.: validation_error.

string
message
required

Mensagem legível em português.

string
details

Detalhes extras, ex.: lista de campos inválidos.

requestId
required

Identificador da requisição, para suporte.

string
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

Seção intitulada “Headers ”
X-Request-Id
string

Identificador da requisição, para suporte.

503

Seção intitulada “503 ”

O CRM está em modo somente leitura durante uma migração (maintenance). Tente de novo depois de Retry-After segundos.

Media type application/json

Formato de erro da API.

object
error
required
object
code
required

Código estável do erro, ex.: validation_error.

string
message
required

Mensagem legível em português.

string
details

Detalhes extras, ex.: lista de campos inválidos.

requestId
required

Identificador da requisição, para suporte.

string
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

Seção intitulada “Headers ”
X-Request-Id
string

Identificador da requisição, para suporte.

Retry-After
integer

Segundos até poder tentar de novo.