Preguntas frecuentes¶
Acceso, credenciales y ambientes¶
¿Cómo obtengo una API Key?¶
Para generar su API Key, en la app de Kordata ingrese al apartado de Configuración y a continuación al módulo de Llaves de acceso para integración. Seleccione generar nueva llave, los permisos necesarios para su configuración, y la fecha de expiración.
¿Qué hago si mi API Key expiró?¶
Genere una nueva llave en Kordata: Configuración → Llaves de acceso para integración. Asigne permisos y fecha de expiración, actualice la llave en su integración y elimine la llave anterior.
¿Por qué mi API Key funciona en un endpoint y en otro no?¶
La API Key es válida, pero cada llave tiene permisos por módulo/ruta. La documentación muestra el catálogo general; su llave solo puede invocar lo habilitado en su contrato. Si recibe 403, revise los permisos en Llaves de acceso para integración en la app Kordata y actualicelos. Ver también Autenticación y Módulos.
¿Existe un ambiente sandbox o de pruebas?¶
No. Actualmente no hay sandbox de pruebas. Las integraciones se realizan contra el ambiente de producción con la URL base y la API Key que genere en app Kordata. Planifique sus pruebas con datos y operaciones acordadas con su equipo. Ver Ambientes
¿Puedo probar la API sin escribir código?¶
Sí. Abra Referencia documentación API, pulse el botón para abrir el explorador en una pestaña nueva, configure Authentication → ApiKeyAuth con su x-api-key, elija un endpoint, complete parámetros y pulse Send.
Headers, versión y contrato¶
¿Qué headers son obligatorios en cada petición?¶
En todas las peticiones: x-api-key (su API Key) y x-api-version: v1. En POST, PUT o PATCH con cuerpo JSON, incluya también Content-Type: application/json. Ver Primeros pasos y Autenticación.
¿Qué pasa si no envío x-api-version?¶
El gateway espera el header de versión del contrato. Si falta o es incorrecto, la petición puede retornará un estado HTTP 400. Incluya siempre x-api-version en cada llamada.
Errores y soporte¶
¿Por qué recibo 404 si la ruta existe en la documentación?¶
Causas habituales: la ruta no está habilitada para su API Key; error en la URL (base, prefijo o parámetros). Confirme método HTTP, path y permisos en Referencia documentación API con su misma llave.
¿Por qué recibo 429 y cómo lo evito?¶
El servicio aplica rate limit por API Key. Recibe 429 cuando supera el límite de peticiones. Reduzca la frecuencia, use paginación en listados, evite bucles agresivos y reintente con backoff (espera creciente). Ver Límites y versionado.
¿Un 500 siempre es fallo técnico o puede ser regla de negocio?¶
Un estado de respuesta HTTP 500 (INTERNAL_ERROR) puede indicar error interno o una regla de negocio no cumplida en Kordata.
¿Por qué recibo 401?¶
Revise que envía x-api-key correcta, sin espacios, y que la llave siga activa. Ver Autenticación.
¿Por qué recibo 403?¶
Su llave es válida pero no tiene permiso para esa operación. Actualice los persmisos con los que cuenta su API Key a través del modulo de Llaves de acceso para integración en app Kordata.
Seguridad y operación¶
¿Es obligatorio usar HTTPS?¶
Sí. Debe consumir el gateway siempre por HTTPS. No envíe la API Key por HTTP ni en canales no cifrados.
¿Puedo guardar la API Key en variables de entorno o en el frontend?¶
Variables de entorno o gestores de secretos en su backend: sí, es la práctica recomendada. Frontend, apps móviles descompilables o repositorios públicos: no. La llave debe vivir solo en sistemas de servidor que usted controla.
Uso técnico¶
¿Qué hago con un error 500?¶
Registre meta.requestId, hora, ruta y payload (sin API Key) y contacte a soporte. Puede reintentar con backoff si fue transitorio.
¿Hay webhooks?¶
Si Kordata habilita notificaciones push para su contrato, se documentarán en una sección dedicada cuando estén disponibles. Hoy el modelo principal es REST bajo demanda.
¿Los ejemplos del sitio son datos reales?¶
Los ejemplos son orientativos. Use identificadores y datos a producción bajo su propia consideración.
Alcance del producto y soporte comercial¶
¿Kordata notifica cambios de contrato o nuevas versiones de la API?¶
Kordata comunicará nuevas versiones mayores, deprecaciones y cambios relevantes por los canales oficiales y por este medio. Mantenga su integración en la versión documentada (v1) hasta completar una migración guiada.
¿Cómo me entero de nuevos módulos o rutas?¶
Revise frecuentemente esta documentación para enterarse de cambios en el contrato y nuevos modulos añadidos.
¿Esta API sustituye el uso del app Kordata en pantalla?¶
No. La API sirve para integrar sistemas externos con el Kordata. No sustituye manuales de usuario, pantallas ni flujos contables internos de Kordata. Ver Qué es el API Gateway.