Sign in

v1

latestOpenAPI 3.0.02026-07-24161168406.5 KB
Position
Position

Replace position by employee identifier (CPF or Email)

Finds a position by the current occupant's CPF or email, then performs a COMPLETE replacement of that position. The identifier parameter automatically detects if the value is an email (contains @) or a CPF.

Parent Position (Leader):

• For ROOT positions: omit all three parent fields (externalCodeParent, parentEmail, parentTaxpayerRegistry)

• For NON-ROOT positions: you MUST provide ONE of:

  • externalCodeParent: External code of the parent position
  • parentEmail: Email of the leader (will find their active position)
  • parentTaxpayerRegistry: CPF of the leader (will find their active position)

This is a PUT operation - all required fields must be provided.

Examples:

• identifier: "maria@gupy.com.br" (email)

• identifier: "13306708792" (CPF)

• externalCodeParent: "POS-123" (traditional way)

• parentEmail: "leader@cliente.com" (sets the position leader by email)

• parentTaxpayerRegistry: "987.654.321-00" (sets the position leader by CPF)

Business Rules:

• The identifier (CPF or email) must match an existing employee

• The employee must have an active position

• For non-root positions, ONE parent identifier must be provided (externalCodeParent OR parentEmail OR parentTaxpayerRegistry)

• If parentEmail/parentTaxpayerRegistry is provided, the leader must exist and have an active position

• All required fields (name, externalCodeRole, externalCodeArea) must be provided

• This operation replaces all position data

• Set nullable fields to null to remove them

• Role and Area must exist

• New employee can only be assigned to one position at a time

• When additionalParents is provided, it completely replaces any existing additional leaders

• An empty array for additionalParents removes all additional leaders

• When additionalParents is not provided (undefined), existing additional leaders remain unchanged

• Maximum of 5 additional parents allowed

• Additional parents cannot include the position itself (self-reference)

• Additional parents cannot include the direct parent position

• All additional parent positions must exist

Use Cases:

• Complete position replacement

• Update all position fields at once including the leader

• Change the occupant with full position update

• Make a position vacant by setting employeeEmail to null

• Create or update root positions by omitting parent fields

put/os/v1/positions/update-by-employee/{identifier}

Path parameters

identifierstring required
Example:82301395553

Employee identifier to find the current position occupant. Can be either an email address or a CPF (taxpayer registry). The API will automatically detect the type based on the format.

Request body

namestring required

Human-readable name for the position

externalCodestring

External code identifier for the position. If not provided, keeps the current externalCode.

descriptionstring nullable

Detailed description of the position. Set to null to remove description.

externalCodeRolestring required

External code of the role to associate with this position

externalCodeAreastring required

External code of the area to associate with this position

externalCodeParentstring

External code of the parent position in the organizational hierarchy. Required for non-root positions. Use this OR parentEmail OR parentTaxpayerRegistry (only one is needed). Omit all three to create a root position.

externalCodeCostCenterstring nullable

External code of the cost center to associate with this position. Set to null to remove cost center.

externalCodeOperationUnitstring nullable

External code of the operation unit to associate with this position. Set to null to remove operation unit.

parentEmailstring email

Email da nova líder (alternativo ao externalCodeParent). Required for non-root positions if externalCodeParent and parentTaxpayerRegistry are not provided. Será usado para localizar a posição ativa da líder.

parentTaxpayerRegistrystring

CPF da nova líder (alternativo ao externalCodeParent). Required for non-root positions if externalCodeParent and parentEmail are not provided. Será usado para localizar a posição ativa da líder.

employeeEmailstring email nullable

Email address of the new employee to assign to this position. Set to null to unassign employee.

employeeTaxpayerRegistrystring nullable

Tax payer registry (CPF) of the new employee to assign to this position. Set to null to unassign employee. Must be a valid CPF format.

employeeInternalCompanyNumberstring nullable

Internal company identification number of the new employee to assign to this position. Set to null to unassign employee.

additionalParentsstring[] nullable

Optional list of external codes of additional parent positions (additional leaders) for this position. When provided, this list will completely replace any existing additional leaders. An empty array or null will remove all additional leaders. If not provided (undefined), existing additional leaders will be kept unchanged. Maximum of 5 items allowed.

Example request

{
  "name": "Senior Software Engineer",
  "externalCode": "POS-12345",
  "description": "Senior software engineer responsible for backend development and architecture decisions",
  "externalCodeRole": "SE_ROLE",
  "externalCodeArea": "TECH_AREA",
  "externalCodeParent": "TECH_LEAD",
  "externalCodeCostCenter": "CC_TECH",
  "externalCodeOperationUnit": "OU_TECH",
  "parentEmail": "leader@company.com",
  "parentTaxpayerRegistry": "987.654.321-00",
  "employeeEmail": "jane.doe@company.com",
  "employeeTaxpayerRegistry": "123.456.789-00",
  "employeeInternalCompanyNumber": "EMP001",
  "additionalParents": [
    "LEADER_01",
    "LEADER_02"
  ]
}

Response

Position successfully replaced

resultobject required

Result data

pathstring required

Request path

durationstring required

Request duration

method'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' required

HTTP method used

Example response

{
  "data": {
    "uuid": "cc2339c3-bf5a-406b-bafa-3bf8c0acbf23",
    "name": "Software Engineer",
    "externalCode": "SE123",
    "description": "Posição de desenvolvedor time ABC",
    "role": {
      "name": "Desenvolvedor",
      "similarity": "CONSULTANT",
      "externalCode": "RR-001"
    },
    "employee": {
      "uuid": "d20dc017-80c6-4706-bbfe-549c1cc4d2c1",
      "internalCompanyNumber": "132AT41"
    },
    "area": {
      "uuid": "cab41475-caa7-47a7-9b28-eecae80c1ae3",
      "name": "Produto",
      "similarity": "ACCOUNTING",
      "externalCode": "AA-001"
    },
    "costCenter": {
      "name": "CC-001",
      "externalCode": "CC-001"
    },
    "operationUnit": {
      "name": "Operation Unit 1",
      "externalCode": "OU-001"
    },
    "parent": {
      "uuid": "0372fc1b-35e0-42c5-bbe7-98dc7c218da1",
      "name": "Software Engineer",
      "externalCode": "SE123",
      "employee": {
        "uuid": "d20dc017-80c6-4706-bbfe-549c1cc4d2c1",
        "internalCompanyNumber": "132AT41"
      }
    },
    "additionalParents": [
      {
        "uuid": "0372fc1b-35e0-42c5-bbe7-98dc7c218da1",
        "name": "Software Engineer",
        "externalCode": "SE123",
        "employee": {
          "uuid": "d20dc017-80c6-4706-bbfe-549c1cc4d2c1",
          "internalCompanyNumber": "132AT41"
        }
      }
    ],
    "status": "OPEN"
  }
}