Primeros pasos
Por Maxim
Por Maxim
Conexión, autorización, formato de las solicitudes y datos de referencia
Descripción general de la API
La API de Controlata permite que sistemas externos (un sitio web, un CRM, un sistema contable o un marketplace) trabajen con tus datos en Controlata: gestionar el catálogo de materiales, productos y recursos, crear ventas, compras, producciones, bajas, traslados e inventarios físicos, y leer las existencias en los almacenes. La conexión requiere experiencia en programación y con APIs. Si no eres desarrollador, entrega esta documentación a un especialista técnico o a un asistente de IA: cada artículo se puede copiar en formato Markdown. Conexión 1. Abre Configuración → Integraciones y pulsa Conectar junto a API general. 2. Copia la Clave API. Autoriza todas las solicitudes. 3. Si lo necesitas, cambia el Prefijo del número de venta. El valor por defecto es «A-». Dirección base y formato de las solicitudes Dirección base de la API: https://api.controlata.com/connect/ En esta documentación las rutas de los métodos se indican respecto a esta dirección. Por ejemplo, el método v1/materials/add se llama en https://api.controlata.com/connect/v1/materials/add.php. El primer segmento de la ruta es la versión del método: una versión nueva aparece solo si la respuesta cambia de forma incompatible, y la anterior sigue funcionando. - Todos los métodos se llaman con una solicitud POST. - Cuerpo de la solicitud: JSON en UTF-8, encabezado Content-Type: application/json. La API está pensada para solicitudes desde tu servidor. Las solicitudes desde un navegador en otro dominio se rechazan con el código 401. Autorización Pasa la Clave API en el encabezado Authorization tal cual, sin la palabra Bearer: Authorization: tu_clave_api Ejemplo de solicitud: curl -X POST https://api.controlata.com/connect/v1/storages/get_list.php \ -H "Authorization: tu_clave_api" \ -H "Content-Type: application/json" \ -d '{}' Respuestas y errores Una respuesta correcta llega con el código 200 y el campo success igual a true. El resto de los campos dependen del método: { "success": true, "material_id": 2051 } En caso de error, success es false y el campo error contiene una descripción en inglés: { "success": false, "error": "Material not found or access denied" } Código HTTP Cuándo Cuerpo de la respuesta 200 Solicitud ejecutada JSON, success: true 400 Error en los datos de la solicitud: falta un campo obligatorio, un valor no válido, no se encuentra un registro JSON, success: false 401 Falta la Clave API o no es válida Vacío 429 Límite diario de solicitudes alcanzado JSON, success: false 500 Error interno JSON, success: false Si falta un campo obligatorio, el error se ve como «No in input», por ejemplo «No material_id in input». El resto de los errores se enumeran en el artículo de cada método. Límite de solicitudes Una empresa puede enviar hasta 10 000 solicitudes al día. Se cuentan todas las solicitudes con una clave válida, incluidas las que terminan en error. El contador se reinicia una vez al día, por la noche. Al superar el límite, la API responde con el código 429 y el error «Daily connections limit reached». Qué sigue - Reglas generales: edición parcial, paginación, precisión de los números. - Catálogos con los que suele empezar una integración: Categorías, Almacenes, Unidades de medida. - Secciones con métodos: Materiales, Productos, Recursos, Clientes, Ventas, Proveedores, Compras, Producción, Bajas, Traslados, Inventarios físicos. Controlata guarda un registro de las solicitudes a la API. Si una solicitud no funciona como esperas, escribe al soporte e indica el método y la hora de la solicitud.
Reglas generales
Reglas que funcionan igual en todos los métodos de la API. Precisión de los números Las cantidades se guardan con hasta 3 decimales, los importes y los precios hasta el céntimo. La API redondea los valores entrantes igual que la interfaz de Controlata: 0.3333 se guarda como 0.333, y 10.125 como 10.13. La cantidad en las líneas de una operación debe seguir siendo mayor que cero tras el redondeo: 0.0004 se rechaza. Edición Los métodos edit cambian solo los campos que envías. Solo el ID del registro es obligatorio, el resto de los campos conservan sus valores anteriores. - Los array (líneas de la operación, categorías, proveedores, componentes del producto) se reemplazan por completo cuando se envían. Para vaciar un array, envía un array vacío. - Si se envía al menos uno de los array materials y products, las líneas de la operación se reemplazan por completo, y el array que no se envía se considera vacío. Si no se envía ninguno, las líneas no cambian. Por ejemplo, para cambiar solo las notas de una compra, envía purchase_id y notes: las líneas, las fechas, los almacenes y el proveedor se quedan como estaban. Paginación Los métodos get_list aceptan parámetros opcionales de paginación. Excepción: los catálogos pequeños (unidades de medida, categorías y almacenes) siempre se devuelven completos y no aceptan estos parámetros. Campo Tipo Descripción limit int Tamaño de página, de 1 a 1000 offset int Cuántos registros omitir. Se envía junto con limit Sin limit se devuelve toda la lista. La respuesta incluye el campo total con el número total de registros que cumplen los filtros. Error Motivo Invalid limit value. Must be between 1 and 1000 limit no válido Invalid offset value. Must be 0 or greater offset no válido Offset requires limit se envió offset sin limit