Integrações

API de Vendas da AdOptify

Documentação para enviar vendas à AdOptify. Escolha o guia conforme seu caso: envio genérico (você gera a chave na AdOptify) ou integração nativa (o gateway gera a chave e o usuário cola na AdOptify).

Use este guia quando a credencial é gerada na AdOptify: você cria o token em Integrações > Webhooks e configura a URL + token no seu sistema ou no gateway (webhook genérico).

1. Formato da Requisição

Gere a credencial, copie o endpoint exibido no painel e envie requisições HTTPS.

1.1 - Endpoint

Utilize sempre a URL de webhook mostrada em Integrações > Webhooks. Ela já contém o Project ID.

POST https://app.adoptify.com.br/api/track/{PROJECT_ID}

1.2 - Headers

Header	Descrição	Exemplo
Content-Type	Sempre application/json	application/json
x-api-key	Token salvo em Integrações > Webhooks (plataforma "Custom")	KVRxalfMiBfm8Rm1nP5YxfwYzArNsA0VLeWC
Authorization	Opcional. Também aceita Bearer <token> se preferir.	Bearer KVRxalfMiBfm8Rm1nP5YxfwYzArNsA0VLeWC

A chave pode ser gerada no painel. Para máxima segurança, revogue e regenere tokens que não forem mais usados.

1.3 - Payload

Use JSON. Estrutura inspirada em plataformas de checkout para facilitar a adaptação.

1.3.1 - Body

{
  "orderId": "string",
  "platform": "string",
  "paymentMethod": ["credit_card","boleto","pix","paypal","free_price"],
  "status": ["waiting_payment","paid","refused","refunded","chargedback"],
  "createdAt": "YYYY-MM-DD HH:MM:SS",
  "approvedDate": "YYYY-MM-DD HH:MM:SS | null",
  "refundedAt": "YYYY-MM-DD HH:MM:SS | null",
  "customer": Customer,
  "products": Product[],
  "trackingParameters": TrackingParameters,
  "commission": Commission,
  "isTest": false
}

products pode ter vários itens: produto principal e order bumps. O valor total da venda é a soma de priceInCents * quantity de todos os itens (quando não informar commission.totalPriceInCents ou totalPriceInCents na raiz). O nome exibido da venda é derivado da concatenação dos nomes de todos os produtos.

1.3.2 - Customer

{
  "name": "string",
  "email": "string",
  "phone": "string | null",
  "document": "CPF/CNPJ | null",
  "country": "ISO 3166-1 alpha-2",
  "ip": "string | null"
}

1.3.3 - Product

{
  "id": "string",
  "name": "string",
  "title": "string | null",
  "type": "main | orderbump",
  "planId": "string | null",
  "planName": "string | null",
  "quantity": number,
  "priceInCents": number
}

Use name ou title para o nome do produto. type opcional: main (produto principal) ou orderbump. Múltiplos itens em products permitem enviar produto principal e order bumps no mesmo pedido.

1.3.4 - TrackingParameters

{
  "src": "string | null",
  "sck": "string | null",
  "utm_source": "string | null",
  "utm_campaign": "string | null",
  "utm_medium": "string | null",
  "utm_content": "string | null",
  "utm_term": "string | null"
}

1.3.5 - Commission

{
  "totalPriceInCents": number,
  "gatewayFeeInCents": number,
  "userCommissionInCents": number,
  "currency": "BRL | USD | EUR | GBP | ARS | CAD"
}

2. Descrição dos Parâmetros

Campos obrigatórios e regras para validação.

2.1 - Autenticação

Acesse Integrações > Webhooks e adicione um segredo com a plataforma Custom (Genérico). Você pode:

Inserir manualmente um valor forte (mínimo recomendado: 32 caracteres).
Gerar automaticamente clicando no botão "Gerar" disponibilizado na própria interface.

É possível criar múltiplos tokens (ex.: um por ambiente). Guarde-os em local seguro — o dashboard apenas exibe o valor uma vez.

2.2 - Body

orderId: identificador único do pedido no seu sistema.
platform: nome da sua plataforma (use PascalCase). É usado para logs e para identificar tokens específicos.
paymentMethod e status: seguem os enums mostrados acima.
products: array de produtos. Pode incluir produto principal e order bumps (vários itens). O valor total da venda é a soma de priceInCents * quantity de todos os itens, exceto se informar commission.totalPriceInCents ou totalPriceInCents na raiz. O nome exibido da venda é a concatenação dos nomes (name ou title) de todos os produtos.
createdAt / approvedDate / refundedAt: formato UTC YYYY-MM-DD HH:MM:SS.
isTest: se true, a AdOptify valida o payload, mas não salva a venda (ideal para homologação).

