Trinks
Esta página do wiki foi descontinuada e pode estar desatualizada. A documentação oficial e atualizada do NicoChat está em docs.nicochat.com/p/462-trinks. Consulte sempre o link acima — o conteúdo abaixo é mantido apenas como histórico.
O Trinks é o NicoApp de integração com a plataforma de agendamento Trinks, usada por salões de beleza, barbearias e clínicas de estética. Com ele, seu bot cria, edita, consulta e cancela agendamentos, gerencia o cadastro de clientes (dados, etiquetas, telefones, créditos e vales-presente) e consulta o catálogo de serviços e profissionais — tudo direto do fluxo do NicoChat.
Disponível na aba de NicoApps. Base da integração: API oficial Trinks (api.trinks.com), documentada em trinks.readme.io.
Autenticação
Acesse “Minha área pessoal”
Acesse “Meu Cadastro”
Acesse o seu cadastro no Trinks através deste link. (requer login)
Navegue até a seção Token de API Pessoal e então clique em Gerar token.
Copie o token exibido e insira no campo Token (X-Api-Key) do NicoApp.
Além do token, o app também exige o header estabelecimentoId — o ID do estabelecimento na Trinks ao qual esse token tem acesso. Sem ele, a Trinks recusa a requisição mesmo com o token válido.
Como obter o estabelecimentoId: com o token já gerado, chame GET https://api.trinks.com/v1/estabelecimentos (header X-Api-Key com o token) — esse endpoint lista todos os estabelecimentos aos quais o token tem acesso. Pegue o campo id do estabelecimento desejado na resposta e informe-o no campo estabelecimentoId na instalação do NicoApp. Se o token tiver acesso a um único estabelecimento (caso mais comum), será o único item da lista.
Os dois campos — Token (X-Api-Key) e estabelecimentoId — são obrigatórios em toda chamada da API. Se uma ação falhar com erro de autorização/estabelecimento não encontrado, confira os dois valores na configuração do app.
Limites de Requisição
A API da Trinks possui um limite de requisições por minuto e por mês, aplicado por chave (token) de API.
Por minuto: 60 requisições
Por mês: 5000 requisições
Ao ultrapassar qualquer um dos dois limites, a Trinks responde com HTTP 429 (Too Many Requests) até a janela ser renovada (o próximo minuto ou o próximo mês). A documentação não indica limites diferentes por plano contratado — para volumes maiores, é preciso negociar diretamente com o suporte Trinks.
Economize requisições: evite consultar o catálogo (serviços/profissionais) a cada mensagem — esses dados mudam pouco; guarde os IDs em variáveis do bot sempre que possível.
Fonte: https://trinks.readme.io/reference/limites-de-requisi%C3%A7%C3%A3o
O que o miniapp faz
O app tem 20 ações, organizadas em 6 grupos. Todas usam Basic/API Key (X-Api-Key + estabelecimentoId) e, quando a Trinks recusa a operação, devolvem a mensagem de erro real da API pelo caminho de erro do bloco.
Agendamentos
Ação | O que faz | Endpoint | Entradas principais | Saídas |
|---|---|---|---|---|
Criar Agendamento | Cria um novo agendamento de serviço com um profissional | POST /v1/agendamentos/ | ID do Serviço, ID do Cliente, ID do Profissional, Duração (min), Valor, Data/Hora de Início | ID do Agendamento |
Editar Agendamento | Atualiza os dados de um agendamento existente | PUT /v1/agendamentos/{id} | ID do Agendamento + mesmos campos de Criar, mais Observações | ID do Agendamento |
Editar Status Agendamento | Altera o status de um agendamento (ex.: confirmado, atendido) | PATCH /v1/agendamentos/{id}/status/{status} | ID do Agendamento, Status + mesmos dados do agendamento | ID do Agendamento |
Cancelar Agendamento | Cancela um agendamento (endpoint dedicado, status "cancelado") | PATCH /v1/agendamentos/{id}/status/cancelado | ID do Agendamento; Motivo e Quem Cancelou (fixos no fluxo) | Confirmação de cancelamento |
Obter Agendamento | Lista/consulta os agendamentos de um cliente num período | GET /v1/agendamentos | ID do Cliente, Data Início, Data Fim, tamanho de página (todos opcionais) | Agendamentos Encontrados (JSON) |
Listar Horários Disponíveis | Lista os horários dos profissionais numa data, filtrando por serviço/profissional | GET /v1/agendamentos/profissionais/{data} | Data (obrigatória); ID do Serviço, ID do Profissional (opcionais) | Horários Encontrados (JSON), Total Encontrado |
Clientes
Ação | O que faz | Endpoint | Entradas principais | Saídas |
|---|---|---|---|---|
Listar Clientes | Busca clientes por nome, CPF, e-mail ou telefone | GET /v1/clientes | Nome, CPF, E-mail, Telefone (ao menos um) | Clientes Encontrados (JSON, com telefones e detalhes do 1º resultado) |
Criar Cliente | Cadastra um novo cliente na Trinks | POST /v1/clientes | Nome (obrigatório); E-mail, CPF, Sexo, Observações, Código Externo, Telefone | ID do Cliente |
Atualizar Cliente | Atualiza os dados de um cliente existente | PUT /v1/clientes/{id} | ID do Cliente + campos a atualizar (só os preenchidos são enviados) | ID do Cliente |
Excluir Cliente | Remove um cliente do cadastro | DELETE /v1/clientes/{id} | ID do Cliente | — |
Etiquetas do Cliente
Ação | O que faz | Endpoint | Entradas principais | Saídas |
|---|---|---|---|---|
Adicionar Etiqueta Cliente | Vincula uma etiqueta a um cliente | POST /v1/clientes/{id}/etiquetas/{etiquetaId} | ID do Cliente, ID da Etiqueta | — |
Remover Etiqueta Cliente | Remove uma etiqueta de um cliente | DELETE /v1/clientes/{id}/etiquetas/{etiquetaId} | ID do Cliente, ID da Etiqueta | — |
Obter Etiquetas do Cliente | Lista as etiquetas vinculadas a um cliente | GET /v1/clientes/{id}/etiquetas | ID do Cliente | Etiquetas Encontradas (JSON) |
Telefones do Cliente
Ação | O que faz | Endpoint | Entradas principais | Saídas |
|---|---|---|---|---|
Adicionar telefone do cliente | Adiciona um telefone ao cadastro do cliente (separa DDD/número automaticamente) | POST /v1/clientes/{id}/telefones | ID do Cliente, Telefone completo, Tipo de Telefone | ID do Cliente |
Obter telefones do cliente | Lista os telefones cadastrados de um cliente | GET /v1/clientes/{id}/telefones | ID do Cliente | Telefones Encontrados (JSON) |
Deletar telefone do cliente | Remove um telefone do cadastro do cliente | DELETE /v1/clientes/{id}/telefones/{telefoneId} | ID do Cliente, ID do Telefone | — |
Créditos e Vale-presente
Ação | O que faz | Endpoint | Entradas principais | Saídas |
|---|---|---|---|---|
Adicionar um crédito cliente | Lança um crédito na conta do cliente | POST /v1/clientes/{id}/creditos | ID do Cliente, Valor, Forma de Pagamento | Confirmação |
Adicionar vale presente a um cliente | Gera um vale-presente para o cliente | POST /v1/clientes/{id}/valespresentes | ID do Cliente, Valor, Forma de Pagamento, Número do vale, Validade | Confirmação |
Catálogo
Ação | O que faz | Endpoint | Entradas principais | Saídas |
|---|---|---|---|---|
Listar Serviços | Lista os serviços cadastrados no estabelecimento, com paginação automática | GET /v1/servicos | Nome, Categoria (opcionais) | Serviços Encontrados (JSON: id, nome, descrição, categoria, duração, preço) |
Listar Profissionais | Lista os profissionais do estabelecimento, com paginação automática | GET /v1/profissionais | Nome, Categoria (opcionais) | Profissionais Encontrados (JSON) |
Dicas e observações
Paginação automática: Listar Serviços e Listar Profissionais já percorrem todas as páginas da Trinks sozinhos (loop interno por
page/totalPages), então você recebe a lista completa numa única chamada da ação.Telefone em uma peça só: nos campos de telefone (Criar Cliente, Adicionar telefone do cliente), informe o telefone completo com DDD — o app separa DDD e número automaticamente (removendo o DDI 55 quando presente).
IDs encadeados: o ID do Cliente sai de Criar/Listar Clientes e alimenta praticamente todas as ações de cliente (etiquetas, telefones, crédito, vale-presente, agendamento). O ID do Agendamento sai de Criar Agendamento e alimenta Editar, Editar Status e Cancelar.
Tratamento de erros: quando a Trinks recusa uma operação (dado inválido, permissão insuficiente, limite de requisições atingido), a ação falha e devolve a mensagem de erro real da Trinks — use o caminho de erro do bloco para tratar no fluxo.
Status de agendamento: os valores aceitos por Editar Status Agendamento (e o status fixo "cancelado" usado por Cancelar Agendamento) seguem os códigos definidos pela Trinks — confirme os valores válidos na documentação de referência da Trinks antes de usar em produção.
Economize requisições: com o limite de 60/min e 5000/mês por token, evite consultar o catálogo (serviços/profissionais) a cada mensagem — cacheie IDs em variáveis do bot sempre que possível.