Cómo enviar datos a la API de Plecto

¿Qué es la API de Plecto?

La API de Plecto permite a los desarrolladores crear una integración avanzada personalizada que permite que otro software se comunique con nuestra plataforma y exporte sus datos a Plecto.

Si quieres probar la API de Plecto manualmente, puedes usar un software gratuito como Postman, pero también se admite cualquier otra herramienta capaz de enviar solicitudes HTTP.

Autenticación

El esquema de autenticación utilizado para la API de Plecto es Basic Authentication. Consiste en enviar tu correo electrónico y contraseña junto con la solicitud.
¡Consejo! 💡 Recomendamos crear un nuevo usuario (nuevo perfil de empleado) por cada integración en tu organización de Plecto; de esta manera, evitarás compartir la misma contraseña entre varias integraciones.
El usuario debe tener acceso a las áreas relevantes de Plecto para poder usar correctamente la mayoría de los endpoints de la API. Si tu suscripción de Plecto incluye la gestión avanzada de permisos, puedes crear un perfil de permisos específico para la cuenta de usuario.

Para crear nuevos empleados, ve a Configuración > Empleados > Nuevo empleado en Plecto o añádelos mediante una solicitud a la API.

URL base y endpoints

Todos los endpoints de la API de Plecto están listados bajo la siguiente URL base: https://app.plecto.com/api/v2/

Esta URL es la base de todos los endpoints de la API de Plecto. Si has iniciado sesión en tu cuenta de Plecto, puedes ver la lista de endpoints de la API directamente en el navegador.

Cómo crear una fuente de datos de la API

Puedes crear una fuente de datos de la API de dos maneras:

Enviar una solicitud POST a este endpoint: https://app.plecto.com/api/v2/datasources/ Basta con incluir las claves "title" y "fields" en la solicitud para crear la fuente de datos.
O ve a Fuentes de datos > Nueva fuente de datos > Plecto API y crea una nueva fuente de datos desde la interfaz de Plecto.

Puedes ejecutar una prueba usando el cuerpo de la solicitud anterior.

Añadir más campos

Si necesitas añadir más campos a tu fuente de datos de la API, tendrás que hacerlo a través de la interfaz de usuario en la configuración de tu fuente de datos. Actualmente no admitimos la actualización de campos a través de la API.

Añadir registros: Claves obligatorias

Endpoint: https://app.plecto.com/api/v2/registrations/

El cuerpo de la solicitud anterior muestra cómo añadir varios registros a la vez. Si quieres usarlo, asegúrate de añadir los UUID de data_source y member de tu organización.

Claves obligatorias que se deben incluir en cada registro

Hay 3 claves obligatorias que deben incluirse en el cuerpo de la solicitud para cada solicitud a la API que envíes. Las claves son las siguientes:

data_source,
member (o member_api_provider, member_api_id y member_name), y
external_id.

#1	data_source	La clave data_source requiere el UUID de tu fuente de datos. El UUID es una cadena alfanumérica que puedes encontrar en la URL al abrir una fuente de datos.
#2Elige una u otra	member	Usar el UUID de member requiere tener un perfil de empleado existente en Plecto. Para encontrar el UUID de member, ve a la página Empleados y haz clic en un nombre. Verás el UUID en la URL.
member_api_providermember_api_idmember_name	Con esta opción, Plecto puede crear nuevos perfiles de empleado cuando envías los datos, y el empleado seguirá siendo gestionado por tu sistema. member_api_provider se refiere al nombre de tu sistema. En la imagen de abajo, el nombre de sistema mostrado es Postman. member_api_id se refiere al ID del empleado en tu sistema. En Plecto, se muestra en el campo External ID. En la imagen de abajo, 101032 representa el member_api_id. member_api_provider y member_api_id identifican juntos a un empleado en Plecto. member_name es el nombre del empleado. Este nombre se mostrará en el campo Empleado de tu fuente de datos de Plecto y se puede actualizar, siempre que uses los mismos valores de member_api_provider y member_api_id.
#3	external_id	external_id es un número o una cadena de caracteres que debe ser único para cada registro. Podría ser algo como 123, abc o cualquier cosa que se te ocurra. Esto es importante, ya que será la referencia del registro creado. Los valores de external ID en el cuerpo de tu solicitud se muestran en el campo "ID" de tu fuente de datos de Plecto.

¿Puedo usar el mismo external ID?

Si envías una solicitud con el mismo external ID que ya has usado, se sobrescribirá un registro existente en Plecto y se mostrará la nueva información actualizada.

Convenciones de nomenclatura: ¡no te confundas!

La clave member_api_id en el cuerpo de tu solicitud representa el External ID que se muestra en el perfil del empleado en Plecto, y la clave external_id representa el Registration ID en una fuente de datos de Plecto.

Registros masivos

Si quieres asignar varios registros al mismo usuario, puedes usar el mismo member_api_id. Sin embargo, la clave external_id debe ser diferente para cada registro, a menos que quieras sobrescribir un registro existente con nuevos datos.

Ejemplo básico: Añadir registros a través de la API

¡Enviemos nuevos registros a una fuente de datos de Plecto!

La solicitud para crear un registro en una fuente de datos debe usar la URL del endpoint de registrations, que es la siguiente: https://app.plecto.com/api/v2/registrations/
El cuerpo de la solicitud POST debe incluir las claves obligatorias más una clave llamada "Value", ya que la fuente de datos en Plecto tiene un campo personalizado añadido llamado Value.

Si la autenticación se supera y la solicitud es correcta, Plecto aceptará el registro y devolverá una respuesta exitosa. En la respuesta, el "id" es el UUID del registro recién creado o actualizado en Plecto.

Inserción masiva

La API de Plecto admite el envío de una lista de registros en un único cuerpo de solicitud. Sin embargo, la API también impone un límite de 100 registros que se pueden enviar en una sola solicitud.

Arriba hay un ejemplo de cómo podría verse un cuerpo de solicitud.

Nota sobre los ID externos

No puedes enviar varios registros con el mismo external_id en la misma solicitud masiva. Si eso ocurre, obtendrás el siguiente error:

{ "message": "Duplicated registrations found", "id": "<your id>" }

Aprende a crear empleados en Plecto en este artículo: Cómo añadir empleados a Plecto a través de la API

Cómo actualizar datos existentes a través de la API

Endpoint: https://app.plecto.com/api/v2/registrations/

data_source y external_id identifican un registro en una fuente de datos en Plecto. El external_id representa el ID de registro en Plecto. Si quieres actualizar los valores del registro, envía una solicitud usando las mismas claves data_source y external_id, pero cambiando los valores de los campos.
member_api_provider y member_api_id identifican un empleado en Plecto. Si quieres actualizar el nombre del empleado, puedes enviar la misma solicitud, pero cambiando el valor de member_name, por ejemplo, de "Empleado X" a "Curtis Miller".
Puedes enviar un campo date a Plecto (opcional). Se mostrará en el campo Fecha de creación de tu fuente de datos. Cada vez que envías un registro, Plecto añade automáticamente la fecha y hora actuales. Si quieres actualizar un registro pero mantener la fecha y hora originales, añade la siguiente clave al cuerpo de tu solicitud: "date": "2022-12-31T10:22:55"

Formato de fecha

Si incluyes una clave date en el cuerpo de la solicitud, el formato de fecha debe seguir el estándar ISO 8601, con fecha y hora.

El formato debe verse así: 2018-12-31T22:33:44+00:00 La última parte después del + es una zona horaria opcional. Si no se establece, se asume que la zona horaria es UTC.

Resumen de los endpoints de la API de Plecto →