Trinks
Trinks es el NicoApp de integración con la plataforma de agendamiento Trinks, usada por salones de belleza, barberías y clínicas de estética. Con él, tu flujo crea, edita, consulta y cancela citas.
Nota
Disponible en la pestaña de NicoApps. Base de la integración: API oficial de Trinks (api.trinks.com), documentada en trinks.readme.io.
Autenticación
- Accede a “Minha área pessoal”
- Accede a “Meu Cadastro”
- Accede a tu registro en Trinks a través de este enlace (requiere inicio de sesión).
- Navega hasta la sección Token de API Pessoal y haz clic en Gerar token.
- Copia el token mostrado e insértalo en el campo Token (X-Api-Key) del NicoApp.
Además del token, la app también exige el header estabelecimentoId — el ID del establecimiento en Trinks al que ese token tiene acceso. Sin él, Trinks rechaza la solicitud incluso con el token válido.
Nota
Cómo obtener el estabelecimentoId: con el token ya generado, llama a
GET https://api.trinks.com/v1/estabelecimentos (header X-Api-Key con el token) — ese punto final lista todos los establecimientos a los que el token tiene acceso. Toma el campo id del establecimiento deseado en la respuesta e indícalo en el campo estabelecimentoId en la instalación del NicoApp. Si el token tiene acceso a un único establecimiento (el caso más común), será el único elemento de la lista.Atención
Los dos campos — Token (X-Api-Key) y estabelecimentoId — son obligatorios en toda llamada de la API. Si una acción falla con error de autorización/establecimiento no encontrado, revisa los dos valores en la configuración de la app.
Límites de Solicitudes
La API de Trinks tiene límites de solicitudes por minuto y por mes, aplicados por clave (token) de API.
Por minuto: 60 solicitudes
Por mes: 5000 solicitudes
Al superar cualquiera de los dos límites, Trinks responde con HTTP 429 (Too Many Requests) hasta que la ventana se renueve (el próximo minuto o el próximo mes). La documentación no indica límites diferentes por plan contratado — para volúmenes mayores, es necesario negociar directamente con el soporte de Trinks.
Nota
Ahorra solicitudes: evita consultar el catálogo (servicios/profesionales) en cada mensaje — esos datos cambian poco; guarda los IDs en variables del bot siempre que sea posible.
Qué hace el NicoApp
La app tiene 20 acciones, organizadas en 6 grupos. Todas usan Basic/API Key (X-Api-Key + estabelecimentoId) y, cuando Trinks rechaza la operación, devuelven el mensaje de error real de la API por el camino de error del bloque.
Citas
Acción
Qué hace
Punto final
Entradas principales
Salidas
Crear Cita
Crea una nueva cita de servicio con un profesional
POST /v1/agendamentos/
ID del Servicio, ID del Cliente, ID del Profesional, Duración (min), Valor, Fecha/Hora de Inicio
ID de la Cita
Editar Cita
Actualiza los datos de una cita existente
PUT /v1/agendamentos/{id}
ID de la Cita + los mismos campos de Crear, más Observaciones
ID de la Cita
Editar Estado
Cambia el estado de una cita (ej.: confirmado, atendido)
PATCH /v1/agendamentos/{id}/status/{status}
ID de la Cita, Estado + los mismos datos de la cita
ID de la Cita
Cancelar Cita
Cancela una cita (punto final dedicado, estado "cancelado")
PATCH /v1/agendamentos/{id}/status/cancelado
ID de la Cita; Motivo y Quién Canceló (fijos en el flujo)
Confirmación de cancelación
Obtener Agenda
Lista o consulta las citas de un cliente en un período
GET /v1/agendamentos
ID del Cliente, Fecha de Inicio, Fecha de Fin, tamaño de página (todos opcionales)
Citas Encontradas (JSON)
Listar Horarios
Lista los horarios de los profesionales en una fecha, filtrando por servicio/profesional
GET /v1/agendamentos/profissionais/{data}
Fecha (obligatoria); ID del Servicio, ID del Profesional (opcionales)
Horarios Encontrados (JSON), Total Encontrado
Clientes
Acción
Qué hace
Punto final
Entradas principales
Salidas
Listar Clientes
Busca clientes por nombre, CPF, e-mail o teléfono
GET /v1/clientes
Nombre, CPF, E-mail, Teléfono (al menos uno)
Clientes Encontrados (JSON, con teléfonos y detalles del 1.º resultado)
Crear Cliente
Registra un nuevo cliente en Trinks
POST /v1/clientes
Nombre (obligatorio); E-mail, CPF, Sexo, Observaciones, Código Externo, Teléfono
ID del Cliente
Actualizar Cliente
Actualiza los datos de un cliente existente
PUT /v1/clientes/{id}
ID del Cliente + campos a actualizar (solo se envían los completados)
ID del Cliente
Eliminar Cliente
Elimina un cliente del registro
DELETE /v1/clientes/{id}
ID del Cliente
—
Etiquetas del Cliente
Acción
Qué hace
Punto final
Entradas principales
Salidas
Agregar Etiqueta Cliente
Vincula una etiqueta a un cliente
POST /v1/clientes/{id}/etiquetas/{etiquetaId}
ID del Cliente, ID de la Etiqueta
—
Eliminar Etiqueta Cliente
Elimina una etiqueta de un cliente
DELETE /v1/clientes/{id}/etiquetas/{etiquetaId}
ID del Cliente, ID de la Etiqueta
—
Obtener Etiquetas del Cliente
Lista las etiquetas vinculadas a un cliente
GET /v1/clientes/{id}/etiquetas
ID del Cliente
Etiquetas Encontradas (JSON)
Teléfonos del Cliente
Acción
Qué hace
Punto final
Entradas principales
Salidas
Agregar teléfono del cliente
Agrega un teléfono al registro del cliente (separa DDD/número automáticamente)
POST /v1/clientes/{id}/telefones
ID del Cliente, Teléfono completo, Tipo de Teléfono
ID del Cliente
Obtener teléfonos del cliente
Lista los teléfonos registrados de un cliente
GET /v1/clientes/{id}/telefones
ID del Cliente
Teléfonos Encontrados (JSON)
Eliminar teléfono del cliente
Elimina un teléfono del registro del cliente
DELETE /v1/clientes/{id}/telefones/{telefoneId}
ID del Cliente, ID del Teléfono
—
Créditos y Vales de Regalo
Acción
Qué hace
Punto final
Entradas principales
Salidas
Agregar un crédito de cliente
Registra un crédito en la cuenta del cliente
POST /v1/clientes/{id}/creditos
ID del Cliente, Valor, Forma de Pago
Confirmación
Agregar vale de regalo a un cliente
Genera un vale de regalo para el cliente
POST /v1/clientes/{id}/valespresentes
ID del Cliente, Valor, Forma de Pago, Número del vale, Validez
Confirmación
Catálogo
Acción
Qué hace
Punto final
Entradas principales
Salidas
Listar Servicios
Lista los servicios registrados en el establecimiento, con paginación automática
GET /v1/servicos
Nombre, Categoría (opcionales)
Servicios Encontrados (JSON: id, nombre, descripción, categoría, duración, precio)
Listar Profesionales
Lista los profesionales del establecimiento, con paginación automática
GET /v1/profissionais
Nombre, Categoría (opcionales)
Profesionales Encontrados (JSON)
Consejos y observaciones
- Paginación automática: Listar Servicios y Listar Profesionales ya recorren todas las páginas de Trinks por sí solos (bucle interno por
page/totalPages), así que recibes la lista completa en una única llamada de la acción. - Teléfono completo en un solo campo: en los campos de teléfono (Crear Cliente, Agregar teléfono del cliente), indica el teléfono completo con DDD — la app separa DDD y número automáticamente (eliminando el DDI 55 cuando esté presente).
- IDs encadenados: el ID del Cliente sale de Crear/Listar Clientes y alimenta prácticamente todas las acciones de cliente (etiquetas, teléfonos, crédito, vale de regalo, cita). El ID de la Cita sale de Crear Cita y alimenta Editar, Editar Estado y Cancelar.
- Manejo de errores: cuando Trinks rechaza una operación (dato inválido, permiso insuficiente, límite de solicitudes alcanzado), la acción falla y devuelve el mensaje de error real de Trinks — usa el camino de error del bloque para tratarlo en el flujo.
- Estado de la cita: los valores aceptados por Editar Estado (y el estado fijo "cancelado" usado por Cancelar Cita) siguen los códigos definidos por Trinks — confirma los valores válidos en la documentación de referencia de Trinks antes de usarlos en producción.
- Ahorra solicitudes: con el límite de 60/min y 5000/mes por token, evita consultar el catálogo (servicios/profesionales) en cada mensaje — guarda los IDs en variables del bot siempre que sea posible.