Identificadores en referencias¶

Visión general¶

La API Pontotel utiliza diferentes tipos de identificadores dependiendo del recurso para facilitar la creación de nuevas entidades o actualización de ellas. Entender estos formatos es esencial para construir integraciones robustas con una facilidad más.

En general, los endpoints que poseen este recurso activo tendrán el atributo y también otro campo en la requisición que dice que el identificador estamos utilizando para identificar ese atributo. Por ejemplo, para definir al empleador de un empleado, por defecto, sería necesario informar al id interno del empleador en Pontotel, pero la API permite que se utilice el CNPJ como identificador, siendo posible pasar el CNPJ del empleador por el valor del atributo e informar que vamos a utilizar el CNPJ como identificador para el empleador: {"empregador": "84984743000133", "identificadorEmpregador": "cnpj"}

Por patrón id es el identificador y, en la mayoría de los casos, tenemos el codigo como identificador disponible también.

Identificadores en referencias¶

Al crear o actualizar entidades que referencian a otras, es posible especificar qué identificador está siendo usado para cada referencia. Esto evita la necesidad de buscar el id interno antes de crear un registro, necesitando una operación más para crear o actualizar un registro. El patrón es: el campo con el valor de la referencia acompañado de un campo identificador<Entidade> indicando el tipo:

1
2
3
4

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

Este payload tendría el mismo resultado que el payload a seguir:

1
2
3
4

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

Generalmente el código es bastante utilizado en estos casos porque es un campo abierto para que el cliente de la API pueda definirlo para identificar entidades entre sistemas, siendo el codigo el vínculo entre las entidades en los diferentes sistemas.

Empleado¶

Al registrar o actualizar a un empleado, es posible referenciar escala, regla de cálculo, local de trabajo, empleador y líder directo por diferentes identificadores:

En lugar de pasar los ids internos de las referencias, el payload solo puede tener el código identificando las entidades:

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

{
  "nome": "Juan Pérez",
  "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",
}

De esta forma, como el código se utiliza para salvar el id de conexión entre las entidades en los sistemas, es fácil obtenerlo para construir el payload de integración del empleado.

Usuarios¶

Al registrar o actualizar a un usuario, es posible referenciar empleador y 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"
}

Buenas prácticas¶

Usá claves de negocio para vínculos entre sistemas¶

Siempre usá el campo codigo al integrarse con otros sistemas para identificar a las entidades, de modo que este campo sea equivalente al identificador de la entidad en el otro sistema, es decir, su id interno o matrícula, a fin de facilitar los flujos de integración, id interno de Pontotel puede variar entre ambientes (homologación, sandbox y producción)

Próximos pasos¶

Ahora que ya has aprendido sobre los conceptos básicos de la API y características como filtrso e identificadores, puede:

• Entrar en contacto con la atención solicitando un usuario de API en el ambiente de homologación
• Solicitar materiales complementarios como colecciones en Postman y planilas para facilitar el mapeo de campos entre los sistemas