Central de Ajuda da Trinks

Conecta Trinks

Ativando o Conecta Trinks: Um guia de integração via API e Webhooks

Domine a API e os Webhooks da Trinks para transformar seu sistema em um ecossistema integrado e inteligente

Introdução
Ative o Conecta Trinks no seu negócio
Área do desenvolvedor: Inove com a Trinks
Explorando a API Trinks
Casos de uso da API: Jornadas práticas
Recebendo notificações em tempo real com webhooks
Casos de uso de webhooks: Automação inteligente

Introdução

Boas vindas ao recurso definitivo para empresas e desenvolvedores que desejam expandir as capacidades do sistema Trinks.

Este guia foi projetado para ser seu manual completo na jornada de integração, mostrando como conectar outras ferramentas, automatizar processos e criar soluções personalizadas que revolucionam a gestão do seu negócio.

Ao explorar as APIs e Webhooks da Trinks, você transformará seu sistema de uma ferramenta de gestão em um ecossistema conectado, ágil e pronto para o crescimento.

1.0 Ative o Conecta Trinks no seu negócio

Ativar o Conecta Trinks é um passo estratégico para levar a gestão do seu negócio a um novo patamar. A plataforma transforma o sistema Trinks de uma ferramenta de gestão em um ecossistema aberto e integrado, permitindo a automação de inúmeras tarefas manuais. Ao conectar suas ferramentas preferidas, você libera tempo valioso da sua equipe, permitindo que todos se concentrem no que realmente importa: o crescimento do negócio.

A proposta do Conecta Trinks é simples e poderosa: oferecer acesso aberto aos dados do seu sistema através de APIs e Webhooks. Pense neles como uma ponte de conexão segura que permite que outros sistemas (como um CRM, uma ferramenta de BI ou um aplicativo próprio) troquem informações com a Trinks de forma automática. Com essa flexibilidade, você pode criar dashboards personalizados, automatizar campanhas de marketing e muito mais, expandindo a gestão para muito além do sistema Trinks.

Principais benefícios

Liberdade total: Conecte seu sistema preferido à Trinks, criando um fluxo de trabalho sob medida para suas necessidades.
Automação completa: Receba dados via API ou relatórios automáticos, eliminando a necessidade de extração manual de informações.
Integrações prontas: Aproveite conexões nativas com ferramentas líderes de mercado como F360, Cloudia e Bitrix.
Suporte técnico: Conte com documentação completa, tutoriais e acompanhamento especializado para garantir o sucesso da sua integração.

Para os desenvolvedores e equipes técnicas, esta é a porta de entrada para construir as soluções que farão essa transformação acontecer.

2.0 Área do desenvolvedor: Inove com a Trinks

Olá, dev! A Trinks é a parceira de crescimento de mais de 40 mil negócios de beleza e bem-estar no Brasil, e queremos te convidar para fazer parte dessa revolução. A Área do Desenvolvedor é o seu espaço para criar soluções inovadoras que, conectadas à nossa plataforma robusta e escalável, impactarão positivamente o dia a dia de milhares de empreendedores. Nossa missão é fornecer as ferramentas para que você possa construir integrações incríveis.

Por que integrar com a Trinks?

Alcance um novo mercado: Exponha sua solução para uma base de clientes engajada e com sede de inovação e crescimento.
Tecnologia de ponta: Construa sobre uma plataforma sólida que processa milhões de agendamentos e transações, garantindo estabilidade e performance.
Parceria de verdade: Faça parte de um ecossistema selecionado e conte com nosso suporte para impulsionar e divulgar sua solução.
Inovação contínua: Esteja na vanguarda do mercado, oferecendo recursos que realmente transformam a rotina dos negócios de beleza.

A principal ferramenta para começar a construir é a nossa API. Vamos explorar como ela funciona.

3.0 Explorando a API Trinks

Nossa API foi construída com base nos princípios REST, utilizando URLs previsíveis, retornando respostas no formato JSON e empregando códigos de status HTTP padrão para sinalizar os resultados das operações. O objetivo é proporcionar uma jornada de desenvolvimento ágil, intuitiva e sem complicações.

3.1 Primeiros passos e autenticação

Para obter acesso à API e começar a desenvolver, siga os passos abaixo:

