API de código QR e webhooks
A API permite que o seu próprio software crie, atualize, consulte e exclua códigos QR e leia o resumo de escaneamentos de cada um. Os webhooks enviam um aviso assinado ao seu servidor quando um código é alterado, quando uma pessoa o escaneia ou quando alguém responde ao formulário de uma página de destino.
O que a API e os webhooks fazem
A API REST fica no caminho /api/v1 e responde em JSON. Ela pode listar códigos com busca, filtro por tag e páginas de até cem itens, consultar um código, criar, atualizar e excluir códigos, devolver o SVG simples de um código e resumir os escaneamentos dos últimos trinta dias. Uma chave é um token Bearer que começa com qrk_ e pertence a um único espaço de trabalho, então uma requisição só consegue alterar os códigos desse espaço.
Um webhook é um endereço HTTPS que você cadastra com os eventos sobre os quais quer ser avisado. O app envia uma mensagem JSON para cada evento: um código é criado, atualizado ou excluído, um escaneamento feito por uma pessoa é registrado ou um formulário de página de destino é respondido. Uma ação de teste envia um evento ping, para que você confira o seu receptor antes do tráfego real. Cada entrega é assinada com HMAC-SHA256 usando o segredo do webhook, sobre o carimbo de data e hora e o corpo da mensagem.
A API é para quem desenvolve integrações e não altera a aparência dos códigos. O SVG é simples, em preto e branco, sem logotipo, formas ou cores, porque imagens estilizadas são feitas no editor. A API exige o plano Team. As chaves sobrevivem a uma troca para um plano inferior, mas deixam de funcionar até que o espaço de trabalho volte a um plano que inclua a API.
Como começar a usar a API
-
01
Crie uma chave como proprietário
Abra a página da API como proprietário, dê à chave um nome, como o do servidor que vai usá-la, e crie a chave. O token completo aparece uma única vez, então copie-o imediatamente para o seu cofre de segredos. Depois disso, a página mostra apenas o nome, o prefixo, a data de criação e o último uso.
-
02
Envie a chave em cada requisição
Envie o token em um cabeçalho Authorization, com a palavra Bearer, um espaço e o token. Faça primeiro a verificação da conta: a resposta indica o espaço de trabalho, a chave e os créditos restantes, o que confirma que a configuração funciona. Uma chave ausente ou incorreta recebe uma resposta de não autorizado.
-
03
Crie, atualize e consulte códigos
Envie o nome, o tipo (o padrão é uma URL de site), o conteúdo e os campos opcionais: dynamic, slug, expiry, password, um domínio verificado, tags e style. Criar um código custa um crédito, enquanto consultar e atualizar são gratuitos. Uma requisição que falha na validação devolve os motivos e restitui o crédito.
Onde a API se encaixa
-
Ingressos e reservas
Quando um sistema de reservas confirma um assento, ele cria um código dinâmico para aquele ingresso e envia o link curto e o SVG ao comprador. O e-mail ou o passe para a carteira digital traz o mesmo código, e ninguém precisa copiá-lo à mão.
-
Estoque e patrimônio
Um sistema de armazém pode criar um código por item, usando o número do item como tag. Cada escaneamento é registrado, e o sistema pode consultar o resumo de trinta dias de qualquer item para ver quais itens foram conferidos recentemente.
-
Cardápios de restaurante a partir de uma planilha
Um script pode ler uma planilha de links de cardápio e atualizar o conteúdo de cada código dinâmico pela API. Os códigos impressos continuam os mesmos, e a atualização vale a partir do próximo escaneamento.
-
Check-in e formulários de feedback de eventos
A equipe de um evento pode publicar uma página de destino com um formulário e receber um webhook para cada resposta. Um sistema separado reage ao evento, então ninguém precisa ficar consultando as respostas.
-
Monitoramento e alertas
Um receptor de webhooks pode armazenar os eventos de escaneamento por país e dispositivo e disparar uma mensagem quando um código deixa de ser escaneado. Quem define o que é um problema é o seu sistema, porque o app entrega os eventos e não os avalia.
Dicas para uma integração confiável
- Guarde a chave como uma senha
- As chaves são exibidas uma única vez e guardadas apenas como resumo criptográfico, por isso o app não consegue mostrá-las de novo. Se uma chave vazar, revogue-a na página da API e crie outra. A revogação interrompe de imediato todas as requisições que usam o token antigo.
- Respeite o limite de requisições e os créditos
- Cada chave pode enviar 120 requisições por minuto. Uma requisição acima desse ritmo recebe uma resposta de excesso de requisições. Quando os créditos acabam, criar um código retorna uma resposta de pagamento necessário, cujo código de erro informa que não restam créditos. Por enquanto o app não permite comprar mais créditos, então planeje as tarefas em lote de acordo com o saldo.
- Verifique assinaturas e carimbos de data e hora
- Calcule o HMAC-SHA256 do carimbo de data e hora, de um ponto e do corpo bruto da mensagem, usando o seu segredo, e compare o resultado com o cabeçalho de assinatura. Recuse carimbos muito antigos, para que uma requisição capturada não possa ser reenviada, e use o identificador da entrega para ignorar uma repetição.
- Use um endpoint que você controle
- Os endereços de webhook precisam usar HTTPS, não podem conter credenciais e precisam resolver para endereços públicos. Hosts locais e faixas de rede privada são recusados, e redirecionamentos não são seguidos. Uma entrega com falha é repetida até cinco vezes, com intervalos cada vez maiores.
Perguntas sobre a API e os webhooks
Qual plano inclui a API?
O plano Team. Criar chaves e webhooks exige esse plano, e a API responde com status de pagamento necessário quando o espaço de trabalho está em um plano sem ele. As chaves existentes são mantidas em caso de downgrade, então voltam a funcionar quando o plano é restabelecido.
Para que serve um crédito?
Um crédito é gasto para cada código criado pela API. Consultar, atualizar e excluir códigos, além de ler o resumo de escaneamentos, não custam nada. Se a criação falhar na validação, o crédito é devolvido.
Com quantos créditos um espaço de trabalho começa?
Quarenta, que é o valor padrão do banco de dados para cada espaço de trabalho. O app ainda não tem uma página para comprar mais créditos, então confira o saldo na página da API ou pela consulta de conta antes de uma importação grande.
Dá para obter o código como imagem pela API?
Sim, como SVG simples. Você escolhe o tamanho do módulo, de um a vinte, e a margem, de zero a dez. A imagem é preta e branca e não tem logotipo. Se o conteúdo for longo demais para um código QR, a API informa isso. Para formas, cores ou logotipo, use o editor.
Quais eventos posso receber por webhook?
Criação, atualização e exclusão de um código, escaneamento feito por uma pessoa e resposta a um formulário de página de destino. Requisições de bots e pré-visualizações de links não disparam eventos de escaneamento, e um evento de teste pode ser enviado a qualquer webhook.
O que acontece quando o meu endpoint fica fora do ar?
A entrega é repetida até cinco vezes, com intervalos cada vez maiores, e cada tentativa tem tempo limite de conexão de cinco segundos e tempo limite de leitura de dez. Depois da última falha, a entrega é marcada como falha, e a página de webhooks mostra o código de resposta e o último erro.
Crie seu primeiro código em um minuto
O editor é gratuito. Crie uma conta quando quiser salvar códigos, acompanhar escaneamentos ou mudar um destino depois.