As chaves API do Fixh IT transformam o software do teu centro de assistência numa plataforma aberta: em Empresa > Chaves API, a tua empresa pode gerar e revogar chaves API REST v1, usadas no cabeçalho X-API-Key para autenticar os pedidos ao endpoint /api/v1/company/... Não é uma funcionalidade só para programadores isolados: é a ponte entre a tua oficina de reparações e o resto do teu ecossistema de software, do teu site ao teu programa de contabilidade, do teu CRM ao bot que responde aos teus clientes. Por motivos de segurança, a chave completa é mostrada no ecrã apenas uma vez, logo após a criação: a partir desse momento só é visível de forma mascarada (o key_prefix), pelo que deve ser copiada e guardada de imediato num local seguro.
Porque é importante para um centro de assistência
Uma oficina de reparação de smartphones e computadores raramente trabalha com uma única ferramenta: há o sistema de gestão principal, talvez uma loja online de peças, um chatbot que responde aos clientes no WhatsApp ou Telegram, um software de contabilidade para faturação, uma ferramenta de marketing para campanhas de e-mail. Sem uma integração real, toda esta informação fica isolada em cada sistema, obrigando a equipa a introduzir os mesmos dados várias vezes, com o risco real de erros de transcrição e atrasos na comunicação com o cliente. As chaves API REST v1 resolvem exatamente este problema: permitem que um sistema externo comunique automaticamente com os dados de reparações da tua empresa no Fixh IT, lendo o estado de um ticket, criando novas reparações a partir de um formulário online, ou atualizando um ticket quando um técnico marca uma intervenção como concluída. Para um centro de assistência que gere dezenas ou centenas de reparações por mês, esta integração entre reparações de smartphones e computadores e software externo pode fazer a diferença entre um fluxo de trabalho fluido e um cheio de dupla introdução manual.
Na prática
Cada chave API gerada está associada à tua empresa (key_type "company") e permite que um sistema externo se autentique junto das APIs REST v1 do Fixh IT, incluindo a chave no cabeçalho X-API-Key de cada pedido HTTP. Com este tipo de chave podes consultar a lista de reparações da tua empresa com filtros por loja, estado ou texto de pesquisa, ler o detalhe de uma reparação específica, criar novas indicando loja, cliente, técnico, dispositivo, avaria detetada, acessórios entregues e orçamento, ou atualizar uma reparação existente alterando o seu estado, pagamento, entrega ou notas internas. Cada pedido é sempre filtrado automaticamente pela empresa a que a chave pertence: um sistema externo nunca pode ver ou modificar dados de outra empresa da rede, nem por engano, porque o controlo é feito do lado do servidor em cada consulta.
Por motivos de segurança, a chave completa (a cadeia secreta real) é apresentada no ecrã apenas uma vez, logo após a criação: a partir daí o sistema conserva apenas um hash da chave e mostra na lista apenas o seu prefixo inicial (key_prefix), suficiente para a reconhecer mas não para a reutilizar. É por isso fundamental copiar a chave de imediato e colá-la no ficheiro de configuração do sistema externo que a vai usar, antes de fechar a janela: se te esqueceres, a única solução é revogar essa chave e gerar uma nova. Cada chave mostra também a data da última utilização, útil para perceber se uma integração ainda está ativa ou se pode ser desativada com segurança porque já não é usada. Se uma chave se perder, ficar comprometida ou deixar de ser necessária, podes revogá-la a qualquer momento a partir da lista: depois de revogada deixa imediatamente de funcionar, a data de revogação é registada, e qualquer sistema que a utilizasse perde instantaneamente o acesso às APIs, sem necessidade de intervir noutro sítio.
Além das chaves de tipo empresa, o mesmo sistema técnico tem também um tipo de chave reservado aos revendedores da rede Fixh IT, usada para gerir automaticamente a emissão e o controlo dos códigos de licença a partir do seu próprio software de gestão: os dois tipos de chave são completamente separados (proteções e permissões distintas), e uma chave de empresa nunca pode ser usada para operações reservadas a revendedores, e vice-versa.
Guia rápido
- Vai a Empresa > Chaves API.
- Cria uma nova chave API atribuindo-lhe um nome descritivo que identifique claramente a integração (por exemplo "Loja online de peças" ou "Bot de suporte WhatsApp").
- Copia de imediato a chave completa mostrada no ecrã: não voltará a ser mostrada por inteiro depois disso, apenas de forma mascarada.
- Cola a chave no ficheiro de configuração do sistema externo, na variável prevista para o cabeçalho X-API-Key.
- Configura o sistema externo para enviar a chave no cabeçalho X-API-Key em cada pedido para /api/v1/company/repairs e os outros endpoints disponíveis.
- Testa a integração com uma chamada de teste, por exemplo a leitura da lista de reparações, para verificar se a resposta contém os dados esperados.
- Verifica periodicamente a data da última utilização de cada chave para identificar integrações que já não estão ativas.
- Se necessário, revoga a chave a partir da lista para interromper de imediato a sua utilização, por exemplo ao mudar de fornecedor do site ou deixar de usar uma ferramenta externa.
Casos de uso reais
Formulário de pedido de reparação no site. Uma oficina de reparação de smartphones integra no seu site um formulário "pedir assistência": quando um cliente o preenche, um script externo chama o endpoint de criação de reparação com o cabeçalho X-API-Key, gerando automaticamente um novo ticket no sistema, já atribuído à loja correta e pronto a ser assumido por um técnico, sem que ninguém tenha de copiar manualmente os dados do site para o sistema.
Sincronização com um sistema de contabilidade externo. Uma empresa com várias lojas usa um software de contabilidade separado para faturação: uma integração agendada lê todas as noites, através da chave API, as reparações marcadas como pagas e entregues nas últimas 24 horas, e importa-as para o sistema contabilístico para registo fiscal, evitando a dupla introdução manual de dados.
Notificações automáticas ao cliente via bot. Um centro de assistência liga um bot de mensagens ao seu sistema: quando um técnico atualiza o estado de uma reparação de "em curso" para "pronta a levantar" através da API, o bot externo verifica periodicamente as reparações atualizadas recentemente e envia automaticamente uma mensagem ao cliente, reduzindo as chamadas à loja a perguntar pelo estado da reparação.
Dicas e boas práticas
Cria uma chave API distinta para cada integração, em vez de reutilizar a mesma chave em todo o lado: assim, se um sistema externo for descontinuado ou comprometido, podes revogar apenas essa chave sem teres de reconfigurar todas as outras integrações. Dá a cada chave um nome descritivo que lembre à primeira vista para que serve, sobretudo se ao longo do tempo acumulares várias. Verifica periodicamente a data da última utilização para identificar chaves "esquecidas" ligadas a sistemas que já não usas, e revoga-as: menos chaves ativas significam uma superfície de ataque menor. Guarda a chave completa num gestor de palavras-passe ou num ficheiro de configuração protegido, nunca num documento partilhado ou numa mensagem de chat.
Erros comuns a evitar
Nunca partilhes a mesma chave API entre várias integrações diferentes: se no futuro precisares de desativar uma, arriscas-te a interromper também as outras. Não colocues a chave diretamente no código-fonte público de um site ou aplicação: deve estar sempre num ficheiro de configuração separado e não versionado. Não esperes conseguir recuperar a chave completa depois de fechares a janela pela primeira vez: se te esqueceres de a copiar, a única solução é revogá-la e gerar uma nova. Por fim, não te esqueças de revogar as chaves de integrações descontinuadas: uma chave ativa mas não usada continua a ser um potencial ponto de acesso aos dados das tuas reparações.
Saiba mais
- Fixh Assistant: o chatbot de WhatsApp com Fixh AI para o seu centro de assistência
- Vitrine Empresarial: venda online os produtos do seu estoque
- Exportar todos os dados da empresa: reparações, documentos, clientes e talões num arquivo ZIP
Perguntas frequentes
Posso voltar a ver a chave completa depois de a criar? Não, por motivos de segurança a chave completa só é mostrada na criação; se a perderes, tens de a revogar e gerar uma nova.
O que acontece se revogar uma chave API? A chave deixa de funcionar de imediato, a data de revogação é registada, e qualquer pedido que a utilize é rejeitado pelo sistema.
Posso criar várias chaves API para a mesma empresa? Sim, podes gerar várias chaves, por exemplo uma por cada integração ou sistema externo ligado, e revogá-las individualmente sem afetar as restantes.
Que dados posso ler ou escrever com uma chave API de empresa? As reparações da tua empresa: podes listá-las, filtrá-las por loja ou estado, criar novas e atualizar o estado, pagamento, entrega e notas internas das existentes, sempre limitadas automaticamente à tua empresa.
As chaves API são diferentes das usadas pelos revendedores para licenças? Sim, existem dois tipos de chave completamente separados: as de empresa para reparações e as de revendedor para gerir códigos de licença, com permissões e âmbitos distintos.
É preciso conhecimento técnico para usar as chaves API? Sim, a integração exige que o sistema externo (site, bot, software de terceiros) esteja programado para enviar pedidos HTTP com o cabeçalho X-API-Key: é pensada para programadores ou fornecedores de software que colaboram com o teu centro de assistência.
