Ahora todos los usuarios de la API podrán ampliar la manera en la que obtienen información de los documentos de su cuenta, así como de otros recursos. Al integrar la funcionalidad de búsquedas avanzadas, el rendimiento de cada implementación de API podrá mejorar de la siguiente manera:
- Los usuarios de API tienen mayor control de su implementación sin depender de nuestro equipo técnico. Los atributos y relaciones están definidas, así que pueden hacer uso de cada uno dependiendo de sus necesidades.
- Mayor flexibilidad para consultar recursos por parámetros específicos y no solo por su id. Por ejemplo, ahora se podrá buscar por external id, nombre, etc.
- Mejorarán los tiempos de respuesta, pues ahora solo se obtendrá la información que se solicite, así que no se cargará información innecesaria.
- La infraestructura y recursos se optimizarán, al solo obtener la información relevante.
Para conocer mejor cómo se puede aplicar esta funcionalidad en una integración real, en este artículo se desglosan algunos casos de uso. Asimismo se explican los parámetros de las llamadas a detalle.
Recuerda que para usar la API deberás tener creada una cuenta en Mifiel y haber generado tus access tokens. También te recomendamos probar el servicio en sandbox antes de hacer cualquier cambio en producción.
Contenidos
- ¿De qué manera puedo usar las búsquedas avanzadas?
- Cómo se crean las llamadas de búsqueda de recursos
- Casos y reglas especiales a tomar en cuenta
¿De qué manera puedo usar las búsquedas avanzadas?
Mediante algunos de los casos de uso más comunes, podrás conocer los beneficios de usar búsquedas avanzadas en tu integración. También puedes ver estos ejemplos en acción en el siguiente video:
Caso de uso: Buscar documentos por una parte de su nombre
Los nombres de archivos que das a tus documentos pueden ayudarte a saber más detalles del mismo: qué tipo de documento es, a qué cliente pertenece, si forma parte de alguna tanda de documentos, quién lo creó, etc.
Mediante esta integración puedes buscar documentos por alguna palabra específica que hayas agregado en su nombre de archivo. Por ejemplo, si sueles nombrar tus documentos con el nombre del cliente y quieres buscar todos los documentos de un cliente en específico para ver el estado en el que se encuentran, podrías hacer la siguiente búsqueda:
{
"version": "1.0.0",
"resource": "document",
"page": 1,
"per_page": 20,
"q": {
"file_file_name": {
"cont": "Valencia"
}
},
"sort": "created_at-desc",
"fields": "file_file_name,created_at,state"
}
En el ejemplo anterior se definió que los recursos (resource) que se van a buscar son documentos (document), que en el nombre (file_file_name) deben contener la palabra “Valencia” (en este caso, el apellido de tu cliente), que los resultados se ordenen de manera descendente por su fecha de creación (created_at-desc) y que los resultados solo incluyan el nombre del documento (file_file_name), la fecha de creación (created_at) y su estado (state).
{
"_metadata": {
"page": 1,
"per_page": 20,
"page_count": 1,
"total_count": 4
},
"records": [
{
"file_file_name": "Contrato_Valencia_prestamos.pdf",
"created_at": "2021-10-27T21:47:30.276Z",
"state": "pending"
},
{
"file_file_name": "Anexo_A_Valencia_Prestamos.pdf",
"created_at": "2021-10-27T21:47:02.168Z",
"state": "pending"
},
{
"file_file_name": "Pagaré_Valencia_prestamos.pdf",
"created_at": "2021-10-27T21:45:06.690Z",
"state": "pending"
},
{
"file_file_name": "Anexo_B_Valencia_Prestamos.pdf",
"created_at": "2021-10-27T21:40:03.711Z",
"state": "pending"
}
]
}
Caso de uso: Identificar todos los documentos que necesita firmar un firmante en específico
A veces para continuar el proceso de un cliente, es necesario que firme un grupo de documentos. Sin embargo, con el volumen diario de documentos y clientes, la búsqueda de una sola persona podría resultar complicada.
Esto cambia con las búsquedas avanzadas, ya que además de buscar características globales del documento, es posible identificar también sus relaciones con sus participantes; ya sean firmantes, revisores o incluso espectadores. Así, podrías buscar todos los documentos esperando la firma de una persona en particular.
{
"version": "1.0.0",
"resource": "document",
"page": 1,
"per_page": 20,
"q": {
"stakeholders": {
"type": {
"eq": "Signer"
},
"state": {
"eq": "pending"
},
"email": {
"eq": "victor@mifiel.com"
}
}
},
"sort": "created_at-desc",
"fields": "file_file_name,created_at,state,stakeholders(type,email,state,widget_id)"
}
En el ejemplo anterior se están buscando todos los documentos que tengan participantes firmantes en espera de firma y cuyo correo sea victor(at)mifiel.com Con esta petición se espera que además de cierta información general de los documentos (nombre, estado y fecha de creación), también se muestren datos del participante (stakeholders) como su tipo (type), su correo electrónico (email), su estado (state) y su widget_id, con este último dato se podría crear un flujo de firma de documentos múltiples en una sesión (bulk) para que este firmante lo complete y firme todos los documentos de una sola vez.
{
"_metadata": {
"page": 1,
"per_page": 20,
"page_count": 1,
"total_count": 3
},
"records": [
{
"file_file_name": "Contrato_Crea_Marketing.pdf",
"created_at": "2021-10-27T21:33:37.220Z",
"state": "pending",
"stakeholders": [
{
"type": "Signer",
"email": "victor@mifiel.com",
"state": "pending",
"widget_id": "77635c95-b33a-4fd8-b0ae-5d694554b471"
}
]
},
{
"file_file_name": "Pagare_Crea_Marketing.pdf",
"created_at": "2021-10-27T21:25:50.090Z",
"state": "pending",
"stakeholders": [
{
"type": "Signer",
"email": "victor@mifiel.com",
"state": "pending",
"widget_id": "2a749fff-d5c4-483e-a2c8-31881094ca41"
}
]
},
{
"file_file_name": "1Comprar_documentos___Mifiel_signed.pdf",
"created_at": "2019-10-16T17:22:18.447Z",
"state": "pending",
"stakeholders": [
{
"type": "Signer",
"email": "victor@mifiel.com",
"state": "pending",
"widget_id": "be35b7fe-fe99-40e1-8b67-bb9de38202b3"
},
{
"type": "Signer",
"email": "rosalinda.gonzalez.g@gmail.com",
"state": "completed",
"widget_id": null
}
]
}
]
}
Caso de uso: Identificar todos los documentos sin firmar para eliminarlos y así recuperar créditos
Con la operación diaria, la cantidad de documentos creados puede superar a los adquiridos dentro del paquete. Sin embargo, es posible recuperar algunos créditos al eliminar documentos que nunca se hayan firmado; ya sea porque se usaron como prueba, los firmantes ya no procedieron con su participación o por cualquier otro motivo que haga inservibles estos documentos pendientes. La cantidad y las fechas de creación podrían variar. Aun así, el proceso para buscar estos documentos sin firmar puede facilitarse mediante la integración del nuevo servicio.
{
"version": "1.0.0",
"resource": "document",
"page": 1,
"per_page": 20,
"q": {
"created_at": {
"gteq": "2021-01-01",
"lteq": "2021-07-31"
},
"state": {
"eq": "pending"
}
},
"sort": "created_at-desc",
"fields": "file_file_name,created_at,state,id"
}
En el ejemplo se hace la petición para que la API nos muestre todos los documentos pendientes creados entre el 1 de enero de 2021 y el 31 de julio de 2021. Estos documentos incluirán entre otros parámetros el id, que permitirá realizar llamadas en el endpoint correspondiente para eliminar estos documentos de manera más rápida, obteniendo así esos créditos de regreso.
{
"_metadata": {
"page": 1,
"per_page": 20,
"page_count": 1,
"total_count": 10
},
"records": [
{
"id": "32214f64-f695-4691-8f6c-073681b05543",
"file_file_name": "demo.pdf",
"created_at": "2021-07-21T17:05:36.821Z",
"state": "pending"
},
{
"id": "7a5bb55b-fffe-4864-b252-f85fe1f897f5",
"file_file_name": "demo.pdf",
"created_at": "2021-07-21T15:53:46.963Z",
"state": "pending"
},
{
"id": "0f237a54-96f5-4407-a539-ec8db8b0a1af",
"file_file_name": "demo.pdf",
"created_at": "2021-07-21T15:33:08.228Z",
"state": "pending"
},
{
"id": "1d3b0e40-a66e-4061-9e68-df0071fc2d33",
"file_file_name": "test14.pdf",
"created_at": "2021-07-21T14:44:53.775Z",
"state": "pending"
},
{
"id": "cc3e166c-36ae-493b-8c0d-0bbc50e7c802",
"file_file_name": "demo.pdf",
"created_at": "2021-07-09T23:05:13.922Z",
"state": "pending"
},
{
"id": "6b8f6587-289d-48e6-af32-f9c430622e59",
"file_file_name": "demo.pdf",
"created_at": "2021-07-09T22:17:57.444Z",
"state": "pending"
},
{
"id": "abc85236-4da6-44b3-ad60-378549027ab8",
"file_file_name": "demo.pdf",
"created_at": "2021-07-09T22:16:58.275Z",
"state": "pending"
},
{
"id": "e3efdb84-cb4c-4fc1-a25a-504d711299cb",
"file_file_name": "demo.pdf",
"created_at": "2021-07-09T22:16:51.521Z",
"state": "pending"
},
{
"id": "d06a7e8c-590c-4e93-b94b-7ee176a0b519",
"file_file_name": "demo_no_signers.pdf",
"created_at": "2021-06-10T18:27:19.098Z",
"state": "pending"
},
{
"id": "1180ecb4-7478-4eaf-9267-e4349a238a7a",
"file_file_name": "demo.pdf",
"created_at": "2021-06-02T22:00:12.715Z",
"state": "pending"
}
]
}
Cómo se crean las llamadas de búsqueda de recursos
Primero, deberás estar autenticado en Mifiel.
El endpoint que utilizarás para solicitar los recursos es: /api/query
Los parámetros mínimos requeridos son:
- El recurso del que obtendrás la información (resource). Los recursos disponibles para búsqueda son los siguientes:
- Documentos (document): Todos los documentos creados por la cuenta autenticada en la API, solo los documentos eliminados no se encontrarán disponibles para las búsquedas.
- Access Tokens (access_token): Todos los usuarios de acceso a la API creados por la cuenta autenticada, las contraseñas no se encuentran disponibles para su consulta.
- Plantillas de documentos (template): La información para identificar a las distintas plantillas que se hayan creado por la cuenta autenticada en la API.
- Webhooks (webhook): las URLs que tiene definida tu cuenta a nivel global para recibir callbacks tras ciertas acciones sobre tus documentos.
- Llamadas a la API (api_call): Las llamadas realizadas a la API por la cuenta autenticada, incluyendo información como el método usado, la dirección IP y el código del resultado.
- El número de página a consultar (page), por default se muestra la primera.
- La cantidad de recursos a mostrar por página (per_page), por default se cargan 10
- Los campos que necesites consultar del recurso elegido (fields), estos deberán estar separados por comas, sin espacios. Es importante definir este parámetro en la llamada para que la API sepa qué información regresar, en caso contrario la respuesta podría aparecer “vacía” aunque sí existan los recursos. Para ver el detalle de los campos de cada recurso consulta la documentación de la API.
- Algunos recursos tienen relación con otros y solo pueden ser buscados si se solicitan como un campo dentro de su recurso padre. Tal es el caso de los firmantes (signers), revisores (“stakeholders”: {“type”: “Reviewer”}) y espectadores (viewers). Los campos de estos recursos relacionados se deberán solicitar dentro de un paréntesis. Ejemplos:
- stakeholders(email,name,tax_id)
- viewers(email,name)
- signers(email,name,tax_id,signed_at)
- Algunos recursos tienen relación con otros y solo pueden ser buscados si se solicitan como un campo dentro de su recurso padre. Tal es el caso de los firmantes (signers), revisores (“stakeholders”: {“type”: “Reviewer”}) y espectadores (viewers). Los campos de estos recursos relacionados se deberán solicitar dentro de un paréntesis. Ejemplos:
Considerando los requerimientos mínimos, una llamada podría verse de la siguiente manera:
{
"version": "1.0.0",
"resource": "document",
"page": 1,
"per_page": 20,
"q": {},
"sort": "",
"fields": "file_file_name,created_at,state,id"
}
En este ejemplo se le está pidiendo a la API que muestre los documentos con su id, espectadores, el correo y la fecha de firma de los firmantes y los tipos de stakeholders.
¿Cómo filtrar recursos con características específicas?
En la llamada se incluye el parámetro de búsqueda q, que al usarse tiene la capacidad de filtrar los recursos solicitados de acuerdo a los atributos de sus campos o las relaciones de estos. El formato a usar es el siguiente:
{
"q": {
"{attribute_name}": {
"{predicate}": "{search term}"
}
}
}
Dependiendo del tipo de atributo, la variable predicate podrá usar distintas condiciones. Para conocer el tipo de atributo de cada campo consulta nuestra documentación.
- Integer y Datetime:
- eq: igual a
- gt: mayor que
- gteq: mayor o igual que
- lt: menor que
- lteq: menor o igual que
- Boolean
- eq: igual a
- String
- eq: igual a
- not_eq: diferente a
- cont: contiene
- cont_any: [Array] contiene cualquiera
- cont_all: [Array] contiene todos
- i_cont: “contiene" que no distingue entre mayúsculas y minúsculas
- i_cont_any: “contiene cualquiera" que no distingue entre mayúsculas y minúsculas
- i_cont_all: “contiene todos" que no distingue entre mayúsculas y minúsculas
- not_cont: no contiene
- not_cont_any: no contiene cualquiera
- not_cont_all: no contiene todos
- not_i_cont: “no contiene” que no distingue entre mayúsculas y minúsculas
- not_i_cont_any: “no contiene cualquiera” que no distingue entre mayúsculas y minúsculas
- not_i_cont_all: “no contiene todos” que no distingue entre mayúsculas y minúsculas
- matches: coincide con una parte de la palabra (usa LIKE en lugar de = como eq)
- does_not_match: no coincide con una parte de la palabra
- start: comienza con
- not_start: no comienza con
- end: termina con
- not_end: no termina con
Además del atributo y las condiciones, la búsqueda también deberá incluir el search term que es el valor que cumplirá el recurso buscado. Por lo tanto una llamada para filtrar cierto tipo de documentos luciría de la siguiente forma:
{
"version": "",
"resource": "document",
"page": 1,
"per_page": 20,
"q": {
"signers": {
"signed_at": {
"gteq": "2021/09/01"
}
}
},
"sort": "",
"fields": "id,file_file_name,signers(email,signed_at)"
En este ejemplo se está pidiendo a la API que muestre todos los documentos con firmantes que hayan firmado el 1 de septiembre de 2021 o después.
¿Cómo ordenar los resultados de la llamada de acuerdo a algún criterio en específico?
El parámetro sort se puede usar para ordenar por cualquier atributo del recurso que se esté solicitando, solamente habrá que agregar la terminación -asc para orden ascendente o -desc para orden descendente. El ordenamiento puede realizarse por varios atributos a la vez, solo separándolos por coma, siguiendo el formato a continuación:
"sort": "{atributo}-asc,{atributo}-desc"
Por ejemplo, si se quisiera ordenar por fecha de creación de documento de manera descendente y por nombre del documento de manera ascendente, la llamada se vería de esta manera:
{
"version": "",
"resource": "document",
"page": 1,
"per_page": 20,
"q": {
"signers": {
"signed_at": {
"gteq": "2021/09/01"
}
}
},
"sort": "file_file_name-asc,created_at-desc",
"fields": "id,file_file_name,created_at,signers(email,signed_at)"
}
Casos y reglas especiales a tomar en cuenta
- Para filtrar documentos con revisores, se utilizará la relación stakeholders con el campo type igual a Reviewers (con mayúscula al inicio).
- La relación Signers, por ahora no permite el uso de las condiciones que inician con “not_”. En caso de necesitar hacer una búsqueda de este tipo, se podrá realizar usando la relación stakeholders de tipo Signers.
- Cuando necesites mostrar campos (fields) que sean relaciones (por ejemplo, firmantes dentro de un documento), debes agregar las relaciones después de los atributos del recurso. Por ejemplo, para mostrar el nombre del documento, su estado (ambos son atributos) y la lista de participantes con sus correos y roles debes ordenarlos de esta forma:
"fields":"atributo1,atributo2,relación1(atributoRelación1, atributoRelación2))"
Ejemplo:
"fields":"file_file_name,state,stakeholders(email,role)"
¿Tienes alguna duda respecto a las búsquedas que se pueden realizar? ¿Necesitas ayuda con algún caso de uso en particular? Te invitamos a contactarnos mediante nuestro chat oprimiendo el botón verde en la parte inferior derecha de esta página o mediante tu canal de soporte en Slack, en breve te atenderemos.