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