Pular para o conteúdo

Gravar a fotografia da estrutura de mídia

POST
/ad-entities
 
curl --request POST \
  --url https://dattacrm.com.br/api/v1/ad-entities \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "platform": "meta", "records": [ { "level": "campaign", "entityId": "example", "name": "example", "campaignId": "example", "campaignName": "example", "adsetId": "example", "adsetName": "example", "status": "example", "effectiveStatus": "example", "dailyBudget": 1, "lifetimeBudget": 1, "budgetRemaining": 1, "collectedAt": "2026-11-04T13:00:00Z", "extra": { "additionalProperty": "example" } } ] }'

Grava, em lote, o estado atual das campanhas, conjuntos e anúncios de uma plataforma (meta, google, tiktok ou linkedin) na conta da chave: nome, status próprio, veiculação (effectiveStatus) e orçamentos diário, total e restante. A chave natural de cada registro é platform + level + entityId: se já existe, é atualizado só com os campos enviados (o que não vem fica como está; null enviado grava null; extra, quando vem, substitui o anterior inteiro; collectedAt é regravado); se não existe, é criado. Um registro com collectedAt mais antigo que o já gravado (reenvio atrasado) é ignorado e não conta em upserted, para não desfazer um estado mais novo. A fotografia guarda só o estado atual: reenviar a estrutura de hora em hora é seguro e idempotente, e a entidade que fica mais de 30 dias sem ser enviada sai sozinha. Quando a fotografia mais recente da conta tem mais de 6 horas, o CRM volta a deduzir o status pela mídia diária (/ad-metrics). Se level e entityId 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. Os orçamentos ficam na moeda da conta de anúncios, sem conversão. A estrutura 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 da fotografia da estrutura 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 level e entityId se repetem no lote, vale o último. Um registro inválido recusa o lote inteiro e nada é gravado.

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

Estado atual de uma campanha, conjunto ou anúncio.

object
level
required

Nível da entidade: campaign (campanha), adset (conjunto de anúncios ou grupo de anúncios) ou ad (anúncio).

string
Allowed values: campaign adset ad
entityId
required

Identificador da entidade na plataforma. Com platform e level, é a chave do registro.

string
>= 1 characters <= 200 characters
name
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
status
Any of:
string
<= 100 characters
effectiveStatus
Any of:
string
<= 100 characters
dailyBudget
Any of:
number
<= 999999999999.99
lifetimeBudget
Any of:
number
<= 999999999999.99
budgetRemaining
Any of:
number
<= 999999999999.99
collectedAt
required

Quando a plataforma foi lida, em ISO 8601 com fuso (ex.: 2026-11-04T13:00:00Z ou 2026-11-04T10:00:00-03:00). Não pode passar de agora mais 10 minutos (400). Um registro com collectedAt mais antigo que o já gravado é ignorado.

string format: date-time
/^(?:(?:\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])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$/
Example 
2026-11-04T13:00:00Z
extra

Qualquer outro dado da entidade (objetivo, lance, datas de início e fim 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 entidades foram gravadas (criadas ou atualizadas), já juntadas as repetidas do lote. A entidade cujo collectedAt é mais antigo que o gravado não conta.

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 ou level desconhecidos, mais de 500 registros, collectedAt fora do formato ISO 8601 com fuso ou mais de 10 minutos no futuro, ou orçamento negativo. O índice do registro vem em details[].path (ex.: records.3.collectedAt). 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.