Esteja cadastrado na Trinks: O usuário responsável pela integração deve possuir um perfil vinculado ao estabelecimento.
Realize a solicitação: Envie um pedido formal através do Fale Conosco, informando o nome e o e-mail do usuário responsável.
Receba o token: Em até 48 horas úteis, o token de acesso estará disponível para visualização na sua área de cadastro em Minha Área/Meu Cadastro.

A autenticação é baseada em uma chave de API (ApiKey). Você deve incluir sua chave em todas as requisições, enviando-a através do cabeçalho HTTP X-Api-Key.

X-Api-Key: SUA_CHAVE_DE_API_AQUI

Importante: A chave de API é secreta, pessoal e intransferível. Com ela é possível acessar dados e realizar operações em todos os seus estabelecimentos. Nunca a compartilhe com terceiros.

3.2 Tratamento de erros

A API utiliza códigos de status HTTP padrão para indicar o sucesso ou a falha de uma requisição.

Código HTTP	Significado
2xx	Sucesso. A requisição foi recebida, entendida e aceita.
400 Bad Request	Requisição malformada. Verifique a sintaxe do corpo da sua requisição.
401 Unauthorized	Falha na autenticação. Sua X-Api-Key está faltando ou é inválida.
403 Forbidden	Você não tem permissão para acessar o recurso solicitado.
404 Not Found	O recurso solicitado não foi encontrado no servidor.
429 Too Many Requests	Você excedeu o limite de requisições permitidas.
5xx	Erro do nosso lado. Houve um problema interno no servidor.

3.3 Limites de requisição e boas práticas

A API possui limites de chamadas para garantir a estabilidade e a performance para todos os usuários:

Por minuto: 60 requisições por chave de API.
Por mês: 5.000 requisições por chave de API (padrão).

Ao exceder o limite por minuto, a API retornará o status HTTP 429 até o minuto seguinte. Ao atingir o limite mensal, todas as requisições serão bloqueadas com o mesmo status até o próximo ciclo.

Como Lidar com os Limites

Controle de taxa: Implemente um mecanismo no seu sistema para não exceder 60 requisições por minuto.
Distribuição de chamadas: Evite picos de requisições, distribuindo as chamadas ao longo do tempo.
Monitoramento: Monitore o consumo mensal para evitar interrupções no serviço.
Uso de cache: Armazene dados que não mudam com frequência (como lista de serviços ou profissionais) para reduzir o número de chamadas.
Otimize chamadas: Evite chamadas duplicadas ou consultas excessivas (polling).
Precisa de mais? Se precisar de mais requisições, entre em contato com nosso suporte para avaliar seu caso.

3.4 Referência de Endpoints da API

A seguir, uma visão geral dos principais recursos disponíveis na API.

Clientes

GET /v1/clientes: Retorna a lista de clientes, permitindo filtrar por CPF, nome ou data de nascimento.

Agendamentos

GET /v1/agendamentos: Lista os agendamentos, permitindo filtrar por data de início, data final e status.

Produtos

GET /v1/produtos: Lista todos os produtos, com suporte a paginação através dos parâmetros page e limit.
GET /v1/produtos/{produtoId}: Obtém um produto específico.
POST /v1/produtos: Cria um novo produto.
PUT /v1/produtos/{produtoId}: Atualiza um produto existente.
DELETE /v1/produtos/{produtoId}: Exclui um produto.

Serviços

GET /v1/servicos: Lista todos os serviços disponíveis.
GET /v1/servicos/{servicoId}: Obtém um serviço específico.
POST /v1/servicos: Cria um novo serviço.
PUT /v1/servicos/{servicoId}: Atualiza um serviço existente.
DELETE /v1/servicos/{servicoId}: Exclui um serviço.
GET /v1/servicos/por-categoria-e-estabelecimento: Retorna serviços filtrados. Requer os parâmetros estabelecimento_id e categoria_id.

Profissionais

GET /v1/profissionais: Lista todos os profissionais.
GET /v1/profissionais/{profissionalId}: Obtém um profissional específico.
GET /v1/profissionais/{profissionalId}/servicos: Retorna os serviços de um profissional.
POST /v1/profissionais: Cria um novo profissional.
PUT /v1/profissionais/{profissionalId}: Atualiza um profissional.
DELETE /v1/profissionais/{profissionalId}: Exclui um profissional.

