Mais cedo ou mais tarde, toda a equipa quer que os documentos falem com o restante software: carregar um ficheiro por script, iniciar um fluxo a partir de um agendador ou ser avisada quando um documento termina o processamento. O AuraDoc oferece dois caminhos complementares. A API REST permite que os seus sistemas peçam algo ao AuraDoc, e os webhooks permitem que o AuraDoc avise os seus sistemas de que algo aconteceu. Este artigo percorre ambos e os pormenores de segurança que contam em produção.
Chaves de API e âmbitos
Tudo começa com uma chave de API. Crie uma em Dashboard › Settings › API keys, dê-lhe um nome e escolha os âmbitos. Os âmbitos limitam o que a chave pode fazer, pelo que uma chave usada só para carregar ficheiros não precisa de permissão para administrar mais nada. Uma chave não cria outra com âmbitos maiores que os seus, e as permissões efetivas são sempre as que a chave e o papel da pessoa têm em comum, como descrito em papéis e permissões da equipa. Os pedidos levam a chave no cabeçalho Authorization como token bearer.
A mesma página mostra estatísticas de utilização por chave, para ver que integração está ativa e qual ficou em silêncio. Nos planos pagos também pode definir um limite de pedidos para uma chave concreta, útil quando um script ruidoso não deve prejudicar os outros. Se uma chave for divulgada, elimine-a e crie outra; nada mais precisa de mudar no AuraDoc.
O que a API faz
A página de integrações na documentação lista o endereço base e traz exemplos prontos a copiar. Hoje pode carregar um documento, pedir ao AuraDoc que ingira um documento a partir de um URL, iniciar a execução de um fluxo e criar um pedido de assinatura, cada um com um único pedido autenticado. São as mesmas operações que as pessoas fazem no painel, por isso o resultado criado pela API aparece na interface como qualquer outro.
Se prefere consultar a receber chamadas, existem endpoints de gatilho que devolvem novos documentos, execuções de fluxo concluídas e assinaturas concluídas, além de um catálogo que os descreve. Ferramentas que não recebem webhooks, como suplementos de folhas de cálculo ou plataformas sem código, podem consultá-los a intervalos. A referência completa está na página de documentação de integrações.
Webhooks de saída
Para notificações em tempo real, abra Dashboard › Webhooks e adicione um endpoint. Escolhe os eventos que lhe interessam numa lista, que inclui documento criado, classificado e eliminado, OCR e tradução concluídos ou com falha, eventos de fluxo, avisos de quota de armazenamento e eventos de assinatura. Ao guardar, o AuraDoc mostra o segredo de assinatura uma única vez. Copie-o de imediato para o serviço recetor; se o perder, rode o segredo e é gerado um novo, ficando a rotação registada na trilha de auditoria.
Pode moldar o conteúdo com um modelo, até alguns milhares de carateres, e validá-lo antes de guardar. Um botão de teste envia um evento de exemplo, marcado com um cabeçalho de teste, para confirmar que o endpoint responde e lê o corpo antes de depender dele. Cada webhook pode ser desativado sem ser eliminado, o que ajuda em janelas de manutenção.
Verificar assinaturas e tratar falhas
Cada entrega é assinada. O AuraDoc calcula um HMAC-SHA256 sobre a marca temporal e o corpo em bruto com o seu segredo e envia o resultado no cabeçalho de assinatura, juntamente com cabeçalhos do nome do evento, do id do webhook, do id da entrega, da marca temporal e do número de tentativas. O recetor deve recalcular a assinatura a partir do corpo em bruto, compará-la em tempo constante e rejeitar pedidos com marca temporal demasiado antiga. Assim ninguém forja um evento para o seu endpoint, mesmo conhecendo o endereço.
Os endpoints falham, e o AuraDoc prevê isso. Quando uma entrega falha, é repetida automaticamente com intervalos crescentes, de cinco minutos até seis horas. A vista de entregas mostra cada tentativa com o resultado, e pode acionar uma nova tentativa manualmente depois de resolver o problema. Como o mesmo id de entrega é reutilizado nas novas tentativas, o recetor pode ignorar duplicados com segurança. Para combinar webhooks com ficheiros que chegam de fornecedores, veja armazenamento na nuvem e pastas vigiadas.