Pular para o conteúdo

Gravar métricas de mídia por anúncio e dia

POST
/ad-metrics
 
curl --request POST \
  --url https://dattacrm.com.br/api/v1/ad-metrics \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "platform": "meta", "records": [ { "date": "2026-11-03", "adId": "example", "accountId": "example", "accountName": "example", "campaignId": "example", "campaignName": "example", "adsetId": "example", "adsetName": "example", "adName": "example", "adStatus": "example", "adUrl": "example", "adThumbnail": "example", "spend": 1, "impressions": 1, "reach": 1, "clicks": 1, "pageViews": 1, "platformLeads": 1, "checkouts": 1, "platformPurchases": 1, "platformRevenue": 1, "messagingStarted": 1, "currency": "example", "extra": { "additionalProperty": "example" } } ] }'

Grava, em lote, as métricas de anúncios de uma plataforma (meta, google, tiktok ou linkedin) na conta da chave: investimento, impressões, cliques e conversões da plataforma, uma linha por dia e anúncio. A chave natural de cada linha é platform + date + adId: se já existe, é atualizada só com os campos enviados (o que não vem fica como está; null enviado grava null; extra, quando vem, substitui o anterior inteiro); se não existe, é criada. Por isso o reenvio de uma janela de dias (7 na Meta e no TikTok, 30 no Google) é seguro e idempotente: sobrescreve o que já existe e não duplica. Se date e adId se repetem no mesmo lote, vale o último. De 1 a 500 registros por chamada; um registro inválido recusa o lote inteiro (400, com o índice do registro em details) e nada é gravado. A moeda é a da conta de anúncios, sem conversão: currency é opcional e, ausente, vale a moeda da conta no CRM; um registro com moeda diferente da conta recusa o lote (400), para não somar moedas. A mídia não conta no limite do plano. Exige chave com acesso de leitura e escrita.

Authorizations

Seção intitulada “Authorizations ”

Request Body required

Seção intitulada “Request Body required ”
Media type application/json

Lote de métricas de mídia de uma plataforma.

object
platform
required

Plataforma de anúncios de todos os registros do lote: meta, google, tiktok ou linkedin.

string
Allowed values: meta google tiktok linkedin
records
required

De 1 a 500 registros. Se date e adId se repetem no lote, vale o último. Um registro inválido recusa o lote inteiro e nada é gravado.

Array<object>
>= 1 items <= 500 items

Métricas de um anúncio em um dia.

object
date
required

Dia da métrica na plataforma (data civil na conta de anúncios), no formato AAAA-MM-DD.

string format: date
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$/
Example 
2026-11-03
adId
required

Identificador do anúncio na plataforma (no Google PMax, o id do grupo de recursos). Com platform e date, é a chave do registro.

string
>= 1 characters <= 200 characters
accountId
Any of:
string
<= 200 characters
accountName
Any of:
string
<= 500 characters
campaignId
Any of:
string
<= 200 characters
campaignName
Any of:
string
<= 500 characters
adsetId
Any of:
string
<= 200 characters
adsetName
Any of:
string
<= 500 characters
adName
Any of:
string
<= 500 characters
adStatus
Any of:
string
<= 100 characters
adUrl
Any of:
string
<= 2000 characters
adThumbnail
Any of:
string
<= 2000 characters
spend

Investimento do dia, na moeda da conta de anúncios. (zero a 999999999999.99).

number
<= 999999999999.99
impressions

Impressões do dia.

integer
<= 9007199254740991
reach

Alcance do dia.

integer
<= 9007199254740991
clicks

Cliques no link do dia.

integer
<= 9007199254740991
pageViews

Visualizações da página de destino do dia.

integer
<= 9007199254740991
platformLeads

Leads contados pela plataforma no dia.

integer
<= 9007199254740991
checkouts

Inícios de checkout contados pela plataforma no dia.

integer
<= 9007199254740991
platformPurchases

Compras contadas pela plataforma no dia.

integer
<= 9007199254740991
platformRevenue

Receita das compras contadas pela plataforma no dia. (zero a 999999999999.99).

number
<= 999999999999.99
messagingStarted

Conversas iniciadas (mensagens) no dia.

integer
<= 9007199254740991
currency
Any of:
string
/^[A-Z]{3}$/
extra

Qualquer outro dado do registro (vídeo, engajamento, LinkedIn etc.), como objeto JSON. Quando enviado, substitui o extra anterior inteiro; quando ausente, o anterior fica.

object
key
additional properties

Responses

Seção intitulada “ Responses ”

200

Seção intitulada “200 ”

Sucesso.

Media type application/json
object
data
required

Resultado da gravação do lote.

object
upserted
required

Quantas linhas foram gravadas (criadas ou atualizadas), já juntadas as repetidas do lote.

integer
>= -9007199254740991 <= 9007199254740991
Example generated
{
  "data": {
    "upserted": 1
  }
}

Headers

Seção intitulada “Headers ”
X-Request-Id
string

Identificador da requisição, para suporte.

