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

# Tiếp Nhận Sự Kiện

> Gửi các sự kiện sử dụng từ ứng dụng của bạn để theo dõi mức tiêu thụ của khách hàng và hỗ trợ lập hóa đơn.

Các sự kiện là nền tảng của lập hóa đơn dựa trên mức sử dụng. Gửi sự kiện khi các hành động có thể tính phí xảy ra, và các công tơ sẽ tổng hợp chúng thành các khoản phí.

<Card title="API Reference - Events Ingestion" icon="code" href="/api-reference/usage-events/ingest-events">
  Tài liệu API hoàn chỉnh với các ví dụ và mã phản hồi.
</Card>

## Cấu Trúc Sự Kiện

<Accordion title="Required Fields">
  <ParamField body="event_id" type="string" required>
    Định danh duy nhất. Sử dụng UUID hoặc kết hợp ID khách hàng + dấu thời gian + hành động.
  </ParamField>

  <ParamField body="customer_id" type="string" required>
    ID khách hàng Dodo Payments. Phải là khách hàng hợp lệ đang tồn tại.
  </ParamField>

  <ParamField body="event_name" type="string" required>
    Loại sự kiện khớp với tên sự kiện của đồng hồ đo của bạn (phân biệt chữ hoa chữ thường). Ví dụ: `api.call`, `image.generated`
  </ParamField>
</Accordion>

<Accordion title="Optional Fields">
  <ParamField body="timestamp" type="string">
    Dấu thời gian ISO 8601. Mặc định sử dụng giờ máy chủ nếu bỏ qua. Bao gồm để đảm bảo hóa đơn chính xác với các sự kiện trì hoãn/ghép.
  </ParamField>

  <ParamField body="metadata" type="object">
    Thuộc tính bổ sung để tổng hợp và lọc:

    * Giá trị số: `bytes`, `tokens`, `duration_ms`
    * Bộ lọc: `endpoint`, `method`, `quality`

    ```javascript theme={null}
    metadata: {
      endpoint: "/v1/orders",
      method: "POST",
      tokens: 1024
    }
    ```
  </ParamField>
</Accordion>

## Gửi Sự Kiện

<CodeGroup>
  ```javascript Single Event theme={null}
  await fetch('https://test.dodopayments.com/events/ingest', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.DODO_PAYMENTS_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      events: [{
        event_id: "api_call_1234",
        customer_id: "cus_abc123",
        event_name: "api.call",
        metadata: { endpoint: "/v1/orders" }
      }]
    })
  });
  ```

  ```javascript Batch Events theme={null}
  await fetch('https://test.dodopayments.com/events/ingest', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.DODO_PAYMENTS_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      events: [
        { event_id: "call_1", customer_id: "cus_abc", event_name: "api.call" },
        { event_id: "call_2", customer_id: "cus_abc", event_name: "api.call" },
        { event_id: "call_3", customer_id: "cus_abc", event_name: "api.call" }
      ]
    })
  });
  ```

  ```python Python theme={null}
  import requests

  requests.post(
      'https://test.dodopayments.com/events/ingest',
      headers={'Authorization': f'Bearer {api_key}', 'Content-Type': 'application/json'},
      json={'events': [{'event_id': 'call_1', 'customer_id': 'cus_abc', 'event_name': 'api.call'}]}
  )
  ```

  ```curl cURL theme={null}
  curl -X POST 'https://test.dodopayments.com/events/ingest' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{"events": [{"event_id": "call_1", "customer_id": "cus_abc", "event_name": "api.call"}]}'
  ```
</CodeGroup>

<Tip>
  Gom nhóm tối đa 1.000 sự kiện mỗi yêu cầu để có hiệu suất tốt hơn. API áp đặt giới hạn cứng là 1.000 sự kiện mỗi cuộc gọi.
</Tip>

## Mẫu Tiếp Nhận

Các mẫu sự kiện đã được chuẩn bị sẵn cho các trường hợp sử dụng phổ biến. Bắt đầu với một mẫu đã được chứng minh thay vì xây dựng từ đầu.

