Eventos de uso

Descripcion

Registra uno o varios eventos de uso. Cada evento es append-only e idempotente por contractId + eventId.

Se aceptan aliases para facilitar integraciones:

• external_id -> eventId
• event_time -> occurredAt
• service_code -> metric
• contractRef + empresaId -> alternativa a contractId

Endpoint

• Metodo: POST
• Path: /api/v1/usage-events

Headers

• Authorization: Bearer <JWT>
• Content-Type: application/json
• Idempotency-Key (opcional)

Body

Se permite enviar un objeto o un array de eventos.

Campos requeridos:

• contractId (int) o contractRef + empresaId
• eventId (string) o external_id
• occurredAt (ISO8601) o event_time
• quantity (number)
• unit (string)
• metric (string) o service_code

Campos opcionales:

• description (string)
• metadata (object)

Respuestas

• 201: eventos registrados
• 400: error de validacion
• 404: contrato no encontrado

Recomendaciones

• Generar eventId unico desde el sistema externo.
• Reintentar con el mismo eventId ante timeout (no duplica).
• Usar contractRef si no se conoce el ID interno.