Ragic HTTP API (3.0)

La API HTTP de Ragic es una interfaz de estilo REST que permite leer, crear, actualizar y eliminar registros en cualquier formulario de Ragic. Puede utilizar cualquier cliente HTTP: cURL, Postman o la biblioteca HTTP de su lenguaje de programación.

La API REST de Ragic te permite consultar (query) los datos que tengas en Ragic, ejecutar para crear / actualizar / eliminar operaciones mediante programación para integrar con propias aplicaciones. Ya que la API está basada en principios REST, es muy fácil escribir y hacer pruebas en aplicaciones. Puedes usar tu explorador para acceder a URLs y puedes usar cualquier cliente HTTP en cualquier lenguaje de programación para interactuar con la API. Las solicitudes HTTP pueden enviarse con dos tipos de contenido, datos de formulario y JSON. Sin embargo, para cargar archivos, datos de formulario es la única opción

Puedes probar la mayoría de los métodos GET en APIs fácilmente al ingresar el URL de punto final de la API en tu explorador. Por ejemplo, puedes probar el siguiente URL para acceder a la información de la cuenta del cliente en el demo de Ragic:

https://www.ragic.com/demo/sales/1?api

Nótese que quizá debas modificar www a na3 , ap5 , ó eu2 en tu URL según el URL de tu cuenta Ragic. Ya que no es tan fácil como crear solicitudes con el método POST en tu explorador, te recomendamos usar una herramienta llamada cURL para crear todo tipo de solicitudes HTTP que quieras probar en nuestra API. Nuestro documento también usará comandos cURL como muestras de llamadas API, pero puedes usar cualquier herramienta que te sea familiar para crear las solicitudes HTTP y respuestas parse. Puedes descargar cURL para tu plataforma desde https://curl.haxx.se/download.html y también puedes leer la documentación completa en https://curl.haxx.se/docs/manpage.html . Pero no te preocupes, te diremos los usos necesarios de cURL mientras explicamos la API HTTP de Ragic. Después de descargar cURL, puedes usar el siguiente comando para acceder al mismo punto final mencionado anteriormente, y debes ver el mismo resultado que verías en un explorador.

curl --get -d api https://www.ragic.com/demo/sales/1

Por favor nótese que al usar CURL, -d no codifica el contenido de la cadena de URL. Si tu cadena de contenido tiene caracteres como % o & por favor usa la opción --data-urlencode en lugar de -d.

Postman es una herramienta que ayuda a enviar solicitudes HTTP sin tener que escribir código. Puedes consultar la documentación de Postman aquí y puedes descargar Postman aquí. Postman se recomienda para usuarios con poca experiencia técnica. En este tutorial se explicarán los conceptos básicos. La interfaz de usuario de Postman se parece a la siguiente imagen:

1. El menú desplegable que enumera todos los métodos HTTP para seleccionar
2. La URL de destino a la que se envía la solicitud HTTP
3. El botón de acción que envía la solicitud HTTP
4. Atributos asociados con la solicitud HTTP

En la imagen de arriba, la solicitud HTTP es una solicitud GET y se envía a https://www.ragic.com/demo/sales/1 con un parámetro de consulta "api" que no tiene ningún valor asociado. La siguiente imagen muestra la lista de métodos HTTP del menú desplegable.

En muchos casos, deberás encontrar el ID de campo para un campo. El ID de campo es un número único que Ragic asigna a cada campo que has creado. Esto le da tu programa una forma precisa para referirse a un campo. Con este diseño, los campos pueden tener el mismo nombre en una hoja pero Ragic podrá distinguir entre ellos. Ve al Modo Diseño y haz clic en el campo que deseas referenciar. En la barra lateral izquierda, verás el Nombre de Campo , el ID de campo está bajo el nombre de campo.

Puedes encontrar el punto final de la API para tu formulario Ragic o registro al pasar api como un parámetro en cadena query para especificar que esta es una solicitud API.

https://www.ragic.com/{ACCOUNT_NAME}>/{TAB_FOLDER}>/{SHEET_INDEX}/{RECORD_ID}?v=3&api

Por favor nótese que está usando la versión 3 API al agregar una versión del parámetro v=3. Es buena práctica para especificar la versión de API cada vez que envíes tu solicitud para asegurar una versión correcta. Si la versión no es especificada, se usará la última versión, pero cambios imprevistos en la API podrían causar problemas en tu aplicación. Por ejemplo, si usualmente accedes a tu formulario de Ragic usando el siguiente URL:

https://www.ragic.com/demo/sales/1

Su URL de punto final de la API HTTP sería:

https://www.ragic.com/demo/sales/1?v=3&api

O para un registro individual en tu hoja, incluirías un ID para especificar un registro:

https://www.ragic.com/demo/sales/1/6

Su URL de punto final de la API HTTP correspondiente sería:

https://www.ragic.com/demo/sales/1/6?v=3&api

No tenemos un límite en cuanto a nuestras llamadas API siempre y cuando esté bajo un uso razonable. Si no estás seguro sobre sus usos, puedes enviarnos un mensaje a support@ragic.com para consultar con nosotros. Esto es sólo para asegurar un uso razonable del sistema, para que no haya un uso excesivo en cuentas pequeñas. Si el uso excede 5 solicitudes por segundo, un proceso de revisión manual será activado para determinar si throttling será aplicado.

Puedes autenticar la API de Ragic al proveer una de tus claves API en la solicitud. Tus claves API tienen muchos privilegios, ¡asegúrate de mantenerlas en secreto! Cuando tu código accede a la API de Ragic vía una clave API, básicamente inicia sesión como el usuario de la clave API y ejecuta lectura y escritura como este usuario. Te recomendamos crear un usuario distinto para este acceso con clave API. De esta manera el acceso API no se mezclará con un usuario organizacional, lo cual hace que el registro de auditoría del sistema sea más claro y la depuración (debugging) de tu API sea más fácil. La autenticación de API se realiza vía autenticación básica HTTP. Provee tu clave API como el usuario básico de autenticación. No necesitas brindar una contraseña. Todas las solicitudes API deben ser realizadas a través de HTTPS. Las llamadas realizadas sobre HTTP fallarán. Debes autenticar para todas las solicitudes.

