Sytex API Documentation

Sytex API Documentation

La API de Sytex es una interfaz HTTP que permite realizar operaciones de lectura y manipulación de datos.

Para su utilización será necesario consultar un Token, el Dominio y el número de Organización.

Documentación de endpoints



Locked with Key Autenticación

Para realizar un request a la API, es necesaria la autenticación mediante un Token.
Cada request debe tener la cabecera "Authorization", cuyo valor será la palabra “Token” seguida de una key válida (separada por un espacio).
Ejemplo:
Authorization
Token a87eb729487427d497250dd7d62692xbcc8e65op
El Token está asociado a un usuario de Sytex y los permisos de ese usuario son los que determinan el nivel de acceso a los distintos endpoints.

Métodos soportados

Los recursos siguen el patron REST usual:
  • POST: crear un recurso nuevo.
  • PUT: modificar un recurso existente.
  • GET: consultar información de un recurso.
  • DELETE: eliminar un recurso determinado.
  • PATCH: modificar solamente un atributo de un recurso.

Requests & responses

Tanto los requests como los responses están en formato JSON. Los requests deberán incluir los headers requeridos:
http
Authorization: Token <token>
Organization: <organization_id>
Accept: application/json
Content-Type: application/json
Ejemplo base:
sh
curl \
  -H "Authorization: Token $SYTEX_TOKEN" \
  -H "Organization: 999"
  "https://app.sytex.io/api/user/?limit=20"
Parámetros comunes:
`limit`: cantidad de resultados.
`offset`: desplazamiento de paginacion.
`q`: busqueda textual, cuando el endpoint la soporta.
`ordering`: ordenamiento, cuando el endpoint lo soport

Respuestas y códigos de error

Las API de Sytex utilizan códigos HTTP estándar para informar estados de resolución de los requests.
200
OK. Ejecución satisfactoria, el cuerpo de la respuesta contendrá el contenido requerido.
400
Error de validación. El contenido de la respuesta contendrá un detalle por cada campo con el error de validación. Si el error no está referido a un campo en particular, estará presente en el atributo "non_field_errors" del objeto JSON de la respuesta. Cada atributo del cuerpo de la respuesta corresponde con el campo que generó el error de validación, cada campo tendrá una lista de errores asociados.
401
Sin autenticación. No se envió información de autenticación en la cabecera o el token se encuentra vencido.
403
Prohibido. El usuario vinculado al request no tiene permisos suficientes para realizarlo.
404
No encontrado. La URL requerida no existe en el esquema de la aplicación o el id del objeto requerido no existe.
500
Error en la aplicación.

Organización

Todos los requests deben contener un header con el número de Organización.El formato es simplemente un header llamado “Organization” y su valor es un número entero. Consultar cuál es el número. Ejemplo: Organization: 658

Buenas practicas

  • Usar siempre el header Organization; el mismo token puede acceder a varias organizaciones.
  • Preferir IDs para escrituras y codigos para busquedas humanas.
  • Validar primero con GET antes de ejecutar PATCH, POST o imports.
  • Consultar GET /api/import/<ImportName>/get_config/ antes de usar importadores.
  • No asumir que todos los estados permiten edicion: formularios enviados/aprobados y operaciones cerradas pueden rechazar cambios.
  • Verificar la respuesta del PATCH o POST y volver a consultar el objeto para confirmar el cambio.
  • Para cargas masivas, probar primero con pocos registros y guardar el resultado del importador.
  • No compartir tokens en tickets, capturas o documentacion.

Bug Errores comunes

  • Falta de header Organization: la API puede no resolver permisos o contexto.
  • Permisos insuficientes: el usuario autenticado debe tener permisos sobre el recurso y la organizacion.
  • IDs de otra organizacion: los IDs deben pertenecer a la organizacion enviada en el header.
  • Estado no editable: algunos objetos bloquean cambios por estado.
  • Campos con relaciones genericas: source_location y destination_location pueden requerir tipo de ubicacion ademas del identificador.
  • Respuestas de formularios inexistentes: si se actualiza por importador, debe existir la combinacion form + index.