apointoo.
Solicitar acesso
Atribuição para Clínicas

O relatório de outbox de conversões offline que toda agência deve mostrar aos clientes

cmsapointoo··9 min de leitura

Um relatório de conversões offline deve mostrar aquilo que a agência consegue provar, em vez de resumir tudo em um percentual tranquilizador de entrega. Um bom relatório separa o ledger local do outbox, a requisição inicial da Data Manager, os diagnósticos posteriores por destino, a observação no Google Ads e a atribuição. São evidências diferentes, coletadas em momentos diferentes.

Este formato é uma recomendação editorial. AWS e Google documentam os mecanismos, mas não prescrevem um relatório para clientes. A agência define a apresentação e limita cada conclusão à evidência disponível.

Por que o cliente precisa de evidências separadas?

O cliente precisa saber quais resultados offline estão aguardando, o que a agência enviou, o que o Google ainda processa e o que falhou. Uma contagem única de uploads esconde essas diferenças. Também pode transformar uma resposta HTTP em alegação sobre relatório ou atribuição que a resposta não comprova.

O relatório responde a quatro perguntas. A transação de origem criou um evento local durável? O worker recebeu uma resposta inicial bem-sucedida e guardou o ID da requisição Google? Qual estado terminal o Google devolveu para cada destino? Uma verificação separada encontrou a conversão na conta e janela esperadas do Ads?

A atribuição forma uma quinta camada. Um destino pode concluir o processamento sem produzir o crédito de campanha que a agência esperava. O guia de diagnósticos trata da saúde do upload e de problemas nos dados. Não transforma uma requisição processada em prova de atribuição, uso em lances ou impacto comercial.

Para entender a fronteira anterior ao relatório, consulte a arquitetura server-side para formulários e Data Manager. Ela mantém a saída bloqueada até a aprovação do uso exato. O relatório desta página documenta confiabilidade depois dessa aprovação. Ele não cria permissão para enviar.

Construa primeiro o ledger local do outbox

O AWS Prescriptive Guidance apresenta o transactional outbox como solução para o problema de escrita dupla. A aplicação grava o estado de negócio e o evento de outbox na mesma transação. Outro processo lê apenas registros confirmados e envia a mensagem. Se a transação de origem for revertida, a notificação não deve sair.

O relatório para o cliente não precisa do registro de origem. Dê a cada resultado elegível um ID local opaco e uma versão do resultado. Guarde horário de criação, estado local, número de tentativas, próxima tentativa, base de deduplicação e referência do destino. O payload operacional fica fora do relatório.

Campo local Significado Exibir ao cliente?
ID opaco do evento Referência estável criada pelo sistema da agência Sim
Versão do resultado Estado aprovado que originou o evento Sim
Estado local Na fila, enviando, enviado, nova tentativa, suprimido ou em quarentena Sim
Tentativa e próxima execução Atividade do worker local Sim
Payload de origem Dados do sistema operacional Não
Campos excluídos Conteúdo de saúde, identidade e texto livre Não

Defina enviado de modo estreito. Significa que o worker recebeu uma resposta inicial bem-sucedida da Data Manager e guardou o ID da requisição. Não significa que o Google terminou o processamento. Também não diz nada sobre presença no relatório do Ads ou atribuição.

Mantenha a requisição Google em outro ledger

O guia Send Events do Google informa que uma requisição inicial bem-sucedida devolve um requestId. O guia de diagnósticos descreve esse sucesso com código 0, enum OK e HTTP 200 OK. Guarde o ID. Não dê à resposta inicial um nome que sugira resultado final.

O ledger Google usa uma linha por requisição e destino, não uma linha por evento local. Guarde ID da requisição, referência do destino, horário do envio, primeira consulta, estado atual, contagem de registros, contagens de avisos e erros e último horário consultado. Se uma requisição tiver vários eventos ou destinos, preserve a estrutura do lote.

Camada de evidência Responsável O que ela comprova
Estado do outbox Agência O que o worker local registrou
Sucesso HTTP e request ID Data Manager API Sucesso da requisição inicial de ingestão
Diagnóstico do destino Data Manager API Processamento posterior da requisição naquele destino
Observação no Ads Verificação da agência O que apareceu no relatório e período escolhidos
Observação de atribuição Modelo do Ads Crédito observado sob configurações declaradas

O record_count dos diagnósticos inclui registros bem-sucedidos e com falha. Avisos e erros aparecem como contagens por motivo. Essa evidência é agregada. Se um lote de dez eventos chegar a PARTIAL_SUCCESS, mostre o total e as contagens de erro. Não marque um ID opaco específico como sucesso ou falha sem uma resposta do fornecedor que faça essa ligação.

Use os estados oficiais do destino

O Google documenta quatro estados: PROCESSING, SUCCESS, PARTIAL_SUCCESS e FAILURE. Preserve esses nomes no ledger do fornecedor. Não os comprima em um campo chamado aceito. A palavra pode significar resposta HTTP inicial, destino concluído ou conversão visível, três coisas diferentes.

