Integração AdOptify
Envio automático de vendas PIX (geradas e pagas) para a AdOptify com UTMs, produtos e dados do pagador.
Integração AdOptify
A Zypfy é parceira nativa da AdOptify. Quando você gera uma cobrança PIX enviando os parâmetros de UTM, a Zypfy repassa automaticamente os eventos de venda para a AdOptify — tanto no momento em que o PIX é gerado (waiting_payment) quanto quando ele é pago (paid). Você não precisa chamar a AdOptify diretamente: basta ativar a integração no painel e continuar mandando os UTMs no depósito.
Fluxo da integração
┌──────────┐ 1. POST /api/payments/deposit (com UTMs) ┌──────────┐
│ Seu │ ──────────────────────────────────────────▶│ Zypfy │
│ backend │ │ │
└────┬─────┘◀── 2. { qrcode, transactionId } ───────────┴────┬─────┘
│ │ 3. waiting_payment
│ 4. Cliente paga o PIX ▼
│ ┌──────────┐
│ │ AdOptify │
▼ │ │
┌──────────────────────┐ 5. Webhook COMPLETED ──────┴────┬─────┘
│ Sistema PIX (BACEN) │ ─────────────────────────▶ Zypfy │ 6. paid
└──────────────────────┘ ▼
(conversão gravada)1. Ativar a integração
1.1. Gerar o token na AdOptify
- Acesse sua conta na AdOptify.
- Vá em Integrações → Webhooks → Segredos.
- Clique em Adicionar e selecione o gateway Zypfy — a AdOptify gera o token automaticamente (campo somente leitura).
- Copie o token.
1.2. Colar o token no painel Zypfy
- Acesse
https://app.zypfy.com/integracoes/adoptify. - Ative o toggle Ativar integração AdOptify.
- Cole o token no campo Token (x-api-key).
- Deixe ligados os eventos PIX gerado e PIX pago (padrão).
- Clique em Salvar.
A partir daí, todo PIX gerado na sua conta é encaminhado para a AdOptify.
2. Enviar os UTMs ao gerar o PIX
Use o mesmo endpoint de depósito de sempre — os campos de tracking são os mesmos já documentados em Depósitos PIX. A AdOptify recebe utm_*, src, sck e products quando presentes.
O mesmo vale para o México (SPEI): POST /api/payments/mx/deposit aceita os mesmos campos de tracking e dispara os mesmos eventos. Veja Depósitos MXN (México).
POST https://api.zypfy.com/api/payments/depositHeaders: Authorization: Bearer SEU_TOKEN, Content-Type: application/json.
{
"amount": 100.00,
"external_id": "order-2026-0042",
"clientCallbackUrl": "https://minhaloja.com/webhooks/deposit",
"payer": {
"name": "João Silva",
"email": "[email protected]",
"document": "12345678901",
"phone": "11987654321"
},
"utm_source": "FB",
"utm_medium": "CONJUNTO_2|498046723566488",
"utm_campaign": "CAMPANHA_2|413591587909524",
"utm_content": "ANUNCIO_2|504346051220592",
"utm_term": "Instagram_Feed",
"src": "criativo-A",
"sck": "subconta-loja-9",
"products": [
{
"id": "53d5ce96-a548-4c7b-a0bc-da8bfa0f9294",
"name": "Óleo de Motor",
"quantity": 1,
"priceInCents": 10000
}
]
}Campos de tracking aceitos
| Campo | Tipo | Máx | Descrição |
|---|---|---|---|
utm_source | string | 255 | Origem da campanha (ex.: FB, TT). |
utm_medium | string | 64 | Canal/mídia. |
utm_campaign | string | 255 | Identificador da campanha. |
utm_content | string | 255 | Identificador do anúncio/criativo. |
utm_term | string | 255 | Termo/palavra-chave. |
src | string | 255 | Identificador livre de origem. |
sck | string | 255 | Subconta/identificador livre. |
products | array | 20 itens | Itens do pedido: id, name, planId, planName, quantity, priceInCents. |
Quando algum desses campos está presente, a Zypfy o repassa para a AdOptify (e também para Utmify, se estiver ativa).
3. Quando o evento é disparado
| Evento na Zypfy | Status enviado à AdOptify | Quando |
|---|---|---|
| Depósito gerado (PIX criado) | waiting_payment | Logo após o POST /api/payments/deposit. |
| Depósito pago (webhook do PSP) | paid | No instante em que o PSP confirma o pagamento. |
| Depósito reembolsado | refunded | Quando há reembolso. |
Cada evento pode ser ligado/desligado individualmente em /integracoes/adoptify.
4. Controle por Link de Pagamento
No editor do Link de Pagamento, seção Tracking, há o toggle Disparar AdOptify. Quando desligado, vendas vindas daquele link específico não disparam o evento na AdOptify, mesmo com a integração global ativa. Útil para separar campanhas ou testar links sem poluir o funil.
5. Suprimir o disparo em uma requisição específica
Inclua skip_adoptify: true no body do depósito para suprimir o envio apenas naquela transação (útil em testes/QA):
{
"amount": 100.00,
"external_id": "order-teste-456",
"payer": { "name": "Teste", "email": "[email protected]", "document": "12345678901" },
"skip_adoptify": true
}6. Payload entregue à AdOptify
Para auditoria, este é o payload que a Zypfy envia em cada evento:
POST https://app.adoptify.com.br/api/webhooks/partners/veopag
Headers:
Content-Type: application/json
x-api-key: <token gerado na AdOptify e colado no painel Zypfy>
x-partner-key: <mesmo valor do x-api-key>
{
"orderId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"platform": "ZYPFY",
"paymentMethod": "pix",
"status": "waiting_payment",
"createdAt": "2026-05-26 14:35:13",
"approvedDate": null,
"refundedAt": null,
"customer": {
"name": "João Silva",
"email": "[email protected]",
"phone": "11987654321",
"document": "12345678901",
"country": "BR"
},
"products": [
{
"id": "53d5ce96-a548-4c7b-a0bc-da8bfa0f9294",
"name": "Óleo de Motor",
"planId": null,
"planName": null,
"quantity": 1,
"priceInCents": 10000
}
],
"trackingParameters": {
"src": "criativo-A",
"sck": "subconta-loja-9",
"utm_source": "FB",
"utm_campaign": "CAMPANHA_2|413591587909524",
"utm_medium": "CONJUNTO_2|498046723566488",
"utm_content": "ANUNCIO_2|504346051220592",
"utm_term": "Instagram_Feed"
},
"commission": {
"totalPriceInCents": 10000,
"gatewayFeeInCents": 400,
"userCommissionInCents": 9600,
"currency": "BRL"
},
"isTest": false
}Numa venda do México, o mesmo payload muda em três campos: commission.currency vem "MXN" (o valor vai em pesos, sem conversão), customer.country vem "MX" e o produto sintético se chama "Depósito SPEI". O paymentMethod continua "pix" — o enum do formato Hotmart/Kiwify não tem SPEI, e pix é o equivalente de transferência bancária instantânea.
7. Erros e retries
A Zypfy faz até 3 tentativas por evento (espaçadas em 1s e 3s). Falhas no envio não bloqueiam a geração do PIX.
| HTTP | Significado |
|---|---|
| 200 / 201 | Sucesso — venda registrada na AdOptify. |
| 401 | Token inválido — gere um novo na AdOptify e atualize o painel. |
| 400 | Payload inválido — abra suporte Zypfy. |
| 413 | Payload muito grande — reduza o products[]. |
| 429 | Rate limit — a Zypfy respeita o backoff. |
8. Checklist
- Token gerado na AdOptify (Integrações → Webhooks → Segredos → Zypfy).
- Token colado em
/integracoes/adoptifye integração ativada. - PIX de teste gerado com
utm_sourcee demais UTMs. - Venda apareceu corretamente na AdOptify com os UTMs.
- Se opera no México: cobrança SPEI de teste gerada e venda conferida em
MXN(não em R$).