Pular para o conteúdo
Claro

Gerar a chave da API pública e integrar outros sistemas

A chave de acesso da API pública liga à sua loja um sistema que você ou o seu programador controla: um site, um aplicativo, uma planilha automatizada ou um sistema de gestão. Com ela, esse sistema lê e, se você liberar, grava dados na tecpet (clientes, pets, catálogo, agenda e financeiro) pela internet. Tudo fica em Configurações → Sistema → API, que só aparece com o módulo API pública contratado. Se a ideia é conversar com a loja pelo Claude, ChatGPT ou Gemini, você não precisa de chave: veja Conectar um assistente de IA à tecpet.

Entre em Configurações (vai pedir a senha de administrador) e, no menu lateral, em Sistema → API. No topo, dois selos resumem a situação: Sem chave ou Chave ativa, e quantas IAs estão conectadas.

Sem chave, a tela abre no cartão Gerar chave de acesso: “A chave conecta seu site, aplicativo ou sistema de gestão à loja. Dá para mudar as permissões depois.”

Tela API com o selo Sem chave e o cartão Gerar chave de acesso: pergunta O que o sistema conectado vai fazer? com as opções Só consultar (recomendado), Consultar e agendar e Personalizar, o campo Sua senha de acesso e o botão Gerar chave

Em O que o sistema conectado vai fazer?, escolha uma opção:

  • Só consultar (recomendado): lê loja, catálogo, clientes, agenda e financeiro. Não altera nada;
  • Consultar e agendar: tudo acima, mais cadastrar clientes e pets e criar agendamentos;
  • Personalizar: abre a lista para marcar permissão por permissão, separada em O que a chave pode ler e O que a chave pode alterar.

As permissões são:

  • Consultar loja, catálogo e agenda: dados da loja, serviços, preços, combos, raças, espécies, profissionais e horários disponíveis;
  • Consultar clientes e pets: cadastro de clientes e pets, resumo do cliente e planos do pet;
  • Consultar agendamentos: lista e detalhe dos agendamentos e cálculo de preço;
  • Consultar faturas e transações: faturas e transações financeiras da loja;
  • Cadastrar e editar clientes e pets: cria e altera clientes e pets;
  • Criar e alterar agendamentos: cria, reagenda, troca serviços e muda o status dos agendamentos;
  • Alterar o catálogo: cria, edita e apaga serviços, categorias, combos, raças e espécies.

As quatro de consulta vêm marcadas. As de alterar vêm desmarcadas.

Cartão Gerar chave de acesso com Personalizar escolhido: lista O que a chave pode ler com as quatro permissões de consulta marcadas

Digite a Sua senha de acesso (a mesma que você usa para entrar na tecpet) e clique em Gerar chave.

Aparece o cartão amarelo Copie a chave agora: “Por segurança ela não aparece de novo. Se perder, gere uma nova.” Clique em Copiar chave e guarde num lugar seguro (o gerenciador de senhas da empresa, ou direto na configuração do sistema que vai usar a chave). O botão Já guardei só libera depois que você copia. Ao clicar nele, o cartão some.

Cartão Copie a chave agora com a chave mascarada, os botões Copiar chave e Já guardei e, abaixo, o cartão Chave de acesso com o começo da chave e as permissões

Depois de criada, a tela mostra o cartão Chave de acesso com:

  • O começo da chave (ex.: tpk_…), para você saber qual chave está ativa sem expor o resto;
  • Criada em, Último uso (ou Ainda não usada) e Última troca (ou Nunca trocada);
  • As permissões liberadas, em etiquetas.

E três botões:

  • Gerar nova chave: cria uma chave nova e a antiga para de funcionar. Use quando a chave vazar ou quando alguém que tinha acesso sair da equipe. Depois é preciso atualizar a chave no sistema integrado;
  • Alterar permissões: muda o que a chave pode fazer, sem trocar a chave;
  • Revogar chave: desliga a chave (veja o próximo passo).

Gerar nova chave e alterar permissões pedem a sua senha de novo.

