Pular para o conteúdo principal

Fluxo de aprovação

Um fluxo de aprovação é uma regra de aprovação cadastrada uma vez no tenant e reaproveitada em várias REQUISIÇÕES: quem aprova e em que ordem. Use este modo quando a empresa tem uma regra fixa (por exemplo, gestor → financeiro → diretoria).

Este guia mostra como criar um fluxo de aprovação e como criar uma requisição que usa esse fluxo. Se quem aprova muda a cada requisição, prefira Aprovar com aprovadores.

Endpoints usados:

Como funciona​

Cada fluxo tem etapas (steps), cada etapa tem aprovadores, e o campo typeOrder define como elas andam:

typeOrderEstruturaComportamento
orderedUma etapa por aprovador, na ordem do campo orderUm aprovador por vez. O próximo só recebe o e-mail quando o anterior aprova
parallelUma única etapa com todos os aprovadoresTodos recebem o e-mail ao mesmo tempo
ordered: etapa 1 (Ana) ──aprova──► etapa 2 (Bruno) ──aprova──► etapa 3 (Carla) ──aprova──► approved

parallel: etapa 1 (Ana, Bruno, Carla) ──todos aprovam──► approved

Nos dois casos:

  • Uma etapa fica approved quando todos os aprovadores dela aprovam.
  • A requisição fica approved quando todas as etapas estão aprovadas.
  • Uma reprovação basta: a etapa fica reproved e a requisição fica rejected. As etapas seguintes não recebem e-mail.

Os aprovadores decidem pelo link que recebem por e-mail.

1. Crie o fluxo de aprovação​

O fluxo pode ser cadastrado na tela Configurações > Fluxos de aprovação ou pela API, com Criar Fluxo de Aprovação. Basta criar uma vez: o mesmo fluxo é reaproveitado em todas as requisições que precisarem dele.

CampoObrigatórioDescrição
nameSimNome do fluxo, exibido para quem cria requisições
typeOrderSimordered (um aprovador por vez) ou parallel (todos ao mesmo tempo)
stepsSimEtapas do fluxo
steps[].nameSimNome da etapa (ex.: etapa 1)
steps[].orderSimPosição da etapa. As etapas andam da menor para a maior
steps[].approversSimAprovadores da etapa
steps[].approvers[].nameSimNome do aprovador
steps[].approvers[].emailSimE-mail do aprovador, para onde vai o link de aprovação
steps[].approvers[].typeNãointernal (usuário da InHire) ou external (pessoa de fora da InHire)
steps[].approvers[].positionNãoCargo do aprovador, exibido no fluxo

Monte as etapas de acordo com o typeOrder, do mesmo jeito que a tela faz:

  • ordered: uma etapa por aprovador, com order crescente.
  • parallel: uma única etapa com todos os aprovadores.

Exemplo: fluxo em ordem​

curl --request POST \
--url 'https://api.inhire.app/requisitions/approval-workflows' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'X-Tenant: {{tenantId}}' \
--header 'Content-Type: application/json' \
--data '{
"name": "Aprovação Diretoria",
"typeOrder": "ordered",
"steps": [
{
"name": "etapa 1",
"order": 0,
"approvers": [
{ "name": "Ana Souza", "email": "ana.souza@acme.com", "type": "internal", "position": "Gestora de Dados" }
]
},
{
"name": "etapa 2",
"order": 1,
"approvers": [
{ "name": "Bruno Lima", "email": "bruno.lima@acme.com", "type": "external", "position": "Diretor Financeiro" }
]
}
]
}'

Exemplo: fluxo em paralelo​

{
"name": "Aprovação Comitê",
"typeOrder": "parallel",
"steps": [
{
"name": "etapa 1",
"order": 1,
"approvers": [
{ "name": "Ana Souza", "email": "ana.souza@acme.com", "type": "internal" },
{ "name": "Bruno Lima", "email": "bruno.lima@acme.com", "type": "external" },
{ "name": "Carla Dias", "email": "carla.dias@acme.com", "type": "internal" }
]
}
]
}

A resposta traz o fluxo criado, com id gerado para o fluxo, para cada etapa e para cada aprovador. Guarde o id do fluxo: é ele que identifica o fluxo na criação das requisições.

