Documentação de Orders RPA

raphael.aguiar · Dezembro 31, 2025, 1:21pm

Introdução

Orders são comandos que podem ser retornados por scripts JavaScript executados no sistema de automação de fluxos (RPA). Cada order representa uma ação que será executada pelo sistema de forma assíncrona após o script ser processado.

As orders são utilizadas em scripts de automação que são executados em resposta a eventos de fluxo, como mudanças de etapa, criação de cards, ou alterações em formulários.

Como Usar Orders

Estrutura Básica

Uma order é um objeto JavaScript com a seguinte estrutura:

{
  name: 'nome-da-order',
  args: {
    // parâmetros específicos da order
  },
  priority: 4,  // opcional (padrão: 3)
  hash: 'hash-unico'  // opcional, usado para evitar duplicatas
}

Retornando Orders

As orders devem ser retornadas como um array ou objeto único. O sistema processará todas as orders retornadas:

// Retornando um array de orders
return [
  {
    name: 'upinsert',
    args: {
      tableName: 'user_tabela',
      data: dados
    }
  },
  {
    name: 'change-card',
    args: {
      step_key: 123
    }
  },
  {
    name: 'add-comment',
    args: {
      text: 'Processamento concluído'
    }
  }
];

// Retornando uma única order
return {
  name: 'change-card',
  args: {
    step_key: 123
  }
};

Referência de Orders

new-card

Cria um novo card.

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`puca_pid`	string	Não	PID do card
`flow`	string	Sim	PID do fluxo
`step`	string	Não	PID da etapa (alternativa a `step_key`)
`step_key`	number	Não	Chave numérica da etapa
`title`	string	Sim	Título do card
`id_table_flow`	string	Sim	PID do formulário associado
`company`	string	Não	PID da empresa
`assigned`	string	Não	PID do usuário responsável
`assigned_username`	string	Não	Username do responsável (alternativa a `assigned`)
`skipNotification`	boolean	Não	Se `true`, não envia notificações

Exemplo

return {
  name: 'new-card',
  args: {
    puca_pid: 'uuid-do-card',
    flow: 'uuid-do-fluxo',
    step_key: 123,
    title: 'Novo Card de Processamento',
    id_table_flow: 'uuid-do-formulario',
    company: 'uuid-da-empresa',
    assigned_username: 'usuario.responsavel',
    skipNotification: false
  }
};

Casos de Uso

Criar cards automaticamente em resposta a eventos
Criar cards de monitoramento quando certas condições são atendidas
Criar sub-cards relacionados a um card principal

change-card

Altera propriedades de um card existente. O card é identificado automaticamente pelo contexto de execução.

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`step`	string	Não	PID da etapa (alternativa a `step_key`)
`step_key`	number	Não	Chave numérica da etapa
`assigned`	string	Não	PID do usuário responsável
`assigned_username`	string	Não	Username do responsável. Valores especiais: `{{previousUser}}` para o usuário anterior
`title`	string	Não	Novo título do card
`skipNotification`	boolean	Não	Se `true`, não envia notificações

Exemplo

return {
  name: 'change-card',
  args: {
    step_key: 123,
    assigned_username: '{{previousUser}}',
    title: 'Card Atualizado',
    skipNotification: false
  },
  priority: 4
};

Valores Especiais para `assigned_username`

{{previousUser}}: Retorna o card para o usuário que estava responsável anteriormente
username: Nome de usuário específico

Casos de Uso

Mover card para próxima etapa
Retornar card ao usuário anterior após processamento
Atualizar responsável do card
Finalizar processamento de scripts

change-form

Atualiza dados do formulário associado ao card atual. Os campos fornecidos serão atualizados no registro do formulário.

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`[campo]`	any	Sim	Qualquer campo do formulário pode ser atualizado. O objeto deve conter os campos a serem atualizados com seus valores

Exemplo

return {
  name: 'change-form',
  args: {
    user_campo1: 'valor1',
    user_campo2: 'valor2',
    user_status: 'processado'
  }
};

Observações

O puca_pid do formulário é automaticamente obtido do card atual
Apenas os campos fornecidos serão atualizados
Campos que não existem no formulário serão ignorados

Casos de Uso

Atualizar campos calculados
Atualizar status de processamento
Sincronizar dados de integrações externas

delete

Deleta um registro de uma tabela específica.

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`tableName`	string	Sim	Nome da tabela
`pucaPid`	string	Sim	PID do registro a ser deletado
`omitExceptions`	boolean	Não	Se `true`, ignora erros se o registro não existir (padrão: `false`)

Exemplo

