Trinks
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 c
Nota
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.
Nota
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.Atenção
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.
Nota
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.
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.