2.3 - Segurança e rate limits

Requisições sem token ou com token inválido retornam 401/403 imediatamente.
Bloqueamos IPs com 5 falhas consecutivas em menos de 2 minutos.
Tokens podem ser revogados pelo próprio usuário a qualquer momento.
Envie sempre via HTTPS. Nunca exponha tokens no frontend.

3. Exemplos Práticos

Baseados nos cenários mais comuns.

3.1

Pix gerado e pago

POST https://app.adoptify.com.br/api/track/{PROJECT_ID}
Headers:
  x-api-key: KVRxalfMiBfm8Rm1nP5YxfwYzArNsA0VLeWC
Body:
{
  "orderId": "8e40b27e-0118-4699-8587-e892beedb403",
  "platform": "GlobalPay",
  "paymentMethod": "pix",
  "status": "waiting_payment",
  "createdAt": "2024-07-26 14:35:13",
  "approvedDate": null,
  "refundedAt": null,
  "customer": {
    "name": "Marcos Goncalves Rodrigues",
    "email": "marcosgonrod@hotmail.com",
    "phone": "19936387209",
    "document": "29672656599",
    "country": "BR",
    "ip": "61.145.134.105"
  },
  "products": [{
    "id": "53d5ce96-a548-4c7b-a0bc-da8bfa0f9294",
    "name": "Óleo de Motor",
    "planId": null,
    "planName": null,
    "quantity": 1,
    "priceInCents": 8000
  }],
  "trackingParameters": {
    "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
  },
  "isTest": false
}

Para informar o pagamento, envie novamente o mesmo pedido alterando status para paid e preenchendo approvedDate.

3.2

Cartão de crédito pago e reembolsado

POST https://app.adoptify.com.br/api/track/{PROJECT_ID}
Headers:
  x-api-key: JHTbglkQnUhz7Tk2oQ4ZyuVYxBsOpC1XNdYD
Body:
{
  "orderId": "b101ea20-72c7-473d-bcc4-416fe4d8f3be",
  "platform": "GlobalPay",
  "paymentMethod": "credit_card",
  "status": "paid",
  "createdAt": "2024-07-15 13:30:14",
  "approvedDate": "2024-07-15 13:30:14",
  "refundedAt": null,
  "customer": {
    "name": "Lucas Pereira Barros",
    "email": "lucaspbarros@gmail.com",
    "phone": "21996972147",
    "document": "24883871428",
    "country": "US",
    "ip": "242.53.157.167"
  },
  "products": [
    { "id": "ab341a39", "name": "T-shirt", "planId": "plan_tshirt", "planName": "Winter T-shirts", "quantity": 1, "priceInCents": 3500 },
    { "id": "8d7eb04c", "name": "Pants", "planId": "plan_pants", "planName": "Winter Pants", "quantity": 1, "priceInCents": 4000 }
  ],
  "trackingParameters": {
    "utm_source": "FB",
    "utm_campaign": "CAMPANHA_5|761832537749495",
    "utm_medium": "CONJUNTO_5|636393136432792",
    "utm_content": "ANUNCIO_5|525916699209785",
    "utm_term": "Facebook_Mobile_Feed"
  },
  "commission": {
    "totalPriceInCents": 7500,
    "gatewayFeeInCents": 375,
    "userCommissionInCents": 7125,
    "currency": "USD"
  }
}

Para registrar o reembolso, envie o mesmo JSON trocando status para refunded e preenchendo refundedAt.

4. Perguntas Frequentes

Como gerar a credencial?

Dashboard > Integrações > Webhooks > Segredos. Adicione uma linha com plataforma "Custom" (ou o nome desejado) e salve.

Como sei se o envio funcionou?

Requisições válidas retornam { success: true }. Você também verá a venda no menu Resumo em segundos.

Posso testar sem sujar meus relatórios?

Sim. Envie "isTest": true. Validamos o payload e devolvemos sucesso, mas não registramos a venda.

Há algum limite?

Limites seguem o plano contratado. Cada requisição passa por rate limiting e validação de token para evitar abuso.