Campos adicionais do usuário

Cargo, matrícula, unidade, data de admissão: cada instância da Engage tem seus próprios campos de cadastro, chamados de campos adicionais (ou atributos). Este artigo mostra como descobrir quais existem na sua instância e como preenchê-los pela API.

Antes de começar

• As credenciais da sua instância, reunidas em Comece por aqui: credenciais para integrar com a API da Engage, e um token gerado em Passo 2 — Obtendo o access_token (POST /auth).
• Permissões do usuário de serviço: Gerenciar usuários (para enviar junto do cadastro) e Importação de dados (para enviar só os campos).
• Teste em homologação: https://sandbox.engage.bz/api/v1.

Preencher os campos

1Descubra os nomes dos campos

GET https://sandbox.engage.bz/api/v1/{customer_id}/attributes
Authorization: Bearer {access_token}

Resposta da listagem de campos adicionais, com o tipo do campo e o nome com prefixo destacados

Repare em dois campos de cada item: attribute_type.name, o tipo (texto, número, data, lista), e name, o nome do campo. O nome vem com o seu customer_id como prefixo — no exemplo, manoel_test.

Outras consultas úteis:

2Envie os valores

Caminho recomendado — junto com o cadastro do usuário. Use a propriedade attributes no POST /{customer_id}/users: o usuário e os campos são gravados na mesma chamada.

[
  {
    "login": "joao.silva",
    "name": "João da Silva",
    "status": true,
    "attributes": [
      { "cargo": "Recepcionista", "data_admissao": "25-09-2019", "unidade": "Matriz" }
    ]
  }
]

Caminho alternativo — só os campos, para usuários que já existem:

POST https://sandbox.engage.bz/api/v1/{customer_id}/users/importAttributes/import?customerToken={customer_token}
Authorization: Bearer {access_token}
Content-Type: application/json

[
  { "Login": "joao.silva", "cargo": "Recepcionista", "data_admissao": "25-09-2019" }
]

Corpo do envio só de campos adicionais no Postman: a chave Login e uma chave por campo

Formato de cada tipo de valor

Quando um campo falha

O cadastro do usuário é gravado antes dos campos adicionais. Se um campo falhar, o registro volta com "success": false — mas o usuário existe, e o object_id traz o ID dele:

Resposta real com success false e object_id preenchido: o usuário foi criado, mas um campo não existe e outro obrigatório faltou

Cuidados

• Enviou algum campo? Envie todos os obrigatórios daquele usuário. A validação cobra todos os campos obrigatórios, mesmo os que você não pretendia alterar. Consulte /attributeGroups. Se você omitir attributes por inteiro, essa cobrança não acontece.
• Um campo inválido descarta todos os campos daquele usuário na mesma chamada. Os outros usuários do lote não são afetados.
• Data enviada como número vira outra data, sem erro: 43738 é lido como número de planilha. Envie sempre como texto.
• Não use POST /entityAttributes para integrar. É o caminho das telas da plataforma e substitui todos os campos do usuário pelo que veio na chamada.

Problemas comuns

O código de cada erro vem em detail_messages[].event_code.