> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metrito.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Atualizar Objetos de Anúncios

> Pausar, ativar ou alterar o orçamento de campanhas, conjuntos de anúncios ou anúncios em lote.

Cada item no array `updates` recebe **exatamente um** dos campos `status` ou `budget` — nunca ambos.

O orçamento deve ser enviado em **centavos da moeda da conta** (ex: `5000` = R$ 50,00 ou US$ 50,00).
O Metrito detecta automaticamente se a campanha usa orçamento diário ou vitalício.


## Identificando a conexão

O parâmetro `connectionId` aceita dois formatos:

| Formato          | Exemplo                        | Quando usar                                            |
| ---------------- | ------------------------------ | ------------------------------------------------------ |
| ID Metrito       | `64a1b2c3d4e5f6a7b8c9d0e1`     | Padrão — obtido via `GET /v3/projects/:id/connections` |
| ID da conta Meta | `act_123456789` ou `123456789` | Quando você já tem o ID da conta de anúncios           |

## Tipos de objeto suportados

| `type`     | O que representa     |
| ---------- | -------------------- |
| `campaign` | Campanha             |
| `adset`    | Conjunto de anúncios |
| `ad`       | Anúncio individual   |

## Operações por objeto

| Operação          | Campo    | Valores aceitos              | Suporta             |
| ----------------- | -------- | ---------------------------- | ------------------- |
| Pausar / Ativar   | `status` | `"ACTIVE"`, `"PAUSED"`       | campaign, adset, ad |
| Alterar orçamento | `budget` | Inteiro positivo em centavos | campaign, adset     |

> **Nota:** Anúncios não possuem orçamento próprio. Use `campaign` ou `adset` para alterar orçamento.

## Misturar operações em uma chamada

Você pode misturar operações de `status` e `budget` no mesmo array `updates`. O Metrito agrupa e processa cada tipo separadamente.

## Exemplos de uso

**Pausar uma campanha:**

```json
{
  "type": "campaign",
  "updates": [
    { "id": "120215678901234567", "status": "PAUSED" }
  ]
}
```

**Ativar múltiplos anúncios:**

```json
{
  "type": "ad",
  "updates": [
    { "id": "120215678901234567", "status": "ACTIVE" },
    { "id": "120215678901234568", "status": "ACTIVE" }
  ]
}
```

**Alterar orçamento de múltiplas campanhas:**

```json
{
  "type": "campaign",
  "updates": [
    { "id": "120215678901234567", "budget": 10000 },
    { "id": "120215678901234568", "budget": 5000 }
  ]
}
```

**Pausar e alterar orçamento na mesma chamada:**

```json
{
  "type": "campaign",
  "updates": [
    { "id": "120215678901234567", "status": "PAUSED" },
    { "id": "120215678901234568", "budget": 10000 }
  ]
}
```


## OpenAPI

````yaml /openapi/platform.yaml put /v3/connections/{connection_id}/objects
openapi: 3.1.0
info:
  title: API da Plataforma — Metrito
  version: '3.0'
  description: >
    API para autenticação e consulta de recursos da plataforma Metrito
    (projetos, conexões).

    Utilizada para obter tokens JWT e listar recursos disponíveis para o usuário
    autenticado.
servers:
  - url: https://api.metrito.com
    description: Produção
