Documentação da API

Como as vendas chegam ao Qorvie Ads. Tudo converge para o mesmo formato (v1) e a mesma validação.

Autenticação

Crie um token no painel, em Integrações. Ele aparece uma vez só e começa com qads_. Envie no cabeçalho Authorization: Bearer qads_... (o cabeçalho x-api-token também é aceito).

Para testar a conexão, GET /api/v1/eu devolve o workspace do token, ou 401. Limite de 600 requisições por minuto por token e corpo de até 64 KB.

Enviar uma venda

Um POST /api/v1/vendas a cada mudança de status do pedido.

venda.json (exemplo)

{
  "pedidoId": "ped_8f2k1",
  "plataforma": "minhaloja",
  "status": "pago",
  "metodo": "pix",
  "valorCentavos": 19700,
  "taxaCentavos": 1232,
  "comissaoCentavos": 18468,
  "criadoEm": "2026-10-19T13:05:09Z",
  "pagoEm": "2026-10-19T13:07:00Z",
  "ocorridoEm": "2026-10-19T13:07:00Z",
  "produto": { "id": "prod_1", "nome": "Nome do produto" },
  "cliente": { "nome": "Nome", "email": "cliente@exemplo.com", "ip": "203.0.113.7" },
  "origem": {
    "utm_source": "FB",
    "utm_campaign": "Nome da campanha|120210000000001",
    "utm_medium": "Nome do conjunto|120210000000002",
    "utm_content": "Nome do anúncio|120210000000003",
    "fbclid": "IwAR..."
  }
}

terminal

curl -X POST https://ads.qorvie.com/api/v1/vendas \
  -H "Authorization: Bearer qads_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d @venda.json

Campos

Campo	Obrigatório	Regra
`pedidoId`	sim	Até 120 caracteres. Com a plataforma, identifica o pedido.
`plataforma`	não	Letras minúsculas, números, _ ou -. Padrão: api.
`status`	sim	pix_gerado, pago, recusado, reembolsado ou chargeback. pix_gerado vale para qualquer pagamento pendente.
`metodo`	não	pix, cartao, boleto ou outro (padrão).
`valorCentavos`	sim	Inteiro: o que o comprador pagou.
`taxaCentavos`	não	Taxa da plataforma ou do gateway. Padrão 0.
`comissaoCentavos`	não	O que fica para você (faturamento líquido). Padrão: valor menos taxa.
`moeda`	não	BRL: o Qorvie Ads trabalha em real.
`criadoEm`	não	ISO 8601 com fuso. Data do pedido, a que o painel usa.
`pagoEm, reembolsadoEm`	não	ISO 8601 ou null.
`ocorridoEm`	não	Quando o status mudou. Mande sempre: é o que ordena os eventos.
`produto`	não	id e nome.
`itens`	não	Até 20: id, nome, valorCentavos e tipo (principal, bump, upsell ou outro). A oferta principal e os order bumps do pedido; aparecem na lista de vendas.
`cliente`	não	nome, email, telefone, ip, userAgent.
`origem`	não	utm_source, utm_medium, utm_campaign, utm_content, utm_term, src, sck, xcod, fbclid, gclid, ttclid, fbc, fbp. Outras chaves são descartadas.
`teste`	não	true grava a venda, mas o painel a esconde por padrão e ela não vai para a Meta.

Respostas e idempotência

201: primeira notícia do pedido. {"ok":true,"vendaId":"...","status":"pago","duplicado":false}
200: novo status aplicado; ou "duplicado":true quando o mesmo pedido e status já chegaram; ou "ignorado":"status_mais_antigo" quando o ocorridoEm é mais velho que o do status atual.
400: corpo inválido, com campos dizendo o que corrigir. Não tente de novo sem corrigir.
401: token inválido ou revogado. 429 e 5xx: tente de novo com espera crescente.

A chave de idempotência é plataforma + pedidoId + status. Em empate de horário, vence o status mais adiante. Para reverter um chargeback, mande pago de novo com ocorridoEm mais novo. A origem é de primeiro toque: eventos seguintes só preenchem UTMs vazias.

Conector da Qorvie

A Qorvie usa esta mesma API. Crie um token no Qorvie Ads e cole nas configurações de integrações da Qorvie: cada mudança de status do pedido chega com UTMs, IDs de clique, comissão e taxa. Pix pendente vira pix_gerado, expirado ou recusado vira recusado, estorno vira reembolsado e contestação vira chargeback.

Webhooks de outras plataformas

Para plataformas que não deixam configurar cabeçalho, crie uma URL em Integrações: https://ads.qorvie.com/api/v1/webhooks/<formato>/qwh_.... O token vai na URL. Formatos:

padrao: o mesmo JSON da API. Serve para qualquer plataforma que deixe montar o corpo do webhook, direto ou por n8n, Make ou um script seu.
utmify: o JSON da API de pedidos da Utmify. Quem já integra com a Utmify aponta o mesmo envio para cá.

Atribuição

O painel casa a venda com o anúncio por utm_content (anúncio), utm_medium (conjunto) e utm_campaign (campanha), no formato nome|id, o mesmo padrão da Utmify. O id vence o nome; o nome só casa quando aponta para um item só. O gerador de links do painel monta os parâmetros com as macros de cada rede.