Estabelecimentos

GET /v1/estabelecimentos: Lista os estabelecimentos.
GET /v1/estabelecimentos/{estabelecimentoId}: Retorna dados cadastrais de um estabelecimento.
PUT /v1/estabelecimentos/{estabelecimentoId}: Edita dados de um estabelecimento.

Fidelidade

GET /v1/fidelidade: Retorna informações do programa de fidelidade.
POST /v1/fidelidade: Adiciona pontos a um cliente.
POST /v1/fidelidade/resgatar: Resgata pontos de um cliente.

Vendas

GET /v1/vendas: Retorna as vendas, permitindo filtrar por data de início, data final e forma de pagamento.
GET /v1/vendas/{vendaId}: Obtém uma venda específica.
POST /v1/vendas: Cria uma nova venda.

Transações

GET /v1/transacoes: Lista as transações financeiras.
GET /v1/transacoes/{transacaoId}: Obtém uma transação específica.

Clube e Planos

GET /v1/clube/planos: Retorna informações sobre planos e assinaturas.
GET /v1/clube/planos/{planoId}: Obtém um plano específico.
POST /v1/clube/planos: Cria um novo plano.
PUT /v1/clube/planos/{planoId}: Edita um plano.
DELETE /v1/clube/planos/{planoId}: Exclui um plano.

Após entender a estrutura da API, o próximo passo é ver como aplicá-la em cenários do mundo real.

4.0 Casos de uso da API: Jornadas práticas

Esta seção abandona a listagem técnica de endpoints em favor de "jornadas práticas". O objetivo é mostrar um passo a passo claro de como utilizar a API para resolver problemas reais de negócio, como realizar um agendamento de ponta a ponta ou sincronizar clientes com um CRM externo.

4.1 Jornada prática: Realizar um agendamento completo

Passo 1: Listar os serviços que o estabelecimento oferece.
- Descrição: Antes de tudo, sua aplicação precisa exibir os serviços disponíveis para o cliente.
- Endpoint: GET /v1/servicos
- Para que serve? Para montar a vitrine de serviços no seu aplicativo, permitindo que o usuário selecione o que deseja agendar. O retorno inclui nome, preço e duração.
Passo 2: Encontrar os profissionais disponíveis.
- Descrição: Após a escolha do serviço, liste os profissionais que o realizam.
- Endpoint: GET /v1/profissionais
- Para que serve? Para mostrar a lista de profissionais qualificados e obter o ID daquele que for selecionado.
- Atenção: Lembre-se de filtrar na sua aplicação apenas os profissionais com o status ativo: true.
Passo 3: Buscar os horários livres na agenda.
- Descrição: Com o serviço e o profissional definidos, é hora de consultar a disponibilidade. A abordagem recomendada é deduzir os horários livres a partir dos ocupados.
- Endpoint Principal: Use GET /v1/agendamentos com os filtros data_inicial, data_final e profissionalId para obter todos os horários já preenchidos.
- Para que serve? Ao comparar a lista de horários ocupados com a jornada de trabalho e as regras da agenda (obtidas via GET /v1/estabelecimentos/{id} para horários de funcionamento e GET /v1/agendamentos/configuracoes para regras de negócio), seu sistema pode identificar e exibir para o cliente apenas os horários realmente vagos.
Passo 4: Criar o agendamento (o grande momento!)
- Descrição: Com todas as informações validadas, efetive a reserva na agenda.
- Endpoint: POST /v1/agendamentos
- Para que serve? Para reservar o horário e confirmar o agendamento. Envie um JSON com os IDs do cliente, serviço, profissional e a data/hora. Uma resposta 201 Created confirmará o sucesso.
Passo 5: Consultar e, se necessário, cancelar.
- Descrição: Permita que o usuário visualize ou cancele seus agendamentos.
- Endpoint de Consulta: GET /v1/agendamentos/{id}
- Endpoint de Cancelamento: DELETE /v1/agendamentos/{id}
- Para que serve? Para exibir o status atualizado do agendamento na sua interface ou processar um cancelamento.

4.2 Jornada prática: Sincronizar clientes com um CRM externo

