ZypfyDocs Acessar painel
Guia de integração

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

código
┌──────────┐  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

  1. Acesse sua conta na AdOptify.
  2. Vá em Integrações → Webhooks → Segredos.
  3. Clique em Adicionar e selecione o gateway Zypfy — a AdOptify gera o token automaticamente (campo somente leitura).
  4. Copie o token.

1.2. Colar o token no painel Zypfy

  1. Acesse https://app.zypfy.com/integracoes/adoptify.
  2. Ative o toggle Ativar integração AdOptify.
  3. Cole o token no campo Token (x-api-key).
  4. Deixe ligados os eventos PIX gerado e PIX pago (padrão).
  5. 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).

código
POST https://api.zypfy.com/api/payments/deposit

Headers: Authorization: Bearer SEU_TOKEN, Content-Type: application/json.

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

CampoTipoMáxDescrição
utm_sourcestring255Origem da campanha (ex.: FB, TT).
utm_mediumstring64Canal/mídia.
utm_campaignstring255Identificador da campanha.
utm_contentstring255Identificador do anúncio/criativo.
utm_termstring255Termo/palavra-chave.
srcstring255Identificador livre de origem.
sckstring255Subconta/identificador livre.
productsarray20 itensItens 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 ZypfyStatus enviado à AdOptifyQuando
Depósito gerado (PIX criado)waiting_paymentLogo após o POST /api/payments/deposit.
Depósito pago (webhook do PSP)paidNo instante em que o PSP confirma o pagamento.
Depósito reembolsadorefundedQuando há reembolso.

Cada evento pode ser ligado/desligado individualmente em /integracoes/adoptify.

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):

json
{
  "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:

código
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.

HTTPSignificado
200 / 201Sucesso — venda registrada na AdOptify.
401Token inválido — gere um novo na AdOptify e atualize o painel.
400Payload inválido — abra suporte Zypfy.
413Payload muito grande — reduza o products[].
429Rate limit — a Zypfy respeita o backoff.

8. Checklist