Criar uma chave de API

Uma API é uma porta nas traseiras da sua conta. Onde clica no seu painel, outro programa pode, por essa porta, obter diretamente os seus dados: os seus produtos, os seus preços, os seus lugares livres, as suas vendas.

Isto é útil quando, por exemplo:

• quer mostrar no seu próprio site que visitas guiadas ainda têm lugar esta semana;
• quer que o seu contabilista receba automaticamente os seus números de faturação;
• quer ligar a sua lista de sócios a outro programa.

Quem constrói uma integração destas — o seu programador web, o seu software de contabilidade, um amigo que saiba programar — precisa de duas coisas suas: o endereço e uma chave. Encontra ambos num único ecrã.

Bom saber: a API faz parte de um plano superior. Se estiver num plano inferior, Acesso à API não aparece no seu menu; se mesmo assim chegar a esse ecrã, vê uma explicação e um botão Ir para Assinatura, e nenhuma chave.

Onde tem de ir

No menu à esquerda, abra Definições → Acesso à API. Só a função proprietário vê este ecrã.

No topo há dois separadores: Chaves e Webhooks. Este artigo trata do primeiro; os webhooks estão em Configurar webhooks.

No separador Chaves vê três blocos:

1. A ligação — o endereço e a descrição técnica. São estes dois dados que entrega a quem constrói a integração.
2. Nova chave — aqui cria uma.
3. Chaves — as que já existem e quando foram usadas pela última vez.

Criar uma chave

Passo 1. Dê-lhe um nome. Não o seu próprio nome, mas o nome do que está do outro lado: "o nosso site", "contabilidade", "newsletter". Esse nome serve apenas para si. Aparece depois na lista e junto a "usada pela última vez". Assim, daqui a um ano ainda sabe a que pertence cada chave — e quais pode revogar sem receio.

Passo 2. Assinale o que a chave pode fazer. Em O que pode fazer esta chave? estão as permissões, ou scopes na linguagem técnica. Ler já vem assinalada:

Permissão	O que o programa pode fazer
Ler	Consultar o seu catálogo, preços, lugares livres, descontos, vales-oferta e passes anuais — e também as suas encomendas, bilhetes, leituras e compradores, com o nome e o endereço de e-mail.
Escrever	Criar encomendas, cobrá-las, cancelá-las e reembolsá-las, pedir uma fatura, revogar bilhetes e reenviá-los por e-mail, registar entradas, e emitir, resgatar ou renovar vales-oferta e passes anuais.
Webhooks	Configurar o envio de uma notificação nossa para um endereço próprio assim que algo acontece.
Pago externamente	Marcar uma encomenda como paga sem fornecedor de pagamentos (transferência bancária, numerário). Só funciona em conjunto com Escrever.

Assinale apenas o que é realmente necessário. Um site que só tem de mostrar os lugares livres precisa apenas de Ler. Se essa chave também tiver Escrever, um erro nesse site pode criar encomendas ou reembolsos que não deseja.

Seja especialmente cuidadoso com Pago externamente: quem tiver esta permissão pode emitir bilhetes sem que entre dinheiro. Dê-a apenas a uma caixa ou contabilidade geridas por si.

Tem de assinalar pelo menos uma permissão. Uma chave sem permissões não poderia fazer nada, e esse é o tipo de erro mais difícil de detetar — por isso o ecrã recusa-a.

Passo 3 (opcional). Defina uma data de expiração. Se deixar o campo Expira em (opcional) em branco, a chave continua a funcionar até a revogar. Se introduzir uma data, funciona ainda nesse dia e deixa de funcionar automaticamente depois. A data tem de ser no futuro. Útil quando dá acesso temporário a alguém: assim não tem de se lembrar disso mais tarde.

Passo 4 (opcional). Chave de teste. Assinale Chave de teste (sandbox) para quem ainda está a desenvolver. Uma chave destas lê os mesmos dados que uma normal. Se também tiver Escrever, cria apenas encomendas de teste: estas nunca vão para o seu fornecedor de pagamentos, não contam para a sua faturação e são eliminadas automaticamente ao fim de 24 horas. Um erro de digitação não pode, assim, provocar um pagamento ou reembolso real. Uma chave de teste não pode configurar webhooks.

Atenção: uma encomenda de teste reserva, até ser eliminada, um lugar real, e o e-mail de confirmação é mesmo enviado. Faça os testes com um produto ou horário criado para esse efeito.

Reconhece uma chave de teste pelo início: começa por pv_test_ em vez de pv_live_.

Passo 5. Clique em "Criar chave".

Só vê a chave uma vez

Logo após a criação, a chave aparece numa caixa. É a única vez que a vê.

Copie-a agora e entregue-a de imediato. Se atualizar a página, desaparece.

Não é um incómodo, é uma proteção. Não guardamos a sua chave: guardamos apenas uma espécie de impressão digital, com a qual a conseguimos reconhecer mas não ler. Se alguém algum dia acedesse à nossa base de dados, não teria com isso acesso aos seus dados. A contrapartida é que nem nós a conseguimos voltar a mostrar.

Perdeu-a? Não há problema: crie uma nova e revogue a antiga.

Trate uma chave como uma chave

Quem tem a chave pode fazer o que nela estiver assinalado — sem palavra-passe e sem abrir a sua conta. Por isso:

• não a envie num chat de grupo comum, onde fica guardada;
• não a coloque no código visível do seu site;
• dê a cada integração uma chave própria. Assim pode revogar uma sem estragar as restantes, e vê na lista quais ainda estão a ser usadas.

Revogar uma chave

Na lista, clique em Revogar ao lado da chave e confirme.

A partir desse momento, deixa de funcionar. A linha continua, no entanto, na lista, com a etiqueta "Revogada": assim pode sempre consultar mais tarde que integração existiu e quando.

Revogue uma chave quando:

• deixa de usar a ferramenta que a utilizava;
• a perdeu ou ela anda por aí perdida;
• sai alguém que a tinha.

A criação e a revogação de uma chave ficam também registadas no registo de atividade de quem o fez (Definições → Colaboradores, essa pessoa, separador Atividade), com a hora. A chave em si nunca lá aparece.

Quando foi usada pela última vez?

Por baixo de cada chave aparece quando foi usada pela última vez para obter dados. Se há meses aparece "ainda não utilizada", provavelmente já nada depende dela. Revogue-a sem receio — uma porta que ninguém usa não tem de ficar aberta.

O que entrega a quem constrói a integração

Três coisas:

1. o endereço da API do bloco A ligação;
2. a descrição técnica (o link que termina em openapi.json) — com ela, um programador vê logo tudo o que é possível;
3. a chave em si, e que permissões assinalou.

Não precisa de mais nada.

E depois?

Tem o endereço e a chave. O que acontece a seguir é trabalho para quem constrói a integração — e a essa pessoa indica o portal para programadores. Aí está a referência completa, com exemplos de código em quatro linguagens e um ficheiro que pode ser importado diretamente no Postman ou no Insomnia.

• O que é uma API e preciso dela? — se primeiro quiser perceber do que se trata tudo isto.
• Webhooks: saber de imediato que foi vendido um bilhete — avise o seu site de que algo foi vendido, sem que ele tenha de estar sempre a perguntar.
• Configurar webhooks — o separador Webhooks neste mesmo ecrã, passo a passo.