Documentos de API

Descripción general de la API REST de Kintone

Contenido

La API REST de Kintone

La API REST de Kintone es capaz de realizar operaciones generales de creación/recuperación/actualización/eliminación de registros de aplicaciones, recuperación de descripciones de aplicaciones y manipulación de espacios.

PROTOCOL FORMATO CODIFICACIÓN DE CARACTERES SECUENCIA DE ESCAPE
HTTPS JSON UTF-8 Utilice "\"

Autenticación

Consulte el siguiente artículo:
Autenticación

Solicitudes

Encabezados de solicitud

Estos encabezados de solicitud se utilizan para la API de REST. No es necesario especificar encabezados de solicitud cuando se utiliza una solicitud de API de REST de Kintone. Para obtener más información, consulte el siguiente artículo:
Solicitud de API REST de Kintone

ENCABEZADO OBLIGATORIO VALOR
Host Obligatorio {subdomain}.kintone.com:443
Content-Type Condicional Para JSON: application/json o para datos de varias partes: multipart/form-data.
Solo es necesario cuando se envía un cuerpo de solicitud.
X-Cybozu-Authorization Condicional login_name:password codificado en base64. Solo es necesario cuando se utiliza la autenticación con contraseña. Para obtener más información, consulte el siguiente documento:
Autenticación de contraseña
X-Cybozu-API-Token Condicional El token de API de la aplicación Kintone. Solo es necesario cuando se utiliza la autenticación de token de API. Para obtener más información, consulte el siguiente documento:
Autenticación de token de API
Authorization Condicional Basic seguido de un código Base64 login_name:password. Solo es necesario cuando se usa la autenticación básica obsoleta, que ya no está disponible a partir de junio de 2020. Para obtener más información, consulte el siguiente documento:
Autenticación básica
X-HTTP-Method-Override Opcional El método HTTP. Especifique una de las siguientes opciones: GET / POST / PUT / DELETE.
Especificando un método HTTP en X-HTTP-Method-Override y enviando un POST , se ejecutará una API que corresponda al método HTTP especificado.
  • El encabezado X-HTTP-Method-Override solo será válido durante un POST pedir.
  • Se puede llamar a todas las API de REST cuando se usa X-HTTP-Method-Override.
  • El método HTTP especificado para X-HTTP-Method-Override distingue entre mayúsculas y minúsculas.
* Este encabezado se utiliza para evitar el método Request URI Too Large error que se produce cuando el URI de la solicitud supera los 8 KB.
* Este método de encabezado está disponible en todas las rutas de la API de REST de Kintone, pero no se puede garantizar el comportamiento cuando se usa con API externas.
* Si un GET La solicitud se envía mediante kintone.api()y la longitud supera los 4 KB, el encabezado X-HTTP-Method-Override se agregará automáticamente y la solicitud se enviará como un POST pedir. Para obtener más información, consulte el siguiente artículo:
Solicitud de API REST de Kintone
La siguiente solicitud ejecutará la siguiente API:
Obtener registros

Encabezado de solicitud
POST /k/v1/records.json
  Host: example.kintone.com:443
  X-Cybozu-Authorization: a2ludG9uZTpkZXZlbG9wZXI=
  Content-Type: application/json
  X-HTTP-Method-Override: GET
Cuerpo de la solicitud
{
  "app":"8",
  "query":"date > "2015-05-03T09:00:00-0800" and date < "2015-05-03T10:00:00-0800""
}
Aceptar-Idioma Opcional El código lingüístico, p. ej.en, ja, zh, es.
Fuerza que los datos de un campo se devuelvan en el idioma especificado, si se ha establecido una localización. Esto invalida el idioma de la configuración regional del sistema y el idioma de la configuración regional del usuario.

Solicitud de URI

PROPÓSITO URI DETALLES
General https://{subdomain}.kintone.com/k/v1/{APIpath}.json Este es el URI de solicitud general que debe usar. Si está tratando con aplicaciones que se encuentran en espacios de invitado, use el siguiente URI de solicitud.
Aplicaciones en espacios de invitados https://{subdomain}.kintone.com/k/guest/{spaceID}/v1/{APIpath}.json Si la aplicación se creó dentro de un espacio de invitado, este es el URI de solicitud que deberá usar.
Tenga en cuenta que los usuarios invitados no pueden iniciar las API de REST.

Cuerpo de la solicitud

El cuerpo de la solicitud tiene formato JSON. La codificación de caracteres debe estar en UTF-8. Sin embargo, cuando se utiliza la API de carga de archivos, el cuerpo de la solicitud debe tener el formato multipart/form-data. Para obtener más información, consulte el siguiente artículo:
Carga de archivos

Una barra invertida \ se puede usar para escapar caracteres dentro del JSON según sea necesario.

Parámetros de consulta

En el caso de las rutas de API que utilizan el método GET , los parámetros de solicitud se pueden pasar a través de la URL como parámetros de consulta. Por ejemplo, para especificar un App Id de 1, los parámetros de consulta se pueden establecer de la siguiente manera:

/k/v1/records.json?app=1

Codificación

De acuerdo con el estándar de URL, las claves y los valores de los parámetros de consulta se codifican mediante la codificación de URL. En el ejemplo siguiente se muestra una cadena codificada de URL para "Updated_datetime > "2021-10-01T09:00:00+0900":

