Duda
¿Cómo utilizar la API de Integración en la práctica?
Ambiente
Cross Segmentos - TOTVS CRM Gestión de Clientes MI - API de Integración - Todas las versiones
Solución
Para explicar como funciona la API de Integración, vamos a mostrar paso a paso como registrar un cliente, teniendo en cuenta un usuario ficticio.
Para registrar un cliente (utilizar la API de Integración en la práctica), siga estas etapas:
1. Ejecuta una solicitud con el método POS para hacer login en la aplicación:
1.1. Utiliza esta URL: https://app2.mastercrm.ws/api/login
2. Pase las informaciones de login de la aplicación abajo, en formato JSON, para el cuerpo de la solicitud (body)
{
"username": "usuario@dominio.com.br",
"password": "micontraseña",
"tenant": "miempresa"
}
2.1. Recibirás un retorno 200;
2.2. Un registro llamado JSESSIONID, con el token de sección, será retornado en el cookie.
3. Pase en Header el cookie con la información del JSESSIONID:
3.1. Es necesario pasar en Cookie para enviar todas las próximas solicitudes.
4. Encuentra los recursos disponibles de la API:
4.1. Todos los recursos están disponibles en Git Lab en esta url:
https://gitlab.wssim.com.br/docs/api/-/tree/master/integration
4.2. Vamos utilizar como ejemplo el recurso de clientes (customers);
4.3. Se nota que, dentro de la documentación de la API, tenemos todo lo que necesitamos (URL, el método HTTP y la extensión de URL):
5. En la documentación de API, encuentra los parámetros que deben ser pasados en Header de la solicitud:
5.1. Se nota que, los que están con " * ", son obligatorios;
5.2. Integration-Action: Acción a ser realizada en la API de Integración. Son soportadas las acciones:
- create: acción para creación de nuevo registro en CRM;
- update: acción para actualización parcial del registro presente en CRM;
- upsert: tiene dos comportamientos, donde puede actuar como actualización o inserción. Lo que determina el comportamiento es el contenido informado en header Integration-Filter. Si el registro informado ya existe en CRM, es realizada una actualización completa del registro presente en CRM, reemplazando todo el contenido presente en CRM por el contenido enviado en la solicitud. Si el ID no esté presente en CRM, se hace una inserción del contenido enviado en la solicitud;
5.3. Integration-Service: Servicio responsable por la entidad. Por ejemplo: customer;
5.4. Integration-Resource: Recurso para solicitud. Por ejemplo: customers-integration;
5.5. Integration-Version: Versión de la API de integración. Por ejemplo: v1;
5.6. Integration-Filter: Usado en acciones de update e upsert como identificador del registro a ser actualizado o cuando la consulta realizada sea un GET, actúa como filtro de registros, siendo soportado el formato RestQuery para la filtración. Para el ejemplo de creación de cliente con la acción create, no es soportado para el uso de este header:
| KEY | VALUE |
| Integration-Version | V1 |
| Integration-Service | customer |
| Integration-Resource | customers-integration |
| Integration-Action | create |
6. Informa los dados en el cuerpo de la solicitud (body) en formato JSON, de las informaciones del cliente que deben ser registradas:
{
"active": true,
"name": "Mi empresa Ltda",
"tradingName": "Mi empresa y cia",
"code": "00001"
}
6.1. Después de haber ejecutado la solicitud, deberás recibir un retorno 200, y será retornado en el cuerpo del ID del cliente registrado.
7. Lista los clientes con una solicitud GET:
7.1. Si no has realizado la autenticación, repita los pasos hasta el artículo 3;
7.2. Utiliza el método GET en la misma URL, como descrito en la documentación:
7.3. Para listar los clientes, no es necesario enviar el cuerpo de la solicitud (body). Al realizar la solicitud, en el cuerpo de la respuesta será retornado um JSON con la lista de clientes:
7.4. Para más informaciones sobre otros recursos dela API del TOTVS CRM, acceda a documentación de la API en Git Lab.
Sepa más
Para más detalles sobre este proceso, acceda los artículos abajo:
0 Comentarios