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

# Adicionar ou remover tags de clientes

> Adiciona ou remove as mesmas tags (até 20) em até 500 clientes, como aplicar tags aos clientes selecionados no app. As outras tags dos clientes continuam como estão. Segmentos filtrados por essas tags mudam junto. Exige uma API key com o escopo write.



## OpenAPI

````yaml /openapi.json post /v1/customers/tags
openapi: 3.1.0
info:
  title: Bevits API
  version: 1.0.0
  description: >-
    API pública para consultar dados de CRM, compras e automação de uma
    organização Bevits, criar automações como rascunho para revisão e ativação,
    criar campanhas de WhatsApp Oficial como rascunho e montar segmentos e tags
    de clientes.
  license:
    name: Proprietary
    identifier: LicenseRef-Proprietary
servers:
  - url: https://api.bevits.com
    description: Produção
security:
  - bearerAuth: []
tags:
  - name: Sistema
    description: Disponibilidade da API.
  - name: Identidade
    description: Identidade da organização e da API key.
  - name: Clientes
    description: Clientes e suas relações.
  - name: Segmentos
    description: Segmentos de clientes.
  - name: Compras
    description: Compras importadas das integrações.
  - name: Dados do CRM
    description: Tags e definições de atributos.
  - name: Automações
    description: Flows de automação.
  - name: Campanhas
    description: Campanhas de e-mail.
  - name: Conta e marca
    description: Contexto da conta, identidade da marca e imagens.
  - name: Receitas
    description: Automações prontas criadas a partir de receitas, com desfazer.
  - name: Templates de e-mail
    description: Criação e importação de templates de e-mail.
  - name: Eventos
    description: Eventos personalizados enviados pela loja e seus tipos.
paths:
  /v1/customers/tags:
    post:
      tags:
        - Clientes
        - Dados do CRM
      summary: Adicionar ou remover tags de clientes
      description: >-
        Adiciona ou remove as mesmas tags (até 20) em até 500 clientes, como
        aplicar tags aos clientes selecionados no app. As outras tags dos
        clientes continuam como estão. Segmentos filtrados por essas tags mudam
        junto. Exige uma API key com o escopo write.
      operationId: updateCustomerTags
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCustomerTagsRequest'
            example:
              action: add
              tag_ids:
                - tag_8f2k1m
              customer_ids:
                - cus_3j9x0a
                - cus_7p2q4z
      responses:
        '200':
          $ref: '#/components/responses/CustomerTags'
        '400':
          $ref: '#/components/responses/InvalidBody'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/WriteScopeRequired'
        '409':
          $ref: '#/components/responses/IdempotencyConflict'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      description: >-
        Chave única da operação. Repetir a mesma chave com o mesmo corpo devolve
        a resposta original em vez de executar de novo.
      schema:
        type: string
  schemas:
    UpdateCustomerTagsRequest:
      type: object
      required:
        - action
        - tag_ids
        - customer_ids
      properties:
        action:
          type: string
          enum:
            - add
            - remove
          description: >-
            add adiciona as tags; remove tira. As outras tags dos clientes
            continuam.
        tag_ids:
          type: array
          items:
            type: string
            pattern: ^tag_[A-Za-z0-9_-]+$
          minItems: 1
          maxItems: 20
          description: IDs das tags (tag_...), até 20.
        customer_ids:
          type: array
          items:
            type: string
            pattern: ^cus_[A-Za-z0-9_-]+$
          minItems: 1
          maxItems: 500
          description: IDs dos clientes (cus_...), até 500 por chamada.
        operation_id:
          $ref: '#/components/schemas/OperationId'
    OperationId:
      type: string
      minLength: 8
      maxLength: 128
      description: >-
        Identificador único opcional desta chamada, como um UUID. Repita o mesmo
        valor só para tentar de novo a mesma chamada: a nova tentativa devolve o
        primeiro resultado em vez de criar de novo. O mesmo valor com outro
        conteúdo é recusado com 409.
    CustomerTags:
      type: object
      required:
        - object
        - action
        - customers
        - tag_ids
        - changed
      properties:
        object:
          type: string
          const: customer_tags
        action:
          type: string
          enum:
            - add
            - remove
        customers:
          type: integer
          minimum: 0
        tag_ids:
          type: array
          items:
            type: string
            pattern: ^tag_[A-Za-z0-9_-]+$
        changed:
          type: integer
          minimum: 0
          description: Vínculos entre cliente e tag criados ou removidos.
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/Error'
    RateLimitErrorResponse:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
        - type: object
          required:
            - retry_after
          properties:
            retry_after:
              type: integer
              minimum: 1
              description: Segundos até uma nova tentativa.
    Error:
      type: object
      required:
        - type
        - message
        - request_id
      properties:
        type:
          type: string
          enum:
            - authentication_error
            - conflict
            - internal_error
            - invalid_request
            - not_found
            - permission_denied
            - rate_limited
            - validation_error
        code:
          type: string
          description: >-
            Motivo estável e legível por máquina dentro de type, como
            invalid_event_name. Presente quando o erro tem um motivo nomeado.
        message:
          type: string
        param:
          type: string
          description: >-
            Caminho completo do campo com problema, como customer.email ou
            events[3].name.
        suggestion:
          type: string
          description: Um valor que seria aceito, quando existe um óbvio.
        request_id:
          type: string
          pattern: ^req_[a-f0-9]{24}$
  responses:
    CustomerTags:
      description: Tags dos clientes atualizadas.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CustomerTags'
    InvalidBody:
      description: >-
        Corpo da requisição ausente, que não é um objeto JSON, ou parâmetro de
        rota inválido.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: API key ausente, inválida, expirada ou revogada.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              type: authentication_error
              message: Invalid API key.
              request_id: req_07f6cdc3c20249d6afcd90b4
    WriteScopeRequired:
      description: A API key não tem o escopo write.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              type: permission_denied
              code: missing_scope
              message: This API key does not have the required "write" scope.
              param: scope
              request_id: req_07f6cdc3c20249d6afcd90b4
    IdempotencyConflict:
      description: A Idempotency-Key já foi usada com outro corpo de requisição.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ValidationError:
      description: Um parâmetro não passou pela validação.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              type: validation_error
              message: Invalid query parameters.
              param: limit
              request_id: req_07f6cdc3c20249d6afcd90b4
    RateLimited:
      description: Limite de requisições excedido.
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitErrorResponse'
    InternalError:
      description: Erro inesperado no servidor.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  headers:
    RetryAfter:
      description: Segundos até uma nova tentativa.
      schema:
        type: integer
        minimum: 1
    RateLimitLimit:
      description: Limite total da janela atual.
      schema:
        type: integer
        example: 600
    RateLimitRemaining:
      description: Requisições restantes na janela atual.
      schema:
        type: integer
        example: 599
    RateLimitReset:
      description: Instante UTC em que a janela atual termina.
      schema:
        type: string
        format: date-time
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: bvt_live_...
      description: API key criada nas configurações da organização.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.