Descripción general de la API de registros
La API de registros es una API REST a la que se puede acceder mediante llamadas HTTP explícitas; la API expone la mayoría de las funciones relacionadas con los registros disponibles en la interfaz Web de GW Apps. Este documento describe cómo utilizar las llamadas RESTful.
Nota: La API no admite llamadas que modifiquen el diseño o la configuración de la aplicación.
Nota: Esta documentación de la API pretende ofrecer al lector una visión general de las capacidades de la API y de cómo acceder a ellas. Cuando intente escribir llamadas a la API, le recomendamos encarecidamente que utilice la documentación de la API directamente asociada a la clave de API específica a la que vaya a llamar. Esa documentación incluye ejemplos con los ID reales del formulario y los elementos del formulario, incluye ejemplos para cada campo disponible en los formularios asociados, etc. Esto le permitirá copiar y pegar directamente los fragmentos de código de la documentación en su código. Si intentara utilizar los ejemplos de esta documentación, tendría que modificarlos para los campos, ID de formulario, etc.
Autenticación
Antes de que su aplicación pueda acceder al punto final para obtener datos privados, debe obtener un access_token que conceda acceso a esa API. Un único access_token puede conceder distintos grados de acceso a varias API.
Por lo general, la mejor práctica consiste en solicitar únicamente los ámbitos necesarios. Por ejemplo, una aplicación que desee acceder a la búsqueda de las entidades disponibles sólo debería habilitar los ámbitos "Ver y buscar". Siempre puedes modificar el acceso al ámbito cuando cambie tu caso de uso o generar otras claves para otros fines.
Después de que una aplicación obtiene una clave de acceso, envía la clave a una API de GW Apps en un encabezado de solicitud de autorización HTTP. Los tokens de acceso sólo son válidos para el conjunto de operaciones y recursos descritos en el ámbito de la clave de API creada.
Por ejemplo, si se emite un token de acceso para el formulario A, éste no da acceso a la API de registros del formulario B.
Autenticación
Su aplicación debe utilizar este API "/token" para autorizar las solicitudes. Cada access_token generado es válido durante 1 hora.
Solicitud HTTP
POST https://api.gwapps.com/v1/token
Encabezados de solicitud
| Cabecera | valor |
|---|---|
| Tipo de contenido | application/json |
Solicitar cuerpo
| Parámetro | Descripción | Tipo |
|---|---|---|
| Parámetros corporales requeridos | ||
| clave | La clave generada por GWAPPS | cadena |
| correo electrónico | El correo electrónico que se utilizará para suplantar la cuenta de usuario para realizar las llamadas a la api. | cadena |
| customerId | El customerId citen_e0b70 | cadena |
Ejemplo de solicitud
{
"key": apiKey,
"email": email,
"customerId": "citen_e0b70"
}
Respuesta
iniciar
Nota: El token generado es válido durante 1 hora, es posible que tenga que implementar una estrategia para generar un nuevo access_token en consecuencia.
{
"access_token": access_token,
"expires_in": 3600,
"token_type": "Bearer"
}
iniciar
Nota: Cada solicitud que su aplicación envíe a la API de Registros debe incluir un token de autorización. El token también identifica la cuenta de usuario que quieres suplantar (que define el nivel de acceso que tienes a determinados registros).
| Cabecera | valor |
|---|---|
| Autorización | Ficha_de_acceso_al_portador |
| Tipo de contenido | Aplicación/json |
Filtros
Los filtros y operadores admitidos al buscar registros mediante la API "Buscar registros".
Referencia
| Operador | Campos admitidos | Tipo de valor | Ejemplo de valor |
|---|---|---|---|
| EN BLANCO | Todos los campos | No se requiere ningún valor | |
| NOT_BLANK | Todos los campos | No se requiere ningún valor | |
| IGUALESNO_IGUALES | Creado el, Actualizado el | cadena | “2023-11-16T03:30:00” |
| Moneda, Número | número | 100 | |
| Fecha | cadena | "2023-11-16" | |
| Envíe un correo electrónico a | cadena | "john.doe@example.com" | |
| Número de teléfono | cadena | “3103101234” | |
| ID de registro | cadena | "REQ#00001" | |
| País, Estado, Texto, Textarea | cadena | "Estados Unidos", "CA", "John" | |
| Tiempo | cadena | "17:30" | |
| VALOR_IGUAL | Casilla de verificación, Radio, Desplegable, Búsqueda | cadena | "Opción 1" |
| VALOR_NO_IGUAL | |||
| CONTIENE_NO_CONTIENE | Creado por, Actualizado por, Usuario, Lista de usuarios | cadena | "Jane" |
| Envíe un correo electrónico a | cadena | "jane.doe" | |
| País, Estado, Texto, Textarea | cadena | "United", "John" | |
| ID de registro | cadena | "REQ#" | |
| MAYOR_QUE MENOR_QUE | Creado el, Actualizado el | cadena | “2023-11-16T03:30:00” |
| Moneda, Número | número | 100 | |
| Fecha | cadena | "2023-11-16" | |
| Tiempo | cadena | "17:30" | |
| MAYOR_QUE_EQ_TOLESS_QUE_EQ_TO | Moneda, Número | número | 100 |
| LIKENOT_LIKE | País, Estado, Número de teléfono | cadena | "Unidos", "310310" |
| COMO_VALORNO_COMO_VALOR | Casilla de verificación, Radio, Desplegable, Campo de búsqueda | cadena | "Opción 1" |
| EN | Escenario | cadena [ ] | ["stg0"] |
Notas:
- Las fechas están en UTC
- El formato de fecha aceptado es aaaa-MM-dd.
- El formato de fecha y hora aceptado es aaaa-MM-ddTHH:mm:ss.
- El formato de valor de hora aceptado es 24h, por ejemplo 13:30
- El formato de valor de número de teléfono aceptado no contiene código de país, por ejemplo 3236397888
Filtros con condición OR
Los registros se devolverán en función de los criterios si al menos una de las condiciones es verdadera.
{
"filters": [
[
{
"fieldCode": "company1",
"operator": "CONTAINS",
"value": "vip"
},
{
"fieldCode": "name1",
"operator": "CONTAINS",
"value": "john"
}
]
]
}
Filtros con condición AND
Los registros se devolverán en función de los criterios si todas las condiciones son verdaderas.
{
"filters": [
{
"fieldCode": "company1",
"operator": "EQUALS",
"value": "Vipe"
},
{
"fieldCode": "stage",
"operator": "IN",
"value": [
"stg0"
]
}
]
}
Una vez que haya introducido el nombre de la nueva clave API, y opcionalmente haya añadido una descripción, y haya hecho clic en "Crear", verá el Editor de Claves API con su nueva clave cargada para que pueda completar su configuración:
Métodos API
Todos los tipos de campo
Parámetros
| Parámetro | Valor | Descripción |
|---|---|---|
| formId | ????????????????????????? | El identificador del formulario seleccionado, este valor es requerido como parámetro de consulta en cada endpoint. |
Etapas
Todos los registros tienen un atributo de etapa que define el estado del registro. El registro "Todos los tipos de campo" tiene definidas las siguientes etapas, por lo que deberá hacer referencia al atributo stage.id para crear y actualizar registros.
| Estado / Nombre de la etapa | Id de etapa |
|---|---|
| Borrador | stg0 |
| Publicado en | stg1 |
Ejemplo de solicitud
{
"stage": "stg0"
}
O
{
"stage": {
"id": "stg0"
"status": "Draft"
}
}
Definición de registro para el formulario "Todos los tipos de campo"
Esta es la representación del registro incluyendo todos los campos y los tipos de valores esperados.
| Código corto | Nombre del campo | Tipo | Valores aceptados |
|---|---|---|---|
| campo_texto1 | Texto | Texto | cadena |
| campo_fecha2 | Fecha | Fecha | Fecha ISO |
| usuario1 | Usuario | Búsqueda en directorios | { “_id”: “string”, “name”: “string”, “email”: “string” } |
| desplegable1 | Búsqueda desplegable | Lista | { “code”: “string”, “value”: “string” } |
| área_de_texto1 | Área de texto | Área de texto | cadena |
| hora1 | Tiempo | Tiempo | cadena |
| lista_usuarios1 | Lista de usuarios | Lista de directorios | [ { “_id”: “string”, “name”: “string”, “email”: “string” } ] |
| búsqueda2 | Búsqueda | Búsqueda múltiple | { “code”: “string”, “value”: “string” } |
| campo_numero1 | Número | Número | número |
| radio_button1 | Botón de radio | Radio | { “code”: “string”, “value”: “string” } |
| departamento1 | Departamento | Texto | cadena |
| casilla1 | Casilla de verificación | Casilla de verificación | [ { “code”: “string”, “value”: “string” } ] |
| teléfono1 | Teléfono | Número de teléfono | { “code”: “string”, “phone”: “string” } |
| ciudad1 | Ciudad despejada | Texto | cadena |
| estado1 | Estado Limpio | Estado | cadena |
| zip1 | Cremallera transparente | Texto | cadena |
| país1 | País Claro | País | cadena |
| archivo adjunto1 | Adjunto | Selector de archivos | [ { “name”: “string”, “mimeType”: “string”, “fileId”: “string” } ] |
| drive_picker1 | Drive Picker | Drive Picker | [ { “id”: “string”, “mimeType”: “string”, “name”: “string”, “url”: “string” } ] |
| firma1 | Firma | Firma | { “data”: “string”, “date”: “ISODate” } |
| tabla1 | Cuadro | Tabla dinámica | Matriz |
| tabla1.nueva_columna-ta1 | Nueva columna-[tabla] | Texto | cadena |
| tabla1.nueva_columnatab1 | Nueva columna[tabla] | Moneda | { “code”: “string”, “value”: “number” } |
| tabla1.nueva_columnatab2 | Nueva columna[tabla] | Moneda | { “code”: “string”, “value”: “number” } |
| escenario | Estado | Escenario | { “id”: “string”, “status”: “string” } |
| Campos de sólo lectura | |||
| creadoPor | Creado por | Creado por | { “name”: “string”, “email”: “string”, “_id”: “string” } |
| creadoEn | Creado en | Creado en | Fecha ISO |
| actualizadoPor | Actualizado por | Actualizado por | { “name”: “string”, “email”: “string”, “_id”: “string” } |
| actualizadoEn | Actualizado el | Actualizado el | Fecha ISO |
| recordId | Id de registro | Id de registro | { “inc”: “number”, “value”: “string” } |
| aprobadores | Aprobadores | Aprobadores | |
Artículos relacionados con la API
Este artículo cubre la estructura general de la API de registros y las llamadas/puntos finales. Los detalles de las llamadas/puntos finales específicos se tratan en artículos individuales. Se pueden encontrar opciones adicionales para Claves API dentro de la sección API de los Ajustes de la Plataforma, y en la sección Seguridad > Claves API de Editar App dentro de cada aplicación.