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

# واجهة أحداث الخادم بالدفعات — POST /server-events/batch

> أرسل ما يصل إلى 100 حدث تحويل من الخادم لديك في طلب موثّق واحد. ويُنصح بهذه الطريقة مع الإرسال عبر الطوابير ومع الخوادم ذات الحجم الكبير.

استخدم نقطة وصول الدفعات متى كان لديك أكثر من حدث لإرساله: فهي تقلل عبء HTTP، وهي الأنسب للبنى القائمة على العمال أو الطوابير.

استخدم مفتاح API المخصص للموقع الذي أنشأته من لوحة تحكم موقع التتبع لديك: **التحليلات ← تتبع التحويلات ← إعداد تتبع التحويلات**، ثم **إعداد التتبع ← تتبع عبر API** في موقعك.

راجع [إرسال أحداث الخادم](/ar/conversion-tracking/server/send-events#sending-a-batch-of-events) للاطلاع على مثال كامل لطلب بالدفعات.


## OpenAPI

````yaml POST /server-events/batch
openapi: 3.1.0
info:
  title: Scanova Conversion Tracking API
  description: Server-side conversion event ingestion API for Scanova tracking sites.
  version: 1.0.0
servers:
  - url: https://track.scanova.io
    description: Production
security: []
tags:
  - name: Server Events
    description: Authenticated server-side conversion/event ingestion
paths:
  /server-events/batch:
    post:
      tags:
        - Server Events
      summary: Send batch of server-side events
      description: >-
        Send multiple server-side events in a single request. Maximum 100 events
        per batch.
      operationId: serverEventBatch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchServerEventRequest'
      responses:
        '200':
          description: Batch processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchServerEventResponse'
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Invalid API key or unauthorized site_id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    BatchServerEventRequest:
      type: object
      required:
        - events
      properties:
        events:
          type: array
          minItems: 1
          maxItems: 100
          items:
            $ref: '#/components/schemas/ServerEventRequest'
    BatchServerEventResponse:
      type: object
      required:
        - success
        - accepted
        - rejected
        - event_ids
      properties:
        success:
          type: boolean
        accepted:
          type: integer
        rejected:
          type: integer
        event_ids:
          type: array
          items:
            type: string
            format: uuid
    ErrorResponse:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: boolean
          example: true
        code:
          type: string
          example: RATE_LIMIT_EXCEEDED
        message:
          type: string
          example: Too many requests. Retry after 60 seconds.
    ServerEventRequest:
      type: object
      required:
        - site_id
        - event_name
      properties:
        site_id:
          type: string
          minLength: 1
          maxLength: 64
          description: Tracking site ID
        event_name:
          type: string
          minLength: 1
          maxLength: 64
          description: Event name (normalized to lowercase/underscore by API)
        scan_session_id:
          type: string
          format: uuid
          description: QR scan session id from scnv redirect
        event_id:
          type: string
          format: uuid
          description: Unique event ID for deduplication
        event_time:
          type: string
          format: date-time
          description: Event occurrence time
        user_identifiers:
          $ref: '#/components/schemas/UserIdentifiers'
        conversion_value:
          $ref: '#/components/schemas/ConversionValue'
        properties:
          type: object
          additionalProperties: true
          description: >-
            Custom properties. Max serialized size 10KB. Do not include raw
            email addresses.
        consent:
          type: string
          nullable: true
          enum:
            - granted
            - denied
            - pending
          description: Consent signal propagated from browser-side tracking
      example:
        site_id: site_abc123
        event_name: purchase
        scan_session_id: 550e8400-e29b-41d4-a716-446655440000
        conversion_value:
          amount: 99.99
          currency: USD
        user_identifiers:
          email_hash: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
          external_id: user_12345
        properties:
          order_id: order_789
          product_ids:
            - prod_1
            - prod_2
    UserIdentifiers:
      type: object
      properties:
        email_hash:
          type: string
          minLength: 64
          maxLength: 64
          description: SHA-256 hash of normalized lowercase email
        phone_hash:
          type: string
          minLength: 64
          maxLength: 64
          description: SHA-256 hash of normalized E.164 phone number
        external_id:
          type: string
          maxLength: 128
          description: Your internal user ID
    ConversionValue:
      type: object
      required:
        - amount
      properties:
        amount:
          type: number
          minimum: 0
          description: Conversion amount
        currency:
          type: string
          minLength: 3
          maxLength: 3
          default: USD
          description: ISO 4217 currency code
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        Site-scoped server API key generated from Dashboard > Analytics >
        Conversion Tracking > Script/API > API tab

````