# Registrar uso del producto

POST `https://api.bydomu.com/v1/usage/events`

This reference is generated from the API’s code, so descriptions are in Spanish. Names, parameters and examples are the same in every language.

Un evento de uso de tu producto (una función que se usó, un límite que se alcanzó, etc.), del mismo tipo que `Domu('track', …)` en el widget. Identifica a quién pertenece con `contactId`, `externalId` (el id de tu usuario en tu sistema) o `email`. Se agrega por contacto y por día para la ficha y el riesgo de cancelación; el detalle se retiene un tiempo acotado. Responde `200` aunque no encuentre el contacto.

Permission required

`contacts:write`

Required header

`X-API-Key` · secret key

Access level

Level 3 · with support review

## Headers

1 · all optional

`Idempotency-Key` string · optional

Clave única de la operación (8-128 caracteres de `[a-zA-Z0-9._:-]`). Un reintento con la misma clave y el mismo cuerpo devuelve la respuesta original sin repetir la operación. Vive 24 horas. 8–128 chars

## Body (JSON)

9 · 1 required

`name` string · **required**

1–60 chars

`label` string · optional

≤ 80 chars

`props` object · optional

`contactId` string · optional

`externalId` string · optional

≤ 200 chars

`email` string · optional

email

**See the other 3 parameters**

`companyId` string · optional

≤ 200 chars

`actorLabel` string · optional

≤ 120 chars

`occurredAt` string · optional

date-time

## Response 200

`SuccessFlag` · 1 fields

**`data` La operación se aceptó.**

`success` boolean true

## Possible errors

shaped as `{ "error": { "code", "message" } }`

- **400** Datos inválidos: el cuerpo o la query no cumplen el esquema, o `Idempotency-Key` está mal formada.
- **401** UNAUTHORIZED
- **402** PAYMENT_REQUIRED
- **403** FORBIDDEN
- **409** DUPLICATE
- **429** RATE_LIMITED
- **500** INTERNAL_ERROR

cURL:

```bash
curl -X POST "https://api.bydomu.com/v1/usage/events" \
  -H "X-API-Key: $BYDOMU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "nomina_liquidada",
  "label": "Liquidó la nómina",
  "props": {
    "empleados": 142
  },
  "externalId": "user_8841"
}'
```

JavaScript:

```js
import { ByDomu } from "@bydomu/sdk";

const bydomu = new ByDomu({
  apiKey: process.env.BYDOMU_API_KEY,
});

const { data } = await bydomu.events.trackUsage({
  "name": "nomina_liquidada",
  "label": "Liquidó la nómina",
  "props": {
    "empleados": 142
  },
  "externalId": "user_8841"
});
```

Python:

```python
import os, requests

r = requests.post(
    "https://api.bydomu.com/v1/usage/events",
    headers={"X-API-Key": os.environ["BYDOMU_API_KEY"]},
    json={
        "name": "nomina_liquidada",
        "label": "Liquidó la nómina",
        "props": {
            "empleados": 142
        },
        "externalId": "user_8841"
    }
)
data = r.json()
```

**Response · 200 · example**

```json
{
  "data": {
    "success": true
  }
}
```