API de registros de GW Apps

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	"[email protected]"
	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.