curl https://www.ragic.com/demo/sales/1\
   --get -d api \
   -H "Authorization:Basic TU_CLAVE_API_VA_AQUÍ"

Nótese que el nombre del encabezado del HTTP es Authorization, y el valor es tu clave API precedida de “Basic ”, Basic con un espacio al final y quizá necesites modificar www a na3 , ap5 , ó eu2 en tu URL según tu URL de cuenta Ragic. Puedes generar tu clave API desde configuración personal.

La mayoría de los clientes HTTP (incluyendo exploradores web) muestran un cuadro de diálogo o te indican que debes proveer un nombre de usuario y contraseña (vacía) para autenticación básica HTTP. La mayoría de las clientes te permitirán dar tus credenciales directamente en el URL. Si por alguna razón no puedes enviar la clave API como el encabezado de HTTP o autorización básica, puedes enviar la clave API como un parámetro con el nombre APIKey. Necesitarás agregar este parámetro para cada solicitud individual que envíes.

curl https://www.ragic.com/demo/sales/1\
   --get -d api \
   -d "APIKey=YOUR_API_KEY_GOES_HERE"

Si alguna vez tu plataforma no es compatible con la autenticación básica HTTP, puedes pasar el correo electrónico y contraseña del usuario como credenciales para autenticar tu programa. Si te registraste a través de Regístrate con Google, asegúrate de registrar una contraseña Ragic antes de seguir con este tutorial. Por favor usa este método sólo cuando no puedas realizar la Autenticación Básica HTTP. Puedes enviar una solicitud para una sesión id con correo y contraseña válidos. Puedes enviar una solicitud HTTP usando el argumento -d con el id y contraseña. El parámetro -c guardará el ID de sesión en el archivo cookie jar especificado:

curl --get -d "u=jeff@ragic.com" \
 --data-urlencode "p=123456" \
 -d "login_type=sessionId" \
-d api \
 -c cookie.txt \
 -k \
 https://www.ragic.com/AUTH

Si la autenticación falló, el servidor devolverá -1. Si lo autenticó, recibirás un ID de sesión en la respuesta así:

2z5u940y2tnkes4zm49t2d4

Si deseas recuperar información detallada del usuario para inicio de sesión, también puedes proveer un parámetro adicional json-1 para que Ragic devuelva un objeto json con los detalles del usuario.

curl --get -d "u=jeff@ragic.com" \
 --data-urlencode "p=123456" \
 -d "login_type=sessionId" \
 -d "json=1" \
-d api \
 -c cookie.txt \
 -k \
 https://www.ragic.com/AUTH

El formato devuelto debe verse así:

{
"sid":"8xkz874fdftl116vkd3wgjq0t",
"email":"jeff@ragic.com",
"accounts":
  {
    "account":"demo",
    "ragicId":25,
    "external":false,
    "groups":["EVERYONE","SYSADMIN"]
  }
}

Por ejemplo, esta una respuesta API para https://www.ragic.com/demo/sales/1?v=3&api. Recuerda especificar tu archivo cookie jar en la llamada como "-b cookie.txt"

