API REST do Marketing Cloud: autenticação OAuth 2.0 e gravação em Data Extension

Integrar um sistema externo ao Marketing Cloud Engagement começa sempre pelo mesmo passo: conseguir um token de acesso. Este tutorial cobre a autenticação server-to-server (OAuth 2.0, client credentials) e um primeiro uso real: gravar linhas numa Data Extension.

1. Installed Package

Em Setup → Apps → Installed Packages:

1. New e dê um nome (ex.: "Integração ERP").
2. Add Component → API Integration → Server-to-Server.
3. Marque só as permissões que a integração precisa. Para gravar em Data Extension: Data → Data Extensions: Read e Write.
4. Salve e anote: Client Id, Client Secret, Authentication Base URI e REST Base URI.

2. Pedindo o token

curl -X POST "https://SEU_SUBDOMINIO.auth.marketingcloudapis.com/v2/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "SEU_CLIENT_ID",
    "client_secret": "SEU_CLIENT_SECRET",
    "account_id": "MID_DA_BUSINESS_UNIT"
  }'

• account_id é o MID da Business Unit em que você quer agir. Sem ele, o token vale para a BU do pacote.
• O subdomínio é o mesmo que aparece na Authentication Base URI do pacote.

A resposta:

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 1079,
  "scope": "data_extensions_read data_extensions_write",
  "rest_instance_url": "https://SEU_SUBDOMINIO.rest.marketingcloudapis.com/",
  "soap_instance_url": "https://SEU_SUBDOMINIO.soap.marketingcloudapis.com/"
}

3. Reaproveite o token

O token vale por cerca de 18 minutos (expires_in, em segundos). Pedir um token novo a cada chamada é o erro mais comum: deixa a integração lenta e pode esbarrar em limites de requisição.

O padrão correto:

1. guarde o access_token e o horário em que ele expira;
2. reutilize enquanto faltar mais de um ou dois minutos para expirar;
3. peça outro só quando estiver perto do fim, ou quando uma chamada voltar 401.

Use sempre o rest_instance_url que veio na resposta para as chamadas seguintes.

4. Gravando numa Data Extension

O endpoint de upsert de linhas usa a chave externa da Data Extension:

curl -X POST "https://SEU_SUBDOMINIO.rest.marketingcloudapis.com/hub/v1/dataevents/key:PEDIDOS_API/rowset" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "keys":   { "Numero": "10021" },
      "values": { "Email": "ana@exemplo.com", "Valor": "189.90", "Status": "Enviado" }
    }
  ]'

• keys leva as colunas da chave primária; values, as demais.
• Se a linha com aquela chave já existe, ela é atualizada; se não existe, é criada.
• Envie várias linhas no mesmo array em vez de uma chamada por linha.

Erros comuns

Resumo

Um Installed Package server-to-server, um token reaproveitado até perto de expirar e o rest_instance_url da resposta: com isso, qualquer integração com o Marketing Cloud fica estável. O upsert por /hub/v1/dataevents é o jeito mais direto de manter uma Data Extension sincronizada com outro sistema.