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:
- Obter Campos Personalizados de uma entidade —
GET /custom-data-manager/custom-fields/entity/REQUISITIONS - Criar Requisição —
POST /requisitions - Obter Requisição —
GET /requisitions/{id}
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:
| Modo | Como enviar | Quem decide | Guia |
|---|---|---|---|
| Aprovadores | approvers: [{ name, email }] | As pessoas listadas no body, todas ao mesmo tempo | Aprovar com aprovadores |
| Fluxo de aprovação | approvalWorkflow (+ approvers: []) | As pessoas de um fluxo cadastrado no tenant, em etapas | Fluxo 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.
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
| Campo | Descrição |
|---|---|
name | Título da requisição, normalmente o cargo |
positions | Uma entrada por posição pedida, com o motivo de abertura: expansion, replacement ou other. Precisa ter pelo menos um item |
approvers | Lista de aprovadores (name + email), ou [] quando usar approvalWorkflow |
Opcionais
| Campo | Descrição |
|---|---|
approvalWorkflow | Fluxo de aprovação a seguir (objeto completo, veja o guia do fluxo) |
description | Descrição da posição (aceita HTML) |
notes | Observações para quem vai aprovar |
contractType | Lista de tipos de contrato (CLT, PJ, Estágio, ...) |
salaryMin / salaryMax / salaryCurrency | Faixa salarial e moeda ISO 4217 (padrão: moeda do tenant) |
customFields | Valores dos campos personalizados de requisição (veja abaixo) |
responsibleRecruiterId | Recrutador 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:
| Campo | Valor |
|---|---|
id, createdAt, updatedAt | Gerados na criação |
status | Sempre pending |
tenantId, userId, userName | Vêm do token de acesso |
approvers[].token, approvers[].status, approvalWorkflow.steps[].approvers[].token | Gerados para cada aprovador |
files | Anexos 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:
type | value |
|---|---|
text / textarea | Texto livre |
number | Apenas números, como string ("12", "1500.50") |
date | Data no formato YYYY-MM-DD |
select / radio | O value de uma das options; envie também o label da opçã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
| Status | Mensagem | Causa |
|---|---|---|
400 | Requisition must have at least one position | positions vazio ou ausente |
400 | Approval workflow not found! | O approvalWorkflow.id não existe no tenant |
400 | O campo '<nome>' deve conter apenas números válidos | Valor inválido em campo number |
400 | O campo '<nome>' possui formato inválido. Use o formato YYYY-MM-DD | Valor 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 |