Em PROCESSING, avisos e erros ainda não estão preenchidos. SUCCESS indica conclusão sem erros, mas ainda pode conter avisos sobre dados ignorados. FAILURE indica falha de todos os registros naquele destino. PARTIAL_SUCCESS reúne sucessos e falhas no lote.

Na documentação consultada em 16 de agosto de 2026, o Google recomenda esperar 30 minutos antes da primeira consulta de diagnóstico. Depois, a equipe deve usar intervalos crescentes, com backoff exponencial, até todos os destinos chegarem a um estado terminal. O processamento pode levar até 24 horas. O relatório deve exibir uma contagem datada de em processamento, sem classificar uma janela incompleta como falha.

Guarde códigos de motivo, contagens e horários de consulta. Não copie o conteúdo dos registros rejeitados. A contagem é suficiente no relatório recorrente. A investigação técnica pode usar logs controlados sem transformar a prestação de contas ao cliente em outro repositório de dados sensíveis.

Separe deduplicação e novas tentativas

A idempotência local e a deduplicação do Google resolvem problemas relacionados, mas não idênticos. O outbox local impede que o worker repita um efeito ao receber novamente o mesmo evento. O guia Send Events informa que o Google Ads usa transactionId, dentro da mesma ação de conversão, para deduplicar eventos enviados por fontes diferentes nos cenários documentados.

O relatório pode mostrar novo, duplicado suprimido ou revisão manual como resultado local. Também pode indicar se o evento aprovado recebeu um identificador de transação externo. Não mostre esse identificador se ele revelar informação do sistema de origem. Não prometa deduplicação universal fora do produto e da ação documentados.

Novas tentativas precisam de duas colunas. A tentativa de entrega é uma ação do worker após falha transitória. A consulta de diagnóstico verifica uma requisição que já teve sucesso inicial. Consultar nunca deve reenviar a conversão. Se a resposta inicial ficar desconhecida, coloque o evento em quarentena até o runbook definir se outra tentativa é segura.

Use a taxonomia de resultados de agendamento para manter a versão do resultado estável. Ela ajuda a distinguir mudança real do resultado, repetição da mesma entrega e correção operacional. Essa distinção deve acontecer antes de qualquer sincronização externa.

Monte o relatório mensal em duas tabelas

A primeira tabela contém os eventos locais: ID opaco, versão, criação, estado, tentativas, próxima ação e ID Google, quando existir. A segunda contém as requisições Google: request ID, destino, estado de processamento, total de registros, contagens de avisos e erros e último diagnóstico.

Acima das tabelas, apresente um resumo curto:

  • resultados locais elegíveis criados no período;
  • eventos na fila, enviados, suprimidos, aguardando tentativa ou em quarentena;
  • requisições iniciais ao Google com sucesso ou falha;
  • destinos processando, concluídos, parcialmente concluídos ou com falha;
  • registros, avisos e erros agregados pelos diagnósticos;
  • observações feitas separadamente no relatório do Ads;
  • diferenças de reconciliação e responsável por cada investigação.

Uma diferença não prova perda. Pode vir de lotes em processamento, tentativas, janelas de tempo, duplicados ou configurações do Ads. Informe o motivo ou marque a questão como não resolvida. Não infira resultados individuais.

O relatório de taxa de comparecimento sem detalhes da consulta aplica a mesma contenção. Contagens e estados bastam para operar a entrega.

Erros que tornam o relatório enganoso

  • Somar eventos locais e diagnósticos Google como se fossem a mesma unidade.
  • Chamar HTTP 200 de conversão concluída.
  • Marcar eventos individuais a partir de PARTIAL_SUCCESS agregado.
  • Confundir consulta de diagnóstico com nova tentativa de entrega.
  • Expor payload, identificadores de origem ou detalhes do atendimento.
  • Tratar presença no relatório do Ads como prova automática de atribuição.
  • Usar o relatório como justificativa para ativar um envio ainda não aprovado.

O relatório pode conter processamento em aberto e resultados ainda não observados no Ads. Nomeie o responsável e date a próxima verificação, sem misturar as camadas.

Perguntas frequentes

HTTP 200 significa que a conversão apareceu no Google Ads?

Não. Significa sucesso da requisição inicial e devolução de um request ID. Consulte o diagnóstico por destino e faça outra verificação no relatório do Ads. A atribuição exige observação separada.

O relatório pode marcar cada evento depois de PARTIAL_SUCCESS?

Não. O diagnóstico traz contagens agregadas para a requisição e o destino. Sem ligação individual fornecida pelo Google, mantenha o resultado no nível do lote.

Quais dados ficam fora do relatório?

Payloads de origem, campos de saúde, campos de identidade e texto livre. O relatório precisa de referências opacas, estados, contagens, datas e códigos de motivo.

Este relatório autoriza uma rota de conversão offline?

Não. Ele documenta a confiabilidade de uma rota previamente aprovada nas revisões necessárias. Sem aprovação válida, a saída permanece desativada.

Referências

Leia também