X-RateLimit-Limit
integer

Máximo de requisições por janela de 60 segundos para esta chave.

X-RateLimit-Remaining
integer

Requisições restantes na janela atual.

X-RateLimit-Reset
integer

Fim da janela atual, em milissegundos desde a época Unix (epoch ms).

400

Seção intitulada “400 ”

Dados inválidos na requisição (validation_error): platform desconhecida, mais de 500 registros, date fora do formato AAAA-MM-DD ou currency diferente da moeda da conta. O índice do registro vem em details[].path (ex.: records.3.date). Nada é gravado.

Media type application/json

Formato de erro da API.

object
error
required
object
code
required

Código estável do erro, ex.: validation_error.

string
message
required

Mensagem legível em português.

string
details

Detalhes extras, ex.: lista de campos inválidos.

requestId
required

Identificador da requisição, para suporte.

string
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

Seção intitulada “Headers ”
X-Request-Id
string

Identificador da requisição, para suporte.

401

Seção intitulada “401 ”

Chave ausente, inválida (invalid_api_key), vencida (api_key_expired) ou revogada (api_key_revoked).

Media type application/json

Formato de erro da API.

object
error
required
object
code
required

Código estável do erro, ex.: validation_error.

string
message
required

Mensagem legível em português.

string
details

Detalhes extras, ex.: lista de campos inválidos.

requestId
required

Identificador da requisição, para suporte.

string
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

Seção intitulada “Headers ”
X-Request-Id
string

Identificador da requisição, para suporte.

403

Seção intitulada “403 ”

A chave é somente leitura e a operação grava dados (insufficient_scope).

Media type application/json

Formato de erro da API.

object
error
required
object
code
required

Código estável do erro, ex.: validation_error.

string
message
required

Mensagem legível em português.

string
details

Detalhes extras, ex.: lista de campos inválidos.

requestId
required

Identificador da requisição, para suporte.

string
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

Seção intitulada “Headers ”
X-Request-Id
string

Identificador da requisição, para suporte.

409

Seção intitulada “409 ”

Conflito com o estado atual (conflict), contato oculto, cujo negócio não muda (lead_hidden), ou limite do plano atingido (plan_limit).

Media type application/json

Formato de erro da API.

object
error
required
object
code
required

Código estável do erro, ex.: validation_error.

string
message
required

Mensagem legível em português.

string
details

Detalhes extras, ex.: lista de campos inválidos.

requestId
required

Identificador da requisição, para suporte.

string
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

Seção intitulada “Headers ”
X-Request-Id
string

Identificador da requisição, para suporte.

413

Seção intitulada “413 ”

O corpo da requisição passa de 2 MB (payload_too_large).

Media type application/json

Formato de erro da API.

object
error
required
object
code
required

Código estável do erro, ex.: validation_error.

string
message
required

Mensagem legível em português.

string
details

Detalhes extras, ex.: lista de campos inválidos.

requestId
required

Identificador da requisição, para suporte.

string
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

Seção intitulada “Headers ”
X-Request-Id
string

Identificador da requisição, para suporte.

429

Seção intitulada “429 ”

Limite de requisições atingido (rate_limited). Aguarde Retry-After segundos.

Media type application/json

Formato de erro da API.

object
error
required
object
code
required

Código estável do erro, ex.: validation_error.

string
message
required

Mensagem legível em português.

string
details

Detalhes extras, ex.: lista de campos inválidos.

requestId
required

Identificador da requisição, para suporte.

string
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

Seção intitulada “Headers ”
X-Request-Id
string

Identificador da requisição, para suporte.

X-RateLimit-Limit
integer

Máximo de requisições por janela de 60 segundos para esta chave.

X-RateLimit-Remaining
integer

Requisições restantes na janela atual.

X-RateLimit-Reset
integer

Fim da janela atual, em milissegundos desde a época Unix (epoch ms).

Retry-After
integer

Segundos até poder tentar de novo.

500

Seção intitulada “500 ”

Erro interno (internal_error). Informe o requestId ao suporte.

Media type application/json

Formato de erro da API.

object
error
required
object
code
required

Código estável do erro, ex.: validation_error.

string
message
required

Mensagem legível em português.

string
details

Detalhes extras, ex.: lista de campos inválidos.

requestId
required

Identificador da requisição, para suporte.

string
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

Seção intitulada “Headers ”
X-Request-Id
string

Identificador da requisição, para suporte.

503

Seção intitulada “503 ”

O CRM está em modo somente leitura durante uma migração (maintenance). Tente de novo depois de Retry-After segundos.

Media type application/json

Formato de erro da API.

object
error
required
object
code
required

Código estável do erro, ex.: validation_error.

string
message
required

Mensagem legível em português.

string
details

Detalhes extras, ex.: lista de campos inválidos.

requestId
required

Identificador da requisição, para suporte.

string
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

Seção intitulada “Headers ”
X-Request-Id
string

Identificador da requisição, para suporte.

Retry-After
integer

Segundos até poder tentar de novo.