mecaractizo — API REST

mecaractizo (también conocido como SisUNQ o CaracTagena) es un sistema de caracterización ciudadana construido con Django + Django REST Framework. Expone una API REST que permite registrar, consultar y validar datos de formularios dinámicos, trámites y certificados.

Backend: Django 5 + DRF · Auth: JWT (SimpleJWT) + Knox · Base URL: /home/

Arquitectura general

El sistema organiza su API en dos grupos principales:

Formularios dinámicos: Estructura de preguntas y respuestas configurable en BD. Los formularios pueden tener habilitada la consulta por API con el flag for_can_api=True.
Trámites: Flujos asociados a formularios que permiten crear registros, consultar estado y ejecutar procedimientos almacenados.

Endpoints disponibles

Grupo	Método	Ruta	Descripción	Auth
Auth	`POST`	`/home/api/token/login`	Obtener par JWT (access + refresh)	No
Auth	`POST`	`/home/api/token/refresh`	Renovar access token con refresh	No
Auth	`POST`	`/home/api/auth/login/`	Login alternativo (Knox token)	No
Auth	`POST`	`/home/api/auth/logout/`	Invalidar token Knox activo	Knox
Auth	`POST`	`/home/api/auth/logoutall/`	Invalidar todas las sesiones Knox	Knox
Formularios	`POST`	`/home/api/getInformacion`	Última acción de un ente en un formulario	JWT
Formularios	`GET`	`/home/api/getInformacionFormulario/<codigo>`	Todos los entes de un formulario (serializado)	No
Formularios	`GET`	`/home/api/getInformacionFormularioHistoria/<codigo>`	Historia de acciones (serializada por pregunta)	No
Formularios	`GET`	`/home/api/v2/getInformacionFormularioHistoria/<codigo>`	Historia V2 (cache de maestros, optimizada)	No
Formularios	`GET`	`/home/api/getInformacionNotSerialized/<codigo>`	Historia sin serializar (datos crudos)	No
Formularios	`GET`	`/home/api/getInformacionTramite/<codigo>`	Todos los registros de un trámite	No
Trámites	`POST`	`/home/api/tramite/<codigo>`	Crear registro en un trámite	No
Trámites	`GET`	`/home/api/tramite/estado/<codigo>`	Buscar registro de trámite por campo	No
Trámites	`POST`	`/home/api/tramite/info/<codigo>`	Preguntas del formulario del trámite	No
Trámites	`GET`	`/home/api/tramite/estado_all/<codigo>`	Buscar en todos los trámites por campo	No
Validación	`GET`	`/home/api/validar/`	Iniciar validación de usuario (envía email)	No
Validación	`POST`	`/home/api/validar/`	Verificar código de validación	No
Certificados	`POST`	`/home/api/listacertificados/`	Registrar y ejecutar un certificado	JWT
Acciones	`POST`	`/home/api/ejecutar/<codigo>`	Ejecutar stored procedure por código	JWT

Conceptos clave

Formulario dinámico (Formulario): Estructura de preguntas configurable en BD. Identificado por for_codigo. El flag for_can_api controla si el formulario es consultable via API pública.
Ente / Entidad (FormularioEntidad): Una entidad registrada en un formulario. Las respuestas se almacenan en fent_informacion (JSONField).
Acción (FormularioAccion): Una acción (edición/registro) sobre un ente en un formulario. Lleva historial de cambios.
Trámite (Tramite): Flujo asociado a un formulario. Los registros del trámite se almacenan en TramiteEntidad.
Maestro (Maestro): Fuente de datos para preguntas de tipo selección. Puede ser tabla BD (TBL) o query SQL (SQL).
Procedimiento (Procedimientos): Stored procedure ejecutado desde la API de acciones.

mecaractizo (also known as SisUNQ or CaracTagena) is a citizen characterization system built with Django + Django REST Framework. It exposes a REST API for registering, querying, and validating data from dynamic forms, procedures, and certificates.

Backend: Django 5 + DRF · Auth: JWT (SimpleJWT) + Knox · Base URL: /home/

General architecture

The system organizes its API into two main groups:

Dynamic forms: Question-and-answer structure configurable in the database. Forms can have API access enabled with the for_can_api=True flag.
Procedures: Flows linked to forms that allow creating records, checking status, and executing stored procedures.

Available endpoints

Group	Method	Path	Description	Auth
Auth	`POST`	`/home/api/token/login`	Obtain JWT pair (access + refresh)	No
Auth	`POST`	`/home/api/token/refresh`	Renew access token with refresh token	No
Auth	`POST`	`/home/api/auth/login/`	Alternative login (Knox token)	No
Auth	`POST`	`/home/api/auth/logout/`	Invalidate active Knox token	Knox
Auth	`POST`	`/home/api/auth/logoutall/`	Invalidate all Knox sessions	Knox
Forms	`POST`	`/home/api/getInformacion`	Last action of an entity in a form	JWT
Forms	`GET`	`/home/api/getInformacionFormulario/<codigo>`	All entities of a form (serialized)	No
Forms	`GET`	`/home/api/getInformacionFormularioHistoria/<codigo>`	Action history (serialized per question)	No
Forms	`GET`	`/home/api/v2/getInformacionFormularioHistoria/<codigo>`	History V2 (master data cache, optimized)	No
Forms	`GET`	`/home/api/getInformacionNotSerialized/<codigo>`	History without serialization (raw data)	No
Forms	`GET`	`/home/api/getInformacionTramite/<codigo>`	All records of a procedure	No
Procedures	`POST`	`/home/api/tramite/<codigo>`	Create a record in a procedure	No
Procedures	`GET`	`/home/api/tramite/estado/<codigo>`	Find procedure record by field	No
Procedures	`POST`	`/home/api/tramite/info/<codigo>`	Questions of the procedure's form	No
Procedures	`GET`	`/home/api/tramite/estado_all/<codigo>`	Search across all procedures by field	No
Validation	`GET`	`/home/api/validar/`	Start user validation (sends email)	No
Validation	`POST`	`/home/api/validar/`	Verify validation code	No
Certificates	`POST`	`/home/api/listacertificados/`	Register and execute a certificate	JWT
Actions	`POST`	`/home/api/ejecutar/<codigo>`	Execute stored procedure by code	JWT

Key concepts

Dynamic form (Formulario): Question structure configurable in the database, identified by for_codigo. The for_can_api flag controls whether the form can be queried via public API.
Entity (FormularioEntidad): An entity registered in a form. Answers are stored in fent_informacion (JSONField).
Action (FormularioAccion): A recorded action (edit/register) on an entity. Maintains change history.
Procedure (Tramite): A flow linked to a form. Records are stored in TramiteEntidad.
Master data (Maestro): Data source for selection-type questions. Can be a database table (TBL) or SQL query (SQL).
Stored procedure (Procedimientos): Stored procedure executed via the actions API.