Passo 1: Buscar um cliente existente.
- Descrição: Antes de criar um novo cadastro, verifique se o cliente já existe na base.
- Endpoint: GET /v1/clientes
- Para que serve? Para encontrar o ID de um cliente usando filtros como nome, CPF ou telefone, evitando a criação de cadastros duplicados.
Passo 2: Criar um novo cliente.
- Descrição: Caso o cliente não seja encontrado, crie um novo registro.
- Endpoint: POST /v1/clientes
- Para que serve? Para cadastrar novos usuários na base do estabelecimento. Envie os dados essenciais como nome e telefone para receber o ID do cliente recém-criado.
Passo 3: Atualizar os dados de um cliente.
- Descrição: Mantenha as informações dos clientes sempre atualizadas.
- Endpoint: PUT /v1/clientes/{id}
- Para que serve? Para editar informações de um cadastro existente, como telefone ou e-mail.
- Atenção: Você precisa passar o ID do cliente na URL e enviar no corpo da requisição apenas os campos que deseja alterar.

4.3 Mais ideias para potencializar sua gestão

Gestão de agendamentos

Para que serve?	Endpoint Sugerido	Ideias para dar um up na sua gestão
Buscar e listar agendamentos	GET /v1/agendamentos	Crie um painel de Business Intelligence (BI) para analisar os horários de pico, os serviços mais agendados e a produtividade dos profissionais.
Criar um novo agendamento	POST /v1/agendamentos	Permita que seus clientes agendem horários através do seu próprio site, aplicativo da franquia ou totem de autoatendimento, e o horário é criado diretamente na Trinks.
Consultar detalhes de um agendamento	GET /v1/agendamentos/{id}	Exiba as informações detalhadas de um agendamento em seu sistema de CRM antes de um contato com o cliente.
Ver as regras da sua agenda	GET /v1/agendamentos/configuracoes	Seu aplicativo personalizado pode consultar essas regras para exibir apenas os horários realmente disponíveis para agendamento online.
Editar um agendamento existente	PUT /v1/agendamentos/{agendamentoId}	Permita que o cliente altere o horário ou o serviço de um agendamento através do seu aplicativo, e a mudança é refletida na Trinks.
Mudar o status de um agendamento	PATCH /v1/agendamentos/.../status/{status}	Integre com um sistema de chamada por voz ou painel na recepção. Quando o profissional marca o status como "Em atendimento", o sistema pode chamar o próximo cliente da fila.
Ver a agenda dos profissionais em uma data	GET /v1/agendamentos/profissionais/{data}	Crie uma visão de disponibilidade para a recepção da sua rede, facilitando encontrar horários livres entre diferentes profissionais ou unidades.

Conexão com clientes

Para que serve?	Endpoint Sugerido	Ideias para dar um up na sua gestão
Buscar e listar todos os seus clientes	GET /v1/clientes	Importe sua base de clientes da Trinks para sua ferramenta de e-mail marketing ou CRM para criar campanhas segmentadas.
Cadastrar um novo cliente	POST /v1/clientes	Quando um cliente preenche um formulário no seu site ou app, crie o cadastro dele automaticamente na Trinks.
Consultar os dados de um cliente	GET /v1/clientes/{id}	Tenha a ficha completa do cliente à mão no seu sistema de CRM ou de atendimento ao realizar uma ligação ou contato.
Editar os dados de um cliente	PUT /v1/clientes/{clienteId}	Permita que o cliente atualize seus próprios dados (como endereço ou e-mail) em uma "área do cliente" no seu site, e a informação é sincronizada na Trinks.
Excluir o cadastro de um cliente	DELETE /v1/clientes/{clienteId}	Atenda a solicitações de privacidade (LGPD) de forma integrada, removendo o cliente de todos os seus sistemas de uma só vez.
Adicionar créditos para um cliente	POST /v1/clientes/{clienteId}/creditos	Crie uma campanha de "cashback" no seu sistema de fidelidade. Quando o cliente atinge uma meta, o crédito é inserido automaticamente na conta dele na Trinks.
Gerenciar etiquetas (tags) dos clientes	GET / POST / DELETE /v1/clientes/{id}/etiquetas	Segmente seus clientes de forma automática. Se um cliente compra um pacote de noiva no seu e-commerce, adicione a etiqueta "Noiva" a ele na Trinks para um atendimento personalizado.
Gerenciar os telefones de um cliente	GET / POST / DELETE /v1/clientes/{id}/telefones	Mantenha os contatos dos clientes sempre atualizados e sincronizados com sua plataforma de envio de WhatsApp ou SMS.
Lançar um vale-presente para um cliente	POST /v1/clientes/{clienteId}/valespresentes	Venda vales-presente através do seu site ou aplicativo e, após a confirmação do pagamento, o vale é gerado e associado ao cliente automaticamente na Trinks.