/k/v1/records.json?app=1&query=Updated_datetime+%3E+2021-10-01T09%3A00%3A00%2B0900

Parámetros de matriz

Descomponga la matriz y codifique la URL de cada elemento. En el siguiente ejemplo, se utiliza la API Get Records. El fields incluye un parámetro Record Id campo y un campo Dropdown campo. Para obtener más información, consulte el siguiente artículo:
Obtener registros

  1. fields=[Record_Id,Dropdown] se descompone en elementos separados /k/v1/records.json?app=1&fields[0]=Record_Id&fields[1]=Dropdown
  2. Las claves y los valores de cada parámetro están codificados en URL /k/v1/records.json?app=1&fields%5B0%5D%3DRecord_Id%26fields%5B1%5D%3DDropdown

Respuestas

Códigos de estado HTTP

El código de estado HTTP 200 indica que la solicitud se recibió correctamente.
Trate cualquier otro código de estado como errores. Los errores responderán con datos JSON, incluida la siguiente información.

LLAVE VALOR
message El mensaje de error. El idioma del mensaje variará según la configuración de idioma del usuario de Kintone.
id El identificador del error.
code El código del error, para especificar el tipo de error que es.
Ejemplo de respuesta de error
1
2
3
4
5

{
  "message": "Invalid JSON string.",
  "id": "1505999166-897850006",
  "code": "CB_IJ01"
}

Encabezados de respuesta

Todas las API REST de Kintone incluyen los siguientes detalles en el encabezado de respuesta.

LLAVE VALOR
X-ConcurrencyLimit-Limit El límite de solicitudes de API simultáneas.
El valor predeterminado es 100.
X-ConcurrencyLimit-Running El número de solicitudes de API simultáneas en ejecución.

Acerca de la respuesta de una solicitud realizada con kintone.api()

Al usar kintone.api() para realizar solicitudes de API REST de Kintone, solo se pasa el cuerpo de la respuesta a la función de devolución de llamada. Para usar otros datos que no están incluidos en el cuerpo de la respuesta, no use kintone.api() para realizar las solicitudes y utilizar otro método.

Formatos de fecha

Los campos relacionados con la fecha y la hora siguen los siguientes formatos.

TIPO DE CAMPO FORMATO DESCRIPCIÓN
Fecha YYY-MM-DD Esto no se convierte a UTC.

Se pueden utilizar los siguientes formatos de fecha:
  • 2015
  • 2015-07
  • 2015-7
  • 2015-7-5
Si se ignora la fecha y/o el mes, se complementará con 01:
  • 2015 -> 2015-01-01
  • 2015-07 -> 2015-07-01
  • 2015-7 -> 2015-07-01
  • 2015-7-5 -> 2015-07-05
Hora HH:MM Esto no se convierte a UTC.
Fecha y hora YYY-MM-DD
o
YYYY-MM-DDTHH:MM:SSZ
o
YYYY-MM-DDTHH:MM:SS±HH:MM		 Símbolos
  • Z: Indica que la fecha y hora se expresa en UTC.
  • T: Un valor fijo para separar la fecha de la hora.
Para obtener respuestas
  • Los datos se responden como YYYY-MM-DDTHH:MM:SSZ
  • Ejemplo: 22 de enero de 2021 07:00 PST se responderá como 2021-01-22T15:00:00Z.
Para solicitudes
  • Los datos se solicitan en uno de los siguientes formatos:
    • YYY-MM-DD
    • YYYY-MM-DDTHH:MM:SSZ
    • YYYY-MM-DDTHH:MM:SS±HH:MM
  • Si la fecha se solicita como YYYY-MM-DD, se trata como UTC
  • Valores indicados para SS será ignorado, y será tratado como 00
  • Ejemplo: 22 de enero de 2021 07:23 PST se puede solicitar como 2021-01-22T15:23:00Z o 2021-01-22T07:23:00-08:00

Notas

  • Después de las actualizaciones de Kintone, los cambios en las especificaciones, como la adición de nuevos campos y claves, se pueden aplicar a los formatos JSON de los datos de solicitud y respuesta.
  • Para ver información de las operaciones de aplicación, registro, comentario y espacio, consulte los registros de auditoría. Para obtener más información, consulte el siguiente artículo:
    Comprobación de los registros de auditoría de Kintone (External link)
  • El número de solicitudes de API disponibles por día es de 10.000 por aplicación. Para las API que no se cuentan como parte de los límites de llamadas a la API, consulte el siguiente enlace:
    El número de solicitudes de API disponibles por día (External link)
  • Si un dominio tiene restricción de dirección IP, solo las solicitudes de API de una dirección IP aprobada se realizarán correctamente.

Limitaciones

  • Al operar en Búsqueda con la API Add Record(s) y la API Update Record(s), el campo clave de la aplicación de origen de datos debe ser un Número de registro o un campo con la opción "Prohibir valores duplicados" activada.
  • Si el campo clave de la aplicación de origen de datos de un Búsqueda campo es un campo Text con la opción "Calcular automáticamente" activada, el campo Búsqueda no se puede operar con API.

Para obtener más información sobre las limitaciones y el uso de la API de REST de Kintone, consulte la sección API de REST del siguiente artículo:
Lista de valores límite (External link)