O que é uma API e preciso dela?

Encontra estas três letras num orçamento do seu programador web, ou na lista de funcionalidades do seu software de contabilidade: API. Este artigo explica o que é, sem que precise de saber programar.

A resposta curta

Uma API é uma porta nas traseiras da sua conta.

Onde clica no seu painel para ver quantos lugares ainda estão livres, outro programa pode pedir exatamente a mesma informação por essa porta — sem que ninguém esteja sentado em frente a um ecrã. Por trás das duas portas estão os mesmos dados: os seus produtos, os seus preços, os seus lugares livres, as suas vendas.

A diferença está em quem entra. Pela porta da frente entra uma pessoa com um rato. Pela porta das traseiras entra um programa com uma chave.

Quando precisa de uma?

Apenas quando quer algo que o painel não faz. Por exemplo:

• mostrar no seu próprio site que visitas guiadas ainda têm lugar esta semana, com o seu próprio design e números atualizados ao momento;
• deixar o seu contabilista consultar os dados, para que ele próprio obtenha a faturação do mês passado em vez de receber todos os meses uma exportação sua;
• um ecrã no átrio de entrada que mostra que horário vai começar a seguir;
• vender a partir de um programa que já utiliza, sem ter de iniciar sessão primeiro no painel.

E quando é que não precisa? Quando o pode fazer com uns cliques. Construir uma integração exige tempo e manutenção; exportar uma lista duas vezes por mês demora dois minutos. Escolha a primeira opção só quando a segunda começar a atrapalhar.

Atenção: não precisa de ser o próprio a construir isto. Quem o constrói — o seu programador web, o fornecedor do seu software de contabilidade, alguém da sua direção que saiba programar — só precisa de duas coisas suas: o endereço e uma chave. Encontra ambos no seu painel.

O que entrega exatamente

Abra Definições → Acesso à API (este ecrã é para o proprietário da organização). No separador Chaves estão três coisas que pode entregar:

1. O endereço. Uma linha de texto. É para lá que o outro programa comunica.
2. A descrição técnica, o link que termina em openapi.json. Com ela, um programador vê num relance tudo o que é possível: que dados existem, como pedi-los, o que é devolvido.
3. Uma chave, criada por si. Consulte Criar uma chave de API.

Não precisa de mais nada, e não deve dar mais nada — muito menos a sua palavra-passe.

O que uma chave pode e não pode fazer

Ao criá-la, assinala o que a chave pode fazer. Não é uma formalidade:

• Ler — consultar tudo, sem alterar nada. É o que a maioria das integrações precisa. Atenção: "tudo" inclui também as suas encomendas e os seus 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 — indicar para onde podem ser enviadas mensagens. Consulte Webhooks: saber de imediato que foi vendido um bilhete.
• Pago externamente — marcar uma encomenda como paga sem intervenção de um fornecedor de pagamentos (transferência bancária, numerário). Dê esta permissão apenas a uma caixa ou contabilidade geridas por si: quem a tiver pode emitir bilhetes sem que entre dinheiro.

Dê a cada integração uma chave própria apenas com o que ela precisa. Assim pode revogar uma sem estragar as restantes, e vê na lista quais ainda estão a ser usadas.

Aliás, uma chave não é uma palavra-passe que dê acesso à sua conta: dá apenas o que nela estiver assinalado, e pertence a uma única organização. Mesmo que ande por aí perdida, ninguém a pode usar para consultar os dados de outra pessoa.

Experimentar primeiro em segurança

Além de uma chave normal, pode criar uma chave de teste. Esta lê exatamente os mesmos dados. Se também puder 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. Uma chave de teste não pode configurar webhooks.

Existe precisamente para este momento — alguém que está a experimentar e ainda não tem a certeza do que está a fazer. Deixe o seu programador web começar com uma chave de teste e mudar apenas no fim.

Uma coisa a saber: também uma encomenda de teste reserva um lugar real (até ser eliminada), e o e-mail de confirmação é mesmo enviado. Por isso, peça ao seu programador web que teste com um produto ou horário criado para esse efeito.

E se algo correr mal?

Revogue a chave. Na lista, clique em Revogar e, a partir desse momento, deixa de funcionar. A integração para, os seus dados ficam. Não existe nenhuma situação em que uma chave possa causar algo que não consiga parar com um clique.

Quanto custa

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, em que plano está a API e um botão Ir para Assinatura — sem chaves. O que está incluído em cada plano está na página de preços de Passavo.

Para saber mais

• Criar uma chave de API — o próprio ecrã, passo a passo.
• 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 próprio ecrã, passo a passo.
• O portal para programadores — para quem faz a integração.