Información general sobre la API de usuario
La API de usuario
La API de usuario es una API REST que obtiene, agrega y actualiza información de usuario/grupo/departamento.
PROTOCOL | FORMATO | CODIFICACIÓN DE CARACTERES | SECUENCIA DE ESCAPE |
---|---|---|---|
HTTPS | JSON | UTF-8 | Utilice "\" |
Autenticación de usuario
La API de REST de usuario requiere autenticación de contraseña, con las claves y los valores adecuados establecidos en el encabezado de la solicitud. Si la función de seguridad de autenticación básica también está configurada en su dominio, se requerirán tanto encabezados para la autenticación de contraseña como para la autenticación básica para la solicitud.
Autenticación de contraseña
Establezca "X-Cybozu-Authorization" en el encabezado de la solicitud, con un nombre de inicio de sesión y una contraseña codificados en BASE64 como valor.
Si su nombre de inicio de sesión es Tono de kintone" y su contraseña es "developer", codificación BASE64 "Kintone:developer" y configúrelo en el encabezado de la siguiente manera:
|
|
Autenticación de sesión
La autenticación de sesión es un método de autenticación en el que el servidor web asigna un ID de sesión a un usuario y lo guarda como una cookie. Esta cookie se utiliza para identificar y autenticar al usuario. La autenticación de sesión solo puede ser utilizada por códigos JavaScript que se ejecutan en las páginas de Kintone. Los tokens CSRF son necesarios cuando se utiliza la autenticación de sesión con métodos POST/PUT/DELETE. Consulte la siguiente documentación para obtener más detalles sobre la recuperación de un token CSRF:
Get CSRF Token
Prioridad de autenticación
La prioridad de la autenticación es la siguiente.
- Autenticación con contraseña
- Autenticación de sesión
Autenticación básica (heredada)
Advertencia
A partir de junio de 2020, la autenticación básica ha quedado obsoleta y ya no está disponible para su uso.
Si su entorno Kintone ha establecido la función de seguridad de autenticación básica, agregue "Autorización" en el encabezado de la solicitud, con la cadena "Basic" y un nombre de inicio de sesión y contraseña codificados en BASE64 de la autenticación básica como valor.
Si el nombre de inicio de sesión de autenticación básica es "chocolate" y la contraseña de autenticación básica es "pudding", lugar "Basic " en el valor, seguido de un BASE64 codificado "Chocolate:pudín" de la siguiente manera:
|
|
Encabezados de solicitud
Estos encabezados de solicitud se utilizan para la API de REST.
ENCABEZADO | OBLIGATORIO | VALOR |
---|---|---|
Host | Obligatorio | {subdomain}.kintone.com:443 |
Content-Type | Condicional | application/json. Especifique esto solo si el cuerpo de la solicitud está en formato JSON. |
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 sobre la autenticación con contraseña, consulte la siguiente documentación: Autenticación de contraseña |
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 sobre la autenticación básica, consulte la siguiente documentación: Autenticación básica |
Solicitud de URI
PROPÓSITO | URI | DETALLES |
---|---|---|
General | https://{subdomain}.kintone.com/v1/{API_command}.json | Este es el formato general de las API de usuario. |
Respuestas
El código de estado HTTP 200 indica que la solicitud se realizó 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á en función de la configuración de idioma del usuario de Kintone utilizado para la autenticación. |
id | El identificador del error. |
code | El código del error, para especificar el tipo de error que es. |
Ejemplo de respuesta de error
|
|
Estructuras de datos utilizadas con la API de usuario
Tipo de ID
Se utiliza para entidades (usuario/grupo/departamentos) en Kintone.
Un número entero entre 1 y Long.MAX.
Tipo de usuario
Llave | Tipo | Detalles |
---|---|---|
id | Tipo de ID | El ID de usuario. Consulte la siguiente sección para obtener más información sobre los tipos de identificación: Tipo de ID |
code | Cuerda | El nombre de inicio de sesión del Usuario. |
ctime | Formato de fecha y hora ISO-8601 | La fecha y hora creada por el Usuario. |
mtime | Formato de fecha y hora ISO-8601 | La fecha y hora actualizada del Usuario. |
valid | Booleano | Si el estado del usuario es Activo o no. |
name | Cuerda | El nombre para mostrar del usuario. |
surName | Cuerda | El apellido del Usuario. |
givenName | Cuerda | El nombre del Usuario. |
surNameReading | Cuerda | La lectura fonética del apellido. |
givenNameReading | Cuerda | La lectura fonética del Nombre. |
localName | Cuerda | El nombre para mostrar localizado del usuario. |
localNameLocale | Cuerda | La configuración regional del nombre para mostrar localizado del usuario. |
timezone | Cuerda | El identificador de zona horaria de la zona horaria establecida por el usuario. Vea toda la lista de zonas horarias en la Ayuda de Kintone: Lista de zonas horarias |
locale | Cuerda | La configuración de idioma del usuario. |
description | Cuerda | La sección "Acerca de mí" del perfil del usuario. |
phone | Cuerda | El número de teléfono del Usuario. |
mobilePhone | Cuerda | El número de teléfono móvil del Usuario. |
extensionNumber | Cuerda | El número de extensión del Usuario. |
Cuerda | La dirección de correo electrónico del Usuario. | |
callto | Cuerda | El ID de Skype del usuario. |
url | Cuerda | La sección "URL" del perfil del usuario. |
employeeNumber | Cuerda | El número de empleado del usuario. |
birthDate | ISO-8601 formato de fecha o nulo | El cumpleaños del usuario. |
joinDate | ISO-8601 formato de fecha o nulo | La fecha de contratación del usuario. |
primaryOrganization | Entero o nulo | El ID de departamento del departamento prioritario del usuario. Establézcalo en null si no hay ningún departamento prioritario. |
sortOrder | Integer | La prioridad del orden de visualización del usuario. |
customItemValues | Matrices customItemValue | Una lista de pares de nombres de campos personalizados y códigos de campos personalizados. Consulte la siguiente sección para obtener más información sobre customItemValues: customItemValue type |
Solo los usuarios y administradores del sistema pueden obtener datos de campos personalizados que tienen la opción "Visibilidad" desmarcada.
Para obtener más información sobre usuarios y administradores de sistemas, consulte el siguiente enlace:
Tipos de administradores
Tipo de departamento
Llave | Tipo | Detalles |
---|---|---|
id | Tipo de ID | La identificación del Departamento. Consulte la siguiente sección para obtener más información sobre los tipos de identificación: Tipo de ID |
code | Cuerda | El Código del Departamento. |
name | Cuerda | El nombre para mostrar del Departamento. |
localName | Cuerda | El nombre localizado del Departamento. |
localNameLocale | Cuerda | La configuración regional del nombre localizado del Departamento. |
parentCode | Cuerda | El código del Departamento de Padres. null, si el elemento primario es la raíz. |
description | Cuerda | La descripción del Departamento. |
Tipo de título
Llave | Tipo | Detalles |
---|---|---|
id | Tipo de ID | El identificador del puesto de trabajo. Consulte la siguiente sección para obtener más información sobre los tipos de identificación: Tipo de ID |
code | Cuerda | El código del puesto de trabajo. |
name | Cuerda | El nombre del puesto de trabajo. |
description | Cuerda | La descripción del puesto de trabajo. |
Tipo de grupo
Llave | Tipo | Detalles |
---|---|---|
id | Tipo de ID | El ID del grupo. Consulte la siguiente sección para obtener más información sobre los tipos de identificación: Tipo de ID |
code | Cuerda | El código del Grupo. |
name | Cuerda | El nombre para mostrar del grupo. |
description | Cuerda | La descripción del Grupo. |
organizationTipo de título
Llave | Tipo | Detalles |
---|---|---|
organización | Tipo de departamento | La información del Departamento. Consulte la siguiente sección para obtener más información sobre los tipos de departamentos: Tipo de departamento |
title | Tipo de título o nulo | La información del puesto de trabajo. null para "sin título". Consulte la siguiente sección para obtener más información sobre los tipos de títulos: Tipo de título |
userTipo de título
Llave | Tipo | Detalles |
---|---|---|
user | Tipo de usuario | La información del Usuario. Consulte la siguiente sección para obtener más información sobre los tipos de usuarios: Tipo de usuario |
title | Tipo de título o nulo | La información del puesto de trabajo. null para "sin título". Consulte la siguiente sección para obtener más información sobre los tipos de usuarios: Tipo de título |
customItemValue tipo
Llave | Tipo | Detalles |
---|---|---|
code | Cuerda | Código |
valor | Cuerda | Valor |
Es posible que los campos personalizados tengan la configuración "Hacer público este campo" de la opción "Visibilidad" sin marcar. Solo los usuarios y administradores del sistema pueden obtener datos de campos personalizados que tienen la opción "Visibilidad" desmarcada.
Para obtener más información sobre usuarios y administradores de sistemas, consulte el siguiente enlace:
Tipos de administradores
Notas
Encabezado X-HTTP-Method-Override
- Agregue el encabezado X-HTTP-Method-Override para evitar el error URI de solicitud demasiado grande que se produce cuando el URI de solicitud supera los 4 KB. Todas las API de usuario admiten este encabezado.
- Si se envía una solicitud GET de una API de usuario mediante el método de solicitud de API REST de Kintone y la longitud del URI supera los 4 KB, el encabezado X-HTTP-Method-Override se agregará automáticamente y la solicitud se enviará como una solicitud POST. Esto permite que las solicitudes de API de usuario con URI largos se ejecuten sin errores.
Para obtener más información sobre el método de solicitud de API REST de Kintone, consulte el siguiente enlace:
Solicitud de API REST de Kintone