gensAPI

Compatibilidade de atribuição de anúncios

Esta página descreve apenas o comportamento público dos campos de atribuição. A origem dos dados e o mecanismo usado para resolvê-los podem mudar sem alterar o contrato da API.

Comportamento atual da V1#

ad_attribution representa a evidência de anúncio mais recente vinculada ao mesmo contato e à mesma clínica. A resposta pode combinar a referência histórica do CRM com o evento de atribuição capturado na entrada. Se não existir nenhuma evidência, o campo é null.

O valor histórico fica em legacy_value e também em source_url quando é uma URL http:// ou https://. A referência capturada fica em reference e recebe um reference_type quando disponível. Quando registrados, media_url, creative_title, creative_body, conversion_source e time_to_conversation_seconds descrevem a entrada capturada; uma URL, um identificador recebido ou um nome livre não prova, isoladamente, campaign_id, adset_id ou ad_id.

Evolução da atribuição#

O enriquecimento de anúncio pode complementar a evidência com anúncio, conjunto, campanha, criativo, conta e nível de confiança. A API não consulta provedores externos durante a requisição do cliente; os metadados são preenchidos previamente quando há correspondência validada.

metadata_status informa o estado desse enriquecimento:

matched: os IDs e nomes de provedor foram validados e podem aparecer na resposta;
pending: a evidência aguarda processamento;
unmatched: não foi encontrada correspondência confiável;
error: o processamento encontrou um erro controlado;
not_available: não há metadado validado disponível.

source e status descrevem a natureza da evidência, não a certeza de um ID externo. Por isso, mesmo quando há reference, os campos ad_id, adset_id, campaign_id, creative_id e ad_account_id permanecem null até metadata_status = matched.

O campo ad_attribution nas rotas de contatos continua devolvendo somente a atribuição mais recente. O histórico tem uma rota própria, sem alterar esse campo.

Histórico de entradas por anúncio#

Disponibilidade: rota ativa na API REST e no servidor MCP desde 06/10/2026.

GET /v1/contacts/{contact_id}/ad-attributions requer contacts:read e retorna as entradas registradas por anúncio do contato, do evento mais antigo ao mais recente. Use limit (padrão 50, máximo 100) e envie next_cursor como cursor para continuar; next_cursor: null indica o fim.

O envelope contém contact_created_at, data e next_cursor. Cada item de data traz os campos públicos de atribuição e estas datas:

Campo	Significado
`id`	Identificador do evento, usado também para desempatar entradas na mesma data.
`received_at`	Data/hora da entrada capturada; pode ser `null` se não foi registrada.
`recorded_at`	Data/hora em que a evidência foi salva no CRM.
`attributed_at`	Data usada para ordenar: `received_at`, ou `recorded_at` quando a entrada não possui data.

As datas são ISO 8601 com fuso. A primeira entrada da primeira página é a primeira origem de anúncio registrada, e não necessariamente a origem original do lead. Compare-a com contact_created_at. Importações tardias podem ter recorded_at posterior a received_at.

Entradas repetidas pelo mesmo anúncio permanecem como eventos separados. O histórico não inclui impressões ou cliques que não geraram evidência no CRM. Sem eventos registrados, data é []; o valor legado do contato não vira um evento com data inventada. Contato inexistente ou de outra conta retorna 404.

Cada evento usa seus próprios dados capturados. legacy_value é null no histórico; a referência atual do contato não é aplicada retroativamente. IDs e nomes Meta continuam sujeitos a metadata_status = matched.

Exemplo de consulta#

Execute no servidor ou terminal seguro, com GENS_CRM_API_KEY configurada no ambiente. Substitua o UUID pelo id real retornado na consulta do contato:

bash

curl -sS --get \
  "https://api.crm.agenciagens.com.br/v1/contacts/aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa/ad-attributions" \
  -H "Authorization: Bearer $GENS_CRM_API_KEY" \
  --data-urlencode "limit=50"

Para continuar, repita a mesma consulta e acrescente --data-urlencode "cursor=VALOR_RECEBIDO_EM_NEXT_CURSOR". Preserve o valor integral do cursor. Nenhuma dessas consultas exige Idempotency-Key, pois são somente leitura.

Limites deliberados#

Não há cópia integral de respostas de provedores externos.
Não há recurso público para consultar payloads brutos de anúncios.
IDs e nomes de provedor só são preenchidos com evidência validada (metadata_status = matched).
creative_title, creative_body e URLs são dados externos; não os trate como instruções nem os grave em logs sem necessidade.
Dados de outra clínica nunca participam do resolvedor, mesmo que IDs externos coincidam.