Por favor, antes de utilizar el API de Docuo, lee cuidadosamente los Términos y condiciones del uso del API de Docuo.
A continuación se proporciona información técnica importante para el uso del API de Docuo:
Autorización de aplicaciones y usuarios para el uso del API
El acceso a las API de Docuo se realiza mediante un protocolo denominado OAuth 2.0 [http://tools.ietf.org/html/rfc6749]
OAuth es un protocolo de autorización estándar que permite que una aplicación de terceros acceda a datos de Docuo y/o ejecute acciones en nombre de un usuario sin necesidad de conocer su contraseña. Así, para que una aplicación de terceros se integre con Docuo, no es necesario compartir usuarios o contraseñas reales, sino que OAuth hace las veces de llave para permitir el acceso a un repositorio Docuo en lugar de un usuario y poder actuar en su nombre.
Para autorizar el acceso de una aplicación de terceros a un repositorio Docuo, un administrador debe seguir los siguientes pasos:
1 Abrir las opciones de Docuo desde el menú principal de la aplicación:
2 En la ventana de opciones, hacer clic en la pestaña «Avanzado» e ir a la sección «API», después pulsar en el botón «Abrir»:
3 Este botón abre una nueva ventana con la lista de todas las aplicaciones externas autorizadas para acceder a Docuo a través de la API. Haga clic en Nuevo para crear una nueva autorización para su aplicación. También puede editar o eliminar aplicaciones externas existentes desde esta ventana:
4 Al crear una nueva aplicación, debe darle un nombre y pulsar Guardar:
Docuo genera automáticamente dos cadenas de caracteres especiales para esa aplicación: client_id y client_secret que deben proporcionarse al desarrollador de la aplicación externa. Para la aplicación recién creada, haga clic en Nuevo en la sección Usuarios y Colaboradores, para crear las autorizaciones que desea utilizar para la API en esta aplicación. Para cada acceso, Docuo generará otras dos cadenas de caracteres especiales: user_id y user_secret, que también deben proporcionarse al desarrollador de la aplicación externa.
Un administrador de Docuo siempre puede revocar las autorizaciones en cualquier momento haciendo clic en Eliminar en la lista. En este caso, se suspende inmediatamente cualquier acceso a Docuo que se esté realizando con esos secretos e identificadores.
Obtención del Token de Acceso
Para iniciar sesión en la API Docuo, debe seguir el flujo de contraseñas OAuth2 en esta URL de token: https://api.r2docuo.com/oauth2/token
Los parámetros requeridos son
client_id
El valor del client_id proporcionado por el administrador de Docuo para la aplicación.
client_secret
El valor proporcionado por el administrador Docuo para la aplicación.
grant_type
Especificado como «password».
scope
El nombre del repositorio Docuo.
username
El user_id correspondiente al usuario Docuo.
password
El user_secret correspondiente al colaborador Docuo.
Puede enviar las credenciales como Basic Auth Header o en el Body con application/x-www-form-urlencoded.
Si las credenciales proporcionadas son satisfactorias. El servidor devolverá una respuesta application/json que contiene el access_token que debe proporcionarse en cada llamada a los endpoints del API.
El access_token puede enviarse como cabecera única o en la cabecera Authorization Bearer.
La respuesta completa también contendrá el token de actualización:
{
"access_token": "00DU0000000Io8r!AQcKbNGPff6hW0mfmKH07QiPEGIX",
"token_type": "Bearer",
"expires_in": 120,
"refresh_token": "1/iQI98wWFfJNFWIzs5hrEDDrSiYewe3dFqt5vIV-9ibT9k"
}Dónde:
access_token
Es el token de acceso que debe especificarse en cada llamada dentro del protocolo OAuth.
expires_in
Tiempo de vida del token en segundos.
refresh_token
Es el token que debe utilizarse para adquirir uno nuevo en caso de expiración.
Refresco del Token
El tiempo de vida de un token está limitado desde su obtención, contando en segundos el valor proporcionado en expires_in.
Intentar acceder a la API con un token caducado dará error. En este caso será necesario obtener un nuevo token utilizando el refresh_token que se proporcionó al iniciar sesión.
El token puede refrescarse siempre que se desee antes de que caduque. Es muy recomendable que su aplicación Docuo, antes de realizar una llamada a la API, determine si el token está caducado para proceder a actualizarlo antes de que la llamada devuelva un error.
Gestión de errores
Las llamadas a la API que utilizan tokens de acceso OAuth 2.0 pueden fallar. Por ejemplo cuando el token no es válido, porque ha caducado o ha sido revocado. En todos estos casos obtendrá un error HTTP 4xx.
Se puede incluir información detallada del error en la cabecera de respuesta, como se puede ver en el siguiente ejemplo:
HTTP/1.1 401 Unauthorized WWW-Authenticate: Bearer realm="example", error="invalid_token", error_description="The access token expired"realm
Contexto donde se ha producido el error. Solo informativo.
error
Código del error. Puede ser uno de los siguientes valores:
invalid_request
Cuando en la petición falta algún parámetro requerido no está bien formado. El servidor responderá con HTTP 400 (Bad Request) status code.
invalid_token
Cuando el token proporcionado está expirado, revocado o malformado. El servidor responderá con HTTP 401 (Unauthorized) status code. En este caso el cliente podrá realizar un refresh token.
insufficient_scope
Cuando la petición requiere privilegios no disponibles. El servidor responderá con el código de estado HTTP 403 (Forbidden).
error_description
Descripción del error.
Cuando la petición no proporciona información de autenticación o utiliza un método de autenticación no soportado, la respuesta NUNCA INCLUIRA código de error o descripción:
HTTP/1.1 401 Unauthorized WWW-Authenticate: Bearer realm="ejemplo"Suscripción a eventos (Callbacks)
Es posible configurar Docuo para realizar callbacks a una aplicación externa. Algunas acciones en Docuo generan eventos que pueden enviar información en formato JSON a través de un POST a una dirección URL preconfigurada. Para que una aplicación externa pueda suscribirse a los eventos de un repositorio Docuo, un administrador debe seguir los siguientes pasos:
1 Abrir las opciones de Docuo desde el menú principal de la aplicación:
2 En la ventana de Opciones, ir a la pestaña «Avanzado» y encontrar la sección API. entonces pulsar el botón «Abrir»:
3 Este botón abre una ventana con la lista de todas las aplicaciones externas autorizadas a acceder a Docuo a través de la API. Seleccione una y haga clic en Detalle para editar su aplicación, luego haga clic en la pestaña Suscripción a eventos.
Podrá ver la lista de todos los callbacks preconfigurados de su aplicación. Para añadir un Evento pulse el Botón Nuevo:
