Reference identifiers¶

Overview¶

The Pontotel API uses different types of identifiers depending on the resource to facilitate the creation of new entities or updating them. Understanding these formats is essential for building robust integrations with an extra ease.

In general, the endpoints that have this active resource will have the attribute and also another field in the request that says which identifier we are using to identify that attribute. For example, to define an employee's employer by default, it would be necessary to inform the employer's internal id at Pontotel, but the API allows the CNPJ to be used as an identifier, and it is possible to pass the employer's CNPJ on the attribute value and inform that we will use CNPJ as an identifier for the employer: {"empregador": "84984743000133", "identificadorEmpregador": "cnpj"}

By default o id is the identifier and, in most cases, we have the codigo as available identifier as well.

Reference identifiers¶

When creating or updating entities that refer to others, it is possible to specify which identifier is being used for each reference. This avoids the need to seek the id internal before creating a record, requiring an extra operation to create or update a record. The default is: the field with the reference value accompanied by a field identificador<Entidade> indicating the type:

1
2
3
4

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

This payload would have the same result as the payload following:

1
2
3
4

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

Usually the code is widely used in these cases because it is an open field so that the API client can define it to identify entities between systems, being the codigo the link between entities in different systems.

Employee¶

When registering or updating an employee, it is possible to refer to scale, calculation rule, workplace, employer and direct leader by different identifiers:

Instead of passing the internal ids of the references, payload may only have the code identifying entities:

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

{
  "nome": "John Smith",
  "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",
}

This way, as the code is used to save the link id between entities in the systems, it is easy to get it to build the employee integration payload.

Users¶

When registering or updating a user, it is possible to refer to employer and location by different identifiers:

 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"
}

Good practice¶

Use business keys for system links¶

Always use the field codigo by integrating with other systems to identify entities, so that this field is equivalent to the entity identifier in the other system, i.e. its internal id or registration, in order to facilitate integration flows — the id inside Pontotel can vary between environments (homologation, sandbox and production)

Next Steps¶

Now that you've learned about basic API concepts and features like filter and identifiers, you can:

• Contact the service requesting an API user in the approval environment
• Request complementary materials such as Postman collections and plans to facilitate field mapping between systems