{
"id": "0b6c7a52-3c1e-4f0a-9a7d-5e2f8b1c4d90",
"name": "Aprovação Diretoria",
"typeOrder": "ordered",
"steps": [
{
"id": "c1f0e7a2-8b4d-4c6e-9f1a-2d3b5c7e9a01",
"name": "etapa 1",
"order": 0,
"approvers": [
{
"id": "5e8a1c3d-7f2b-4a9e-b6d0-1c4f7a2e9b35",
"name": "Ana Souza",
"email": "ana.souza@acme.com",
"type": "internal",
"position": "Gestora de Dados",
"createdAt": "2026-10-26T12:00:00Z",
"updateAt": "2026-10-26T12:00:00Z"
}
],
"createdAt": "2026-10-26T12:00:00Z",
"updatedAt": "2026-10-26T12:00:00Z"
},
{ "...": "etapa 2" }
],
"userId": "…",
"userName": "Usuário de API",
"createdAt": "2026-10-26T12:00:00Z",
"updatedAt": "2026-10-26T12:00:00Z"
}
StatusMensagemCausa
400Invalid approver email(s): <e-mails>Algum aprovador tem e-mail inválido
400Invalid request bodyCampo fora do formato acima (o body não aceita campos extras)

2. Escolha o fluxo​

Na hora de criar a requisição, você precisa do objeto completo do fluxo. Se guardou o id, use Obter Fluxo de Aprovação:

curl --request GET \
--url 'https://api.inhire.app/requisitions/approval-workflows/{{approvalWorkflowId}}' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'X-Tenant: {{tenantId}}'

Ou liste todos os fluxos do tenant com Listar Fluxos de Aprovação e escolha pelo nome:

curl --request GET \
--url 'https://api.inhire.app/requisitions/approval-workflows' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'X-Tenant: {{tenantId}}'

A listagem devolve um array com os fluxos no mesmo formato da resposta de criação.

dica

Busque o fluxo a cada requisição em vez de guardar o objeto inteiro na sua integração. Assim, se o time de RH trocar um aprovador em Configurações > Fluxos de aprovação, as novas requisições já saem com o fluxo atualizado.

3. Crie a requisição com o fluxo​

Envie o objeto do fluxo, exatamente como veio do passo anterior, em approvalWorkflow, e approvers: []:

curl --request POST \
--url 'https://api.inhire.app/requisitions' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'X-Tenant: {{tenantId}}' \
--header 'Content-Type: application/json' \
--data '{
"name": "Analista de Dados Pleno",
"positions": [{ "reason": "replacement" }],
"contractType": ["CLT"],
"approvers": [],
"approvalWorkflow": {{objeto retornado em GET /requisitions/approval-workflows/{id}}}
}'

Em TypeScript, com a função inhire do exemplo completo:

const APPROVAL_WORKFLOW_ID = "0b6c7a52-3c1e-4f0a-9a7d-5e2f8b1c4d90";

const workflow = await inhire(`/requisitions/approval-workflows/${APPROVAL_WORKFLOW_ID}`);

const requisition = await inhire("/requisitions", {
method: "POST",
body: JSON.stringify({
name: "Analista de Dados Pleno",
positions: [{ reason: "replacement" }],
contractType: ["CLT"],
approvers: [],
approvalWorkflow: workflow,
}),
});

console.log(requisition.id, requisition.status); // "...", "pending"

Para incluir campos personalizados, faixa salarial e os demais campos, veja Criar requisição.

aviso
  • O approvalWorkflow.id precisa existir no tenant; senão a resposta é 400 Approval workflow not found!.
  • A requisição guarda uma cópia do fluxo no momento da criação. Mudanças posteriores no fluxo não alteram requisições já criadas.
  • Não envie aprovadores em approvers junto com o fluxo: quando os dois vêm preenchidos, vale o fluxo e a lista é ignorada.

Na resposta, cada etapa e cada aprovador do fluxo ganham status: "pending". Os aprovadores da primeira etapa recebem o e-mail de aprovação logo após a criação.

4. Acompanhe a aprovação​

  • Webhook (recomendado): assine REQUISITION_STATUS_UPDATED. Ele dispara quando a requisição fica approved ou rejected.
  • Consulta: chame Obter Requisição e leia approvalWorkflow.steps[]. A etapa atual é a de menor order com status: "pending".
const requisition = await inhire(`/requisitions/${requisitionId}`);

const currentStep = [...requisition.approvalWorkflow.steps]
.sort((a: any, b: any) => a.order - b.order)
.find((step: any) => step.status === "pending");

console.log(
requisition.status,
currentStep ? `aguardando ${currentStep.name}` : "sem etapas pendentes",
);

Os status das etapas e dos aprovadores do fluxo são pending, approved e reproved (note: reproved, e não rejected como no status da requisição). A justificativa de cada aprovador fica em approvers[].reason.

Depois da decisão​

  • Aprovada: a requisição pode virar vaga.
  • Reprovada: o requisitante pode editar a requisição e reenviá-la. Ela volta para pending e o fluxo recomeça da primeira etapa.