{
"17": {
"Account Name": "Dunder Mifflin",
"Account Owner": "Jim Halpert",
"Phone": "1-267-922-5599",...
"14": {
"Account Name": "Ratshotel",
"Account Owner": "Dwight Schrute",
"Phone": "1-267-922-5529",
...

El listado está predeterminado a 1000 registros. Puedes agregar parámetro de límite de paginado limit según las siguientes secciones para obtener más registros. Los datos en subtablas se mostrarán como en el siguiente ejemplo. El nombre del atributo empezará con subtable seguido por ID de subtabla para identificar cual subtabla es. El contenido de la subtabla es presentado de la misma forma que los campos en un formulario.

"14": {
"Account Name": "Ratshotel",
"Account Owner": "Dwight Schrute",
"Phone": "1-267-922-5529",
...

"_subtable_800014": {
"29": {
"Contact Name": "Arden Jacobs",
"Title": "Specialist",
"E-mail": "Arden@ratshotel.com",
},

"30": {
"Contact Name": "Kermit Moore2",
"Title": "Manager",
"E-mail": "Kermit@ratshotel.com",
}

}

}

Si tu aplicación no necesita los datos en las subtablas, puedes agregar el parámetro subtables=0 para desactivar la recuperación de datos de subtabla. Los comentarios de los registros también son recuperados como subtablas. Serán recuperados en una subtabla con el id de campo 61, pero deberás agregar el parámetro comment=true al recuperar datos de comentarios para que los datos sean devueltos.

Con frecuencia, tu base de datos puede tener una gran cantidad de registros, asique es mejor aplicar filtros al recuperar datos. Los filtros de API Ragic están en un formato especial. Puedes usar el parámetro “where” para agregar una condición e3 filtro hacer query como a continuación:

curl --get -d "where=800003,eq,Dwight Schrute" \
-H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
-d api \
https://www.ragic.com/demo/sales/1

El parámetro es un formato delimitado por comas “,” con al menos 3 argumentos.

1. El ID de campo que deseas filtrar.
2. El operador en la forma de entero para especificar tu filtro de operación. La lista de operadores se muestra en la parte inferior.
3. El valor con el que deseas filtrar el campo. Recuerda, si tu valor puede incluir un caracter de coma “,” por favor usa codificación de URL o usa %2C para evitar colisiones.

Puedes hacer una query con múltiples condiciones de filtro como se muestra a continuación:

curl --get -d "where=800003,eq,Dwight Schrute" \
-d "where=800007,eq,Reseller" \
-H "Authorization:Basic YOUR_API_KEY_GOES_HERE" \
-d api \
https://www.ragic.com/demo/sales/1

Esta es la lista de los operadores que puedes usar:

Por favor nótese que:

1. Cuando filtras por fecha o fecha y hora, deberán estar en el siguiente formato: yyyy/MM/dd o yyyy/MM/dd HH:mm:ss.

2. No necesitas rellenar el tercer argumento si deseas filtrar por valores vacíos, por ejemplo, "where=800003,eq,".

Hay algunos campos de sistema que tienen IDs especiales de campo los cuales puedes usar en tu query. Los campos de sistemas se muestran a continuación:

| Nombre del campo

Puedes usar una búsqueda de texto completo como filtro de query. Sólo provee tu término de búsqueda en el parámetro fts y el resultado coincidente será devuelto.

curl --get -d "fts=Dwight" \
-H "Authorization:Basic TU_CLAVE_API_VA_AQUÍ" \
-d api \
https://www.ragic.com/demo/sales/1

También puedes aplicar una Vista Compartida. Sólo fija el id como se muestra a continuación:

curl --get -d "filterId=EL_ID_DE_TU_VISTA_COMPARTIDA" \
-H "Authorization:Basic TU_CLAVE_API_VA_AQUÍ" \
-d api \
https://www.ragic.com/demo/sales/1

Puedes obtener el id al hacer clic en compartir URL de la vista.

Con frecuencia, quizá no quieras incluir todos los registros en una solicitud, puedes usar los parámetros limit y b>offset para especificar cuántos registros deseas recuperar, y cuántos registros deseas omitir al principio, para que los clientes puedan implementar páginas para ver los registros. El uso los parámetros limit y b>offset es similar al parámetro de límite SQL. Offset es cuántos registros deseas omitir al principio, y limit es cuántos registros deseas devolver. Los datos devueltos están predeterminado a 1000 registros , debes proveer parámetros de límite si quieres que tu respuesta tenga más de 1000 registros. El formato es el siguiente:

limit=<offset>,<page size>
</page></offset>

El parámetro offset es el número de registros que deben ser omitidos antes de devolver datos, es usado para buscar entre páginas que han sido recuperadas. El parámetro limit es el número máximo de registros que debe devolver por llamada. Por ejemplo, en la siguiente llamada omitiremos los primeros 5 registros, y devolveremos 6 – 13, un total de 8 registros.

curl --get -d "limit=5,8" \
-H "Authorization:Basic TU_CLAVE_API_VA_AQUÍ" \
-d api \
https://www.ragic.com/demo/sales/1

Si no hay un orden, por defecto los datos serán ordenados por fecha y hora de creación, del más antiguo al más reciente. Si deseas obtener los datos más recientes primero, puedes especificar reverse=true así:

curl --get -d "reverse=true" \
-H "Authorization:Basic TU_CLAVE_API_VA_AQUÍ" \
-d api \
https://www.ragic.com/demo/sales/1

También puedes especificar cómo los registros son ordenados al agregar el parámetro order. También es similar a la cláusula ORDER BY en SQL, su valor es una cadena separada por comas con dos argumentos. El primero es el id de campo del dominio según el cual deseas ordenar los registros, el segundo es el orden: ya sea ASC para orden ascendente, o DESC para orden descendente.

curl --get -d "order=800236,DESC" \
-H "Authorization:Basic TU_CLAVE_API_VA_AQUÍ" \
-d api \
https://www.ragic.com/demo/sales/1

Al agregar un parámetro de función callback adjuntará el objeto JSON devuelto como un argumento en una llamada a la función callback especificada por ti. Esto es especialmente útil cuando estás accediendo a nuestra API usando Javascript, debes hacer esto para llamadas cross domain y Ajax. Por ejemplo, agregar callback=testFunc como se muestra a continuación:

curl --get -d "callback=testFunc" \
-H "Authorization:Basic TU_CLAVE_API_VA_AQUÍ" \
-d api \
https://www.ragic.com/demo/sales/1

Adjuntaremos el objeto JSON devuelto en una función llamada para que puedas procesar los datos devueltos en tu función callback:

testFunc({"17": {

"Account Name": "Dunder Mifflin",

"Account Owner": "Jim Halpert",

"Phone": "1-267-922-5599",

 ...

 ...

});

El formato de datos JSON usa la cadena de nombre de campo como el nombre de atributo, puedes usar un parámetro “naming” para especificar que deseas usar el id de campo como el nombre de atributo para identificar un campo. Entre los valores posibles incluyen: EID (ID de campo), FNAME (Nombre del campo).

curl --get -d "naming=EID" \
-H "Authorization:Basic TU_CLAVE_API_VA_AQUÍ" \
-d api \
https://www.ragic.com/demo/sales/1

Hay varios parámetros útiles que puedes aplicar a tu solicitud GET HTTP para cambiar el contenido de la respuesta:

El formato JSON del historial de modificaciones con history=true es el siguiente:

{
  "Time": "",   // Hora UTC
  "Type": "",   // Tipo de edición
  "Sheet": "",  // Hoja a la que pertenece el registro
  "User": "",   // Usuario que realizó la edición
  "Detail": ""  // Detalle de la edición
}

En la respuesta JSON devuelta por tu llamada API HTTP, verás algo así para los campos de archivo o imagen adjunta:

"1000537": "Ni92W2luv@My_Picture.jpg",

Podrás descargar el archivo usando una llamada diferente (asumiendo que el nombre de tu cuenta es “demo” y el URL de la llamada API es https://www.ragic.com/demo/sales/1?v=3&api):

https://www.ragic.com/sims/file.jsp?a=demo&f=Ni92W2luv@My_Picture.jpg

El formato es:

https://www.ragic.com/sims/file.jsp?a=<nombre de cuenta>&f=<nombre de archivo>
</nombre></nombre>

Recuerda codificar el nombre de tu archivo cuando lo envíes como un URL. El nombre real de tu archivo debe empezar después del caracter @, esto es para evitar colisiones en los nombres de archivos.

Por ejemplo, si tienes un URL de un registro como el siguiente

https://www.ragic.com/demo/sales/1/41

1. Print Friendly

Puedes obtener una versión HTML apta para imprimir como ésta, agregando un .xhtml al final:

https://www.ragic.com/demo/sales/1/41.xhtml

2. PDF o versión Excel

You can add a .pdf for a PDF version, .xlsx for an Excel version: Puedes agregar .pdf para una versión PDF , .xlsx para una versión Excel :

https://www.ragic.com/demo/sales/1/41.pdf
https://www.ragic.com/demo/sales/1/41.xlsx

3. Combinación de Correspondencia

Puedes obtener una Combinación de correspondencia de un registro agregando .custom? y un CID de combinación de correspondencia para especificar qué plantilla (que es 1 para la plantilla de combinación de correspondencia utilizada en este caso):

https://www.ragic.com/demo/sales/1/41.custom?cid=1

Para obtener el cid de una combinación de correspondencia, primero puedes descargar manualmente una combinación de correspondencia desde la interfaz de usuario de Ragic y prestar atención al parámetro cid en la URL de descarga.

https://www.ragic.com/demo/sales/1/41.custom?rn=41&<b>cid=1</b>

4. Reporte de Impresión Personalizada

You can retrieve a Custom Print Report of a record by appending .carbone? to the URL, along with the following parameters (joined with &). Puedes obtener un reporte de impresión personalizada de un registro agregando .carbone? a la URL, junto con los siguientes parámetros (unidos con &).

https://www.ragic.com/demo/sales/1/41.carbone?fileFormat=pdf&ragicCustomPrintTemplateId=1&fileNameRefDomainId=1001000

(1) Sintaxis de Formato de archivo : fileFormat="formato de archivo" (ej.:, pdf, png, docx). Ejemplo: fileFormat=pdf

(2) ID de plantilla personalizada syntax: ragicCustomPrintTemplateId="ID de Plantilla". Ejemplo: ragicCustomPrintTemplateId=1 Para obtener el "ID de plantilla", primero descarga manualmente el Reporte de impresión personalizado y busque el parámetro ID de plantilla en la URL de descarga:

https://www.ragic.com/demo/sales/1/41.carbone?fileFormat=pdf&fileNameRefDomainId=-1&<b>ragicCustomPrintTemplateId=2</b>

(3) Sintaxis del campo de referencia del nombre de archivo (opcional): fileNameRefDomainId="ID de campo". Ejemplo: fileNameRefDomainId=1001000

Si no estás usando formularios simples HTML para crear registros en Ragic, deberás crear solicitudes API para crear los registros. Los puntos finales (endpoints) para escribir en un formulario es el mismo para leerlos, pero envías una solicitud POST and lugar de una solicitud GET. La API ahora es compatible con datos JSON, y la forma recomendada para hacer solicitudes HTTP. Para agregar datos JSON (POST), debes cambiar la configuración de la pestaña Body a raw JSON, como se muestra a continuación.

Lo que necesitas hacer es usar los IDs de campos como nombres de los campos, y los valores que deseas ingresar como valores de parámetro. Por favor nótese que el usuario deberá escribir acceso al formulario para que esto funcione.

curl -F "800001=Dunder Mifflin" \
 -F "800002=1-267-922-5599" \
 -F "800003=Jim Halpert" \
 -F "800007=Customer" \
-F "api=" \
 -H "Authorization:Basic TU_CLAVE_API_VA_AQUÍ" \
 https://www.ragic.com/demo/sales/1

El formato JSON equivalente es como a continuación:

{
    "800001": "Dunder Mifflin"
    "800002": "1-267-922-5599"
    "800003": "Jim Halpert"
    "800007": "Customer
}

Si el campo es un tipo selección múltiple que puede tener múltiples valores, puedes tener múltiples parámetros con el mismo ID de campo como nombres. Si el campo es de tipo Fecha , el valor debe estar en el formato yyyy/MM/dd o yyyy/MM/dd HH:mm:ss si hay períodos de tiempo. Asique la solicitud se vería así:

curl -F "800001=Dunder Mifflin" \
 -F "800002=1-267-922-5599" \
 -F "800003=Jim Halpert" \
 -F "800007=Customer" \
 -F "800007=Reseller" \
 -F "800008=2018/12/25 23:30:00" \
 -F "api=" \
 -H "Authorization:Basic TU_CLAVE_API_VA_AQUÍ" \
 https://www.ragic.com/demo/sales/1

El formato JSON equivalente es como a continuación los corchetes para el ID de campo 1000143 permite múltiples valores en una oración

{
    "800001": "Dunder Mifflin",
    "800002": "1-267-922-5599",
    "800003": "Jim Halpert",
    "800007": ["Customer", "Reseller"],
    "800008": "2018/12/25 23:30:00"
}

Si deseas insertar datos a las subtablas el mismo tiempo, necesitarás un formato ligeramente diferente para los campos en las subtablas ya que Ragic necesita una forma para determinar si los valores de campo pertenecen al mismo registro de subtabla. Si los valores están en la misma fila de subtabla, asígnales el mismo ID de fila negativo a cada uno. Puede ser un entero negativo. Es la única forma de determinar que están en la misma fila.

1000014_-1=Bill
1000015_-1=Manager
1000016_-1=billg@microsoft.com

1000014_-2=Satya
1000015_-2=VP
1000016_-2=satyan@microsoft.com

La solicitud completa se vería así:

curl -F "800001=Dunder Mifflin" \
 -F "800002=1-267-922-5599" \
 -F "800003=Jim Halpert" \
 -F "800007=Customer" \
 -F "800007=Reseller" \
 -F "1000014_-1=Bill" \
 -F "1000015_-1=Manager" \
 -F "1000016_-1=billg@microsoft.com" \
 -F "1000014_-2=Satya" \
 -F "1000015_-2=VP" \
 -F "1000016_-2=satyan@microsoft.com" \
-F 'api=' \
 -H "Authorization:Basic TU_CLAVE_API_VA_AQUÍ" \
 https://www.ragic.com/demo/sales/1

El formato JSON equivalente es como a continuación

{

    "800001": "Dunder Mifflin",
    "800002": "1-267-922-5599",
    "800003": "Jim Halpert",
    "800007": ["Customer", "Reseller"],
    "_subtable_800014": {
        "-1": {
            "1000014": "Bill",
            "1000015": "Manager",
            "1000016": "billg@microsoft.com"
        },
       "-2": {
            "1000014": "Satya",
            "1000015": "VP",
            "1000016": "satyan@microsoft.com"
        }
    }
}

Si deseas rellenar un campo de tipo archivo adjunto , asegúrate de que el tipo de codificación de la solicitud sea multipart/form-data. El equivalente HTML sería enctype='multipart/form-data'. Con una solicitud de partes múltiples, puedes agregar tu archivo a la solicitud, y sólo pon el nombre del archivo como valor de campo.

1000088=test.jpg

El punto final (endpoint) para modificar un registro es el mismo para leer un registro existente. Nótese que al crear un registro, el punto final apunta a una hoja Ragic, pero cuando editas un registro, tu punto final necesitará un ID de registro extra para apuntar al registro exacto.

https://www.ragic.com/<account>/<tab folder>/<sheet index><b>/<record id></record></b>?api

</sheet></tab></account>

Todo lo que necesitas proveer son los IDs de los campos que deseas modificar. Si el campo es de tipo Fecha , el valor debe estar en el formato yyyy/MM/dd o yyyy/MM/dd HH:mm:ss si hay períodos de tiempo.

curl -F "800003=Dwight Schrute" \
 -F "800007=Partner" \
 -F "api=" \
 -H "Authorization:Basic TU_CLAVE_API_VA_AQUÍ" \
 https://www.ragic.com/demo/sales/1<b>/3</b>

Para subtablas, es poco más complicado ya que Ragic necesita saber cuál fila estás editando, asique debes encontrar el ID de la fila que estás editando. Esta información puedes obtenerla desde una llamada API. Como hemos mencionado en un capítulo anterior, el formato devuelto para un registro con subtablas se ve así:

"14": {
"Account Name": "Ratshotel",
"Account Owner": "Dwight Schrute",
"Phone": "1-267-922-5529",
...

"_subtable_800014": {
  "29": {
  "Contact Name": "Arden Jacobs",
  "Title": "Specialist",
  "E-mail": "Arden@ratshotel.com",
  },

  "30": {
  "Contact Name": "Kermit Moore",
  "Title": "Manager",
  "E-mail": "Kermit@ratshotel.com",
  }

}

}

El formato JSON equivalente es el siguiente:

{
    "800003": "Dwight Schrute",
    "800007": "Partner"
}

Para subtablas, es un poco más complejo, ya que Ragic necesitará cuál fila estás editando. Asique debes encontrar el ID de fila de la fila que estás editando. Esta información puedes encontrarla en una llamada API. Como se mencionó en un capítulo anterior, el formato devuelto para un registro con subtablas se ve así:

"14": {
"Account Name": "Ratshotel",
"Account Owner": "Dwight Schrute",
"Phone": "1-267-922-5529",
...

"_subtable_800014": {
  "29": {
  "Contact Name": "Arden Jacobs",
  "Title": "Specialist",
  "E-mail": "Arden@ratshotel.com",
  },

  "30": {
  "Contact Name": "Kermit Moore",
  "Title": "Manager",
  "E-mail": "Kermit@ratshotel.com",
  }

}

}

En la subtabla, 29 es el ID de fila para el contacto Arden Jacobs, y 30 es el ID de fila para el contacto Kermit Moore. Con este ID de fila, puedes modificar datos de la subtabla, así como creas registro en subtablas. Usa el ID de fila como identificador después del ID de campo. Sólo debes incluir los campos que deseas modificar:

1000015_29=Senior Specialist
1000016_29=arden2@ratshotel.com

1000015_30=Senior Manager

La solicitud completa se vería así:

curl -F "800003=Dwight Schrute" \
 -F "800007=Partner" \
 -F "1000015_29=Senior Specialist" \
 -F "1000016_29=arden2@ratshotel.com" \
 -F "1000015_30=Senior Manager" \
 -F "api=" \
 -H "Authorization:Basic TU_CLAVE_API_VA_AQUÍ" \
 https://www.ragic.com/demo/sales/1<b>/3</b>

El formato JSON equivalente es el siguiente:

{
    "800003": "Dwight Schrute",
    "800007": "Partner" ,
    "_subtable_800014": {
        "29" :{
            "1000015": "Senior Specialist",
            "1000016": "arden2@ratshotel.com"
        },
        "30" :{
            "1000015": "Senior Manager"
        }
    }
}

Si deseas eliminar una fila de subtabla, puedes crear una solicitud así:

DELSUB_<subtable key>=<subtable row id>
</subtable></subtable>

El formato JSON equivalente es el siguiente:

_DELSUB_<subtable key>=[<subtable row id>,<subtable row id>,...,<subtable row id>];
</subtable></subtable></subtable></subtable>

Por ejemplo, si quieres eliminar el contacto Arden Jacobs, la solicitud completa se vería así:

curl -F "DELSUB_800014=29" \
 -F "api=" \
 -H "Authorization:Basic TU_CLAVE_API_VA_AQUÍ" \
 https://www.ragic.com/demo/sales/1<b>/3</b>

El formato JSON equivalente es el siguiente:

{
    "_DELSUB_800014": [26]
}

Usar el formato JSON para eliminar filas te permite especificar filas de una forma simple,

{
    "_DELSUB_subtable key": [<subtable row id>,..., <subtable row id>]
}
</subtable></subtable>

Hay muchos parámetros útiles que puedes usar al crear o actualizar registros en Ragic para ahorrar tiempo al escribir código duplicado para lo que puede realizarse en Ragic.

Eliminar un registro es similar a leer un registro. Todo lo que debes hacer es cambiar el método de solicitud de GET a DELETE. Cuando es una solicitud DELETE, el registro al punto final de la API será eliminado.

curl -X DELETE \
-H "Authorization:Basic TU_CLAVE_API_VA_AQUÍ" \
-d "api"  \
https://www.ragic.com/demo/sales/1/3

Asegúrate que el tipo de contenido sea multipart/form-data , y podrás cargar archivos.

curl -F "1000088=@/your/file/path" \
-F "api=" \
-F "v=3" \
-H "Authorization:Basic TU_CLAVE_API_VA_AQUÍ" \
https://www.ragic.com/demo/sales/1

Después de cargarlos exitosamente, recibirás tu archivo en este formato.

"1000088": "Ni92W2luv@test.jpg",

Desplaza tu cursor sobre la flecha del menú desplegable y selecciona la opción "File" (archivo) para permirtir la carga de archivos.

Si quieres obtener los archivos cargados, sigue estas instrucciones. Si quieres cargar los archivos vía enlace, primero descárgalos y luego sigue las instrucciones anteriores.

curl -o __TEMP_FILE__ ENLACE_DE_TU_IMAGEN
curl -F "1000002=@__TEMP_FILE__" -F "api=" -F "v=3" -H "Authorization:Basic TU_CLAVE_API" https://www.ragic.com/demo/sales/1

Recuerda reemplazar el ENLACE_DE_TU_IMAGEN y TU_CLAVE_API Puedes obtener tu clave API aquí.

Asegúrese de que su tipo de contenido sea multipart/form-data.

curl -F "at=@/your/file/path" \
-F "c=yourComment"
-F "api=" \
-H "Authorization:Basic TU_CLAVE_API_VA_AQUÍ" \
https://www.ragic.com/demo/ragicsales-order-management/10001/2

En el cuerpo de la solicitud, el valor del parámetro c es el comentario (obligatorio) y el valor del parámetro at es el archivo adjunto (opcional). Su clave API podría obtenerse aquí.

Respuesta:

{
  "61": "2025/02/13 14:30",
  "65": "Juan García",
  "66": "Por favor revise este pedido.",
  "67": "",
  "73": "1739425800000"
}

El campo 61 es la marca de tiempo formateada, 65 es el nombre del autor del comentario, 66 es el texto del comentario, 67 es el nombre del archivo adjunto (vacío si no hay ninguno) y 73 es la marca de tiempo en milisegundos.

Debes tener privilegios de SYSAdmin para usar esta API. Antes de utilizar esta API, habilita la función "Importación periódica desde URL". Una vez completada la configuración, puedes activar la importación llamando a la siguiente API:

curl -F "importData="
-F "api=" \
-H "Authorization:Basic TU_CLAVE_API_VA_AQUÍ" \
https://www.ragic.com/demo/ragicsales-order-management/10001

Cuando necesites crear o actualizar una gran cantidad de datos, también puedes usar este método para importar todo de una vez en lugar de hacer múltiples llamadas API. Puedes encontrar tu clave API en tu página de Configuración personal.

Respuesta:

{
  "status": "SUCCESS",
  "msg": "Import completed."
}

Para bloquear o desbloquear datos usando la API HTTP, simplemente agrega las cadenas de consulta "api" y "lock"/"unlock" a la URL del registro de destino y envía la solicitud usando el método POST.

curl -X POST https://www.ragic.com/demo/ragicforms23/10004/102?api&lock

curl -X POST https://www.ragic.com/demo/ragicforms23/10004/102?api&unlock

Los permisos para bloquear/desbloquear son los mismos que al realizar la acción a través de la interfaz del formulario. Puedes encontrar tu clave API en tu página de Configuración personal.

Respuesta:

{
  "status": "SUCCESS",
  "code": 200
}

Para ejecutar un Botón de Acción a través de la API HTTP, primero necesitas obtener el ID del Botón de Acción. Usa el método GET para enviar la siguiente solicitud:

curl "https://{nombreServidor}/{nombreCuenta}{ruta}/{índiceHoja}/metadata/actionButton?api&category=massOperation" \
  -H "Authorization: {Basic claveAPI}"

Después de obtener el ID del Botón de Acción, puedes usar el método POST para enviar la siguiente solicitud y ejecutar el Botón de Acción especificado en el registro de destino:

curl -X POST "https://{nombreServidor}/{nombreCuenta}{ruta}/{índiceHoja}/{idRegistro}?api&bId={idBotón}" \
  -H "Authorization: Basic claveAPI"

Nota: Además de tener permiso para ejecutar el Botón de Acción, también debes tener permiso para ver el registro de destino para poder usar esta API HTTP. Puedes encontrar tu clave API en tu página de Configuración personal.

Respuesta:

{
  "status": "SUCCESS",
  "msg": "Action completed."
}

Si la solicitud devuelve un error, se verá algo así:

{
"status": "ERROR",
"code": 303,
"msg": "Su cuenta ha expirado."
}

Esta es una lista de los códigos de estado HTTP que podrían ser devueltos en una solicitud Ragic:

Si hay un error al procesar tu solicitud, generalmente tendrá un código de error y una descripción. Aquí hay una lista de códigos de errores que podrías recibir como respuesta a una solicitud Ragic:

Las API de operaciones masivas están diseñadas para realizar el mismo conjunto de operaciones para varios registros de una hoja en una única solicitud. Hay dos formas de especificar los registros que se actualizarán:

• Filtros where

https://www.ragic.com/< cuenta >< carpeta de pestañas >/< índice de hoja >/massOperation/< tipo de operación masiva >?api&where=< ID de campo >,< Operando de filtro >,< Valor >

• recordId en la cadena de consulta, recordId=< recordId >. p. ej. recordId=1&recordId=2

https://www.ragic.com/< cuenta >< carpeta de pestañas >/< índice de hoja >/massOperation/< tipo de operación masiva >?api&recordId=< recordId >

• Las API de operaciones masivas son operaciones sincronizadas.
  • Es necesario modificar www a na3, ap5 o eu2 en la URL de la API según la URL de la cuenta de la base de datos de Ragic.

Método HTTP: POST
URL: https://www.ragic.com/< cuenta >< carpeta de pestañas >/< índice de hoja >/massOperation/< tipo de operación masiva >?api

Encabezados
Autorización: Básica < Clave API >

Cuerpo
{
// Datos JSON que describen la operación a realizar
}

==========

Response
{
"taskId": < A UUID Que Identifica la Tarea >
}

La API de bloqueo masivo permite bloquear o desbloquear varios registros a la vez. Bloqueo masivo de documentos

Método HTTP - POST
URL - https://www.ragic.com/< cuenta >< tarea de pestaña >/< índice de hoja >/massOperation/massLock?api

{
"action": < bloquear o desbloquear >
}

==========

Response
{
"taskId": "6dbc796a-07d5-475b-b578-d254eb30f7d2"
}

La API de aprobación masiva permite la aprobación o el rechazo de varios registros a la vez. Documento de aprobación masiva

Método HTTP: POST
URL: https://www.ragic.com/< cuenta >< carpeta de pestañas >/< índice de hoja >/massOperation/massApproval?api

{
"action": < aprobar o rechazar >,
"comment": < comentario opcional > // opcional
}

==========

Response
{
"taskId": "6dbc796a-07d5-475b-b578-d254eb30f7d2"
}

La API del botón de acción masiva permite la ejecución de un botón de acción en varios registros a la vez. Documento del botón de acción masiva

Método HTTP: POST
URL: https://www.ragic.com/< cuenta >< carpeta de pestaña >/< índice de hoja >/massOperation/massActionButton?api

{
"buttonId": < ID del botón >
}

==========

Response
{
"taskId": "6dbc796a-07d5-475b-b578-d254eb30f7d2"
}

Para obtener la lista de botones de acción disponibles en una hoja

Método HTTP: GET
URL: https://www.ragic.com/< cuenta >< carpeta de pestañas >/< índice de hoja >/metadata/actionButton?api&category=massOperation

==========

Respuesta
{
"actionButtons": [
{
"id": < ID del botón 1 >,
"name": < nombre del botón 1 >
},
.....
,{
"id": < ID del botón 2 >,
"name": < nombre del botón 2 >
}
]
}

La API de actualización masiva permite actualizaciones de valores de campo en varios registros a la vez. Documento de Actualización masiva

Método HTTP: POST
URL: https://www.ragic.com/< cuenta >< carpeta de pestañas >/< índice de hoja >/massOperation/massUpdate?api

{
    "action": [
        {
            "field": < ID de Campo >,
            "value": < Nuevo Valor de Campo >
        }
    ]
}

==========

Response
{
    "taskId": "6dbc796a-07d5-475b-b578-d254eb30f7d2"
}

La API de actualización masiva también admite el uso de usuarios internos y usuarios externos, pero existen algunas restricciones.

Los siguientes campos no se pueden actualizar de forma masiva:

• Correo electrónico (domainId: 1)
• Nombre completo (domainId: 4)
• Registro del sistema (domainId: 10)
• Estado (domainId: 31)
• Interno/Externo (domainId: 43)

La actualización masiva de grupos Ragic (domainId: 3) debe seguir las siguientes reglas:

• El valor de la clave "valor" debe escribirse en una matriz JSON, que tiene cadenas como contenido.
• Todos los caracteres especiales deben usarse con el carácter de escape (\), especialmente " debe usarse como ".

Método HTTP: POST
URL: https://www.ragic.com/< cuenta >< carpeta pestaña >/< índice de hoja >/massOperation/massUpdate?api

{
    "action": [
        {
            "field": 3,
            "value": "[\"SYSAdmin\"]"
        }
    ]
}

==========

Respuesta
{
    "taskId": "6dbc796a-07d5-475b-b578-d254eb30f7d2"
}

• En Usuarios internos, es necesario tener al menos un usuario cuyo Grupo Ragic sea SYSAdmin.
  • En Usuarios externos, el nombre del Grupo Ragic de los usuarios debe comenzar con "x-" o "X-".

La API de búsqueda y reemplazo masivo permite reemplazar valores en varios registros a la vez. Búsqueda y reemplazo masivo de documentos

HTTP Method - POST
URL - https://www.ragic.com/< cuenta >< carpeta de pestañas >/< índice de hoja >/massOperation/massSearchReplace?api

{
"action": [
{
"field": < ID de campo >,
"valueReplaced": < Valor a Reemplazar >,
"valueNew": < Nuevo Valor >,
}
]
}

==========

Respuesta
{
"taskId": "6dbc796a-07d5-475b-b578-d254eb30f7d2"
}

Las operaciones masivas son operaciones asincrónicas. El identificador de la tarea de la operación se puede utilizar para supervisar su progreso.

Método HTTP - GET
URL - https://www.ragic.com/< account >?api&taskId=< ID de Tarea >

==========

Respuesta
{
  "id": "6dbc796a-07d5-475b-b578-d254eb30f7d2",
  "ap": "myaccount",
  "taskName": "Mass Update",
  "status": "PROCESSING"
}

Un webhook es una forma para que tus aplicaciones externas puedan suscribirse a los cambios en tu aplicación Ragic. Al suscribirse a los cambios, cada vez que haya cambios realizados en Ragic, éste llamará al URL del webhook que hayas indicado para notificarte del cambio, incluyendo el ID del registro exacto que ha sido editado. La mayor ventaja de usar un webhook API en lugar de API RESTful, es que es más eficiente al procesar cambios. Ya no tienes que hacer polling en la API cada X horas para ver los cambios más recientes.

Puedes encontrar webhook para una hoja en Ragic al hacer clic en el botón Herramientas en la parte superior. Encontrarás el webhook en la sección Sincronizar.

Cosas que debes tener en cuenta sobre el webhook API:

1. Se activará al crear, actualizar y eliminar.
2. No está completamente sincronizado, podría haber un ligero retraso si la carga está elevada.
3. Los cambios no incluirán los cambios de hojas relacionadas tales como versiones múltiples.

Haz clic en la función “webhook” e ingresa el URL que debe recibir esta notificación y listo. También puedes optar por recibir información completa sobre los datos modificados marcando la casilla “enviar contenido completo sobre el registro modificado”. Para cancelar la configuración del webhook, haz clic en la x en la esquina del cuadro de configuración del webhook. El formato JSON sin contenido completo se vería así:

[1 ,2 ,4]

Para este ejemplo, significa que se modificaron los registros con ID de nodo 1, 2 y 4. El formato JSON con contenido completo se vería así:

{
  “data”: [
          < DATOS MODIFICADOS EN JSON >
   ]
  “apname”: “< NOMBRE DE CUENTA >”,
  “path”: “< NOMBRE DE RUTA >”,
  “sheetIndex”: <ÍNDICE DE HOJA >,
  “eventType”: “< TIPO DE EVENTO CREAR/ACTUALIZAR/ELIMINAR >”
}

También puedes elegir los tipos de eventos que deseas que activen el webhook. Ofrecemos las siguientes opciones: Activar al crear nuevo registro, Activar al actualizar registro, Activar al eliminar registro. Ejemplo de Activar al crear nuevo registro:

1. Crear un registro en la página de formulario
2. Agregar un registro en la página de listado

(Nota: dado que otros registros no modificados también se guardan aquí, esto generará una gran cantidad de eventos Activar al actualizar registro)

1. Restaurar un registro eliminado
2. Creación masiva
3. Importar

Ejemplo de Activar al actualizar registro:

1. Editar un registro en la página de formulario
2. Editar un registro en la página de listado

(Nota: dado que otros registros no modificados también se guardan aquí, esto generará una gran cantidad de Evento: actualización)

1. Actualización masiva
2. Buscar y reemplazar
3. Importar

Ejemplo de Activar al eliminar registro:

1. Eliminar un registro en la página de formulario
2. Eliminar un registro en la página de listado

Para garantizar que la solicitud de Webhook realmente proviene de Ragic y que su contenido no ha sido manipulado, los Webhooks configurados como "Enviar contenido completo del registro modificado" incluirán una firma en la solicitud. Después de recibir el Webhook, puedes usar la clave pública que proporcionamos para verificar la firma. Si la verificación falla, significa que la solicitud pudo haber sido manipulada, y se recomienda rechazar el procesamiento.

1. Obtener la cadena a firmar (string-to-sign)

1.1. Extrae la propiedad data de la solicitud del Webhook. (La propiedad data debe estar en formato JSONArray) 1.2. Serialízala en una cadena JSON con claves ordenadas alfabéticamente, sin indentación y sin saltos de línea. En otras palabras, "para cada objeto en el JSONArray, reordena todos los campos alfabéticamente, luego genera como una sola línea JSON".

// Antes de la conversión (propiedad data original):
[
  {
    "1001030":"banana",
    "1001029":"apple"
  }
]

// Después de la conversión (string-to-sign):
[{"1001029":"apple","1001030":"banana"}]

Nota: Si el método de serialización es inconsistente con el nuestro, la verificación de la firma fallará.

2. Verificar la firma

2.1. Extrae la propiedad signature de la solicitud del Webhook. 2.2. Descarga la clave pública (ver "Obtener Clave Pública"). 2.3. Usa una herramienta de verificación que soporte SHA256withRSA.

1. Convierte la cadena a firmar en un array de bytes UTF-8
2. Verifica la firma usando la clave pública y el algoritmo

2.4. Si la verificación es exitosa, significa que la solicitud proviene de Ragic y su contenido no ha sido manipulado.

Proporcionamos dos formas para obtener la clave pública. Elige la que mejor se adapte a tu caso de uso:

1. Obtén la cadena de clave pública directamente llamando a: https://www.ragic.com/api/http/getWebhookSignaturePublicKey.jsp?type=string
2. Haz clic aquí para descargar el archivo PEM.

Se recomienda almacenar en caché la clave pública en tu servidor y solo volver a descargarla al inicio.

• Si estás usando la versión de Servidor Privado, o si "Enviar contenido completo del registro modificado" no está habilitado, el Webhook no soportará verificación de firma.
  • Asegúrate de que tu programa maneje la serialización JSON de manera consistente; de lo contrario, ocurrirán errores de verificación.