API del Web Service STE
De Egeasy
Tipos
Basicos
TGArrayInteger = array of integer;
TGWSSerializedDateTime = String;
TGWSIdentifier = String;
TGSignature = TByteDynArray; Array de bytes usado para enviar datos binarios (ficheros, firmas, etc.).
Errores
TGWSErrorCode = Integer;
TGWSFieldError = class property FieldDefinitionPath: String; property ErrorMessage: String; Descripción de error en un campo. Indica el campo afectado y el error correspondiente.
TGWSArrayFieldError = array of TGWSFieldError;
TGWSError = class property ErrorCode: TGWSErrorCode; property ErrorMessage: String; Error general.
TGWSErrorValidateTask = class(TGWSError) property FieldErrors: TGWSArrayFieldError; Error en la validación o envío de una tarea. Detalla los errores de los campos.
Procedimentos (definiciones)
TGWSFieldType = (ftDummy, ftBoolean, ftInteger, ftReal, ftString, ftMemo, ftDatetime, ftCurrency, ftTable); Tipos de campo.
TGWSFieldDefinition = class property Identifier: TGWSIdentifier; property LabelField: String; property FieldType: TGWSFieldType; property Section: String; property Visible: Boolean; property Editable: Boolean; property Required: Boolean; property FieldDefinitions: TGWSListFieldDefinition; Definición de campo. Si es un campo tabla, incluye las definiciones de las columnas.
TGWSArrayFieldDefinition = array of TGWSFieldDefinition;
TGWSListFieldDefinition = class property FieldDefinitions: TGWSArrayFieldDefinition;
TGWSTaskType = (ttStart, ttSendDocumentation, ttRequirement, ttNotification, ttResponse); Tipos de tarea. Todo proceso ha de tener al menos una tarea de inicio (ttStart). Las tareas de envío de documentación (ttSendDocumentation) permiten añadir documentación a un trámite en cualquier momento. Las tareas de requerimiento se usan para solicitar la participación del interesado en algún momento del trámite, requiriendole para que aporte más documentación a un trámite, por medio de una tarea de respuesta (ttResponse). Las tareas de notificación sirven para informar al interesado de cualquier incidencia en el trámite. Se debe acusar recibo de este tipo de tareas para poder consultar el trámite.
TGWSTaskDefinition = class property Identifier: TGWSIdentifier; property NameTask: String; property LabelTask: String; property Description: String; property TaskType: TGWSTaskType; property FieldDefinitions: TGWSListFieldDefinition; Definición de tarea. Incluye las definiciones de campo.
TGWSArrayTaskDefinition = array of TGWSTaskDefinition;
TGWSRefProcedure = class property Identifier: TGWSIdentifier property NameProcedure: String property Description: String; property Group: String; Descripción abreviada del procedimento, que se usa obtener los datos fundamentales de un procedimento al cargar listados.
TGWSArrayRefProcedure = array of TGWSRefProcedure;
TGWSListRefProcedure = class property RefProcedures: TGWSArrayRefProcedure;
TGWSProcedure = class(TGWSRefProcedure) property TaskDefinitions: TGWSArrayTaskDefinition; Descripción completa del procedimiento.
Trámites
TGWSProcessStatus = (psCreated, psStarted, psFinished, psArchived, psDeleted, psAll); Estados en los que se puede encontrar un trámite.
TGWSArrayProcessStatus = array of TGWSProcessStatus;
TGWSRefProcess = class property Identifier: TGWSIdentifier; property RefProcedure: TGWSRefProcedure; property LabelProcess: String; property Status: TGWSProcessStatus; property CreateDate: TGWSSerializedDateTime; property StartDate: TGWSSerializedDateTime; property EndDate: TGWSSerializedDateTime; property TramitationStatus: String; property TaskCount: Integer; property LastTaskName: String; property LastTaskDate: TGWSSerializedDateTime; property HasPendingTasks: Boolean read; Descripción abreviada de un trámite, usada para obtener los datos fundamentales de un trámite en listados.
TGWSArrayRefProcess = array of TGWSRefProcess;
TGWSListRefProcess = class property RefProcesses: TGWSArrayRefProcess;
TGWSProcess = class(TGWSRefProcess) property Tasks: TGWSArrayTasks read FTasks write FTasks; Datos completos del trámite, incluyendo las tareas que forman parte del mismo.
TGWSSearchProcessArg = class property Status: TGWSArrayProcessStatus; property Condition: String; Parámetros de búsqueda usados para indicar los criterios de búsqueda de trámites.
Tareas
TGWSTaskStatus = (wsTaskCreated, wsTaskSended, wsTaskReceived, wsTaskResponsed); Estados en los que se puede encontrar una tarea.
TGWSTask = class property Identifier: TGWSIdentifier; property DefinitionId: TGWSIdentifier; property Status: TGWSTaskStatus; property CreateOrReceiveDate: TGWSSerializedDateTime; property SendOrResponseDate: TGWSSerializedDateTime; property Files: TGWSArrayRefFiles; property FieldValues: TGWSArrayFieldValue; property FieldAllowedValues: TGWSListFieldAllowedValues; property Signature: TGSignature; Datos de una tarea. Incluye la información de los campos y los archivos adjuntos, así como la firma digital de la tarea.
TGWSArrayTasks = array of TGWSTask;
Campos
TGWSArrayValues = array of String;
TGWSFieldAllowedValues = class property DefinitionId: TGWSIdentifier; property AllowedValues: TGWSArrayValues; Listado de valores permitidos para un campo.
TGWSArrayFieldAllowedValues = array of TGWSFieldAllowedValues;
TGWSListFieldAllowedValues = class property FieldAllowedValues: TGWSArrayFieldAllowedValues;
TGWSFieldValue = class property DefinitionId: TGWSIdentifier; property FieldType: TGWSFieldType; property Value: String read FValue write FValue; property RowsAllowedValues: TGWSListFieldAllowedValues; property Rows: TGWSArrayRows; Campo. Para facilitar la operación con este tipo, se ha añadido el atributo “tipo”, que también está disponible en la definición de campo. Si el campo es de tipo tabla, incluye la información de las filas de la tabla.
TGWSArrayFieldValue = array of TGWSFieldValue;
TGWSRow = class property FieldValues: TGWSArrayFieldValue; Fila de campos tabla.
TGWSArrayRows = array of TGWSRow;
Ficheros
TGWSRefFile = class property Identifier: TGWSIdentifier; property NameFile: String; property AttachDate: TGWSSerializedDateTime; Datos de un fichero adjunto a una tarea.
TGWSArrayRefFiles = array of TGWSRefFile;
TGWSFile = class(TGWSRefFile) property Content: TByteDynArray; Contenido completo de un fichero adjunto a una tarea.
Notificaciones
TGWSNotification = class property Identifier: String read FIdentifier write FIdentifier; property Name: String read FName write FName; Notificación pendiente en un trámite. Incluye el identificador de la tarea de notificación que está pendiente de acusar recibo y un nombre descriptivo para mostrar al usuario.
TGWSArrayNotifications = array of TGWSNotification;
TGWSListNotifications = class(TRemotable) property Notifications: TGWSArrayNotifications read FNotifications write FNotifications;
Usuarios
TGWSRegistrationForm = class property FieldDefinitions: TGWSArrayFieldDefinition; property FieldValues: TGWSArrayFieldValue; property FieldAllowedValues: TGWSListFieldAllowedValues; Formulario de registro de un usuario. Incluye solo los campos adicionales. Los campos obligatorios (nombre, nombre completo, nif, correo electrónico), no están incluidos en el formulario. La definición de los campos de registro se describe en un fichero XML.
TGWSRefUser = class property Identifier: TGWSIdentifier; property UserName: String; property FullName: String; property Nif: String; property EMail: String; property IdOrganization; Datos básicos de un usuario, se usa para listados de usuario.
TGWSArrayRefUsers = array of TGWSRefUser;
TGWSListRefUsers = class property RefUsers: TGWSArrayRefUsers;
TGWSUser = class(TGWSRefUser) property RegistrationForm: TGWSRegistrationForm; Datos completos de un usuario, incluyendo los datos del formulario de registro.
TGWSSearchUsersArg = class property Condition: STring;
Organizaciones
TGWSOrganization = class property Identifier: TGWSIdentifier; property Name: String read; Datos de una organización. La organización permite agrupar los usuarios, de forma que los todos los usuarios individuales que pertenezcan a una organización tienen acceso a todos los trámites que haya iniciado cualquier miembro de la organización.
TGWSArrayOrganizations = array of TGWSOrganization;
TGWSListOrganizations = class property Organizations: TGWSArrayOrganizations;
API de usuario
Sesiones
CreateSession(IdUnit: TGWSIdentifier; out Data: TGWSIdentifier; out Error: TGWSError)
Crear una sesión con el WS que será utilizada en el resto de operaciones.
Parámetros:
IdUnit: Identificador del usuario o centro gestor que inicia sesión.
Data: Identificador de la sesión.
Error: Código y mensaje de error.
Detalles:
Es el punto de entrada al servicio. Es necesario crear una sesión para poder realizar el resto de operaciones.
StartSession(IdSession: TGWSIdentifier; Signature: TGSignature; out Data: TGWSRefUser; out Error: TGWSError)
Activa una sesión, comprobando la identidad del usuario.
Parámetros:
IdSession: Identificador de la sesión.
Signature: Firma digital de la sesión realizada con un certificado de usuario válido.
Data: Datos básicos del usuario que inició sesión.
Error: Código y mensaje de error.
Detalles:
Se tiene que haber creado una sesión previamente. El identificador de sesión debe firmarse con un certificado válido de la FNMT o DNIe.
El DNI del usuario registrado debe coincidir con el almacenado en el certificado.
CloseSession(IdSession: TGWSIdentifier; out Error: TGWSError)
Cierra la sesión.
Parámetros:
IdSession: Identificador de la sesión.
Error: Código y mensaje de error.
Usuarios
RegisterAllowed(out Data: Boolean; out Error: TGWSError)
Indica si el resgistro libre de nuevos usuarios está disponible.
Parámetros:
Data: Verdadero si está permitido el registro libre de usuarios.
Error: Código y mensaje de error.
LoadRegisterForm(out Data: TGWSRegistrationForm; out Error: TGWSError)
Permite obtener el formulario de registro de usuarios.
Parámetros:
Data: Formulario de registro de usuarios.
Error: Código y mensaje de error.
Destalles:
El formulario de registro contiene los campos adicionales a los 4 campos obligatorios que son “nombre”, “nombre completo”,
“nif” y “correo electrónico”.
RegisterUser(const UserName: String; const FullName: String; const NIF: String; const EMail: String; RegistrationData: TGWSRegistrationForm;
out Data: TGWSUser; out Error: TGWSError)
Registra un nuevo usuario para que pueda usar el servicio de tramitación.
Parámetros:
UserName: Nombre de usuario que se usará para iniciar sesión.
FullName: Nombre completo del usuario.
NIF: Número de identificación del usuario.
Email: Dirección de correo electrónico del usuario.
RegistrationData: Formulario de registro relleno con los valores del usuario.
Data: Datos del usuario creado.
Error: Código y mensaje de error.
Detalles:
Los campos “UserName”, “FullName”, “NIF” y “Email” son obligatorios. El formulario de registro se puede obtener llamando a la
función “LoadRegisterForm”. Esta función solo está disponible si el registro libre está permitido. Consultar la función “RegisterAllowed”.
LoadUser(IdSession: TGWSIdentifier; out Data: TGWSUser; out Error: TGWSError)
Permite obtener los datos del usuario actual que inició sesión.
Parámetros:
IdSession: Código de la sesión actual.
Data: Datos del usuario.
Error: Código y mensaje de error.
SaveUser(IdSession: TGWSIdentifier; const FullName: String; const NIF: String; const EMail: String;
RegistrationData: TGWSRegistrationForm; out Error: TGWSError)
Permite modificar los datos del usuario actual.
Parámetros:
IdSession: Código de la sesión actual.
FullName: Nombre completo del usuario.
NIF: Número de identificación del usuario.
Email: Dirección de correo electrónico del usuario.
RegistrationData: Formulario de registro relleno con los valores del usuario.
Error: Código y mensaje de error.
Procedimientos
LoadProcedures(IdSession: TGWSIdentifier; out Data: TGWSListRefProcedure; out Error: TGWSError)
Obtiene lista de definiciones básicas de procedimientos.
Parámetros:
IdSession: Código de la sesión actual.
Data: Lista de definiciones básicas de procedimiento.
Error: Código y mensaje de error.
LoadProcedure(IdSession: TGWSIdentifier; IdProcedure: TGWSIdentifier; out Data: TGWSProcedure; out Error: TGWSError)
Permite obtener la definición completa de un procedimiento que se indique.
Parámetros:
IdSession: Código de la sesión actual.
IdProcedure: Identificador del procedimento.
Data: Definición completa del procedimiento.
Error: Código y mensaje de error.
Trámites
LoadProcesses(IdSession: TGWSIdentifier; SearchParams: TGWSSearchProcessArg; out Data: TGWSListRefProcess; out Error: TGWSError)
Obtiene una lista de trámites (descripción abreviada) del usuario que cumplan las condiciones indicadas en el parámetro de búsqueda.
Parámetros:
IdSession: Código de la sesión actual.
SearchParams: Parámetros de búsqueda.
Data: Lista de trámites (descripción abreviada).
Error: Código y mensaje de error.
LoadProcess(IdSession: TGWSIdentifier; IdProcess: TGWSIdentifier; out Data: TGWSProcess; out Error: TGWSError)
Carga un trámite completo.
Parámetros:
IdSession: Código de la sesión actual.
IdProcess: Identificador del trámite.
Data: Contenido completo del trámite.
Error: Código y mensaje de error.
Destalles:
Si el trámite tiene notificaciones pendientes, el sistema no permite abrir el trámite. Es necesario confirmar la recepción de las notificaciones
antes de abrir el trámite, haciendo uso de las tareas “LoadProcessNotifications”, “LoadTaskSerialization” y “SendTask”.
LoadProcessNotifications(IdSession: TGWSIdentifier; IdProcess: TGWSIdentifier; out Data: TGWSListNotifications; out Error: TGWSError)
Obtiene una lista de las notificaciones pendientes del trámite.
Parámetros:
IdSession: Código de la sesión actual.
IdProcess: Identificador del trámite.
Data: Lista de notificaciones pendientes del trámite.
Error: Código y mensaje de error.
Detalles:
Cuando un proceso tenga notificaciones pendientes, será necesario cargar cada una de las tareas indicadas por las notificaciones,
firmarlas y enviarlas para confirmar la recepción de dichas notificaciones.
CreateProcess(IdSession: TGWSIdentifier; IdProcedure: TGWSIdentifier; ProcessLabel: String; out Data: TGWSProcess; out Error: TGWSError)
Crea un trámite basado en una definición de procedimiento. Le asigna una etiqueta al nuevo trámite creado, para facilitar la
localización del mismo.
Parámetros:
IdSession: Código de la sesión actual.
IdProcedure: Identificador del procedimento que sirve como definición del trámite a crear.
ProcessLabel: Etiqueta identificativa del nuevo trámite.
Data: Proceso creado.
Error: Código y mensaje de error.
RemoveProcess(IdSession: TGWSIdentifier; IdProcess: TGWSIdentifier; out Error: TGWSError)
Elimina el trámite indicado.
Parámetros:
IdSession: Código de la sesión actual.
IdProcess: Identificador del trámite.
Error: Código y mensaje de error.
Detalles:
Para que se pueda eliminar un trámite, es necesario que no se haya enviado ninguna tarea asociada al mismo.
ArchiveProcess(IdSession: TGWSIdentifier; IdProcess: TGWSIdentifier; out Error: TGWSError)
Archiva el trámite indicado.
Parámetros:
IdSession: Código de la sesión actual.
IdProcess: Identificador del trámite.
Error: Código y mensaje de error.
Detalles:
Para que se pueda archivar el trámite, es necesario que este haya finalizado.
Tareas de los trámites
CreateTask(IdSession: TGWSIdentifier; IdProcess: TGWSIdentifier; IdTaskDefinition: TGWSIdentifier; out Data: TGWSTask;
out Error: TGWSError)
Crea una tarea dentro del trámite indicado.
Parámetros:
IdSession: Código de la sesión actual.
IdProcess: Identificador del trámite.
IdTaskDefinition: Tipo de tarea a crear.
Data: Tarea creada.
Error: Código y mensaje de error.
SaveTask(IdSession: TGWSIdentifier; IdProcess: TGWSIdentifier; Task: TGWSTask; out Error: TGWSError)
Guarda los cambios realizados en una tarea.
Parámetros:
IdSession: Código de la sesión actual.
IdProcess: Identificador del trámite.
Task: Tarea que se va a modificar.
Error: Código y mensaje de error.
Detalles:
Para que la tarea pueda ser guardada no debe haber sido enviada.
RemoveTask(IdSession: TGWSIdentifier; IdProcess: TGWSIdentifier; IdTask: TGWSIdentifier; out Error: TGWSError)
Elimina una tarea de un trámite.
Parámetros:
IdSession: Código de la sesión actual.
IdProcess: Identificador del trámite.
IdTask: Identificador de la tarea a eliminar.
Error: Código y mensaje de error.
Detalles:
Para que la tarea pueda ser eliminada no debe haber sido enviada.
LoadTaskSerialization(IdSession: TGWSIdentifier; IdProcess: TGWSIdentifier; IdTask: TGWSIdentifier;
out Data: String; out Error: TGWSError)
Carga el contenido serializado de una tarea. Este contenido serializado es el que habrá de ser firmado
cuando se quiera enviar la tarea.
Parámetros:
IdSession: Código de la sesión actual.
IdProcess: Identificador del trámite.
IdTask: Identificador de la tarea.
Data: Serialización de la tarea.
Error: Código y mensaje de error.
ValidateTask(IdSession: TGWSIdentifier; IdProcess: TGWSIdentifier; IdTask: TGWSIdentifier; out Error: TGWSErrorValidateTask);
Comprueba las condiciones de validación que se hayan definido sobre la tarea. Si no se cumplen alguna o algunas de las condiciones,
vendrá indicado en el parámetro de salida “Error”.
Parámetros:
IdSession: Código de la sesión actual.
IdProcess: Identificador del trámite.
IdTask: Identificador de la tarea.
Error: Código y mensaje de error. Cada validación que no se cumpla vendrá identificada por un código y mensaje de error y, cuando sea posible,
por el identificador del campo relacionado con el error.
SendTask(IdSession: TGWSIdentifier; IdProcess: TGWSIdentifier; IdTask: TGWSIdentifier; Signature: TGSignature; out Error: TGWSErrorValidateTask)
Envía la tarea al backoffice, para que continue el trámite. La tarea ha de cumplir las validaciones definidas.
Parámetros:
IdSession: Código de la sesión actual.
IdProcess: Identificador del trámite.
IdTask: Identificador de la tarea.
Signature: Firma de la serialización de la tarea.
Error: Código y mensaje de error. Cada validación que no se cumpla vendrá identificada por un código y mensaje de error y, cuando sea posible,
por el identificador del campo relacionado con el error.
ResponseTask(IdSession: TGWSIdentifier; IdProcess: TGWSIdentifier; IdTask: TGWSIdentifier; out Error: TGWSError)
Genera una tarea de respuesta a una tarea que haya sido recibida.
Parámetros:
IdSession: Código de la sesión actual.
IdProcess: Identificador del trámite.
IdTask: Identificador de la tarea.
Error: Código y mensaje de error.
Ficheros adjuntos de los trámites
LoadFile(IdSession: TGWSIdentifier; IdProcess: TGWSIdentifier; IdTask: TGWSIdentifier; IdFile: TGWSIdentifier;
out Data: TGWSFile; out Error: TGWSError)
Permite obtener el contenido de un fichero que pertenezca una tarea de un trámite.
Parámetros:
IdSession: Código de la sesión actual.
IdProcess: Identificador del trámite.
IdTask: Identificador de la tarea.
IdFile: Identificador del fichero.
Data: Descriptor y contenido del fichero.
Error: Código y mensaje de error.
AttachFile(IdSession: TGWSIdentifier; IdProcess: TGWSIdentifier; IdTask: TGWSIdentifier; FileName: String; Content: TByteDynArray;
out Data: TGWSFile; out Error: TGWSError)
Adjunta un nuevo fichero a una tarea de un trámite.
Parámetros:
IdSession: Código de la sesión actual.
IdProcess: Identificador del trámite.
IdTask: Identificador de la tarea.
FileName: Nombre del fichero.
Content: Contenido del fichero.
Data: Descriptor y contenido del fichero.
Error: Código y mensaje de error.
RemoveFile(IdSession: TGWSIdentifier; IdProcess: TGWSIdentifier; IdTask: TGWSIdentifier; IdFile: TGWSIdentifier; out Error: TGWSError)
Elimina un fichero que haya sido adjuntado a una tarea de un trámite.
Parámetros:
IdSession: Código de la sesión actual.
IdProcess: Identificador del trámite.
IdTask: Identificador de la tarea.
IdFile: Identificador del fichero.
Error: Código y mensaje de error.
Detalles.
Para que un fichero pueda ser eliminado de la tarea, la tarea no puede haber sido enviada.
