Esta guía es para el proveedor de software que integra la aplicación de un cliente con su ERP a través de SmartQuery. Da por hecho que el cliente ya tiene su instancia desplegada y le entregó a usted una API key con su alcance.
Última actualización
/api/v1/proxy/execute/{connection_slug}/{endpoint_slug}Todo el catálogo se invoca por aquí. El verbo lo define el endpoint almacenado: si no coincide con el suyo, la respuesta es 405.
La credencial del integrador es una API key en su propio encabezado, no un token Bearer. Es la única credencial con la que se integra contra esta ruta.
X-API-KEYAPI key con prefijo sk_AtenciónAnte una credencial ausente o inválida el 401 dice «Authentication required», no «llave inválida». No lo interprete como que la llave existe y está mal: trate cualquier 401 como falta de credencial válida.
| Encabezado | Obligatorio | Comportamiento |
|---|---|---|
X-API-KEY | Sí | Credencial del integrador, con prefijo sk_. Determina qué conexiones y qué endpoints puede ejecutar. |
Idempotency-Key | Condicional | Solo en operaciones REST que lo declaran, y solo en POST. Obligatorio si la operación lo declara; rechazado con 400 si no. Cadena alfanumérica corta. En endpoints SQL y de blueprint no tiene efecto. |
Content-Type | No | Envíe application/json en POST y PUT. |
Retry-After | Respuesta | Puede venir en respuestas de error. Respete el valor antes de reintentar. |
Usted nunca envía SQL. Llama a un endpoint publicado por su slug, y lo que ese endpoint puede hacer quedó fijado cuando se publicó, no por su petición.
¿Qué puede hacer un endpoint de consulta sobre su ERP?
Incluye el trabajo intermedio que un informe necesita: tablas temporales (#t), variables de tabla (@t) y varias sentencias.
Sin excepción de verbo, de parámetro ni de perfil. La ejecución se detiene antes de salir hacia el ERP.
Por eso un endpoint de consulta admite el script completo que un informe necesita, con SET NOCOUNT ON, DECLARE, CTE y varias sentencias, sin dejar de ser de solo lectura.
Sus parámetros son valores, nunca SQL. Un parámetro que intente alterar la sentencia publicada se rechaza con HTTP 400 antes de ejecutar, y las construcciones administrativas, de SQL dinámico, de sistema de archivos y entre servidores se rechazan en todo endpoint, sin excepción de perfil.
Usted no escribe SQL de registro. La escritura ya está resuelta: se escoge el blueprint o la operación del conector que corresponde, se le fijan las variables y los valores constantes, y eso genera el endpoint POST con el que su aplicación registra en el ERP.
El formato que exige el ERP, declarado una sola vez al publicar el endpoint. Usted envía JSON y recibe la envolvente única, con el origen del rechazo identificado cuando lo hay.
Es la única envolvente donde el origen de un rechazo es legible por máquina.
La operación REST del proveedor ya declarada y publicada como endpoint suyo. Sin SQL de por medio.
El cuerpo del proveedor se devuelve tal cual bajo data.
Lea esto primeroPara una llamada con X-API-KEY el cuerpo raíz es exactamente {"data": …} — una sola clave. No hay success, ni meta, ni source, ni tiempo de ejecución en la raíz. Equivocarse aquí rompe la integración el primer día.
{"data":{"codigo":200,"mensaje":"Success","data":[
{"codigo":"1","descripcion":"ACTIVO","nivel":1},
{"codigo":"11","descripcion":"DISPONIBLE","nivel":2}
]}}Las claves dentro de cada fila salen en orden alfabético, no en el orden de columnas del SELECT.
{"data":{"codigo":204,"mensaje":"No content / No se encontraron registros","data":[]}}En la ruta de éxito, codigo NO es el estado HTTP. Un codigo 204 llega dentro de un HTTP 200.
{"data":{"codigo":200,"mensaje":"OK","data":{"results":[
{"id":"123","name":"ACME S.A.S."}
]}}}Aquí codigo sí es el estado HTTP crudo del proveedor, y data es su cuerpo tal cual.
{"data":{"success":true,"statusCode":200,"code":"0",
"message":"The file was imported successfully.",
"details":[],
"source":{"system":"SIESA","operation":"Importar"}}}code es siempre una cadena, nunca un número. details nunca es null: como mínimo es [].
Saber de dónde viene una falla es la pregunta más cara de una integración. Esta es la respuesta honesta, hoy:
Legible por máquina — solo la envolvente de importación: data.source.system vale "SMARTQUERY" o "SIESA".
No determinable — en endpoints SQL y REST no hay campo de origen. El 500 comodín colapsa un fallo del ERP y uno de la pasarela en el mismo cuerpo.
{"error":"Variables faltantes en el payload","faltantes":["nit","fecha_inicio"]}La clave faltantes está en español y no se traduce.
{"success":false,"error":"Authentication required",
"message":"Please provide either X-API-KEY header or Authorization: Bearer <token> header"}Su forma es distinta a la de los demás errores de esta página: parséelo aparte.
{"error":"access denied to this connection"}Mensajes hermanos: «connection is not active», «endpoint is disabled for this connection», «no tienes acceso a esta consulta».
{"success":false,"message":"Method not allowed for this query","error":"method not allowed for this query"}Cada endpoint declara su verbo al publicarse; usar otro devuelve 405.
{"data":{"success":false,"statusCode":422,"code":"1",
"message":"The file could not be imported because it contains validation errors.",
"details":[{"linea":"3",
"detalle":"El grupo entidad no está autorizado para moverse por: [Documento]"}],
"source":{"system":"SIESA","operation":"Importar"}}}details[] trae una entrada por registro rechazado, con el motivo tal como lo redactó el ERP. Muéstrelo a su usuario: es la única descripción fiel del rechazo.
{"data":{"success":false,"statusCode":422,"code":"FIELD_VALIDATION",
"message":"validacion fallida: la variable 'NIT' en la linea 'Documento contable' es obligatoria y no puede estar vacia",
"details":[],
"source":{"system":"SMARTQUERY","operation":"Importar"}}}Mismo estado que el anterior, origen distinto. Es exactamente por esto que source.system existe.
{"data":{"codigo":502,"mensaje":"Siigo rechazó las credenciales de la conexión",
"data":null,
"errors":[{"code":"unauthorized","message":"token invalido"}]}}errors[] solo aparece en endpoints REST. Se descarta en las respuestas de SIESA. Los 429 y 503 llegan con Retry-After.
{"error":"Error procesando la solicitud en el ERP"}El texto dice ERP, pero este error es el comodín para cualquier falla sin clasificar. No lo interprete como origen del ERP.
¿Algo no coincide con lo que está viendo? Escríbanos y lo corregimos aquí.