Docs AACT
|
Início

Guias

Visão geral
Começar
Integrações
  • Checkout
  • Cliente e notifier
  • Eventos
  • Autenticação
  • Idempotência
  • Reembolsos
API
Segurança
Operações

Integração de checkout

Adicionar ?ref=CODE a um link não cria atribuição por si. O sistema de origem deve preservar o código e enviar um evento assinado após confirmação de pagamento.

Regra crítica

Links de referral não são pixels de tracking

A AACT não observa visitas à loja. A aplicação deve ler ?ref=, mantê-lo no carrinho/checkout e enviá-lo como referral_code no evento de sale depois da venda estar paga.

Fluxo real

  1. Visitante abre shop.example com ?ref=CODE
  2. Sistema externo associa CODE ao carrinho/encomenda
  3. Pagamento externo conclui no PSP de origem
  4. Backend de origem valida a confirmação do fornecedor de pagamento
  5. Venda paga é persistida no sistema de origem
  6. Evento de integração é construído (envio síncrono hoje; outbox durável é planned)
  7. Evento é enviado à AACT com bearer + HMAC
  8. AACT responde 201 (novo) ou 200 (replay) após persistência/processamento
  9. Comissão é calculada quando atribuição e regras coincidem
  10. Refunds/chargebacks posteriores são eventos separados

Ingestão sale servidor-a-servidor· implementado

Outbox persist-before-ack + HTTP 202· planeado

Regras do integrador

  • Nunca coloque tokens bearer ou segredos HMAC no browser
  • Página de sucesso ou query GET não é prova de pagamento
  • O browser não decide montantes de comissão
  • Não envie PAN/CVV para a AACT
  • Não falhe uma venda já paga porque a AACT está temporariamente indisponível — faça retry
  • Retries devem reutilizar o mesmo external_event_id; novo timestamp e nonce em cada tentativa
  • HTTP 201/200 significa evento aceite/replay — não payout concluído

Setup no admin

  1. Criar business e website
  2. Criar regra de comissão para esse website
  3. Criar credencial de integração (exige step-up) e guardar token + hmac_secret (mostrados uma vez)
  4. Usar um source estável como node_checkout

Ambiente no site de origem

Configure o backend do site externo (nunca o browser) com o URL do gateway AACT e os segredos da credencial em Admin → Integrations.

VariávelFunção
AACT_URLURL base do gateway AACT (demo local: http://localhost:18080)
AACT_TOKENBearer token do create/rotate da credencial
AACT_HMAC_SECRETSegredo HMAC mostrado uma vez no create/rotate
AACT_ENABLEDKill switch opcional no produto de origem
bash
AACT_ENABLED=true
AACT_URL=http://localhost:18080
AACT_TOKEN=aact_…
AACT_HMAC_SECRET=…

Hook no site externo

  1. Persistir estado paid após confirmação do PSP na BD de origem
  2. Correr side-effects locais (ledger, fiscal, …)
  3. Enfileirar um job que faz POST assinado para /api/v1/integration/events
  4. Em refunds, enfileirar um evento separado com related_external_event_id

Não bloquear a confirmação de pagamento

Se a AACT estiver temporariamente indisponível, faça retry mais tarde com o mesmo external_event_id. Nunca reverta uma venda já paga na origem só porque a AACT falhou.

Exemplos copy-paste PHP e TypeScript de client + notifier: /docs/integrations/client. Deep-dive no repositório: docs/integrations/external-hook.md.

  • Cliente e notifier

    Helpers mínimos em PHP e TypeScript

Exemplo local

bash
export AACT_URL=http://localhost:18080
export AACT_TOKEN=…          # do create/rotate no admin
export AACT_HMAC_SECRET=…    # mostrado uma vez
export REFERRAL_CODE=REF-DEMOCODE01
node examples/node-checkout/post-sale.mjs

Ver também examples/offline-sale para canais não ecommerce.

Anterior

Integrações

Seguinte

Cliente e notifier