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

# 事件摄取

> 从您的应用程序发送使用事件，以跟踪客户消费并支持计费。

事件是基于使用的计费的基础。当可计费操作发生时发送事件，计量器将其汇总为费用。

<Card title="API Reference - Events Ingestion" icon="code" href="/api-reference/usage-events/ingest-events">
  完整的 API 文档，包含示例和响应代码。
</Card>

## 事件结构

<Accordion title="Required Fields">
  <ParamField body="event_id" type="string" required>
    唯一标识符。使用 UUID 或组合客户 ID + 时间戳 + 操作。
  </ParamField>

  <ParamField body="customer_id" type="string" required>
    Dodo Payments 客户 ID。必须为有效的现有客户。
  </ParamField>

  <ParamField body="event_name" type="string" required>
    与您的计量器事件名称相匹配的事件类型（区分大小写）。示例：`api.call`、`image.generated`
  </ParamField>
</Accordion>

<Accordion title="Optional Fields">
  <ParamField body="timestamp" type="string">
    ISO 8601 时间戳。如省略则默认使用服务器时间。对于延迟/批量事件请务必包含，以确保计费准确。
  </ParamField>

  <ParamField body="metadata" type="object">
    用于聚合和过滤的附加属性：

    * 数值：`bytes`、`tokens`、`duration_ms`
    * 过滤器：`endpoint`、`method`、`quality`

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

## 发送事件

<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>
  每次请求最多可批量处理 1,000 个事件，以提高性能。API 强制执行每次调用 1,000 个事件的硬限制。
</Tip>

## 摄取蓝图

适用于常见用例的现成事件模式。使用经过验证的蓝图开始，而不是从头开始构建。

<CardGroup cols={2}>
  <Card title="LLM Blueprint" icon="brain-circuit" href="/developer-resources/ingestion-blueprints/llm">
    跟踪 OpenAI、Anthropic、Groq、Gemini 等平台的 AI 令牌使用情况。
  </Card>

  <Card title="API Gateway Blueprint" icon="cloud" href="/developer-resources/ingestion-blueprints/api-gateway">
    通过端点过滤和速率限制支持对 API 请求进行计量。
  </Card>

  <Card title="Object Storage Blueprint" icon="box-archive" href="/developer-resources/ingestion-blueprints/object-storage">
    跟踪云存储服务的文件上传和存储消耗情况。
  </Card>

  <Card title="Stream Blueprint" icon="tower-broadcast" href="/developer-resources/ingestion-blueprints/stream">
    衡量视频、音频和实时数据的流式带宽。
  </Card>

  <Card title="Time Range Blueprint" icon="clock" href="/developer-resources/ingestion-blueprints/time-range">
    按运行时间为无服务器函数和计算实例计费。
  </Card>

  <Card title="View All Blueprints" icon="copy" href="/features/usage-based-billing/ingestion-blueprints">
    查看所有可用蓝图及详细实现指南。
  </Card>
</CardGroup>

## 最佳实践

<AccordionGroup>
  <Accordion title="Use Unique Event IDs">
    使用确定性 ID 防止重复：`${customerId}_${action}_${timestamp}`
  </Accordion>

  <Accordion title="Implement Retries">
    在遇到 5xx 错误时使用指数退避重试。不要对 4xx 错误重试。
  </Accordion>

  <Accordion title="Include Timestamps">
    实时事件可省略。对于延迟/批量事件请包含，以确保准确性。
  </Accordion>

  <Accordion title="Monitor Delivery">
    跟踪成功率并将失败事件排队以便重试。
  </Accordion>
</AccordionGroup>

## 故障排除

<AccordionGroup>
  <Accordion title="Events not appearing">
    * 事件名称必须与计量器完全匹配（区分大小写）
    * 客户 ID 必须存在
    * 检查计量器过滤器是否排除了事件
    * 确认时间戳是最近的
  </Accordion>

  <Accordion title="Authentication errors (401)">
    验证 API 密钥是否正确并使用格式：`Bearer YOUR_API_KEY`
  </Accordion>

  <Accordion title="Validation errors (400)">
    确保所有必填字段都已提供：`event_id`、`customer_id`、`event_name`
  </Accordion>

  <Accordion title="Metadata not aggregating">
    * 元数据键必须与计量器的“Over Property”完全一致
    * 使用数字，而非字符串：`tokens: 150`，而不是 `tokens: "150"`
  </Accordion>
</AccordionGroup>

## 下一步

<CardGroup cols={2}>
  <Card title="Create Meters" icon="sliders" href="/features/usage-based-billing/meters">
    使用过滤器和聚合函数定义事件如何汇总为可计费数量。
  </Card>

  <Card title="Ingestion Blueprints" icon="copy" href="/features/usage-based-billing/ingestion-blueprints">
    使用现成蓝图处理常见用例，如 LLM 跟踪、API 网关和存储。
  </Card>

  <Card title="Complete Tutorial" icon="code" href="/developer-resources/usage-based-billing-build-ai-image-generator">
    从零开始构建一个带有基于使用量计费的完整 AI 图像生成器。
  </Card>

  <Card title="API Reference" icon="terminal" href="/api-reference/usage-events/ingest-events">
    完整的 API 文档，包含所有参数、响应代码和交互式测试。
  </Card>
</CardGroup>