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

> Guarda condiciones como un segmento por filtros, como crear un segmento a partir de los filtros en la pantalla de Clientes. El segmento siempre está actualizado: se calcula de nuevo cada vez que se lee o se usa en un envío, así que quien usa su cashback (giftback) sale y quien recibe uno nuevo entra. No se envía nada: el segmento solo se convierte en público cuando una persona lo elige en una campaña. Si el nombre ya está en uso, Bevits agrega un número al final. Revisa el conteo antes con POST /v1/segment-builder/preview. Exige una clave API con el permiso write.



## OpenAPI

````yaml /openapi.es.json post /v1/segments
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:
    post:
      tags:
        - Segmentos
      summary: Crear segmento por filtros
      description: >-
        Guarda condiciones como un segmento por filtros, como crear un segmento
        a partir de los filtros en la pantalla de Clientes. El segmento siempre
        está actualizado: se calcula de nuevo cada vez que se lee o se usa en un
        envío, así que quien usa su cashback (giftback) sale y quien recibe uno
        nuevo entra. No se envía nada: el segmento solo se convierte en público
        cuando una persona lo elige en una campaña. Si el nombre ya está en uso,
        Bevits agrega un número al final. Revisa el conteo antes con POST
        /v1/segment-builder/preview. Exige una clave API con el permiso write.
      operationId: createSegment
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSegmentRequest'
            example:
              name: Giftback que vence en 7 días
              description: >-
                Giftback para usar que vence esta semana, con R$ 500 o más en
                compras
              match: all
              conditions:
                - kind: coupon
                  status: has_available
                  source: cashback
                  expires_within_days: 7
                - kind: field
                  field: totalSpentInCents
                  operator: gte
                  value: 50000
      responses:
        '201':
          $ref: '#/components/responses/SegmentCreated'
        '400':
          $ref: '#/components/responses/InvalidBody'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/WriteScopeRequired'
        '409':
          $ref: '#/components/responses/IdempotencyConflict'
        '422':
          $ref: '#/components/responses/SegmentValidationError'
        '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:
    CreateSegmentRequest:
      type: object
      required:
        - name
        - conditions
      properties:
        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
        match:
          $ref: '#/components/schemas/SegmentMatch'
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/SegmentCondition'
          minItems: 1
          maxItems: 30
          description: >-
            Condiciones del catálogo de filtros (GET
            /v1/segment-builder/catalog). Hasta 30.
        operation_id:
          $ref: '#/components/schemas/OperationId'
    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'
    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.
    SegmentWrite:
      type: object
      required:
        - object
        - segment
        - next_step
      properties:
        object:
          type: string
          const: segment_write
        segment:
          $ref: '#/components/schemas/Segment'
        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.
    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.'
    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
    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}$
  responses:
    SegmentCreated:
      description: Segmento creado.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SegmentWrite'
    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'
    SegmentValidationError:
      description: >-
        Alguna condición o campo fue rechazado, por ejemplo un operador que no
        aplica al campo o un segmento RFM. El mensaje dice qué corregir y las
        opciones válidas, y error.param indica el campo.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    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.