return {
  name: 'delete',
  args: {
    tableName: 'user_tabela',
    pucaPid: 'uuid-do-registro',
    omitExceptions: false
  }
};

Observações

Atenção: O parâmetro omitExceptions pode mascarar erros importantes. Use com cuidado e apenas quando necessário.
A deleção é permanente e não pode ser desfeita
Verifique permissões antes de deletar registros

Casos de Uso

Limpar registros temporários
Remover dados obsoletos após processamento
Deletar registros relacionados quando um card é cancelado

upinsert

Realiza operação de upsert (insert ou update) em uma tabela. Se o registro existir (baseado em uk ou puca_pid), será atualizado. Caso contrário, será inserido.

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`tableName`	string	Sim	Nome da tabela
`data`	object	Sim	Objeto com os dados do registro
`uk`	string	Não	Array de nomes de campos que formam a chave única para verificar se o registro existe
`hash`	string	Não	Hash único para evitar duplicatas (usado internamente)

Exemplo

// Upinsert simples
return {
  name: 'upinsert',
  args: {
    tableName: 'user_implantacao_jira',
    data: {
      puca_pid: 'uuid-opcional', // se existir, atualiza; se não, cria novo
      user_chave_jira: 'KEY-123',
      user_cliente: 'uuid-cliente',
      user_empresa: 'uuid-empresa',
      user_produto: 'uuid-produto',
      user_resumo: 'Resumo da implantação',
      user_situacao: 'Em andamento'
    }
  },
  priority: 4
};

// Upinsert com chave única customizada
return {
  name: 'upinsert',
  args: {
    tableName: 'user_hs_maxpedido',
    data: {
      user_data_geracao: '2024-01-01',
      user_cod_cliente: 'uuid-cliente',
      user_total: 85.5
    },
    uk: ['user_data_geracao', 'user_cod_cliente'] // campos que formam a chave única
  }
};

// Upinsert com hash para evitar duplicatas
return {
  name: 'upinsert',
  args: {
    tableName: 'puca_crm_api_interaction',
    data: {
      target: 'uuid-cliente',
      type: 'uuid-tipo',
      text: 'Interação realizada'
    }
  },
  hash: 'hash-unico-para-evitar-duplicatas'
};

Comportamento Especial

Para a tabela puca_crm_api_interaction:

Se link não for fornecido, será automaticamente gerado como puca-flow-front/card/{cardPid}
Se author não for fornecido, será automaticamente definido como o robot user

Observações

Se puca_pid estiver presente em data e o registro existir, ele será atualizado
Se nenhum registro for encontrado, um novo será criado
Campos de data devem estar no formato ISO string
Se uk for fornecido, o sistema busca por registros com esses campos e atualiza se encontrar
Atenção: Se você utilizar null como valor em qualquer um dos campos listados em uk (exemplo: args: { data: { campo: null }, uk: ['campo'] }), a verificação de unicidade não funcionará corretamente. Evite utilizar null em campos de chave única para garantir o funcionamento adequado da upsert.

Casos de Uso

Sincronizar dados de integrações externas
Atualizar ou criar registros baseados em chaves únicas
Manter dados atualizados sem duplicatas
Processar dados de APIs externas

add-comment

Adiciona um comentário ao card atual.

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`text`	string	Sim	Texto do comentário

Exemplo

return {
  name: 'add-comment',
  args: {
    text: 'Processamento concluído com sucesso'
  },
  priority: 4
};

Observações

O comentário é automaticamente associado ao card atual
O autor do comentário será o robot user
Comentários são úteis para rastreabilidade e debugging

Casos de Uso

Registrar erros ou avisos durante processamento
Documentar decisões tomadas pelo script
Fornecer feedback sobre o processamento
Registrar validações e verificações

add-task

Cria uma tarefa relacionada ao card atual.

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`kind`	string	Sim	Tipo da tarefa
`title`	string	Sim	Título da tarefa
`description`	string	Não	Descrição da tarefa
`start_date`	Date	Não	Data de início
`end_date`	Date	Não	Data de término
`all_day`	boolean	Não	Se é tarefa de dia inteiro
`assigned`	string	Não	PID do usuário responsável
`related_entity`	string	Não	Nome da entidade relacionada (padrão: `puca_flow_api_card`)
`related_entity_id`	string	Não	PID da entidade relacionada (padrão: PID do card atual)
`blockedStep`	string	Não	PID da etapa que está bloqueada por esta tarefa

Exemplo

return {
  name: 'add-task',
  args: {
    kind: 'reminder',
    title: 'Revisar processamento',
    description: 'Verificar se todos os dados foram processados corretamente',
    end_date: new Date('2024-12-31'),
    assigned: 'uuid-do-usuario',
    blockedStep: 'uuid-da-etapa'
  }
};

