Tiếp Nhận Sự Kiệ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í.

API Reference — Events Ingestion

Tài liệu API đầy đủ kèm ví dụ và mã phản hồi.

Cấu Trúc Sự Kiện

Required Fields

string

bắt buộc

Mã định danh duy nhất của event, được dùng để phát hiện các event trùng lặp khi retry. Hãy tạo mã này từ hành động, chẳng hạn như customer ID + action + timestamp, để event được retry vẫn giữ nguyên ID. Việc tạo một UUID ngẫu nhiên mới cho mỗi lần retry sẽ khiến cùng một event bị tính hai lần.

string

bắt buộc

Customer ID của Dodo Payments. Phải là một customer hiện có và hợp lệ.

string

bắt buộc

Loại event khớp với tên event của meter (phân biệt chữ hoa chữ thường). Ví dụ: api.call, image.generated.

Optional Fields

string

Timestamp ISO 8601 (UTC). Nếu bỏ qua, mặc định sử dụng thời gian hiện tại của server. Hãy thêm timestamp để tính billing chính xác đối với các event bị trì hoãn hoặc event theo batch. Các timestamp cũ hơn 1 giờ hoặc sớm hơn 5 phút so với thời điểm hiện tại sẽ bị từ chối.

object

Các thuộc tính bổ sung để tổng hợp và lọc. Tối đa 50 khóa; mỗi khóa có thể dài tối đa 100 ký tự và mỗi giá trị tối đa 500 ký tự.

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

metadata: {
  endpoint: "/v1/orders",
  method: "POST",
  tokens: 1024
}

Gửi Sự Kiện

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" }
    }]
  })
});

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" }
    ]
  })
});

import os
import requests

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

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"}]}'

Gộp tối đa 1.000 event trong mỗi request để cải thiện hiệu suất. API áp dụng giới hạn cứng là 1.000 event cho mỗi request.

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.

LLM Blueprint

Theo dõi việc sử dụng token AI trên OpenAI, Anthropic, Groq, Gemini và hơn thế nữa.

API Gateway Blueprint

Đo lượng yêu cầu API với lọc đầu cuối và hỗ trợ giới hạn tốc độ.

Object Storage Blueprint

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.

Stream Blueprint

Đo băng thông truyền phát cho video, âm thanh và dữ liệu thời gian thực.

Time Range Blueprint

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.

View All 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.

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

Use Unique Event IDs

Sử dụng ID xác định để ngăn bản sao: ${customerId}_${action}_${timestamp}.

Implement Retries

Retry khi gặp lỗi 5xx và lỗi 429 với exponential backoff. Không retry các lỗi 4xx khác.

Include Timestamps

Bỏ qua timestamp đối với các event theo thời gian thực. Thêm timestamp cho các event bị trì hoãn hoặc event theo batch để đảm bảo độ chính xác.

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.

Khắc Phục Sự Cố

Events not appearing

Tên event phải khớp chính xác với meter (phân biệt chữ hoa chữ thường)
Customer ID phải tồn tại trong account của bạn
Kiểm tra để đảm bảo các filter của meter không loại trừ event
Xác minh timestamp vẫn còn mới

Authentication errors (401)

Xác minh API key là chính xác và sử dụng định dạng: Bearer YOUR_API_KEY.

Validation errors (400)

Đảm bảo tất cả các field bắt buộc đều có mặt: event_id, customer_id, event_name.

Metadata not aggregating

Các key trong metadata phải khớp chính xác với “Over Property” của meter
Sử dụng số, không sử dụng chuỗi: tokens: 150 thay vì tokens: "150"

Các Bước Tiếp Theo

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

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

Complete Tutorial

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.

API Reference

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.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

API Reference — Events Ingestion

Cấu Trúc Sự Kiện

Gửi Sự Kiện

Mẫu Tiếp Nhận

LLM Blueprint

API Gateway Blueprint

Object Storage Blueprint

Stream Blueprint

Time Range Blueprint

View All Blueprints

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

Khắc Phục Sự Cố

Các Bước Tiếp Theo

Create Meters

Ingestion Blueprints

Complete Tutorial

API Reference

API Reference — Events Ingestion

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

​Gửi Sự Kiện

​Mẫu Tiếp Nhận

LLM Blueprint

API Gateway Blueprint

Object Storage Blueprint

Stream Blueprint

Time Range Blueprint

View All Blueprints

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

​Khắc Phục Sự Cố

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

Create Meters

Ingestion Blueprints

Complete Tutorial

API Reference

Cấu Trúc Sự Kiện

Gửi Sự Kiện

Mẫu Tiếp Nhận

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

Khắc Phục Sự Cố

Các Bước Tiếp Theo