Tutorial: Criar um workflow

Um exemplo prático de uso da API de desenvolvedor do Portant para criar um workflow, executá-lo por meio de sua fonte webhook e monitorar eventos quando documentos são criados. Todas as requisições usam cURL. Substitua <DEVELOPER_ACCESS_TOKEN> pelo token fornecido pela equipe de integrações do Portant.

Dica: antes de começar, crie e execute um workflow no aplicativo web Portant Workflow para familiarizar-se com o funcionamento dos workflows. Recomendamos um template do Google Docs, o que também confirma que sua conta está corretamente autorizada com as APIs do Google.

Este tutorial pressupõe que você concluiu as etapas descritas no guia Visão geral para desenvolvedores.

Etapa 1. Criar um workflow

Nomearemos o workflow como "Developer Workflow" e o criaremos com o endpoint Workflows POST.

curl --location --request POST 'https://api.portant.co/v0/workflows/' \
--header 'Authorization: <DEVELOPER_ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Developer Workflow"
}'

Uma requisição bem-sucedida retorna 201 Created com um corpo JSON semelhante a este:

{
    "id": "wkf_<id>",
    "name": "Developer Workflow",
    "icon": "DocumentText",
    "color": "#cccccc",
    "status": "INCOMPLETE",
    "autoCreate": true,
    "owner": {
        "id": "usr_<id>",
        "name": "Your Name",
        "email": "you@email.com"
    },
    "team": null,
    "source": {
        "id": "src_<id>",
        "sourceType": "WEBHOOK",
        "sourceFields": [],
        "webhookUrl": "https://webhooks.portant.co/<webhook_token>"
    },
    "documents": [],
    "outgoingWebhook": null,
    "createdByApi": true,
    "createdAt": "2024-08-13T17:49:28.639426+10:00",
    "updatedAt": "2024-08-13T17:49:28.659242+10:00"
}

Salve o valor de id. Você o utilizará nas próximas requisições.

Se você abrir https://app.portant.co/w/wkf_<id>/ com esse ID, verá o seu novo workflow no aplicativo web. Dois campos são mais importantes aqui: source.webhookUrl e status.

source.webhookUrl é o endereço para o qual você enviará dados via POST para iniciar uma automação assim que o workflow estiver completo. Salve este valor também.

status está como "INCOMPLETE" porque o workflow ainda não possui documentos de template. Um workflow precisa de uma fonte e de pelo menos um template para poder ser executado. Adicionaremos um template a seguir.

Etapa 2. Criar um documento de template

Para adicionar um template, copie um arquivo do Google Docs existente para o workflow.

curl --location --request POST 'https://api.portant.co/v0/workflows/wkf_<id>/documents/' \
--header 'Authorization: <DEVELOPER_ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "file_id": "1frlTt7Jj8HuXWHkS9o0mshLaym6NQBImsAIhw4Iiew4"
}'

file_id é o ID de um arquivo no Google Drive ao qual você tem acesso. É possível encontrar o ID de um arquivo na sua URL. O ID de exemplo acima provém de este documento público do Portant, portanto você pode utilizá-lo para testes.

A resposta tem o seguinte formato:

{
    "id": "doc_<id>",
    "documentType": "GOOGLE_DOCS",
    "file": {
        "id": "1MvPvT3cLilEw6ktXxjOYFUGrZH6JO8dm5Gpj8GExMcc",
        "name": "Developer Workflow - [Template]",
        "url": "https://docs.google.com/document/d/1MvPvT3cLilEw6ktXxjOYFUGrZH6JO8dm5Gpj8GExMcc/edit?usp=drivesdk",
        "mimeType": "application/vnd.google-apps.document"
    },
    "outputName": "Developer Workflow - {{Timestamp}}",
    "createPdfCopy": false,
    "removeOutput": false,
    "enablePdfPassword": false,
    "pdfPassword": "",
    "pdfPasswordPreventCopy": false,
    "previewUrl": "https://preview.portant.co/doc_LcQWshvjR9XLzQ"
}

Um novo template foi adicionado ao seu workflow com uma cópia do arquivo fornecido. O recurso de documento possui um conjunto de opções que alteram a forma como os documentos de saída são criados. É possível alterá-las com uma requisição PATCH para o endpoint Document.

Se você fizer um GET no workflow novamente, o status será "COMPLETE". Antes de executar a primeira automação, vamos também configurar as notificações de eventos.

Etapa 3. Monitorar eventos de automação

Para ser notificado quando uma automação for executada, registre um webhook de saída no workflow. Para testes, você pode criar um webhook temporário em webhook.site.

curl --location --request POST 'https://api.portant.co/v0/workflows/wkf_<id>/outgoing-webhook/' \
--header 'Authorization: <DEVELOPER_ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "webhookUrl": "https://webhook.site/<token>"
}'

Você receberá uma resposta 201 Created com a URL registrada. O workflow está pronto para ser executado.

Etapa 4. Enviar dados para a fonte webhook via POST

Para iniciar uma automação, envie um corpo JSON via POST para a URL de origem do webhook do fluxo de trabalho (a retornada na Etapa 1).

curl --location --request POST 'https://webhooks.portant.co/<webhook_address>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "Name": "Jeremy the Koala"
}'

O endpoint retorna 200 OK com um corpo JSON vazio. Em até um minuto, a caixa de entrada do webhook.site deverá exibir um evento com um link para o novo documento no seu Google Drive.

No aplicativo web Portant Workflow, a nova saída também aparece na página de saídas do fluxo de trabalho. É isso: você criou e executou seu primeiro fluxo de trabalho por meio da Developer API.

Para detalhes sobre cada endpoint e recurso, consulte o restante da referência da API. Se tiver dúvidas ou solicitações de funcionalidades, entre em contato com a equipe de sucesso do cliente ou de integrações.

(E sim, Jeremy é o mascote do Portant. 🐨)