Inicio rápido
Realiza tu primera solicitud a la API REST de KintiSoft y conoce los pasos básicos para conectar una aplicación externa con la plataforma.
Al finalizar esta guía, tendrás preparado tu entorno y podrás ejecutar una petición autenticada a un recurso disponible.
Antes de comenzar
Necesitarás:
- Acceso a una organización o tenant de KintiSoft.
- Una API Key válida y con los permisos necesarios.
- La URL base correspondiente a tu entorno.
- Una herramienta HTTP como cURL, Postman o Insomnia.
- Conexión a Internet.
Las operaciones disponibles dependen de los permisos de tu API Key y de los recursos habilitados para tu tenant.
1. Configura tu entorno
Para comunicarte con la API necesitas conocer la URL base de tu entorno.
Define las siguientes variables en tu cliente HTTP:
| Variable | Descripción |
|---|---|
BASE_URL | URL base de la API de KintiSoft. |
API_KEY | Credencial utilizada para autenticar solicitudes. |
TENANT_ID | Identificador del tenant, cuando sea requerido por la integración. |
Puedes almacenar estos valores como variables de entorno para evitar incluir información sensible directamente en tu código.
:::warning Seguridad No publiques tus API Keys en repositorios, ejemplos públicos ni aplicaciones frontend. Utiliza mecanismos seguros para almacenar y administrar credenciales. :::
2. Configura la autenticación
La API de KintiSoft utiliza API Keys para autenticar las solicitudes.
Cada solicitud debe incluir las credenciales de acuerdo con el mecanismo documentado para la API.
Consulta Autenticación para conocer el formato de los encabezados y los requisitos de seguridad.
3. Selecciona un endpoint
Para comprobar la conexión, elige una operación de lectura disponible en la referencia de API.
Te recomendamos comenzar con una solicitud GET, ya que permite consultar información sin crear ni modificar registros cuando el endpoint es de solo lectura.
4. Realiza tu primera solicitud
El siguiente ejemplo muestra la estructura general de una solicitud HTTP autenticada.
Sustituye los valores de ejemplo por los datos reales de tu integración.
curl --request GET \
"${BASE_URL}/RUTA_DEL_RECURSO" \
--header "Accept: application/json" \
--header "ENCABEZADO_DE_AUTENTICACION: ${API_KEY}"
:::warning Importante
RUTA_DEL_RECURSO y ENCABEZADO_DE_AUTENTICACION son marcadores de posición.
Antes de ejecutar la solicitud, reemplázalos por un endpoint y un encabezado válidos, según la referencia oficial de KintiSoft. :::
¿Qué hace esta solicitud?
- GET: solicita información de un recurso.
- BASE_URL: identifica el servidor de la API.
- Accept: indica que el cliente espera una respuesta JSON.
- API_KEY: proporciona la credencial de autenticación mediante el encabezado correspondiente.
5. Comprueba la respuesta
Si la solicitud se procesa correctamente, el servidor devolverá una respuesta HTTP de éxito.
El cuerpo de la respuesta dependerá del endpoint consultado.
Para comprobar el resultado:
- Revisa el código de estado HTTP.
- Verifica que recibiste los datos esperados.
- Comprueba que la estructura de respuesta corresponde a la documentación del endpoint.
Códigos HTTP frecuentes
| Código | Significado |
|---|---|
200 | La solicitud se procesó correctamente. |
201 | Se creó un recurso correctamente. |
400 | La solicitud contiene datos incorrectos. |
401 | No se proporcionaron credenciales válidas. |
403 | El cliente no tiene permisos suficientes. |
404 | No se encontró el recurso solicitado. |
429 | Se alcanzó un límite de solicitudes. |
500 | Se produjo un error interno del servidor. |
Estos son códigos HTTP habituales. Su disponibilidad y el formato de los errores deben verificarse en la documentación de cada endpoint de KintiSoft.
6. Utiliza un SDK
Además de HTTP REST, puedes trabajar con los SDKs disponibles de KintiSoft.
Selecciona el lenguaje que utilizas:
Los SDKs permiten simplificar tareas de comunicación con la API según las funcionalidades implementadas por cada librería.
Buenas prácticas
Para desarrollar integraciones seguras y mantenibles:
- Utiliza HTTPS en todas las comunicaciones.
- Mantén las credenciales fuera del código fuente.
- Solicita únicamente los permisos necesarios.
- Valida los datos enviados y recibidos.
- Implementa un manejo adecuado de errores HTTP.
- Evita registrar información sensible en logs.
- Prueba los flujos de integración antes de utilizarlos en producción.
Siguientes pasos
Ahora que conoces el proceso inicial de conexión, continúa explorando:
Estas secciones te permitirán comprender los mecanismos de acceso y las operaciones disponibles para integrar KintiSoft con otras aplicaciones.