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:
- Criar Fluxo de Aprovação —
POST /requisitions/approval-workflows - Listar Fluxos de Aprovação —
GET /requisitions/approval-workflows - Obter Fluxo de Aprovação —
GET /requisitions/approval-workflows/{id} - Criar Requisição —
POST /requisitions - Obter Requisição —
GET /requisitions/{id}
Como funciona
Cada fluxo tem etapas (steps), cada etapa tem aprovadores, e o campo typeOrder define
como elas andam:
typeOrder | Estrutura | Comportamento |
|---|---|---|
ordered | Uma etapa por aprovador, na ordem do campo order | Um aprovador por vez. O próximo só recebe o e-mail quando o anterior aprova |
parallel | Uma única etapa com todos os aprovadores | Todos 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
approvedquando todos os aprovadores dela aprovam. - A requisição fica
approvedquando todas as etapas estão aprovadas. - Uma reprovação basta: a etapa fica
reprovede a requisição ficarejected. 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.
| Campo | Obrigatório | Descrição |
|---|---|---|
name | Sim | Nome do fluxo, exibido para quem cria requisições |
typeOrder | Sim | ordered (um aprovador por vez) ou parallel (todos ao mesmo tempo) |
steps | Sim | Etapas do fluxo |
steps[].name | Sim | Nome da etapa (ex.: etapa 1) |
steps[].order | Sim | Posição da etapa. As etapas andam da menor para a maior |
steps[].approvers | Sim | Aprovadores da etapa |
steps[].approvers[].name | Sim | Nome do aprovador |
steps[].approvers[].email | Sim | E-mail do aprovador, para onde vai o link de aprovação |
steps[].approvers[].type | Não | internal (usuário da InHire) ou external (pessoa de fora da InHire) |
steps[].approvers[].position | Não | Cargo 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, comordercrescente.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"
}
| Status | Mensagem | Causa |
|---|---|---|
400 | Invalid approver email(s): <e-mails> | Algum aprovador tem e-mail inválido |
400 | Invalid request body | Campo 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.
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.
- O
approvalWorkflow.idprecisa 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
approversjunto 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 ficaapprovedourejected. - Consulta: chame Obter Requisição e leia
approvalWorkflow.steps[]. A etapa atual é a de menorordercomstatus: "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
pendinge o fluxo recomeça da primeira etapa.