Clientes (companyUsers)

Un companyUser es un cliente de tu empresa: la persona a la que se le factura y que paga. Internamente Ripei separa la persona (User, identificada por su email) de su relación con tu empresa (CompanyUser, con rol y grupo).

Depende de: grupo (para roles de grupo). Lo necesitan: suscripciones y facturas.

Crear un cliente


POST /company-user/company

Scope requerido: company-user.create

Cuerpo

Campo	Tipo	Requerido	Descripción
`email`	string	Sí*	Email del cliente. Es la clave de identidad de la persona (ver nota abajo).
`firstName`	string	Sí	Nombre.
`lastName`	string	Sí	Apellido.
`phone`	string	No	Teléfono en formato internacional (`+58…`). Necesario para pagos y recordatorios por WhatsApp.
`role`	string	Sí	`GROUP_REPRESENTATIVE` (representante que paga) o `GROUP_MEMBER` (miembro).
`groupId`	número	Sí	Grupo al que pertenece el cliente.
`documentId`	string	No	Cédula/documento.
`documentType`	string	No	`V`, `E`, `J`, `G`.
`metadata`	objeto	No	Pares clave/valor libres para tu integración (ej. tu ID interno del cliente). Se incluyen aplanados en los webhooks.

* Se exige al menos uno de email, firstName, lastName, pero en integraciones siempre envía el email — es lo que evita duplicados.

Reutilización por email. Si ya existe una persona con ese email en la plataforma (por ejemplo, porque es cliente de otra empresa que usa Ripei), no se crea una persona nueva: se asocia la existente a tu empresa como un nuevo companyUser. El matching de email ignora mayúsculas y espacios (Juan@Gmail.com ≡ juan@gmail.com). Los datos de la persona existente (nombre, teléfono) no se sobreescriben con los que envíes.

Si el cliente ya tiene un registro activo en ese mismo grupo, la API responde RIPEI-USER-005 — no lo crees dos veces. Si estaba inactivo, se reactiva automáticamente con el rol que envíes.

Ejemplo


curl -X POST https://api.qa.pagosripei.com/company-user/company \
  -H "Authorization: Bearer $RIPEI_TOKEN" \
  -H "company: 42" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "juan.perez@gmail.com",
    "firstName": "Juan",
    "lastName": "Pérez",
    "phone": "+584141234567",
    "role": "GROUP_REPRESENTATIVE",
    "groupId": 15,
    "metadata": { "idClienteERP": "CLI-00042" }
  }'

Respuesta `201`


{
  "id": 4275,
  "role": "GROUP_REPRESENTATIVE",
  "status": "ACTIVE",
  "user": {
    "firstName": "Juan",
    "lastName": "Pérez",
    "email": "juan.perez@gmail.com"
  }
}

Guarda el id (el ID del companyUser, no el de la persona) — es el que usan suscripciones y facturas.

Errores

Código	Causa
`RIPEI-USER-001`	No enviaste email, nombre ni apellido.
`RIPEI-USER-004`	Falta el `groupId` — es obligatorio.
`RIPEI-USER-005`	El cliente ya tiene un registro activo en ese grupo.