> ## 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.

# Crear segmento por interacción con campañas

> Guarda los clientes de la vista previa, con los mismos criterios, como un nuevo segmento listo para elegirlo como público de una campaña. Quien interactuó queda congelado al crear el segmento; el período de compras se verifica de nuevo en cada envío, así que quien compre después sale del público. No se envía nada. Si el nombre ya está en uso, Bevits agrega un número al final. Exige una clave API con el permiso write.



## OpenAPI

````yaml /openapi.es.json post /v1/segments/campaign-engagement
openapi: 3.1.0
info:
  title: API de Bevits
  version: 1.0.0
  description: >-
    API pública para consultar datos de CRM, compras y automatización de una
    organización de Bevits, crear automatizaciones como borrador para revisarlas
    y activarlas, crear campañas de WhatsApp Oficial como borrador y armar
    segmentos y etiquetas de clientes.
  license:
    name: Proprietary
    identifier: LicenseRef-Proprietary
servers:
  - url: https://api.bevits.com
    description: Producción
security:
  - bearerAuth: []
tags:
  - name: Sistema
    description: Disponibilidad de la API.
  - name: Identidad
    description: Identidad de la organización y de la clave API.
  - name: Clientes
    description: Clientes y sus relaciones.
  - name: Segmentos
    description: Segmentos de clientes.
  - name: Compras
    description: Compras importadas desde las integraciones.
  - name: Datos del CRM
    description: Etiquetas y definiciones de atributos.
  - name: Automatizaciones
    description: Flows de automatización.
  - name: Campañas
    description: Campañas de email.
  - name: Cuenta y marca
    description: Contexto de la cuenta, identidad de la marca e imágenes.
  - name: Recetas
    description: Automatizaciones listas creadas a partir de recetas, con deshacer.
  - name: Plantillas de email
    description: Creación e importación de plantillas de correo.
  - name: Eventos
    description: Eventos personalizados enviados por la tienda y sus tipos.
