Enviar vendas e dados próprios ao LinkHarbor

O LinkHarbor também aceita dados vindos de fora. Para dois casos existem endpoints próprios com segredos próprios – não precisa de chave de API para eles: os callbacks de venda comunicam vendas da sua loja, para que veja nas estatísticas que link gerou receita. A integração «Custom (API)» leva dados em direto das suas próprias ferramentas para a sua página como widget e pode disparar notificações push.

#Callbacks de venda: associar vendas

Como o ID do clique (lt_click_id), a atribuição e os relatórios se relacionam está explicado em Atribuir conversões e vendas; aqui encontra todos os campos e respostas para programadores. Em resumo: quando o LinkHarbor redireciona um clique contado para um destino http ou https, acrescenta o parâmetro lt_click_id; a sua loja guarda-o e devolve-o após a compra.

Criar um segredo de callback

1. Abra «Callback e API»
2. No cartão «Segredos de callback», clique em «+ Criar novo segredo»
3. Se quiser, dê-lhe um nome, por exemplo «Callback da loja», e clique em «Criar segredo»
4. Copie o segredo de imediato – só é mostrado uma vez

Quem

Proprietários e admins, a partir do Creator Pro. No Creator Free aparece «Os segredos de callback estão disponíveis a partir do Creator Pro.»

Quantos

Até 5 segredos por espaço de trabalho, por exemplo um por loja.

«Editar»

Altere o nome e defina o estado como «Ativo» ou «Inativo». Com um segredo inativo, a API recusa os callbacks.

«↺ Rodar»

Gera um novo segredo; o antigo deixa de funcionar de imediato.

«Último callback:»

Mostra quando o segredo foi usado com sucesso pela última vez.

Enviar um callback

curl -X POST https://dock.at-harbor.com/v1/callbacks/sale \
  -H "Content-Type: application/json" \
  -H "X-Callback-Secret: $LH_CALLBACK_SECRET" \
  -d '{
    "click_id": "3f1c2a9e-8d4b-4a51-9f0e-6b7c1d2e3f40",
    "order_id": "A-10023",
    "amount": "49.90",
    "currency": "EUR",
    "occurred_at": "2026-11-01T10:15:00Z"
  }'
# → {"ok":true,"conversion_id":123}

Assinatura opcional

Além do segredo, pode enviar o cabeçalho X-Callback-Signature. Contém sha256= e a assinatura HMAC-SHA256 do corpo em bruto em hexadecimal. A chave não é o próprio segredo, mas o respetivo hash SHA-256 em formato binário. Se enviar o cabeçalho, tem de estar correto – caso contrário, o callback é recusado.

<?php
$body = json_encode($payload);
$key  = hash('sha256', getenv('LH_CALLBACK_SECRET'), true); // hash binário do segredo
$sig  = 'sha256=' . hash_hmac('sha256', $body, $key);
// Cabeçalhos: X-Callback-Secret e X-Callback-Signature: $sig, corpo: $body

Onde vê as vendas

As vendas comunicadas aparecem como conversões nas suas estatísticas, veja Atribuir conversões e vendas. Através da API, lê-as com read:stats em /v1/stats/…/conversions/breakdown.

#Custom (API): os seus próprios dados em direto

Com a integração «Custom (API)», qualquer programa capaz de enviar pedidos HTTP – um plugin de servidor de jogos, um bot, um script cron – pode enviar dados para o LinkHarbor. Esses dados tornam-se um widget em direto na sua página, e as regras de push podem notificar os seus seguidores.

Ligar

1. Abra «Integrações» no espaço de trabalho
2. Escolha «Custom (API)» e introduza um nome
3. Depois de ligar, a caixa de diálogo mostra o «URL de ingestão» e o «Secret» (com «Mostrar secret»)
4. Guarde ambos na sua ferramenta

As integrações estão disponíveis a partir do Creator Pro. Só proprietários e admins veem o URL de ingestão e o secret, também mais tarde na vista de detalhe da integração. Desligar e voltar a ligar cria um novo secret. Como ligar integrações em geral está explicado em Ligar uma integração.

Enviar dados

curl -X POST "$INGEST_URL" \
  -H "Authorization: Bearer $INGEST_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "player.joined",
    "event_id": "join-2026-11-01T20:01:02Z-steve",
    "data": { "player": "Steve" },
    "state": {
      "type": "game_server",
      "name": "Survival SMP",
      "online": true,
      "players_online": 3,
      "players_max": 20
    }
  }'
# → {"ok":true,"event_id":4711,"duplicate":false,"event_type":"player.joined"}

event

Nome livre do evento, por exemplo player.joined. É convertido para minúsculas e é o nome a que as regras de push reagem. Sem event, o evento chama-se state.updated.

event_id

Chave opcional que impede o processamento duplicado. Se o mesmo event_id for enviado de novo, o LinkHarbor responde com duplicate: true e não faz nada.

data

Valores para os marcadores nos textos de push, por exemplo {player}. Até 40 chaves, apenas valores simples.

state

O estado completo do widget. Substitui totalmente o anterior. type é game_server (cartão de servidor de jogo) ou status (cartão de estado).

Em vez de Authorization: Bearer, também pode enviar o secret no cabeçalho X-LinkHarbor-Secret. São permitidas 120 chamadas por minuto por endereço IP. Opcionalmente, pode assinar o corpo: o cabeçalho X-LinkHarbor-Signature contém sha256= e a assinatura HMAC-SHA256 do corpo em bruto com o secret como chave. Se o enviar, tem de estar correto.