Many times, you want to manage a group of businesses as a group. Some examples of this include:
Entity groups make managing these multi-entity situations much easier.
An entity group consists of a list of entities. Entities can be added to more than one group, though this is typically not recommended.
You can create a group without any entities and add them later, or create the entities first and then add them to the group.
Entity groups have an email inbox that is independent of the entities in the group.
Invoices that are sent to this inbox get created in the UNASSIGNED state, and then can be assigned to an entity in the group for further processing.
Many times, you will want to manage users at the group level. For example, the same admin user might need access to all entities in the group.
Mercoa uses the user’s foreignId to identity users across a group. Users can be added and removed from all entities in the group in a single API call, and roles can be managed on a per-entity basis.
Entity groups allow you to create a JWT token at the group level or group user level. This token gives access to all entities in the group without needed to generate an unique token for every entity in the group.
This token can be used in the Mercoa API, SDKs, and React Library.
In this example, we have three entities that are part of the same group.
ent_e8c2af94-61cd-4036-a765-80341209167bent_1176dd0c-12e1-41c7-85a5-ae9b4746e64bent_3dbb4ede-2d1d-49be-a996-a5dfad3641beFirst, we can create this group with these three entities:
Next, let’s say we want to add a user to all entities in the group with the “admin” role.
Next, let’s say we want to add a user to all entities in the group, but we want to give the user a different role for each entity.
Next, let’s say we want to add another entity to the group.
When adding an entity to a group, you can optionally copy the users from an existing entity in the group.
Do this using the copyUsersFrom field. You can specify an entity ID or set this to true to copy users from
the entity with the most users that has been updated most recently.
If at any point users have been added to a specific entity in the group instead of the group itself, you can sync the users from the entity to the group.
This will let you make sure that all entities in the group have the same users as needed.