Inteligência do negócio

Para que serve?	Endpoint Sugerido	Ideias para dar um up na sua gestão 🚀
Consultar planos e assinaturas (Clube)	GET /v1/clube/...	Crie uma área exclusiva para assinantes no seu site ou app, onde eles podem ver os detalhes do plano, o histórico de uso e as estatísticas de consumo.
Buscar dados dos seus estabelecimentos	GET /v1/estabelecimentos	Alimente um mapa interativo no site da sua franquia com os endereços e contatos de todas as unidades, buscando os dados direto da Trinks.
Listar formas de pagamento	GET /v1/formaspagamentos	Utilize essa lista para padronizar a conciliação de pagamentos no seu sistema financeiro.
Listar motivos de descontos	GET /v1/motivosdescontos	Analise em seu sistema de BI quais são os descontos mais utilizados e o impacto deles no faturamento.
Listar transações e vendas	GET /v1/transacoes e GET /v1/vendas	Exporte os dados de vendas para seu software de contabilidade ou para criar relatórios financeiros personalizados.
Consultar seus produtos, serviços e profissionais	GET /v1/produtos, GET /v1/servicos, GET /v1/profissionais	Exiba sua vitrine de serviços e produtos em seu próprio site ou app, com informações sempre atualizadas direto da Trinks.

Enquanto a API é excelente para buscar e enviar dados ativamente, os Webhooks são a solução ideal para receber atualizações do Trinks em tempo real, de forma passiva.

5.0 Recebendo notificações em tempo real com webhooks

Imagine receber um aviso automático sempre que algo importante acontece no seu sistema Trinks, sem precisar fazer consultas repetidas. É exatamente isso que os Webhooks fazem. Eles funcionam como "mensageiros" que notificam seus outros sistemas instantaneamente, via requisições HTTPS, sempre que um evento específico ocorre, como o fechamento de uma conta ou a criação de um novo agendamento.

5.1 Como funcionam os Webhooks Trinks

O sistema de Webhooks da Trinks utiliza o Amazon SNS (Simple Notification Service) para enviar as notificações. Isso significa que seu sistema precisa ter um endpoint (URL) público capaz de receber e processar as mensagens do protocolo SNS. Todas as notificações de eventos para sua franquia ou estabelecimento são centralizadas e enviadas para essa única URL cadastrada.

5.2 Estrutura da mensagem e segurança

Para garantir a autenticidade e a segurança das notificações, cada mensagem enviada pelo Trinks é assinada digitalmente. É fundamental que o seu sistema receptor valide essa assinatura utilizando o certificado disponível na URL fornecida no campo SigningCertURL do payload.

A estrutura genérica de uma mensagem de webhook é a seguinte:

{

"Message": "{...}",

"MessageId": "string",

"Timestamp": "string",

"Type": "string",

"Signature": "string",

"SigningCertURL": "string",

"Subject": "string"

}

5.3 Eventos suportados por webhooks

A plataforma notifica uma ampla gama de eventos de negócio. Cada evento é acompanhado por um código de ação que especifica a natureza da ocorrência.