<CardGroup cols={2}>
  <Card title="LLM Blueprint" icon="brain-circuit" href="/developer-resources/ingestion-blueprints/llm">
    Theo dõi việc sử dụng token AI trên OpenAI, Anthropic, Groq, Gemini và hơn thế nữa.
  </Card>

  <Card title="API Gateway Blueprint" icon="cloud" href="/developer-resources/ingestion-blueprints/api-gateway">
    Đo lượng yêu cầu API với lọc đầu cuối và hỗ trợ giới hạn tốc độ.
  </Card>

  <Card title="Object Storage Blueprint" icon="box-archive" href="/developer-resources/ingestion-blueprints/object-storage">
    Theo dõi việc tải lên tệp và mức tiêu thụ lưu trữ cho dịch vụ lưu trữ đám mây.
  </Card>

  <Card title="Stream Blueprint" icon="tower-broadcast" href="/developer-resources/ingestion-blueprints/stream">
    Đo băng thông truyền phát cho video, âm thanh và dữ liệu thời gian thực.
  </Card>

  <Card title="Time Range Blueprint" icon="clock" href="/developer-resources/ingestion-blueprints/time-range">
    Hóa đơn theo thời gian trôi qua cho các hàm serverless và phiên bản tính toán.
  </Card>

  <Card title="View All Blueprints" icon="copy" href="/features/usage-based-billing/ingestion-blueprints">
    Xem tất cả các bản mẫu có sẵn cùng hướng dẫn triển khai chi tiết.
  </Card>
</CardGroup>

## Thực Hành Tốt Nhất

<AccordionGroup>
  <Accordion title="Use Unique Event IDs">
    Sử dụng ID xác định để tránh trùng lặp: `${customerId}_${action}_${timestamp}`
  </Accordion>

  <Accordion title="Implement Retries">
    Thử lại khi gặp lỗi 5xx với đệm tăng theo cấp số nhân. Không thử lại lỗi 4xx.
  </Accordion>

  <Accordion title="Include Timestamps">
    Bỏ qua đối với các sự kiện thời gian thực. Bao gồm đối với các sự kiện trì hoãn/ghép để đảm bảo độ chính xác.
  </Accordion>

  <Accordion title="Monitor Delivery">
    Theo dõi tỷ lệ thành công và đưa các sự kiện thất bại vào hàng đợi để thử lại.
  </Accordion>
</AccordionGroup>

## Khắc Phục Sự Cố

<AccordionGroup>
  <Accordion title="Events not appearing">
    * Tên sự kiện phải khớp chính xác với đồng hồ đo (phân biệt chữ hoa chữ thường)
    * ID khách hàng phải tồn tại
    * Kiểm tra xem các bộ lọc của đồng hồ đo có đang loại trừ sự kiện không
    * Xác minh dấu thời gian gần đây
  </Accordion>

  <Accordion title="Authentication errors (401)">
    Xác minh khóa API đúng và sử dụng định dạng: `Bearer YOUR_API_KEY`
  </Accordion>

  <Accordion title="Validation errors (400)">
    Đảm bảo tất cả các trường bắt buộc đều có: `event_id`, `customer_id`, `event_name`
  </Accordion>

  <Accordion title="Metadata not aggregating">
    * Các khóa metadata phải khớp chính xác với "Thuộc tính vượt quá" của đồng hồ đo
    * Sử dụng số, không phải chuỗi: `tokens: 150` chứ không phải `tokens: "150"`
  </Accordion>
</AccordionGroup>

## Các Bước Tiếp Theo

<CardGroup cols={2}>
  <Card title="Create Meters" icon="sliders" href="/features/usage-based-billing/meters">
    Xác định cách các sự kiện của bạn được tổng hợp thành các đơn vị tính phí với bộ lọc và hàm tổng hợp.
  </Card>

  <Card title="Ingestion Blueprints" icon="copy" href="/features/usage-based-billing/ingestion-blueprints">
    Sử dụng các bản mẫu sẵn sàng cho các trường hợp phổ biến như theo dõi LLM, cổng API và lưu trữ.
  </Card>

  <Card title="Complete Tutorial" icon="code" href="/developer-resources/usage-based-billing-build-ai-image-generator">
    Xây dựng một trình tạo hình ảnh AI đầy đủ với thanh toán theo mức sử dụng từ đầu.
  </Card>

  <Card title="API Reference" icon="terminal" href="/api-reference/usage-events/ingest-events">
    Tài liệu API hoàn chỉnh với tất cả tham số, mã phản hồi và kiểm tra tương tác.
  </Card>
</CardGroup>