Observações

A tarefa é automaticamente relacionada ao card atual se related_entity_id não for fornecido
Tarefas podem bloquear etapas do fluxo através do campo blockedStep

Casos de Uso

Criar lembretes para revisão
Agendar tarefas futuras
Bloquear etapas até que uma ação seja concluída
Criar tarefas de acompanhamento

insert-interaction

Insere uma interação CRM com indicadores associados. Esta order é mais completa que add-crm-interaction pois permite associar indicadores de dados.

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`date`	Date	Sim	Data da interação
`interaction_text`	string	Sim	Texto da interação
`interaction_type`	string	Sim	PID do tipo de interação
`target`	string	Sim	PID do alvo da interação (geralmente cliente)
`link`	string	Não	Link relacionado (padrão: link do card)
`indicators`	array	Sim	Array de indicadores associados

Estrutura de `indicators`

Cada indicador no array deve ter:

{
  indicator_field: string,    // Nome do campo do indicador
  indicator_config: string,    // PID da configuração do indicador
  value: any,                 // Valor do indicador
  refs: string[]              // Array de PIDs de referência
}

Exemplo

return {
  name: 'insert-interaction',
  args: {
    date: new Date(),
    interaction_text: 'Cliente contatado via telefone',
    interaction_type: 'uuid-tipo-interacao',
    target: 'uuid-cliente',
    link: 'puca-flow-front/card/uuid-card', // opcional
    indicators: [
      {
        indicator_field: 'user_valor_venda',
        indicator_config: 'uuid-config-indicador',
        value: 1500.00,
        refs: ['uuid-produto-1', 'uuid-produto-2']
      }
    ]
  }
};

Observações

O link é automaticamente gerado se não fornecido
O author é automaticamente definido como o robot user
Indicadores são criados em tabelas separadas e vinculados à interação

Casos de Uso

Registrar interações com clientes incluindo métricas
Criar histórico de vendas com indicadores
Registrar contatos com dados de performance
Rastrear interações com múltiplas referências

call-api

Chama uma API externa de outro módulo do sistema.

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`path`	string	Sim	Caminho do endpoint da API
`method`	string	Não	Método HTTP (padrão: `'post'`)
`headers`	object	Não	Headers HTTP customizados
`body`	any	Não	Corpo da requisição
`moduleName`	string	Não	Nome do módulo a ser chamado

Exemplo

return {
  name: 'call-api',
  args: {
    path: '/api/endpoint',
    method: 'post',
    headers: {
      'Custom-Header': 'valor'
    },
    body: {
      campo1: 'valor1',
      campo2: 'valor2'
    },
    moduleName: 'puca-crud' // opcional
  }
};

Observações

A chamada é feita com autenticação do robot user
Use para comunicação entre módulos do sistema
O método padrão é post se não especificado
Timeout padrão é aplicado
Este metodo não suporta calls para fora do sistema Puca

Casos de Uso

Chamar endpoints de outros módulos
Integrar funcionalidades entre serviços
Disparar processamentos em outros sistemas
Sincronizar dados entre módulos

call-plugin

Chama um plugin configurado no sistema.

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome do plugin
`path`	string	Sim	Caminho do endpoint no plugin
`method`	string	Sim	Método HTTP
`body`	any	Não	Corpo da requisição
`headers`	object	Não	Headers customizados
`params`	any	Não	Parâmetros de query
`timeout`	number	Sim	Timeout em milissegundos

Exemplo

return {
  name: 'call-plugin',
  args: {
    name: 'plugin-name',
    path: '/endpoint',
    method: 'post',
    body: {
      dados: 'valor'
    },
    headers: {
      'Custom-Header': 'valor'
    },
    params: {
      query: 'param'
    },
    timeout: 30000
  }
};

Observações

Plugins são serviços externos configurados no sistema
Timeout deve ser especificado explicitamente
Use para integrações com serviços externos via plugins

Casos de Uso

Integrar com serviços externos via plugins
Chamar APIs de terceiros configuradas como plugins
Executar ações em sistemas externos
Processar dados através de plugins customizados

new-sub-card

Cria um sub-card baseado em uma configuração de subfluxo. O sub-card é criado relacionado ao card atual.

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`subflow_config_key`	number	Sim	Chave numérica da configuração do subfluxo
`assigned`	string	Não	PID do usuário responsável
`assigned_username`	string	Não	Username do responsável
`skipNotification`	boolean	Não	Se `true`, não envia notificações

Exemplo