Tela API com o selo Chave ativa e o cartão Chave de acesso: começo da chave, Criada em, Último uso, Última troca, as quatro permissões e os botões Gerar nova chave, Alterar permissões e Revogar chave

Clique em Revogar chave. A tela pergunta “Revogar a chave? Os sistemas que usam essa chave perdem o acesso na hora.” Clique em Revogar chave de novo para confirmar, ou em Cancelar. Depois disso a tela volta para Gerar chave de acesso. Revogar a chave não desconecta os assistentes de IA: cada um tem a sua conexão e se desconecta em Conexões ativas.

Cartão Chave de acesso com a confirmação Revogar a chave? Os sistemas que usam essa chave perdem o acesso na hora e os botões Cancelar e Revogar chave

No fim da tela, abra Documentação da API (Para quem vai programar uma integração com a chave de acesso). Ele mostra o que o programador precisa:

  • URL base: https://api.tec.pet/v1/;
  • Autenticação: o cabeçalho Authorization: Bearer <sua chave> em toda chamada;
  • Loja: o cabeçalho x-shop é opcional, porque a chave já identifica a loja;
  • Abrir a documentação completa: a documentação interativa de todas as rotas, com os campos de cada uma.

Exemplo de chamada, buscando um cliente pelo telefone:

Terminal window
curl "https://api.tec.pet/v1/client?phone=11999999999" \
-H "Authorization: Bearer SUA_CHAVE"

Bloco Documentação da API aberto: URL base https://api.tec.pet/v1/, Autenticação Authorization: Bearer sua chave, a nota sobre o cabeçalho x-shop e o link Abrir a documentação completa

As principais rotas, agrupadas por área (a lista completa e os campos estão na documentação completa):

  • Loja: GET /v1/shop/configurations (segmentos, horários de funcionamento e regras de agendamento);
  • Clientes: GET /v1/client (busca com paginação, por telefone, código externo ou data de cadastro), GET /v1/client/{id}, GET /v1/client/{id}/summary, POST /v1/client, PUT /v1/client/{id};
  • Pets: GET /v1/pet, GET /v1/pet/{id}, POST /v1/pet, PUT /v1/pet/{id}, GET /v1/pet-plan (planos e pacotes com saldo de uso);
  • Catálogo: GET /v1/service, GET /v1/service/pricing (preço para um pet), GET /v1/combo/pricing, GET /v1/specie, GET /v1/breed, GET /v1/billingMethod (portes e pelagens), GET /v1/employee/list;
  • Agenda: POST /v1/availableTimes (horários livres), POST /v1/service-capacity/by-day (vagas de creche), POST /v1/booking/pricing, GET /v1/booking, GET /v1/booking/{id}, POST /v1/booking, PUT /v1/booking/{id}/reschedule, PUT /v1/booking/{id}/changeStatus, PUT /v1/booking/{id}/changeServices;
  • Financeiro: GET /v1/invoice, GET /v1/transaction (recebimentos por data de pagamento);
  • Resumos (até 12 meses, por dia, semana ou mês): GET /v1/analytics/payments, GET /v1/analytics/sales, GET /v1/analytics/bookings.

Para criar um agendamento: busque o cliente e o pet, consulte os serviços com o preço do pet, peça os horários em availableTimes e envie o timeId devolvido em POST /v1/booking. Agendamentos criados pela API ficam com a origem API pública.

Cada chave de loja faz até 1.000 requisições por hora. Ao passar disso, a resposta é 429 com a mensagem “Limite de 1000 requisições por hora atingido para este token” e o cabeçalho Retry-After dizendo quantos segundos esperar.

  • 401 Token não fornecido: faltou o cabeçalho Authorization: Bearer;
  • 401 Token inválido ou Token expirado: chave errada, trocada por Gerar nova chave ou revogada;
  • 403: a loja está sem o módulo API pública, bloqueada, ou a chave não tem a permissão daquela rota (libere em Alterar permissões);
  • 429: passou do limite por hora, espere o tempo do Retry-After.
Isso ajudou?