Pular para o conteúdo principal

Criar requisição

Uma REQUISIÇÃO é o pedido de abertura de vaga: alguém da empresa pede uma ou mais posições, e o pedido passa por aprovação antes de virar uma VAGA. Este guia mostra como montar o body da criação, incluindo os campos personalizados de requisição, e como escolher quem aprova.

Endpoints usados:

Ciclo de vida​

Toda requisição nasce pending e termina em um dos estados abaixo:

┌──► approved ──► pode virar vaga
POST /requisitions ──► pending
├──► rejected ──► pode ser editada e reenviada (volta para pending)
└──► canceled ──► estado final

A criação dispara o webhook REQUISITION_CREATED e cada mudança de status dispara REQUISITION_STATUS_UPDATED.

Escolha quem aprova​

Toda requisição usa um dos dois modos abaixo, definido na criação:

ModoComo enviarQuem decideGuia
Aprovadoresapprovers: [{ name, email }]As pessoas listadas no body, todas ao mesmo tempoAprovar com aprovadores
Fluxo de aprovaçãoapprovalWorkflow (+ approvers: [])As pessoas de um fluxo cadastrado no tenant, em etapasFluxo de aprovação

Nos dois modos, cada aprovador recebe por e-mail um link para aprovar ou reprovar.

  • Use aprovadores quando quem aprova muda de requisição para requisição (por exemplo, o gestor da área que pediu a vaga) e o seu sistema já sabe quem é.
  • Use o fluxo de aprovação quando a empresa tem uma regra fixa de aprovação (por exemplo, gestor → financeiro → diretoria), mantida pelo time de RH na InHire.
aviso

O campo approvers é sempre obrigatório. Ao usar fluxo de aprovação, envie approvers: []. Se você enviar aprovadores e fluxo juntos, vale o fluxo; não misture os dois.

Campos da criação​

Envie apenas dados de entrada. O servidor preenche o resto.

Obrigatórios​

CampoDescrição
nameTítulo da requisição, normalmente o cargo
positionsUma entrada por posição pedida, com o motivo de abertura: expansion, replacement ou other. Precisa ter pelo menos um item
approversLista de aprovadores (name + email), ou [] quando usar approvalWorkflow

Opcionais​

CampoDescrição
approvalWorkflowFluxo de aprovação a seguir (objeto completo, veja o guia do fluxo)
descriptionDescrição da posição (aceita HTML)
notesObservações para quem vai aprovar
contractTypeLista de tipos de contrato (CLT, PJ, Estágio, ...)
salaryMin / salaryMax / salaryCurrencyFaixa salarial e moeda ISO 4217 (padrão: moeda do tenant)
customFieldsValores dos campos personalizados de requisição (veja abaixo)
responsibleRecruiterIdRecrutador responsável (só é gravado se o usuário da API puder definir recrutador)

Preenchidos pelo servidor​

Se você enviar estes campos, eles são ignorados ou sobrescritos:

CampoValor
id, createdAt, updatedAtGerados na criação
statusSempre pending
tenantId, userId, userNameVêm do token de acesso
approvers[].token, approvers[].status, approvalWorkflow.steps[].approvers[].tokenGerados para cada aprovador
filesAnexos entram depois, pelo endpoint de arquivos da requisição

Campos personalizados​

Os campos personalizados de requisição são configurados pelo time de RH em Configurações > Campos personalizados e variam de tenant para tenant. Antes de criar a requisição, busque quais existem com a entidade REQUISITIONS:

curl --request GET \
--url 'https://api.inhire.app/custom-data-manager/custom-fields/entity/REQUISITIONS' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'X-Tenant: {{tenantId}}'

Resposta (resumida):

[
{
"id": "{{id do campo Centro de custo}}",
"name": "Centro de custo",
"type": "text",
"required": true,
"order": 0
},
{
"id": "{{id do campo Área}}",
"name": "Área",
"type": "select",
"required": false,
"order": 1,
"options": [
{ "value": "produto", "label": "Produto" },
{ "value": "comercial", "label": "Comercial" }
]
}
]

