# Registrar uso del producto

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

Esta referência é gerada a partir do código da API, por isso as descrições estão em espanhol. Nomes, parâmetros e exemplos são iguais em qualquer idioma.

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.

Permissão pedida

`contacts:write`

Cabeçalho obrigatório

`X-API-Key` · chave secreta

Nível de acesso

Nível 3 · com revisão do suporte

## Cabeçalhos

1 · todos opcionais

`Idempotency-Key` string · opcional

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

## Corpo (JSON)

9 · 1 obrigatórios

`name` string · **obrigatório**

1–60 chars

`label` string · opcional

≤ 80 chars

`props` object · opcional

`contactId` string · opcional

`externalId` string · opcional

≤ 200 chars

`email` string · opcional

email

**Ver os outros 3 parâmetros**

`companyId` string · opcional

≤ 200 chars

`actorLabel` string · opcional

≤ 120 chars

`occurredAt` string · opcional

date-time

## Resposta 200

`SuccessFlag` · 1 campos

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

`success` boolean true

## Erros possíveis

com a forma `{ "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()
```

**Resposta · 200 · exemplo**

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