security: []
paths:
  /v3/connections/{connection_id}/objects:
    put:
      summary: Atualizar objetos de anúncios
      description: >
        Pausar, ativar ou alterar o orçamento de campanhas, conjuntos de
        anúncios ou anúncios em lote.


        Cada item no array `updates` recebe **exatamente um** dos campos
        `status` ou `budget` — nunca ambos.


        O orçamento deve ser enviado em **centavos da moeda da conta** (ex:
        `5000` = R$ 50,00 ou US$ 50,00).

        O Metrito detecta automaticamente se a campanha usa orçamento diário ou
        vitalício.
      operationId: updateAdObjects
      parameters:
        - name: connection_id
          in: path
          required: true
          description: >
            ID da conexão no Metrito (`64a1b2c3d4e5f6a7b8c9d0e1`) **ou** ID da
            conta de anúncios na plataforma (`act_123456789` para Meta Ads).
          schema:
            type: string
            example: 64a1b2c3d4e5f6a7b8c9d0e1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - type
                - updates
              properties:
                type:
                  type: string
                  enum:
                    - campaign
                    - adset
                    - ad
                  description: Tipo do objeto a ser atualizado.
                  example: campaign
                updates:
                  type: array
                  minItems: 1
                  description: >
                    Lista de objetos a atualizar. Cada item deve conter `id` e
                    **exatamente um** de `status` ou `budget`.
                  items:
                    oneOf:
                      - title: Alterar status
                        type: object
                        required:
                          - id
                          - status
                        properties:
                          id:
                            type: string
                            description: >-
                              ID do objeto na plataforma de anúncios (Meta,
                              Google, etc.).
                            example: '23850998280630288'
                          status:
                            type: string
                            enum:
                              - ACTIVE
                              - PAUSED
                            description: >-
                              Novo status do objeto. Não pode ser enviado junto
                              com `budget`.
                            example: ACTIVE
                        additionalProperties: false
                      - title: Alterar orçamento
                        type: object
                        required:
                          - id
                          - budget
                        properties:
                          id:
                            type: string
                            description: >-
                              ID do objeto na plataforma de anúncios (Meta,
                              Google, etc.).
                            example: '23850998280630288'
                          budget:
                            type: integer
                            minimum: 1
                            description: >
                              Novo valor de orçamento em **centavos** da moeda
                              da conta.

                              Exemplos: `5000` = R$ 50,00 · `10000` = R$ 100,00
                              · `150000` = R$ 1.500,00.

                              O tipo (diário ou vitalício) é detectado
                              automaticamente.

                              Não pode ser enviado junto com `status`. Não
                              aplicável a `ad`.
                            example: 10000
                        additionalProperties: false
            examples:
              pauseCampaign:
                summary: Pausar uma campanha
                value:
                  type: campaign
                  updates:
                    - id: '120215678901234567'
                      status: PAUSED
              activateAds:
                summary: Ativar múltiplos anúncios
                value:
                  type: ad
                  updates:
                    - id: '120215678901234567'
                      status: ACTIVE
                    - id: '120215678901234568'
                      status: ACTIVE
              updateBudget:
                summary: Alterar orçamento de campanhas
                value:
                  type: campaign
                  updates:
                    - id: '120215678901234567'
                      budget: 10000
                    - id: '120215678901234568'
                      budget: 5000
              mixedOperations:
                summary: Pausar e alterar orçamento na mesma chamada
                value:
                  type: campaign
                  updates:
                    - id: '120215678901234567'
                      status: PAUSED
                    - id: '120215678901234568'
                      budget: 10000
      responses:
        '200':
          description: Todas as atualizações foram aplicadas com sucesso.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdUpdateResponse'
              example:
                success: true
                summary:
                  total: 2
                  successful: 2
                  failed: 0
                results:
                  - id: '120215678901234567'
                    success: true
                    error: null
                  - id: '120215678901234568'
                    success: true
                    error: null
        '207':
          description: Algumas atualizações falharam (resposta parcial).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdUpdateResponse'
              example:
                success: false
                summary:
                  total: 2
                  successful: 1
                  failed: 1
                results:
                  - id: '120215678901234567'
                    success: true
                    error: null
                  - id: '120215678901234568'
                    success: false
                    error:
                      message: Campaign is not active and cannot be paused
                      code: 1487065
        '400':
          description: Parâmetros inválidos ou malformados.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  type: validation_error
                  code: invalid_parameter
                  message: 'type must be one of: campaign, adset, ad'
        '401':
          description: Credencial ausente ou inválida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Conexão não encontrada no workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  type: not_found_error
                  code: resource_not_found
                  message: Connection "act_123456789" not found in this workspace.
        '422':
          description: Plataforma não suportada para esta operação.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  type: platform_error
                  code: PLATFORM_NOT_SUPPORTED
                  message: >-
                    Platform "google-ads" does not support ad management
                    operations yet.
      security:
        - bearerAuth: []
        - apiKeyAuth: []
components:
  schemas:
    AdUpdateResponse:
      type: object
      properties:
        success:
          type: boolean
          description: True only if every update in the batch succeeded.
        summary:
          type: object
          properties:
            total:
              type: integer
            successful:
              type: integer
            failed:
              type: integer
        results:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: ID do objeto atualizado.
              success:
                type: boolean
              error:
                type: object
                nullable: true
                description: Detalhes do erro da plataforma, quando presente.
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            type:
              type: string
              description: Categoria do erro.
              enum:
                - authentication_error
                - authorization_error
                - validation_error
                - not_found_error
                - platform_error
                - api_error
            code:
              type: string
              description: Código de erro específico.
            message:
              type: string
              description: Descrição legível do erro.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT or API Key
      description: >-
        JWT da plataforma ou API key `mtk_live_...` enviada no header
        Authorization
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key `mtk_live_...` enviada via header `x-api-key`

````