Para preencher, envie em customFields um item por campo, copiando id (em customFieldId), name e type do retorno acima e colocando o valor em value:

"customFields": [
{
"customFieldId": "{{id do campo Centro de custo}}",
"name": "Centro de custo",
"type": "text",
"value": "CC-1042"
},
{
"customFieldId": "{{id do campo Área}}",
"name": "Área",
"type": "select",
"value": "produto",
"label": "Produto"
}
]

Regras de valor por tipo:

typevalue
text / textareaTexto livre
numberApenas números, como string ("12", "1500.50")
dateData no formato YYYY-MM-DD
select / radioO value de uma das options; envie também o label da opção
informação

A API valida o formato dos valores (number e date inválidos retornam 400), mas não valida a obrigatoriedade. Envie todos os campos com required: true para que a requisição fique completa para quem aprova e para a vaga gerada a partir dela.

Mais detalhes sobre a listagem em Obter todos os Campos Personalizados de uma Entidade.

Exemplo completo​

O exemplo abaixo autentica, busca os campos personalizados de requisição e cria uma requisição com aprovadores. Para criar com fluxo de aprovação, troque o bloco de aprovação conforme o guia do fluxo.

const INHIRE_AUTH_URL = "https://auth.inhire.app";
const INHIRE_API_URL = "https://api.inhire.app";
const TENANT = "{{tenantId}}";
let INHIRE_TOKEN = "";

async function getAccessToken() {
let response: Response;

try {
response = await fetch(`${INHIRE_AUTH_URL}/login`, {
method: "POST",
headers: { "Content-Type": "application/json", "X-Tenant": TENANT },
body: JSON.stringify({ email: "{{email do usuário de API}}", password: "{{senha}}" }),
});
} catch (error) {
throw new Error(`Falha de rede ao autenticar na InHire: ${error}`);
}

INHIRE_TOKEN = (await response.json()).accessToken;
}

async function inhire(path: string, init: RequestInit = {}) {
let response: Response;

try {
response = await fetch(`${INHIRE_API_URL}${path}`, {
...init,
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${INHIRE_TOKEN}`,
"X-Tenant": TENANT,
...init.headers,
},
});
} catch (error) {
throw new Error(`Falha de rede ao chamar ${path}: ${error}`);
}

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

return response.json();
}

async function main() {
await getAccessToken();

// 1. Busque os campos personalizados de requisição
const fields = await inhire("/custom-data-manager/custom-fields/entity/REQUISITIONS");
const byName = (name: string) => fields.find((field: any) => field.name === name);

const costCenter = byName("Centro de custo");
const area = byName("Área");
const areaOption = area.options.find((option: any) => option.value === "produto");

// 2. Crie a requisição
const requisition = await inhire("/requisitions", {
method: "POST",
body: JSON.stringify({
name: "Analista de Dados Pleno",
description: "<p>Responsável pelos pipelines de dados do time de Produto.</p>",
positions: [{ reason: "replacement" }],
contractType: ["CLT"],
salaryMin: 8000,
salaryMax: 11000,
salaryCurrency: "BRL",
customFields: [
{
customFieldId: costCenter.id,
name: costCenter.name,
type: costCenter.type,
value: "CC-1042",
},
{
customFieldId: area.id,
name: area.name,
type: area.type,
value: areaOption.value,
label: areaOption.label,
},
],
approvers: [
{ name: "Ana Souza", email: "ana.souza@acme.com" },
{ name: "Bruno Lima", email: "bruno.lima@acme.com" },
],
}),
});

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

main();

Erros comuns​

StatusMensagemCausa
400Requisition must have at least one positionpositions vazio ou ausente
400Approval workflow not found!O approvalWorkflow.id não existe no tenant
400O campo '<nome>' deve conter apenas números válidosValor inválido em campo number
400O campo '<nome>' possui formato inválido. Use o formato YYYY-MM-DDValor inválido em campo date
403—O usuário de API não tem permissão para criar requisições
500—approvers ausente do body. Envie [] ao usar fluxo de aprovação

Próximos passos​