paths:
  /v1/segments/campaign-engagement:
    post:
      tags:
        - Segmentos
      summary: Crear segmento por interacción con campañas
      description: >-
        Guarda los clientes de la vista previa, con los mismos criterios, como
        un nuevo segmento listo para elegirlo como público de una campaña. Quien
        interactuó queda congelado al crear el segmento; el período de compras
        se verifica de nuevo en cada envío, así que quien compre después sale
        del público. No se envía nada. Si el nombre ya está en uso, Bevits
        agrega un número al final. Exige una clave API con el permiso write.
      operationId: createCampaignEngagementSegment
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCampaignEngagementSegmentRequest'
            example:
              name: 'Black Friday: leyeron o hicieron clic, sin compra en noviembre'
              campaign_ids:
                - tcp_8f2k1m
                - tcp_3j9x0a
              engagement: engaged
              purchases: none
              purchases_from: '2026-11-01T00:00:00-03:00'
      responses:
        '200':
          $ref: '#/components/responses/CampaignEngagementSegment'
        '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: >-
        Clave única de la operación. Repetir la misma clave con el mismo cuerpo
        devuelve la respuesta original en lugar de ejecutarla de nuevo.
      schema:
        type: string
  schemas:
    CreateCampaignEngagementSegmentRequest:
      type: object
      required:
        - campaign_ids
        - engagement
        - name
      properties:
        campaign_ids:
          type: array
          items:
            type: string
            pattern: ^tcp_[A-Za-z0-9_-]+$
          minItems: 1
          maxItems: 50
          description: IDs de las campañas de WhatsApp Oficial (tcp_...), hasta 50.
        engagement:
          type: string
          enum:
            - engaged
            - not_engaged
            - received
          description: >-
            engaged: leyó el mensaje o hizo clic en uno de sus enlaces.
            not_engaged: el mensaje fue entregado y la persona no lo leyó ni
            hizo clic. received: el mensaje fue entregado.
        purchases:
          type: string
          enum:
            - none
            - any
          description: >-
            Mantiene a quienes no tienen (none) o tienen (any) una compra
            concluida en el período. Exige purchases_from.
        purchases_from:
          type: string
          format: date-time
          description: >-
            Inicio del período de compras (inclusivo), en ISO 8601 con zona
            horaria.
        purchases_to:
          type: string
          format: date-time
          description: >-
            Fin del período de compras (exclusivo), en ISO 8601 con zona
            horaria. Sin él, el período queda abierto.
        only_site_base:
          type: boolean
          default: true
          description: >-
            Si es true (por defecto), deja fuera a los clientes que pertenecen
            solo a las unidades físicas, como en las campañas de la marca.
        name:
          type: string
          minLength: 1
          maxLength: 200
          description: >-
            Nombre del segmento. Si ya está en uso, Bevits agrega un número al
            final.
        description:
          type: string
          maxLength: 1000
        operation_id:
          $ref: '#/components/schemas/OperationId'
    OperationId:
      type: string
      minLength: 8
      maxLength: 128
      description: >-
        Identificador único opcional de esta llamada, como un UUID. Repite el
        mismo valor solo para reintentar la misma llamada: el reintento devuelve
        el primer resultado en lugar de crear de nuevo. El mismo valor con otro
        contenido se rechaza con 409.
    CampaignEngagementSegment:
      type: object
      required:
        - object
        - segment
        - customers_added
        - reachable_count
        - breakdown
        - snapshot_at
        - next_step
      properties:
        object:
          type: string
          const: campaign_engagement_segment
        segment:
          $ref: '#/components/schemas/Segment'
        customers_added:
          type: integer
          minimum: 0
        reachable_count:
          type: integer
          minimum: 0
        breakdown:
          $ref: '#/components/schemas/CampaignEngagementBreakdown'
        snapshot_at:
          type: string
          format: date-time
        next_step:
          type: string
    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 antes de volver a intentarlo.
    Segment:
      type: object
      required:
        - object
        - id
        - created_at
        - updated_at
        - html_url
      properties:
        object:
          type: string
          const: segment
        id:
          type: string
          pattern: ^seg_[A-Za-z0-9_-]+$
        name:
          type: string
        description:
          type: string
        type:
          type: string
          enum:
            - static
            - filters
            - rfm
            - campaign_engagement
          description: >-
            static: clientes agregados manualmente. filters: quienes cumplen las
            condiciones en el momento, más quienes fueron agregados manualmente.
            rfm: lo mantiene Bevits. campaign_engagement: interacción con
            campañas registrada al crearlo.
        match:
          $ref: '#/components/schemas/SegmentMatch'
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/SegmentCondition'
          description: >-
            Condiciones de un segmento por filtros, en el mismo formato que
            aceptan la creación y la actualización.
        customer_count:
          type: integer
          minimum: 0
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        html_url:
          type: string
          format: uri
    CampaignEngagementBreakdown:
      type: object
      required:
        - engaged
        - not_engaged
        - not_received
      properties:
        engaged:
          type: integer
          minimum: 0
        not_engaged:
          type: integer
          minimum: 0
        not_received:
          type: integer
          minimum: 0
    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 estable y legible por máquina dentro de type, como
            invalid_event_name. Presente cuando el error tiene un motivo con
            nombre.
        message:
          type: string
        param:
          type: string
          description: >-
            Ruta completa del campo con problema, como customer.email o
            events[3].name.
        suggestion:
          type: string
          description: Un valor que sería aceptado, cuando existe uno obvio.
        request_id:
          type: string
          pattern: ^req_[a-f0-9]{24}$
    SegmentMatch:
      type: string
      enum:
        - all
        - any
      description: >-
        all: clientes que cumplen todas las condiciones. any: clientes que
        cumplen al menos una.
    SegmentCondition:
      description: >-
        Una condición de un segmento por filtros. El mismo formato entra en la
        creación, la actualización y la vista previa y vuelve en GET
        /v1/segments/{segment_id}.
      oneOf:
        - $ref: '#/components/schemas/SegmentFieldCondition'
        - $ref: '#/components/schemas/SegmentTagsCondition'
        - $ref: '#/components/schemas/SegmentProductCondition'
        - $ref: '#/components/schemas/SegmentCouponCondition'
      discriminator:
        propertyName: kind
        mapping:
          field: '#/components/schemas/SegmentFieldCondition'
          tags: '#/components/schemas/SegmentTagsCondition'
          product: '#/components/schemas/SegmentProductCondition'
          coupon: '#/components/schemas/SegmentCouponCondition'
    SegmentFieldCondition:
      type: object
      additionalProperties: false
      required:
        - kind
        - field
        - operator
      properties:
        kind:
          type: string
          const: field
        field:
          type: string
          minLength: 1
          maxLength: 256
          description: >-
            Un campo del cliente (como totalSpentInCents, lastPurchaseDate o
            city) o el ID de un atributo personalizado (atr_...), del catálogo
            de filtros.
        operator:
          type: string
          minLength: 1
          maxLength: 32
          description: >-
            Uno de los operadores del campo en el catálogo. Texto: eq, neq, in,
            not_in, contains, not_contains, starts_with, is_null, is_not_null.
            Número: eq, neq, gt, gte, lt, lte. Booleano: eq_true, eq_false,
            is_null, is_not_null. Fecha: gt, lt, between.
        value:
          description: >-
            Omítelo en is_null, is_not_null, eq_true y eq_false. Una lista en in
            y not_in. Dinero en centavos. Fechas en ISO 8601 con zona horaria.
          oneOf:
            - type: string
              maxLength: 512
            - type: number
            - type: boolean
            - type: array
              items:
                type: string
                minLength: 1
                maxLength: 256
              minItems: 1
              maxItems: 500
        value_to:
          description: Fin de un intervalo between.
          oneOf:
            - type: string
              maxLength: 64
            - type: number
    SegmentTagsCondition:
      type: object
      additionalProperties: false
      required:
        - kind
        - operator
        - tag_ids
      properties:
        kind:
          type: string
          const: tags
        operator:
          type: string
          enum:
            - has_any
            - has_all
            - has_none
          description: >-
            has_any: tiene alguna de las etiquetas. has_all: tiene todas.
            has_none: no tiene ninguna, incluso quienes no tienen etiquetas.
        tag_ids:
          type: array
          items:
            type: string
            pattern: ^tag_[A-Za-z0-9_-]+$
          minItems: 1
          maxItems: 50
          description: IDs de las etiquetas (tag_...), de GET /v1/tags.
    SegmentProductCondition:
      type: object
      additionalProperties: false
      required:
        - kind
        - operator
      properties:
        kind:
          type: string
          const: product
        operator:
          type: string
          enum:
            - has_purchased
            - has_not_purchased
            - purchased_in_category
        product_id:
          type: string
          minLength: 1
          maxLength: 256
          description: >-
            ID del producto en la tienda, como en los artículos de las compras.
            Para has_purchased y has_not_purchased.
        category:
          type: string
          minLength: 1
          maxLength: 256
          description: Nombre de la categoría del producto. Para purchased_in_category.
    SegmentCouponCondition:
      type: object
      additionalProperties: false
      required:
        - kind
        - status
      description: >-
        Cupones y cashback (giftback) que Bevits generó para el cliente en las
        automatizaciones, en la atención con IA y en las ventas de las tiendas
        físicas.
      properties:
        kind:
          type: string
          const: coupon
        status:
          type: string
          enum:
            - has_available
            - has_unused
            - has_expired_unused
            - has_used
            - has_received
            - has_not_received
          description: >-
            has_available: tiene un cupón sin usar y vigente, con saldo para
            usar ahora. has_unused: tiene un cupón que nunca usó, vencido o no.
            has_expired_unused: dejó vencer un cupón sin usarlo. has_used: usó
            un cupón en una compra. has_received: recibió un cupón.
            has_not_received: nunca recibió un cupón.
        source:
          type: string
          enum:
            - cashback
            - any
            - flows
          default: cashback
          description: >-
            cashback: cupones generados por una compra (cashback o giftback,
            online o en la tienda física). any: todos los cupones que Bevits
            generó para el cliente. flows: solo los cupones de las
            automatizaciones en flow_ids.
        flow_ids:
          type: array
          items:
            type: string
            pattern: ^flw_[A-Za-z0-9_-]+$
          minItems: 1
          maxItems: 50
          description: >-
            Con source flows: automatizaciones que generan cupones, listadas en
            el catálogo.
        received_within_days:
          type: integer
          minimum: 1
          maximum: 3650
          description: Solo cupones generados en los últimos N días.
        expires_within_days:
          type: integer
          minimum: 1
          maximum: 365
          description: 'Con has_available: solo cupones que vencen en los próximos N días.'
  responses:
    CampaignEngagementSegment:
      description: Segmento por interacción creado.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CampaignEngagementSegment'
    InvalidBody:
      description: >-
        Cuerpo de la solicitud ausente, que no es un objeto JSON, o parámetro de
        ruta inválido.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Clave API ausente, inválida, expirada o revocada.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              type: authentication_error
              message: Invalid API key.
              request_id: req_07f6cdc3c20249d6afcd90b4
    WriteScopeRequired:
      description: La clave API no tiene el permiso 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: La Idempotency-Key ya se usó con otro cuerpo de solicitud.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ValidationError:
      description: Un parámetro no superó la validación.
      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: Límite de solicitudes superado.
      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: Error inesperado en el servidor.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  headers:
    RetryAfter:
      description: Segundos antes de volver a intentarlo.
      schema:
        type: integer
        minimum: 1
    RateLimitLimit:
      description: Límite total de la ventana actual.
      schema:
        type: integer
        example: 600
    RateLimitRemaining:
      description: Solicitudes restantes en la ventana actual.
      schema:
        type: integer
        example: 599
    RateLimitReset:
      description: Instante UTC en que termina la ventana actual.
      schema:
        type: string
        format: date-time
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: bvt_live_...
      description: Clave API creada en la configuración de la organización.

````

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