return {
  name: 'new-sub-card',
  args: {
    subflow_config_key: 123,
    assigned_username: 'usuario.responsavel',
    skipNotification: false
  }
};

Observações

O sub-card é automaticamente relacionado ao card atual
A configuração do subfluxo define a estrutura do card criado
Use quando precisar criar cards relacionados em fluxos diferentes

Casos de Uso

Criar cards de acompanhamento em subfluxos
Disparar processos paralelos relacionados
Criar cards de validação em fluxos separados
Gerar cards de notificação em subfluxos

notify

Envia uma notificação para um usuário. A notificação pode ser exibida como toast, push ou email dependendo dos parâmetros fornecidos.

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`username`	string	Sim	Username do destinatário
`userPid`	string	Não	PID do usuário (alternativa a `username`)
`title`	string	Não	Título da notificação
`message`	string	Não	Mensagem (retrocompatibilidade)
`shortMessage`	string	Não	Mensagem curta (para toast/push)
`htmlMessage`	string	Não	Mensagem HTML (para email)
`method`	string	Não	Tipo: `'info'`, `'success'`, `'error'`, `'warning'` (padrão: `'info'`)
`link`	string	Não	Link relacionado
`expires`	number	Não	Tempo de expiração em milissegundos

Exemplo

// Notificação simples
return {
  name: 'notify',
  args: {
    username: 'usuario.destino',
    message: 'Processamento concluído'
  }
};

// Notificação completa
return {
  name: 'notify',
  args: {
    username: 'usuario.destino',
    title: 'Processamento Concluído',
    shortMessage: 'O processamento foi finalizado com sucesso',
    htmlMessage: '<p>O processamento foi finalizado com sucesso</p>',
    method: 'success',
    link: 'puca-flow-front/card/uuid-card',
    expires: 3600000 // 1 hora
  }
};

Retrocompatibilidade

O campo message é mantido para retrocompatibilidade:

Se title não for fornecido, message será usado como título
Se title for fornecido, message será usado como shortMessage

Observações

O usuário deve existir no sistema
Se username não for encontrado, um erro será lançado
Use method para definir o tipo visual da notificação
htmlMessage é usado apenas para notificações por email

Casos de Uso

Notificar usuários sobre conclusão de processamentos
Alertar sobre erros ou problemas
Informar sobre criação de novos cards
Enviar lembretes e avisos

send-email

Envia um email relacionado ao card atual. O email é enviado usando a configuração de email da etapa do card.

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`context`	object	Sim	Contexto de dados para o template do email
`secretContext`	object	Não	Contexto secreto (não exposto no template)
`stepField`	string	Sim	Campo da etapa que contém a configuração do email
`addInteraction`	boolean	Não	Se `true`, adiciona uma interação CRM após enviar (padrão: `true`)

Exemplo

return {
  name: 'send-email',
  args: {
    context: {
      nomeCliente: 'João Silva',
      valor: 1500.00,
      dataVencimento: '2024-12-31'
    },
    secretContext: {
      token: 'token-secreto'
    },
    stepField: 'user_config_email',
    addInteraction: true
  }
};

Observações

O template do email é definido no campo stepField da etapa atual
O contexto é usado para preencher variáveis no template
secretContext permite passar dados que não devem aparecer no template
Uma interação CRM é automaticamente criada após o envio (se addInteraction for true)

Casos de Uso

Enviar emails de notificação para clientes
Enviar propostas e documentos
Enviar lembretes e avisos
Comunicar mudanças de status

Prioridades

As orders são executadas sequencialmente na ordem em que são retornadas. A propriedade priority pode influenciar a ordem de processamento, permitindo que orders mais importantes sejam executadas antes de outras.

Níveis de Prioridade

1. Crítica (priority: 1)

Usada para operações críticas do negócio que devem ter execução imediata e passar na frente de todas as outras orders. Essas orders são processadas com máxima urgência.

Casos de uso:

Processamento de faturamento
Eventos financeiros críticos
Operações que impactam diretamente receita ou pagamentos
Processamentos que bloqueiam outras operações importantes

Exemplo:

return {
  name: 'upinsert',
  args: {
    tableName: 'user_faturamento',
    data: { /* dados do faturamento */ }
  },
  priority: 1
};

2. Alta (priority: 2)

Usada para eventos que requerem feedback imediato ao usuário ou atualizações que precisam ser processadas rapidamente para melhorar a experiência do usuário.

Casos de uso:

Atualizações no formulário de um card resultantes de um script logo após movê-lo de etapa
Notificações urgentes para usuários
Sincronizações que o usuário está aguardando
Processamentos que afetam a interface do usuário em tempo real

