Pular para o conteúdo principal

Aprovar com aprovadores

Neste modo, você informa na criação quem aprova a REQUISIÇÃO: uma lista de pessoas com nome e e-mail. Elas não precisam ser usuárias da InHire. Use este modo quando os aprovadores mudam de requisição para requisição e o seu sistema já sabe quem são (por exemplo, o gestor da área que pediu a vaga).

Se a sua empresa tem uma regra fixa de aprovação em etapas, prefira Fluxo de aprovação.

Endpoints usados:

Como funciona​

POST /requisitions (approvers: [Ana, Bruno])
│
├──► e-mail para Ana ──┐
└──► e-mail para Bruno ┤
▼
todos aprovaram? ──► approved
alguém reprovou? ──► rejected
  • Todos os aprovadores recebem o e-mail ao mesmo tempo, logo após a criação. Não há ordem entre eles.
  • A requisição só fica approved quando todos aprovam.
  • Uma reprovação basta para a requisição ficar rejected. Os links dos demais aprovadores deixam de valer.

1. Crie a requisição com aprovadores​

Envie em approvers uma entrada por aprovador, com name e email. Não envie approvalWorkflow.

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": "expansion" }],
"contractType": ["CLT"],
"approvers": [
{ "name": "Ana Souza", "email": "ana.souza@acme.com" },
{ "name": "Bruno Lima", "email": "bruno.lima@acme.com" }
]
}'

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

Resposta (resumida):

{
"id": "6f1d0c2a-9a51-4c0e-8a8e-2b7d1f4e9c10",
"name": "Analista de Dados Pleno",
"status": "pending",
"approvers": [
{
"name": "Ana Souza",
"email": "ana.souza@acme.com",
"status": "pending",
"token": "3f0c1b8e-6a43-4a8f-9d0e-1c9b2f7a5d21",
"reason": ""
},
{
"name": "Bruno Lima",
"email": "bruno.lima@acme.com",
"status": "pending",
"token": "a7d2e9c4-1b3f-4e6a-8c5d-0f9e2b4a6c81",
"reason": ""
}
],
"positions": [{ "reason": "expansion" }],
"createdAt": "2026-10-26T12:00:00.000Z"
}

O status e o token de cada aprovador são gerados pelo servidor. Os e-mails são normalizados para minúsculas.

2. Acompanhe as decisões​

Cada aprovador decide pelo link que recebeu por e-mail. Para saber em que pé está a requisição:

  • Webhook (recomendado): assine REQUISITION_STATUS_UPDATED. Ele dispara quando a requisição fica approved ou rejected.
  • Consulta: chame Obter Requisição e leia status e approvers[].status (pending, approved ou rejected). Em uma reprovação, a justificativa fica em approvers[].reason.
const requisition = await inhire(`/requisitions/${requisitionId}`);

const pending = requisition.approvers
.filter((approver: any) => approver.status === "pending")
.map((approver: any) => approver.email);

console.log(requisition.status, "aguardando:", pending);

A função inhire é a mesma do exemplo completo.

3. (Opcional) Registre a decisão de um aprovador pela API​

Se o aprovador decide dentro do seu sistema, você pode registrar a decisão dele na InHire com Aprovar ou Reprovar Requisição, usando o token daquele aprovador.

Obtenha o token do aprovador​

Cada aprovador tem um token próprio, gerado na criação da requisição. Ele vem na resposta do POST /requisitions e em Obter Requisição, dentro de approvers[]:

curl --request GET \
--url 'https://api.inhire.app/requisitions/{{requisitionId}}' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'X-Tenant: {{tenantId}}'
{
"id": "6f1d0c2a-9a51-4c0e-8a8e-2b7d1f4e9c10",
"status": "pending",
"approvers": [
{
"name": "Ana Souza",
"email": "ana.souza@acme.com",
"status": "pending",
"token": "3f0c1b8e-6a43-4a8f-9d0e-1c9b2f7a5d21",
"reason": ""
}
]
}

Localize o aprovador pelo e-mail. Como o token muda sempre que a aprovação recomeça, leia a requisição logo antes de registrar a decisão, em vez de reaproveitar um token guardado:

async function getApproverToken(requisitionId: string, approverEmail: string) {
const requisition = await inhire(`/requisitions/${requisitionId}`);

const approver = requisition.approvers.find(
(item: any) => item.email === approverEmail.trim().toLowerCase(),
);

if (!approver) {
throw new Error(`${approverEmail} não é aprovador desta requisição`);
}

if (approver.status !== "pending") {
throw new Error(`${approverEmail} já decidiu: ${approver.status}`);
}

return approver.token;
}

Os e-mails dos aprovadores são gravados em minúsculas, por isso a comparação normaliza o e-mail de entrada.

Registre a decisão​

async function reviewRequisition(
requisitionId: string,
approverEmail: string,
status: "approved" | "rejected",
reason: string,
) {
const token = await getApproverToken(requisitionId, approverEmail);

let response: Response;

try {
// Endpoint sem access token: o token do aprovador é a credencial
response = await fetch(`${INHIRE_API_URL}/requisitions/review/${requisitionId}`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ tenantId: TENANT, token, status, reason }),
});
} catch (error) {
throw new Error(`Falha de rede ao registrar a decisão da requisição ${requisitionId}: ${error}`);
}

if (!response.ok) {
throw new Error(`${response.status}: ${(await response.json()).message}`);
}

return response.json();
}

await reviewRequisition(
requisitionId,
"ana.souza@acme.com",
"approved",
"Headcount aprovado no orçamento de 2027.",
);

Ou, direto com cURL:

curl --request POST \
--url 'https://api.inhire.app/requisitions/review/{{requisitionId}}' \
--header 'Content-Type: application/json' \
--data '{
"tenantId": "{{tenantId}}",
"token": "{{approvers[].token do aprovador}}",
"status": "approved",
"reason": "Headcount aprovado no orçamento de 2027."
}'
CampoDescrição
tenantIdID do tenant
tokentoken do aprovador, lido em approvers[] da requisição
statusapproved ou rejected
reasonJustificativa, exibida para o requisitante

Resposta:

{
"message": "Sua aprovação foi registrada. O requisitante irá receber um email com essa atualização.",
"status": "approved"
}
aviso

O token do aprovador é a credencial da decisão: quem tem o token aprova ou reprova em nome daquele aprovador, sem precisar do access token. Trate-o como segredo e use esta chamada só quando a decisão foi de fato tomada por essa pessoa. A decisão aparece no histórico da requisição com o nome e o e-mail do aprovador.

Erros​

StatusMensagemCausa
400Missing status, tenantId or token in request bodyFaltou um campo obrigatório
400Canceled requisition cannot be approvedA requisição foi cancelada
403Token has been expired or revoked.O token não pertence a nenhum aprovador da requisição (por exemplo, foi invalidado por uma reprovação)
404Requisition not found!O id ou o tenantId não correspondem a uma requisição

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 a aprovação recomeça do zero.
informação

Sempre que a aprovação recomeça (reenvio após reprovação, ou edição de campos que reiniciam a aprovação), todos os tokens dos aprovadores mudam. Leia a requisição de novo antes de registrar outra decisão pela API.