API Reference — Endpoints
API Reference — Endpoints
Referencia de los endpoints de API (clases APIView y ModelViewSet DRF) expuestos por SIUD. Las vistas web de Django (formularios, dashboards, navegación) no están incluidas.
Authorization: Bearer <token> salvo que se indique lo contrario. Ver Autenticación para obtener tokens.
JWT — /api/token/
| Método | Endpoint | Auth | Clase | Descripción |
|---|---|---|---|---|
POST | /api/token/ | Ninguna | UserLoginView | Obtener access + refresh tokens |
POST | /api/token/refresh/ | Ninguna | SimpleJWT | Renovar access token con refresh |
POST /api/token/
Content-Type: application/json
{"username": "usuario", "password": "contraseña"}import requests
resp = requests.post(
"https://TU-DOMINIO/api/token/",
json={"username": "usuario", "password": "contraseña"}
)
access = resp.json()["token"]["access"]
refresh = resp.json()["token"]["refresh"]const { data } = await axios.post(
'https://TU-DOMINIO/api/token/',
{ username: 'usuario', password: 'contraseña' }
);
const { access, refresh } = data.token;var body = new StringContent(
JsonSerializer.Serialize(new { username = "usuario", password = "contraseña" }),
Encoding.UTF8, "application/json"
);
var response = await client.PostAsync("https://TU-DOMINIO/api/token/", body);HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://TU-DOMINIO/api/token/"))
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(
"{\"username\":\"usuario\",\"password\":\"contraseña\"}"
))
.build();Response 200:
{"token": {"access": "eyJ...", "refresh": "eyJ..."}, "msg": "Login success"}Response 404: {"errors": {"non_fields_errors": ["User or Password is not Valid"]}}
EjecutarAccion — POST /api/ejecutar/<codigo>
Ejecuta un stored procedure registrado en PROCEDIMIENTO_P. El cuerpo JSON se serializa y pasa como parámetro JSON_FILTROS. Requiere sesión activa (no JWT).
| Propiedad | Valor |
|---|---|
| Método | POST |
| Ruta | /api/ejecutar/<codigo> |
| Auth | Sesión Django (IsAuthenticated) |
| Clase | EjecutarAccion |
Response 200:
{"EsCorrecto": true, "resultado": { ... }, "mensaje": "Acción ejecutada con éxito"}Response 400/404: texto plano con el error.
EjecutarAccionToken — GET /api/ejecutar-token/<codigo>
Ejecuta un SP vía token UUID (modelo APIToken_P), sin requerir sesión Django. Diseñado para clientes externos como PowerBI. El token puede ir en el header Authorization: Bearer <uuid> o en el query param ?token=<uuid>. Rate limit: 30 req/min por IP.
| Propiedad | Valor |
|---|---|
| Método | GET |
| Ruta | /api/ejecutar-token/<codigo> |
| Auth | UUID Token (AllowAny + validación propia) |
| Clase | EjecutarAccionToken |
| Parámetro | Ubicación | Descripción |
|---|---|---|
Authorization: Bearer <uuid> | Header | Token UUID de APIToken_P (preferido) |
token=<uuid> | Query | Alternativa al header (ej. PowerBI) |
| otros params | Query | Se pasan como JSON_FILTROS al SP |
GET /api/ejecutar-token/BUSCAR_EMPLEADO?identificacion=12345678
Authorization: Bearer <uuid-token>import requests
resp = requests.get(
"https://TU-DOMINIO/api/ejecutar-token/BUSCAR_EMPLEADO",
headers={"Authorization": f"Bearer {api_token_uuid}"},
params={"identificacion": "12345678"}
)
data = resp.json() # {"EsCorrecto": true, "resultado": [...]}const { data } = await axios.get(
'https://TU-DOMINIO/api/ejecutar-token/BUSCAR_EMPLEADO',
{
params: { identificacion: '12345678' },
headers: { 'Authorization': `Bearer ${apiTokenUuid}` }
}
);client.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", apiTokenUuid);
var response = await client.GetAsync(
"https://TU-DOMINIO/api/ejecutar-token/BUSCAR_EMPLEADO?identificacion=12345678");
var json = await response.Content.ReadAsStringAsync();HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(
"https://TU-DOMINIO/api/ejecutar-token/BUSCAR_EMPLEADO?identificacion=12345678"))
.header("Authorization", "Bearer " + apiTokenUuid)
.GET()
.build();Response 200:
{"EsCorrecto": true, "resultado": [{"nombre": "Juan García", ...}]}Response 401: {"error": "Token requerido."} / {"error": "Token inválido."}
Response 403: {"error": "Acción no permitida para este token."}
Response 429: {"error": "Demasiadas solicitudes. Intente más tarde."}
ImprimirPDFView — POST /api/imprimir/
Recibe HTML y lo convierte a PDF. Usado por el frontend para generar documentos descargables.
| Propiedad | Valor |
|---|---|
| Método | POST |
| Ruta | /api/imprimir/ |
| Auth | JWT o Sesión (IsAuthenticated) |
| Clase | ImprimirPDFView |
Body JSON: {"html": "<html>...</html>"}. Retorna el PDF como application/pdf.
ViewSets CRUD — Home base: /
Router DRF estándar. Todos requieren JWT o sesión (IsAuthenticated). Soportan GET (list/retrieve), POST, PUT, PATCH, DELETE.
| Recurso | URL base | Modelo |
|---|---|---|
| Usuarios | /usuario/ | USUARIO_P |
| Módulos | /modulo/ | MODULO_P |
| Menús | /menu/ | MENU_P |
| Vigencias | /vigencia/ | VIGENCIA_P |
| Menú-Usuario | /fmenu/ | MENU_F |
ViewSets CRUD — Global base: /global/
Mismos métodos CRUD que los ViewSets de Home. Datos maestros del sistema.
| Recurso | URL base | Modelo |
|---|---|---|
| Consecutivos | /global/Consecutivo/ | FCONSECUTIVO_P |
| Barrios | /global/barrio/ | PBARRIO_P |
| CIIU | /global/CIIU/ | PCIIU_P |
| Dependencias | /global/dependencia/ | PDEPENDENCIA_P |
| Informes | /global/informe/ | PINFORME_P |
| Localidades | /global/localidad/ | PLOCALIDAD_P |
| Tipos de ID | /global/tipoidentificacion/ | PTIPOIDENTIFICACION_P |
| Unidades comuneras | /global/unidadcomunera/ | PUNIDADCOMUNERA_P |
GenerarCertificadoAPIView — POST /api-siud/documentos/generar/
Genera y descarga un documento firmado a partir de un código de certificado y una llave de instancia. Requiere JWT.
| Propiedad | Valor |
|---|---|
| Método | POST |
| Ruta | /api-siud/documentos/generar/ |
| Auth | JWT (IsAuthenticated) |
| Body | {"codigo": "CERT_RESIDENCIA", "llave": "<uuid>"} |
Workflow — APIs de instancia
Todos los endpoints de workflow usan base /workflow/ y requieren sesión o JWT (IsAuthenticated) salvo reconciliar-bpm que usa header propio.
Tareas y acciones
| Método | Endpoint | Clase | Descripción |
|---|---|---|---|
POST | /workflow/api/ejecutar-accion/ | EjecutarAccionAPIView | Ejecutar SP desde formulario BPM; opcionalmente avanza estado |
POST | /workflow/api/tomar-tarea/ | TomarTareaAPIView | Tomar tarea del pool (select_for_update, libre de race condition) |
POST | /workflow/api/pool-status/ | PoolStatusAPIView | Consultar qué IDs del pool ya fueron tomados |
POST | /workflow/api/soportes-visibles/ | SoportesVisiblesAPIView | Soportes visibles de una tarea evaluando condiciones de contexto |
sp_code (requerido), instf_llave (UUID del F record), jsonfiltros (objeto JSON para el SP), bpm_accion (opcional — código de acción para avanzar el proceso).
Soportes y documentos
| Método | Endpoint | Clase | Descripción |
|---|---|---|---|
POST | /workflow/api/soportes/crear/ | WorkflowCrearSoporteAPIView | Crear soporte (requiere IsWorkflowDesigner) |
Builder de procesos (Admin)
Todos requieren permiso IsWorkflowDesigner.
| Método | Endpoint | Clase | Descripción |
|---|---|---|---|
GET | /workflow/api/catalogos/ | WorkflowCatalogosAPIView | Formularios, menús y SPs disponibles para el builder |
GET | /workflow/api/procesos/<llave>/tareas/<codigo>/detalle/ | TareaDetalleAPIView | Detalle técnico de una tarea |
POST | /workflow/api/procesos/<llave>/staging/guardar/ | StagingGuardarAPIView | Guardar cambios en staging sin afectar producción |
GET | /workflow/api/procesos/<llave>/refrescar/ | RefrescarProcesoAPIView | Recargar estado del proceso desde BD |
POST | /workflow/api/procesos/<llave>/publicar/ | PublishProcesoAPIView | Promover staging a versión activa |
Formularios dinámicos
| Método | Endpoint | Clase | Descripción |
|---|---|---|---|
POST | /workflow/api/formularios/<codigo>/guardar/ | FormularioSaveAPIView | Guardar JSON Schema del formulario dinámico |
GET | /workflow/api/formularios/<codigo>/preview/ | FormularioPreviewAPIView | Vista previa del formulario |
Webhook de reconciliación
| Método | Endpoint | Auth | Descripción |
|---|---|---|---|
POST | /workflow/api/reconciliar-bpm/ | Header X-Reconcile-Token | Reconciliar estado de instancia desde sistema externo |
Ver Workflow / BPM para el ejemplo de código completo.
Reference of API endpoints (DRF APIView and ModelViewSet classes) exposed by SIUD. Django web views (forms, dashboards, navigation) are not included.
Authorization: Bearer <token> header unless noted otherwise. See Authentication to obtain tokens.
JWT — /api/token/
| Method | Endpoint | Auth | Class | Description |
|---|---|---|---|---|
POST | /api/token/ | None | UserLoginView | Obtain access + refresh tokens |
POST | /api/token/refresh/ | None | SimpleJWT | Renew access token with refresh |
EjecutarAccion — POST /api/ejecutar/<codigo>
Executes a stored procedure registered in PROCEDIMIENTO_P. The JSON body is serialized and passed as the JSON_FILTROS parameter. Requires an active session (not JWT).
| Property | Value |
|---|---|
| Method | POST |
| Path | /api/ejecutar/<codigo> |
| Auth | Django Session (IsAuthenticated) |
| Class | EjecutarAccion |
Response 200: {"EsCorrecto": true, "resultado": {...}, "mensaje": "..."}
EjecutarAccionToken — GET /api/ejecutar-token/<codigo>
Executes a SP via UUID token (APIToken_P model), without requiring a Django session. Designed for external clients like PowerBI. Token can be sent in Authorization: Bearer <uuid> header or ?token=<uuid> query param. Rate limit: 30 req/min per IP.
| Property | Value |
|---|---|
| Method | GET |
| Path | /api/ejecutar-token/<codigo> |
| Auth | UUID Token (AllowAny + custom validation) |
| Class | EjecutarAccionToken |
GET /api/ejecutar-token/SEARCH_EMPLOYEE?identificacion=12345678
Authorization: Bearer <uuid-token>import requests
resp = requests.get(
"https://YOUR-DOMAIN/api/ejecutar-token/SEARCH_EMPLOYEE",
headers={"Authorization": f"Bearer {api_token_uuid}"},
params={"identificacion": "12345678"}
)
data = resp.json()const { data } = await axios.get(
'https://YOUR-DOMAIN/api/ejecutar-token/SEARCH_EMPLOYEE',
{
params: { identificacion: '12345678' },
headers: { 'Authorization': `Bearer ${apiTokenUuid}` }
}
);client.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", apiTokenUuid);
var response = await client.GetAsync(
"https://YOUR-DOMAIN/api/ejecutar-token/SEARCH_EMPLOYEE?identificacion=12345678");
var json = await response.Content.ReadAsStringAsync();HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(
"https://YOUR-DOMAIN/api/ejecutar-token/SEARCH_EMPLOYEE?identificacion=12345678"))
.header("Authorization", "Bearer " + apiTokenUuid)
.GET()
.build();Response 200: {"EsCorrecto": true, "resultado": [...]}
ImprimirPDFView — POST /api/imprimir/
Receives HTML and converts it to PDF. Returns application/pdf.
CRUD ViewSets — Home
| Resource | Base URL | Model |
|---|---|---|
| Users | /usuario/ | USUARIO_P |
| Modules | /modulo/ | MODULO_P |
| Menus | /menu/ | MENU_P |
| Terms | /vigencia/ | VIGENCIA_P |
| Menu-User | /fmenu/ | MENU_F |
CRUD ViewSets — Global base: /global/
| Resource | Base URL | Model |
|---|---|---|
| Sequences | /global/Consecutivo/ | FCONSECUTIVO_P |
| Neighborhoods | /global/barrio/ | PBARRIO_P |
| CIIU | /global/CIIU/ | PCIIU_P |
| Departments | /global/dependencia/ | PDEPENDENCIA_P |
| Reports | /global/informe/ | PINFORME_P |
| Localities | /global/localidad/ | PLOCALIDAD_P |
| ID Types | /global/tipoidentificacion/ | PTIPOIDENTIFICACION_P |
| Communal units | /global/unidadcomunera/ | PUNIDADCOMUNERA_P |
GenerarCertificadoAPIView — POST /api-siud/documentos/generar/
Generates and downloads a signed document from a certificate code and instance key. Requires JWT.
Body: {"codigo": "CERT_RESIDENCIA", "llave": "<uuid>"}
Workflow APIs
All workflow endpoints use base /workflow/ and require session or JWT (IsAuthenticated) except reconciliar-bpm which uses its own header.
Tasks & actions
| Method | Endpoint | Class | Description |
|---|---|---|---|
POST | /workflow/api/ejecutar-accion/ | EjecutarAccionAPIView | Execute SP from BPM form; optionally advance state |
POST | /workflow/api/tomar-tarea/ | TomarTareaAPIView | Take task from pool (race-condition safe) |
POST | /workflow/api/pool-status/ | PoolStatusAPIView | Check which pool IDs have already been taken |
POST | /workflow/api/soportes-visibles/ | SoportesVisiblesAPIView | Visible supports for a task evaluating context conditions |
Process builder (Admin)
All require IsWorkflowDesigner permission.
| Method | Endpoint | Class | Description |
|---|---|---|---|
GET | /workflow/api/catalogos/ | WorkflowCatalogosAPIView | Forms, menus and SPs available for the builder |
POST | /workflow/api/soportes/crear/ | WorkflowCrearSoporteAPIView | Create support document type |
GET | /workflow/api/procesos/<llave>/tareas/<codigo>/detalle/ | TareaDetalleAPIView | Technical detail of a task |
POST | /workflow/api/procesos/<llave>/staging/guardar/ | StagingGuardarAPIView | Save changes to staging |
GET | /workflow/api/procesos/<llave>/refrescar/ | RefrescarProcesoAPIView | Reload process state from DB |
POST | /workflow/api/procesos/<llave>/publicar/ | PublishProcesoAPIView | Promote staging to active version |
Dynamic forms
| Method | Endpoint | Class | Description |
|---|---|---|---|
POST | /workflow/api/formularios/<codigo>/guardar/ | FormularioSaveAPIView | Save dynamic form JSON Schema |
GET | /workflow/api/formularios/<codigo>/preview/ | FormularioPreviewAPIView | Preview the form |
Reconciliation webhook
| Method | Endpoint | Auth | Description |
|---|---|---|---|
POST | /workflow/api/reconciliar-bpm/ | X-Reconcile-Token header | Reconcile instance state from external system |
See Workflow / BPM for the full code example.