Criar ou atualizar usuário

POST/functions/v1/api?route=integracao

action usuario-upsertBearer token

Use externalId estável do RH, com até 200 caracteres e único por empresa. Nunca reutilize o identificador para outra pessoa. Na criação, nome (até 160 caracteres), e-mail (até 254) e permissões são obrigatórios.

Primeira chamada: HTTP 201, vínculo pendente e convite de sete dias. O destinatário precisa aceitar. Conta existente exige senha atual; conta nova exige senha de 12 a 128 caracteres. Não há alteração automática de senha.

Repetições com o mesmo externalId: HTTP 200, atualizam nome/permissões informados e retornam created: false, sem novo e-mail. O e-mail do vínculo é imutável. Mudança de identidade exige revogar o vínculo antigo e criar outro externalId. Vínculo revogado exige reconvite.

Parâmetros do corpo

actionstringobrigatório

Operação executada. Valor fixo desta página. usuario-upsert

externalIdstringobrigatório

Identificador estável e único por empresa. Nunca reutilize para outra pessoa.

emailstringna criação

E-mail da conta. Obrigatório na criação; imutável após o vínculo.

nomestringna criação

Nome do vínculo. Obrigatório na criação.

permissionsobjectna criação

Permissões por módulo. Obrigatório na criação; se omitido na atualização, mantém o estado atual.

Corpo da requisição

json

{
  "action": "usuario-upsert",
  "externalId": "RH-12345",
  "email": "pessoa@example.com",
  "nome": "Pessoa da equipe",
  "permissions": {
    "avaliacoes": "leitura",
    "riscos": "nenhum",
    "epi": "nenhum"
  }
}

Resposta

json

{
  "usuario": {
    "id": "11111111-1111-4111-8111-111111111111",
    "empresa_id": "22222222-2222-4222-8222-222222222222",
    "usuario_id": null,
    "email": "pessoa@example.com",
    "nome": "Pessoa da equipe",
    "status": "pendente",
    "permissions": {
      "avaliacoes": "leitura",
      "riscos": "nenhum",
      "epi": "nenhum"
    },
    "external_id": "RH-12345"
  },
  "emailSent": true
}

emailSent: true significa aceitação pelo provedor, não entrega na caixa de entrada. O link do convite não é devolvido à integração. Se emailSent for false, corrija a causa e use um novo evento de reconvite.