Quando os documentos começam noutro sistema

A pergunta que surge na segunda reunião: «integram com o nosso sistema?». Até agora, a resposta honesta era não. Agora, a resposta é esta: tem um portal, um CRM ou um sistema de contabilidade onde o negócio já existe, e o DocuTract pode funcionar como parte dele.

A sexta funcionalidade desta vaga é a porta para fora. Um token com que o seu sistema nos chama, um endereço para onde escrevemos por iniciativa própria e uma descrição aberta de tudo o que há pelo meio.

Um token que não lhe conseguimos mostrar duas vezes

Um token é criado no ecrã Integrações: um nome que vai reconhecer mais tarde, para saber que sistema o está a usar, e uma lista do que lhe é permitido fazer. Depois é mostrado uma vez.

Não é esquecimento, é assim que tem de funcionar um produto que guarda a chave de outra pessoa. Guardamos apenas um hash: mostrar o token uma segunda vez é algo que nem nós conseguimos fazer, o que significa que não nos pode ser roubado. A lista guarda os primeiros caracteres, as permissões e a data da última utilização, para que se veja que token está ativo e se alguém ainda o usa.

Revogar desativa-o instantaneamente. O registo dele fica: que existiu e quando deixou de funcionar faz parte do histórico do espaço de trabalho, não é lixo.

As permissões são verificadas em cada endereço separadamente. Um token que só pode ler modelos recebe um claro «falta o âmbito documents:write» quando tenta criar um documento, e não um vazio «não encontrado». Partimos do princípio de que há uma pessoa real a montar a integração, e uma resposta que não explica nada custa-lhe uma noite.

O que a API consegue fazer

Tudo o que pode fazer no ecrã, só que sem o ecrã: abrir um processo e carregar digitalizações para ele, criar um documento a partir de um modelo com os valores já preenchidos, perguntar em que fase está, obter todos os valores juntamente com a digitalização de onde cada um foi lido, e obter uma ligação de curta duração para o ficheiro final.

É esta última parte que distingue esta integração das outras. O seu sistema não recebe apenas um ficheiro preenchido, recebe cada valor com a sua proveniência: a digitalização, o campo, o grau de confiança da leitura. A mesma fonte que uma pessoa vê no ecrã de revisão está disponível para o código.

A descrição de cada endereço e campo é gerada a partir do próprio código e publicada abertamente, sem token: /api/v1/openapi.json. Documentação que é preciso pedir primeiro é documentação que ninguém lê.

Webhooks e um registo honesto

Não precisa de nos perguntar se um documento está pronto. Indique-nos um endereço e assinale os eventos: documento pronto, documento falhado, processo pronto, divergência encontrada, cliente enviou um ficheiro.

Cada pedido é assinado, e o segredo que verifica a assinatura é mostrado uma vez, tal como o token. Se o seu servidor respondeu outra coisa, ou não respondeu de todo, tentamos de novo: ao fim de um minuto, de cinco, de meia hora, de duas horas e de dez. Depois paramos, porque uma integração que ninguém mantém não deve gastar os recursos de alguém para sempre.

E depois vem a parte para a qual tudo isto foi escrito. Quando o outro lado diz «o nosso sistema não recebeu nada», a resposta está no ecrã: o evento, a hora, quantas tentativas, que código de resposta voltou e o início do corpo da resposta. Vê-se que respondeu 500 cinco vezes. Isto não é uma ajuda de depuração para nós, é uma resposta para o seu engenheiro.

Ao lado, dois botões para a fase em que uma integração ainda está a ser configurada. Enviar teste envia um pedido de teste de imediato, sem esperar por um evento real, para que um recetor possa ser verificado antes de qualquer trabalho passar por ele. Tentar novamente, junto a uma entrega falhada, faz mais uma tentativa de imediato e não reinicia o histórico: as quatro tentativas falhadas ficam registadas, porque essa é a verdade sobre o que esta notificação custou.

Os limites que impomos a nós próprios

Um webhook só vai para https e só para um endereço público: um endereço dentro de uma rede privada é recusado tanto quando é guardado como antes de cada tentativa, porque um nome de anfitrião que ontem apontava para fora pode hoje apontar para dentro. O limite de frequência conta por token e não por endereço, para que um vizinho no mesmo servidor não gaste a sua quota, e quem o ultrapassar recebe um honesto «volte daqui a tantos segundos».

A API e os webhooks fazem parte do plano Team. Se um espaço de trabalho mudar para outro plano, o que já foi criado continua visível e pode ser revogado: chaves a que ninguém consegue chegar são piores do que uma funcionalidade paga.

O que não está nesta versão

O plano desta fase descrevia mais duas partes: exportar um documento final para o Google Drive, o OneDrive ou o Dropbox, e enviá-lo para assinatura através do DocuSign ou do Dropbox Sign. Ambas precisam de credenciais desses fornecedores, que neste momento não temos, e escrever uma integração que não pode ser testada em lado nenhum seria fazer passar código por escrever por código acabado. Ficam no plano como versões autónomas.

O que vem a seguir

A sétima e última funcionalidade desta vaga é a geração em lote: uma lista de cinquenta linhas ou um arquivo de digitalizações em vez de cinquenta preenchimentos idênticos feitos à mão, com o progresso à vista e a opção de repetir apenas os que não funcionaram.

A lista completa está em o que estamos a construir a seguir, e as instruções passo a passo para as integrações estão no centro de ajuda.