Identificadores em referências¶

Visão Geral¶

A API Pontotel utiliza diferentes tipos de identificadores dependendo do recurso para facilitar a criação ou atualização de entidades. Entender esses formatos é essencial para construir integrações robustas. Os endpoints que possuem esse recurso ativo apresentam o atributo e também um campo na requisição que informa qual identificador está sendo utilizado para aquele atributo. Por exemplo, ao definir o empregador de um empregado, a API permite que o CNPJ seja utilizado como identificador: basta passar o CNPJ no valor do atributo e informar que o identificador utilizado é o CNPJ, conforme o exemplo: {"empregador": "84984743000133", "identificadorEmpregador": "cnpj"}.

Por padrão, o id é o identificador utilizado. Para verificar quais outros identificadores são aceitos em cada caso, consulte a documentação específica de cada recurso.

Identificadores em referências¶

Ao criar ou atualizar entidades que referenciam outras, é possível especificar qual identificador está sendo usado para cada referência. Isso evita a necessidade de buscar o id interno antes de criar um registro, necessitando de uma operação a mais para criar ou atualizar um registro. O padrão é: o campo com o valor da referência acompanhado de um campo identificador<Entidade> indicando o tipo:

1
2
3
4

{
  "empregador": "84984743000133",
  "identificadorEmpregador": "cnpj"
}

Este payload teria o mesmo resultado que o payload a seguir:

1
2
3
4

{
  "empregador": "1d3fc7947bee78a5179720a",
  "identificadorEmpregador": "id"
}

Geralmente o código é bastante utilizado nesses casos pois ele é um campo aberto para que o cliente da API possa defini-lo para identificar entidades entre sistemas.

Empregado¶

Ao cadastrar ou atualizar um empregado, é possível referenciar escala, regra de cálculo, local de trabalho, empregador e líder direto por diferentes identificadores:

Ao invés de passar os ids internos das referências, o payload pode ter apenas o código identificando as entidades:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

{
  "nome": "João Silva",
  "cpf": "12345678900",
  "admissao": "2025-01-01",
  "empregador": "84984743000133",
  "identificadorEmpregador": "cnpj",
  "localTrabalho": "123-321",
  "identificadorLocalTrabalho": "codigo",
  "regraCalculo": "1",
  "identificadorRegraCalculo": "codigo",
  "escala": "5x2",
  "identificadorEscala": "codigo",
  "usuarioLiderDireto": "1234",
  "identificadorUsuarioLiderDireto": "codigo",
}

Desta forma, como o código é utilizado para salvar o id de ligação entre as entidades nos sistemas, é fácil obtê-lo para construir o payload de integração do empregado.

Usuários¶

Ao cadastrar ou atualizar um usuários, é possível referenciar empregador e local por diferentes identificadores:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

{
  "nome": "Fulano 1",
  "email": "fulano@pontotel.com.br",
  "codigo": "1234",
  "senha": "fulano@pontotel.com.br",
  "cpf": "1134587624",
  "permissao": "1",
  "identificadorPermissao": "codigo",
  "permissaoAppGestao": "1",
  "identificadorPermissaoAppGestao": "codigo",
  "identificadorEmpregado": "codigo",
  "empregado": "123456",
  "locais": [
    "1234"
  ],
  "identificadorLocaisDeTrabalho": "codigo"
}

Boas práticas¶

Use chaves de negócio para vínculos entre sistemas¶

Sempre utilize o campo codigo ao integrar com outros sistemas para identificar as entidades, de modo que este campo seja equivalente ao identificador da entidade no outro sistema, isto é, o seu id interno ou matrícula, afim de facilitar os fluxos de integração — o id interno da Pontotel pode variar entre ambientes (homologação, sandbox e produção)

Próximos passos¶

Agora que você já aprendeu sobre os conceitos básicos da API e funcionalidades como filtrso e identificadores, você pode:

• Entrar em contato com o atendimento solicitando um usuário de API no ambiente de homologação
• Solicitar materiais complementares como coleções no Postman e planilas para facilitar o mapeamento de campos entre os sistemas