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

_Como gerar, copiar, trocar e revogar a chave de acesso da API pública da tecpet, escolher as permissões e usar a API REST (URL base, autenticação, rotas, limites e erros) para integrar site, aplicativo ou sistema de gestão._

> **💡 Dica**
>
> Dê à chave só o que a integração precisa. Um site que mostra horários livres precisa de **Consultar loja, catálogo e agenda**; um sistema de gestão que lê o faturamento precisa de **Consultar faturas e transações**. Menos permissão é menos risco se a chave vazar.

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](/configuracao/integracoes/conectar-assistente-de-ia/).

## Passo 1: Abra a tela API

Entre em **Configurações** (vai pedir a [senha de administrador](/configuracao/avancado/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](https://help.tec.pet/_md-assets/api-publica-mcp__criar-chave.png)

## Passo 2: Escolha o que o sistema pode fazer

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](https://help.tec.pet/_md-assets/api-publica-mcp__permissoes-personalizar.png)

## Passo 3: Confirme a senha e gere a chave

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](https://help.tec.pet/_md-assets/api-publica-mcp__chave-gerada.png)

## Passo 4: Acompanhe e gerencie a chave

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](https://help.tec.pet/_md-assets/api-publica-mcp__gerenciar-chave.png)

## Passo 5: Revogue a chave quando não usar mais

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](https://help.tec.pet/_md-assets/api-publica-mcp__revogar-confirmar.png)

## Passo 6: Passe os dados para quem vai programar

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:

```bash
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](https://help.tec.pet/_md-assets/api-publica-mcp__documentacao.png)

## O que dá para fazer pela API

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**.

## Limites e erros comuns

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`.

---
_feature: api-publica-mcp · atualizado em 2026-11-16 · fonte: https://help.tec.pet/configuracao/integracoes/gerar-chave-da-api-publica/ · tecpet Central de Ajuda_