Evento	Descrição do Disparo	Códigos de Ação
Fechamento de Conta	Ocorre sempre que uma conta é fechada no sistema.	1 (Inclusão)
Estorno de Conta	Ocorre sempre que uma conta é estornada no sistema.	9 (Estorno)
Cadastro de Novo Cliente	Disparado quando um novo cliente é cadastrado.	1 (Inclusão)
Atualizar Cadastro do Cliente	Disparado quando os dados de um cliente são atualizados.	2 (Alteração)
Cadastro de Novo Profissional	Disparado quando um novo profissional é cadastrado.	1 (Inclusão)
Atualizar Cadastro do Profissional	Disparado quando os dados de um profissional são atualizados.	2 (Alteração)
Inativar Profissional	Disparado quando um profissional é inativado no sistema.	3 (Exclusão)
Cadastro de Estabelecimento	Acionado quando uma nova unidade é cadastrada.	1 (Inclusão)
Exclusão de Estabelecimento	Acionado quando uma unidade é desassociada.	3 (Exclusão)
Alteração de Estabelecimento	Acionado quando os dados de uma unidade são alterados.	2 (Alteração)
Inclusão de Agendamento	Acionado quando um agendamento é criado.	1 (Inclusão)
Alteração de Agendamento	Acionado quando um agendamento é modificado.	2 (Alteração)
Exclusão de Agendamento	Acionado quando um agendamento é cancelado.	3 (Exclusão)

Agora que conhecemos os eventos, vamos ver como eles podem ser usados para automatizar a gestão de forma inteligente.

6.0 Casos de uso de webhooks: Automação inteligente

Com os Webhooks, você pode criar automações que reagem instantaneamente a eventos no Trinks. Imagine, por exemplo, um dashboard para a gestão da sua franquia que mostra, em tempo real, o que acontece em cada unidade: vendas fechadas, novos clientes cadastrados e agendamentos confirmados, tudo atualizado automaticamente.

A tabela a seguir transforma os eventos técnicos em soluções de negócio claras e valiosas.

Quando este evento acontece...	...seu sistema recebe um aviso automático.	Ideias para dar um up na sua gestão 🙌
Conta é fechada	Evento: Fechamento de Conta	Envie os dados da venda na mesma hora para seu sistema financeiro (ERP) ou para uma planilha que calcula a comissão dos profissionais automaticamente.
Venda é estornada	Evento: Estorno de Conta	Atualize seu controle financeiro e de estoque em tempo real, sem precisar de lançamento manual.
Novo cliente é cadastrado	Evento: Cadastro de Novo Cliente	Inicie uma régua de comunicação automática: envie um e-mail de boas-vindas para o novo cliente através da sua ferramenta de marketing.
Cadastro do cliente é atualizado	Evento: Atualizar Cadastro do Cliente	Mantenha a base de dados do seu sistema de CRM ou de e-mail marketing sempre sincronizada e atualizada.
Novo profissional é adicionado	Evento: Cadastro de Novo Profissional	Dispare um processo de onboarding interno, como a criação de acesso do profissional em outras ferramentas da sua rede.
Cadastro do profissional é atualizado	Evento: Atualizar Cadastro do Profissional	Garanta que as informações do profissional (como telefone ou e-mail) estejam sempre consistentes em todos os sistemas da sua empresa.
Profissional é inativado	Evento: Inativar Profissional	Revogue acessos do profissional em outros sistemas ou atualize a lista de equipe no site da sua franquia automaticamente.
Novo estabelecimento (unidade) é criado	Evento: Cadastro de Estabelecimento	Automatize a configuração da nova unidade em outros sistemas da franqueadora, como o financeiro ou de BI.
Estabelecimento (unidade) é excluído	Evento: Exclusão de Estabelecimento	Sincronize a remoção da unidade em todos os seus sistemas de gestão da rede.
Dados do estabelecimento são alterados	Evento: Alteração de Estabelecimento	Mantenha informações como endereço, telefone ou responsável sempre atualizadas no sistema da sua franquia.
Novo agendamento é criado	Evento: Inclusão de Agendamento	Se o agendamento foi feito em um totem ou app próprio, essa notificação confirma que ele foi criado com sucesso na Trinks.
Agendamento é alterado	Evento: Alteração de Agendamento	Envie uma notificação para o cliente através de um canal alternativo (como WhatsApp ou aplicativo da franquia) informando sobre a mudança.
Agendamento é excluído/cancelado	Evento: Exclusão de Agendamento	Libere o horário na agenda de outros sistemas integrados ou atualize painéis de disponibilidade em tempo real.

A combinação da API para consultas ativas e dos Webhooks para notificações passivas oferece um conjunto de ferramentas extremamente poderoso. Com elas, você pode personalizar, automatizar e otimizar a gestão do seu negócio de maneiras que antes eram impossíveis. Explore essas possibilidades, conecte suas ferramentas e acelere o seu crescimento com o Conecta Trinks.