Tutorial: Crear un flujo de trabajo

Un ejemplo práctico del uso de Portant Developer API para crear un flujo de trabajo, ejecutarlo mediante su fuente webhook y recibir notificaciones de eventos cuando se crean documentos. Todas las solicitudes usan cURL. Sustituya <DEVELOPER_ACCESS_TOKEN> por el token que el equipo de integraciones de Portant le proporcionó.

Consejo: antes de comenzar, cree y ejecute un flujo de trabajo en la aplicación web Portant Workflow para familiarizarse con el funcionamiento de los flujos de trabajo. Recomendamos una plantilla de Google Docs, lo cual también confirma que su cuenta está correctamente autorizada con las APIs de Google.

Este tutorial asume que ha completado los pasos de la guía Developers overview.

Paso 1. Crear un flujo de trabajo

Nombraremos el flujo de trabajo "Developer Workflow" y lo crearemos con el 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"
}'

Una solicitud correcta devuelve 201 Created con un cuerpo JSON similar 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"
}

Guarde el valor de id. Lo usará en las siguientes solicitudes.

Si abre https://app.portant.co/w/wkf_<id>/ con ese ID, verá su nuevo flujo de trabajo en la aplicación web. Dos campos son los más importantes aquí: source.webhookUrl y status.

source.webhookUrl es la dirección a la que enviará datos mediante POST para iniciar una automatización una vez que el flujo de trabajo esté completo. Guárdela también.

status es "INCOMPLETE" porque el flujo de trabajo aún no tiene documentos de plantilla. Un flujo de trabajo necesita tanto una fuente como al menos una plantilla para poder ejecutarse. A continuación, agregaremos una plantilla.

Paso 2. Crear un documento de plantilla

Para agregar una plantilla, copie un archivo de Google Docs existente en el flujo de trabajo.

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 es el ID de un archivo en Google Drive al que tiene acceso. Puede encontrar el ID de un archivo en su URL. El ID de ejemplo anterior proviene de este documento público de Portant, por lo que puede usarlo para realizar pruebas.

La respuesta tiene el siguiente aspecto:

{
    "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"
}

Se ha agregado una nueva plantilla a su flujo de trabajo con una copia del archivo que proporcionó. El recurso de documento cuenta con un conjunto de opciones que modifican la forma en que se crean los documentos de salida. Puede cambiarlas mediante una solicitud PATCH al endpoint Document.

Si vuelve a hacer GET del workflow, el estado ahora es "COMPLETE". Antes de ejecutar la primera automatización, también configuraremos las notificaciones de eventos.

Paso 3. Recibir notificaciones de eventos de automatización

Para recibir notificaciones cuando se ejecute una automatización, registre un webhook saliente en el flujo de trabajo. Para realizar pruebas, puede crear un webhook temporal en 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>"
}'

Recibirá una respuesta 201 Created con la URL que registró. El flujo de trabajo está listo para ejecutarse.

Paso 4. Enviar datos a la fuente webhook mediante POST

Para iniciar una automatización, envíe mediante POST un cuerpo JSON a la URL de origen del webhook del flujo de trabajo (la que se devolvió en el Paso 1).

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

El endpoint devuelve 200 OK con un cuerpo JSON vacío. En menos de un minuto, la bandeja de entrada de webhook.site debería mostrar un evento con un enlace al nuevo documento en su Google Drive.

En la aplicación web de Portant Workflow, la nueva salida también aparece en la página de salidas del flujo de trabajo. Eso es todo: ha creado y ejecutado su primer flujo de trabajo a través de la API para desarrolladores.

Para obtener detalles sobre cada endpoint y recurso, consulte el resto de la referencia de la API. Si tiene preguntas o solicitudes de funciones, póngase en contacto con el equipo de éxito del cliente o el equipo de integraciones.

(Y sí, Jeremy es la mascota de Portant. 🐨)