Criar posição

Este endpoint permite criar uma nova posição na estrutura organizacional com base nos dados fornecidos.

Regras de negócio e validações

Campos obrigatórios

name: Nome da posição.
externalCodeRole: Código do cargo. O cargo deve existir previamente na base.
externalCodeArea: Código da área. A área deve existir previamente na base.

Campos opcionais

description: Descrição da posição.
externalCode: Código da posição é opcional. É gerado automaticamente quando não informado.
externalCodeParent: Código da posição pai. Se informado, posição pai deve existir previamente na base.
externalCodeCostCenter: Código do centro de custo. Se informado, o centro de custo deve existir previamente na base.
externalCodeOperationUnit: Código de unidade operacional. Se informado, a unidade operacional deve existir previamente na base.
employeeEmail: Email do colaborador. Se informado, colaborador deve existir previamente na base.
employeeTaxPayerRegistry: CPF do colaborador. Se informado, colaborador deve existir previamente na base.
employeeInternalCompanyNumber: Número de matrícula do colaborador. Se informado, colaborador deve existir previamente na base.

Hierarquia e unicidade

Código único: O externalCode deve ser único dentro da empresa.
Posição Raiz: Se o externalCodeParent não for informado, a posição será criada como raiz.
- Restrição: É permitida apenas uma posição raiz por empresa.

Vínculo de colaborador

O preenchimento do colaborador é opcional (a posição pode ser criada como posição aberta).
Se informado, o colaborador não pode estar vinculado a outra posição ativa simultaneamente.

Exemplo de requisição (cURL)

curl --location 'api.gupy.io/os/v1/positions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer bearer_token_value_here' \
--data-raw '{   
  "name": "Nome da posição",
  "description": "Descrição da posição",
  "externalCodeCostCenter": "COST_CENTER_CODE",
  "externalCodeArea": "AREA_CODE",
  "externalCodeRole": "CARGO_CODE",
  "externalCodeParent": "PARENT_PISITION_CODE",
  "employeeEmail": "[email protected]",
  "employeeTaxpayerRegistry": null,
  "employeeInternalCompanyNumber": null
}'

Atenção: Forneça o token de autenticação no cabeçalho Authorization.

Possiveis erros

Área não encontrada

Erro lançado quando a área não foi encontrada através do externalCodeArea informado.

{
  "statusCode": 404,
  "timestamp": "2025-05-29T21:00:00.000Z",
  "path": "/v1/positions",
  "method": "POST",
  "title": "NotFoundException",
  "message": "Area not found",
  "errors": [
    {
      "code": "AREA_NOT_FOUND",
      "target": "NotFoundException",
      "message": "Area not found"
    }
  ]
}

Cargo não encontrado

Erro lançado quando o cargo não foi encontrado através do externalCodeRole informado.

{
  "statusCode": 404,
  "timestamp": "2025-05-29T21:00:00.000Z",
  "path": "/v1/positions",
  "method": "POST",
  "title": "NotFoundException",
  "message": "Role not found",
  "errors": [
    {
      "code": "ROLE_NOT_FOUND",
      "target": "NotFoundException",
      "message": "Role not found"
    }
  ]
}

Centro de custo não encontrado

Erro lançado quando o centro de custo não foi encontrado através do externalCodeCostCenter informado.

{
  "statusCode": 404,
  "timestamp": "2025-05-29T21:00:00.000Z",
  "path": "/v1/positions",
  "method": "POST",
  "title": "NotFoundException",
  "message": "Cost center not found",
  "errors": [
    {
      "code": "COST_CENTER_NOT_FOUND",
      "target": "NotFoundException",
      "message": "Cost center not found"
    }
  ]
}

Liderança não encontrada

Erro lançado quando a posição da liderança não foi encontrada através do externalCodeParent informado.

{
  "statusCode": 404,
  "timestamp": "2025-05-29T21:00:00.000Z",
  "path": "/v1/positions",
  "method": "POST",
  "title": "NotFoundException",
  "message": "Parent position not found",
  "errors": [
    {
      "code": "PARENT_POSITION_NOT_FOUND",
      "target": "NotFoundException",
      "message": "Parent position not found"
    }
  ]
}

Colaborador não encontrado

Erro lançado quando o colaborador não foi encontrado através do employeeEmail, employeeTaxpayerRegistry e employeeInternalCompanyNumber informado.

{
  "statusCode": 404,
  "timestamp": "2025-05-29T21:00:00.000Z",
  "path": "/v1/positions",
  "method": "POST",
  "title": "NotFoundException",
  "message": "Employee not found",
  "errors": [
    {
      "code": "EMPLOYEE_NOT_FOUND",
      "target": "NotFoundException",
      "message": "Employee not found"
    }
  ]
}

Colaborador alocado em outra posição

Erro lançado quando o colaborador informado está vinculado a outra posição.

{
  "statusCode": 409,
  "timestamp": "2025-05-29T21:00:00.000Z",
  "path": "/v1/positions",
  "method": "POST",
  "title": "ConflictException",
  "message": "Employee is already in another position",
  "errors": [
    {
      "code": "EMPLOYEE_ALREADY_ASSIGNED",
      "target": "ConflictException",
      "message": "Employee is already in another position"
    }
  ]
}

Posição raiz (sem liderança) já existe

Erro lançado quando externalCodeParent não é informado, porém já existe uma posição raiz cadastrada na base.

{
  "statusCode": 409,
  "timestamp": "2025-05-29T21:00:00.000Z",
  "path": "/v1/positions",
  "method": "POST",
  "title": "ConflictException",
  "message": "Only one root position allowed per company.",
  "errors": [
    {
      "code": "ALREADY_EXISTS_ROOT_POSITION",
      "target": "ConflictException",
      "message": "Only one root position allowed per company."
    }
  ]
}

Posição já existe cadastrado na base

Erro lançado quando externalCode informado já existe cadastrado na base.

{
  "statusCode": 422,
  "timestamp": "2025-05-29T21:00:00.000Z",
  "path": "/v1/positions",
  "method": "POST",
  "title": "UnprocessableEntityException",
  "message": "A position with this external code already exists in the company",
  "errors": [
    {
      "code": "POSITION_ALREADY_EXISTS",
      "target": "UnprocessableEntityException",
      "message": "A position with this external code already exists in the company"
    }
  ]
}