Exemplo:

return {
  name: 'change-form',
  args: {
    user_status: 'processado',
    user_resultado: resultadoCalculado
  },
  priority: 2
};

3. Padrão (priority: 3)

Prioridade padrão para a maioria dos eventos e processamentos gerais do sistema. Esta é a prioridade padrão quando não especificada.

Casos de uso:

Processamentos de rotina
Atualizações de dados normais
Sincronizações regulares
Operações que não requerem urgência especial

Exemplo:

return {
  name: 'upinsert',
  args: {
    tableName: 'user_tabela',
    data: { /* dados */ }
  }
  // priority não especificada = padrão (3)
};

4. Baixa (priority: 4)

Usada para eventos que podem ser processados com menor urgência, geralmente operações em lote ou processamentos que ocorrem periodicamente.

Casos de uso:

Fechamentos diários ou mensais
Processamentos em lote
Relatórios e consolidações
Operações de manutenção e limpeza
Sincronizações que não requerem urgência

Exemplo:

return {
  name: 'upinsert',
  args: {
    tableName: 'user_fechamento_mensal',
    data: { /* dados do fechamento */ }
  },
  priority: 4
};

Comportamento

Orders com prioridade mais baixa (número menor) são executadas antes de orders com prioridade mais alta (número maior)
Se não especificada, a prioridade padrão é 3 (padrão)
Orders com a mesma prioridade são executadas na ordem em que foram retornadas
A prioridade mínima é 1 (crítica) e a máxima é 4 (baixa)

Valores Especiais

Usuários

{{previousUser}}: Referencia o usuário que estava responsável pelo card anteriormente

Etapas

{{previousStep}}: Referencia a etapa anterior do fluxo
{{nextStep}}: Referencia a próxima etapa do fluxo

Boas Práticas

Sempre retorne um array: Mesmo que tenha apenas uma order, retorne como array para consistência
Retorne o card ao usuário anterior: Sempre que pelo menos uma order for solicitada, adicione uma última order change-card com assigned_username: '{{previousUser}}' para retornar o card ao usuário anterior. Caso contrário, o card ficará com o robot como responsável mesmo após ele ter concluído suas atividades
Use hash para evitar duplicatas: Especialmente em upinsert quando processar dados que podem ser duplicados
Evite omitExceptions em delete: O sistema por padrão lança excessão se uma linha deletada não existir, este parametro ignora este comportamento

Tópico	Respostas	Visualizações
Retorno de step.step_requeriments_runtime_function General documentacao	3	18 de Dezembro de 2024
Como habilitar e configurar funcionalidade de Subcards? Flow documentacao	261	27 de Março de 2024
Como funciona o campo "Apenas usuários no mesmo galho (na arvore de papeis) que papel do usuário deste campo podem operar cards nesta etapa" da criação/edição de etapas do Kanban? Flow depreciado	23	30 de Novembro de 2023
Como Criar um Relatório Personalizado no PUCA - Passo a Passo General documentacao	7	20 de Junho de 2025
Melhorias QoL no processo de criação e edição de Kanbans Flow documentacao	3	28 de Janeiro de 2026

Documentação de Orders RPA

Introdução

Como Usar Orders

Estrutura Básica

Retornando Orders

Referência de Orders

new-card

Parâmetros

Exemplo

Casos de Uso

change-card

Parâmetros

Exemplo

Valores Especiais para assigned_username

Casos de Uso

change-form

Parâmetros

Exemplo

Observações

Casos de Uso

delete

Parâmetros

Exemplo

Observações

Casos de Uso

upinsert

Parâmetros

Exemplo

Comportamento Especial

Observações

Casos de Uso

add-comment

Parâmetros

Exemplo

Observações

Casos de Uso

add-task

Parâmetros

Exemplo

Observações

Casos de Uso

insert-interaction

Parâmetros

Estrutura de indicators

Exemplo

Observações

Casos de Uso

call-api

Parâmetros

Exemplo

Observações

Casos de Uso

call-plugin

Parâmetros

Exemplo

Observações

Casos de Uso

new-sub-card

Parâmetros

Exemplo

Observações

Casos de Uso

notify

Parâmetros

Exemplo

Retrocompatibilidade

Observações

Casos de Uso

send-email

Parâmetros

Exemplo

Observações

Casos de Uso

Prioridades

Níveis de Prioridade

1. Crítica (priority: 1)

2. Alta (priority: 2)

3. Padrão (priority: 3)

4. Baixa (priority: 4)

Comportamento

Valores Especiais para `assigned_username`

Estrutura de `indicators`