- DESA-L - Índex
- 1 Introducció
- 2 Model de Metadades
- 3 Autenticació
- 4 Capa Fitxer
- 5 Capa Expedient
- 5.1 Alta d'Expedient
- 5.2 Modificació Expedient
- 5.3 Eliminació d'Expedient
- 5.4 Descàrrega d'Expedient
- 5.5 Descàrrega d'Expedient en format ZIP
- 5.6 Consulta estat ticket
- 5.7 Descàrrega d'Expedient en format ENI
- 5.8 Cerca d'Expedients
- 5.9 Descàrrega d'Expedients en format ZIP
- 5.10 Afegeix Documents a un Expedient
- 6 Capa Document
DESA’L és un repositori documental transversal, flexible i parametritzable que s’ha habilitat a tots i cadascun dels ens als que l’AOC ofereix el seu catàleg de serveis d’administració electrònica. El repositori documental del DESA’L ofereix funcionalitats per a la captura, catalogació, classificació, custòdia, retenció, cerca i recuperació de documents electrònics generats pels serveis d’administració electrònica de l’AOC, o fins i tot de tercers.
DESA’L garanteix en tot moment la integritat dels documents, l’absència de malware, l’autenticitat dels integradors i l’auditoria exhaustiva de totes les operacions realitzades.
DESA’L permet enriquir els documents del repositori amb un llenguatge comú i compartit, anomenat model de metadades, que permet categoritzar els documents i, opcionalment, classificar-los en expedients (aquests expedients són la contrapartida als procediments administratius als que donen resposta el nostre catàleg de serveis d’administració electrònica).
DESA’L també ofereix funcionalitats avançades de cerca d’expedients i documents a partir d’un conjunt determinat de metadades definides com a indexables, i també permet la compartició d’expedients i documents amb serveis de tercers gràcies a les funcionalitats d’exportació en format ENI (Esquema Nacional d’Interoperabilitat).
Totes les funcionalitats que ofereix DESA’L són accessibles a través d’una API REST en format JSON. Aquest manual detalla la missatgeria associada a aquesta API, així com el procediment a seguir per realitzar la integració amb el servei DESA’L.
| IMPORTANT |
|---|
| Abans d’iniciar la integració amb el DESA’L és imprescindible que demaneu als responsables del DESA’L una reunió prèvia on us puguin assessorar i recomanar, entre d’altres temes, si heu de fer servir expedients, quin model de metadades de document heu d’escollir (bàsic o complet), com heu d’informar les metadades, quins permisos hauran de tenir els altres serveis integradors sobre els vostres expedients o documents, etc. Els responsables del DESA’L s’encarregaran a la seva vegada de gestionar la vostra alta com a servei de DESA’L i us proporcionaran les credencials d’accés dels diferents entorns. |
| Recordeu que els entorns de DEV i PRE del DESA'L estan destinats únicament per a l'ús de proves i que d'acord amb el Supervisor Europeo de Protecció de Dades (EDPS) en cap cas podem fer servir dades personals reals. Així doncs, als entorns de DEV i PRE de DESA'L hem de fer servir exclusívament dades fictícies o creades artificialment. |
Per tal de garantir la comprensió de la nomenclatura que s’utilitza al DESA’L, a continuació definim les diferents entitats que conformen la nova solució:
-
Servei : cada servei d’administració electrònica de l’AOC, o de tercers, que requereix la integració amb el DESA’L, ja sigui per nodrir el repositori amb nous documents i/o expedients, o bé per recuperar o cercar qualsevol d’aquests documents o expedients. L’alta d’un nou servei integrador s’ha de realitzar de forma exclusiva pel personal de l’AOC i el procediment per fer-ho resta fora de l’abast d’aquest manual.
-
Organisme : cadascun dels diferents ens públics (ajuntaments, consells comarcals, diputacions, etc.) als que l’AOC presta servei a través del seu catàleg de serveis d’administració electrònica, i als que s’ha habilitat el repositori documental del DESA’L. L’alta d’un nou organisme al repositori documental del DESA’L s’ha de realitzar de forma exclusiva pel personal de l’AOC i el procediment per fer-ho resta fora de l’abast d’aquest manual.
-
Expedient : és una entitat d’alt nivell formada pel conjunt ordenat de documents i actuacions que serveixen d’antecedent i fonament a la resolució administrativa, així com les diligències encaminades a executar-la. De forma més pràctica podem veure-ho com una carpeta que conté les seves pròpies metadades i un conjunt ordenat de documents que estan relacionats amb el procediment administratiu al que dona resposta l’expedient. L’ús d’expedients és opcional, però recomanem encaridament el seu ús per les funcionalitats d’alt valor afegit que DESA’L ofereix. DESA’L no té cap limitació en quant al nombre de documents que pot contenir un únic expedient.
-
Fitxer : binari (PDF, Word, imatge, etc.) que es puja i s’emmagatzema a DESA’L per tal que els serveis d’administració electrònica autoritzats el puguin referenciar a través d’un o més documents. Es tracta d’un element de baix nivell que s’utilitza únicament per evitar duplicats en els binaris. El seu cicle de vida per tant anirà condicionat al cicle de vida dels documents associats. La mida màxima que admet DESA’L per als fitxers és de 4,2GB.
-
Document : entitat essencial del DESA’L formada per un conjunt de metadades i la relació amb un i només un fitxer de DESA’L . El document és l’entitat d’alt nivell amb la que realment han de treballar en tot moment els integradors. DESA’L contempla 2 models de metadades a nivell de document: bàsic i complet. DESA’L permet que un mateix fitxer (binari PDF, Word, ...) estigui referenciat per més d’un document i que cadascun d’aquests documents pugui tenir uns permisos i unes polítiques de retenció pròpies. D’altra banda, un document de DESA’L pot pertànyer de forma opcional a un, i només un, expedient.
El model de metadades de cadascuna de les entitats (fitxer, document i expedient) ve definit pel conjunt de metadades que tindran associades cadascuna d’aquestes entitats, la seva tipologia i mida, si poden ser o no editables, així com si es poden fer servir per a les cerques.
En el model de metadades es podem distingir tres grups diferents de tipus de metadades:
Metadades que ha d’aportar l’integrador.
Es tracta de metadades que ha d’informar l’integrador en el moment de crear l’entitat.
Metadades que crea DESA’L automàticament.
Es tracta de metadades que genera automàticament DESA’L en el moment de crear l’entitat i són metadades que DESA’L retorna en la resposta del mètode corresponent d’alta o modificació de l’entitat.
Metadades ENI.
Es tracta de metadades que genera automàticament DESA’L en el moment d’exportar un expedient o document en format ENI, d’acord a les especificacions tècniques publicades a les normes tècniques d’interoperabilitat corresponents.
Ampliació del model de metadades InfoAddicional
El servei integrador pot estendre els models de metadades d’expedient o document fent ús de la metadada infoAddicional. Aquesta metadada és de tipus Text, no té cap limitació de mida i està pensada per emmagatzemar en ella una llista de claus – valor d’acord a les necessitats específiques del servei integrador.
A continuació es presenten els diferents models de metadades que utilitza DESA’L per a cada tipus d’entitat. Per cada metadada s’especifica les següents característiques que determina el seu comportament:
| Camp | Descripció |
|---|---|
| Nom element | Variable que indica el nom de la metadada |
| Consignació | Variable que indica si és obligatòria o opcional. També existeix la possibilitat que sigui obligatòria, però condicionada al valor d’una alta metadada (la metadada relacionada es detalla en el camp observacions). |
| Tipus de camp | Variable que indica el format que ha de tenir el camp. Poden ser de tipus:
|
| Equivalència ENI | Nom de la metadada a la missatgeria ENI. |
| Equivalència MUX | Nom de la metadada a la missatgeria de MUXv3. |
| Qui informa | Variable que identifica qui ha de aportar aquest valor. Es definiran dues opcions: |
| Automàtic | Variable que indica si l'ha de crear el sistema de manera automàtica o el sistema espera rebre aquesta dada |
| Únic | Variable que indica si el valor ha de ser únic dins el repositori documental o si es pot repetir. |
| Repetitiu | Variable que indica si la metadada pot tenir més d'un valor o ha de ser únic. És a dir, si la metadada és de tipus llista. |
| Indexable | Variable que indica si internament, DESA'L ha d'indexar aquesta metadada per tal que es pugui incorporar en un futur com a criteri de cerca. |
| Cercable | Variable que indica si la metadada pot ser utilitzada com a criteri de filtre en els mètodes de cerca de document i expedient. |
| Modificable en edició | Variable que indica si el valor es podrà modificar un cop creada l'entitat. L'integrador només podrà modificar les dades que tinguin la variables Qui l'informa igual a "Aplicació que s'integra". |
| Observacions | Variable que dona més detalls o que aclareix d'algun aspecte important a tenir en compte de la metadada. |
| Nom element | Consignació | Longitud camp | Tipus de camp | Validació i procedència dades | Equivalencia ENI | Equivalencia MUX | Qui l'informa | Automàtic | Únic | Repetitiu | Indexable | Cercable | Modificable edició | Observacions |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| CodiINE | Obligatori | 10 | Text | -- | -- | -- | Aplicació que s'integra | No | No | No | N/A | N/A | N/A | Codi INE de l'ens propietari del fitxer |
| CodiServei | Obligatori | 10 | Text | -- | -- | -- | Aplicació que s'integra | No | No | No | N/A | N/A | N/A | Codi del servei propietari del fitxer |
| NomFitxer | Obligatori | 250 | Text | -- | NombreFichero | nomFitxer | Aplicació que s'integra | No | No | No | N/A | N/A | N/A | Nom del fitxer incloent l’extensió |
| Mida | Obligatori | 500 | Text | Validar que no sigui superior a 4,2GB | TamanoLogico | Mida | Aplicació que s'integra | No | No | No | N/A | N/A | N/A | És necessari informar la mida del fitxer per generar correctament l'URL pre-signada per a fer la càrrega del binari a S3 |
| FormatFitxer | Opcional | 200 | Text | Disposem de la llista de tots els tipus acceptats | NombreFormato | tipusMIME | Aplicació que s'integra | Si | No | No | N/A | N/A | No | -- |
| -- | -- | -- | -- | -- | -- | -- | METADADES QUE CREA DESA'L AUTOMÀTICAMENT | -- | -- | -- | -- | -- | -- | -- |
| UUIDFitxer | Obligatori | 20 | Text | -- | SecuenciaIdentificador | -- | DESA'L | Si | Si | No | N/A | N/A | No | Identificador únic del fitxer |
| FormatFitxer | Obligatori | 200 | Text | -- | NombreFormato | tipusMIME | DESA'L | Si | No | No | N/A | N/A | No | Content Type del fitxer. DESA’L el calcula automàticament si no s'informa a la petició d’alta del fitxer |
| Hash | Obligatori | 100 | Text | -- | Valor | hash | DESA'L | Si | Si | No | N/A | N/A | No | Hash del fitxer. |
| HashAlgoritme | Obligatori | 100 | Text | -- | Algoritmo | -- | DESA'L | Si | No | No | N/A | N/A | No | Algoritme de hash utilitzat per calcular hash. |
| Mida | Obligatori i condicional | 100 | Número | -- | TamanoLogico | Mida | DESA'L | Si | No | No | N/A | N/A | No | Mida real del fitxer. |
| DataAlta | Obligatori | -- | Data i hora | -- | -- | dataCapturaDocument | DESA'L | Si | No | No | N/A | N/A | No | Data de creació del fitxer. |
| Estat | Obligatori | -- | Text | -- | -- | -- | DESA'L | Si | No | No | N/A | N/A | N/A | Aquest camp serveix per controlar l'estat del fitxer:
|
| Nom element | Consignació | Longitud | Tipus de camp | Equivalencia ENI | Qui l'informa | Automàtic | Únic | Repetitiu | Indexable | Cercable | Modificable en edició | Observacions |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| codiINE | Obligatori | 10 | Text | -- | Aplicació que s'integra | No | No | No | Si | Si | No | Codi INE de l’ens propietari de l’expedient |
| codiServei | Obligatori | 10 | Taula | -- | Aplicació que s'integra | No | No | No | Si | Si | No | Codi del servei propietari de l’expedient |
| identificador | Obligatori | 50 | Text | -- | Aplicació que s'integra | No | No | No | Si | Si | Si | Número d’expedient |
| titol | Obligatori | 500 | Text | NombreNatural | Aplicació que s'integra | No | No | No | Si | Si | Si | Títol o assumpte de l'expedient |
| dataInici | Obligatori | -- | Data i hora | FechaAperturaExpediente | Aplicació que s'integra | Si | No | No | Si | Si | Si | Data d’obertura de l’expedient |
| dataFi | Opcional | validar formato data | Data i hora | -- | Aplicació que s'integra | No | No | No | Si | Si | Si | Data de tancament de l’expedient |
| usuari | Opcional | 100 | Text | -- | Aplicació que s'integra | No | No | No | Si | No | No | Dades identificatives de l’usuari que crea l'expedient |
| unitatResponsable | Opcional | 250 | Text | -- | Aplicació que s'integra | No | No | No | Si | No | Si | -- |
| codiClassificacio | Obligatori | 50 | Text | CodigoClasificacion | Aplicació que s'integra | No | No | No | Si | Si | Si | -- |
| nomClassificacio | Obligatori | 250 | Text | DenominacionClase | Aplicació que s'integra | No | No | No | No | No | Si | -- |
| codiSIA | Opcional | 50 | Text | CodigoClasificacion | Aplicació que s'integra | No | No | No | Si | Si | Si | -- |
| nivellAcces | Opcional | -- | Text | NivelAcceso | Aplicació que s'integra | No | No | No | Si | No | Si |
|
| clasificacioENS | Opcional | -- | Text | ClasificacionENS | Aplicació que s'integra | No | No | No | Si | No | Si | Baix,Mig, Alt |
| sensibilitatDadesCaracterPersonal | Opcional | -- | Text | SensibilidadDatosCaracterPersonal | Aplicació que s'integra | No | No | No | Si | No | Si | Basic, Mig, Alt |
| estatExpedient | Obligatori | -- | Text | Estado | Aplicació que s'integra | No | No | No | Si | No | Si |
|
| interessat | Opcional | 15 | Text | Interesado | Aplicació que s'integra | No | No | Si | Si | Si | Si | Llista de ciutadans/persones jurídiques o administracions vinculades amb l’expedient
|
| descripcio | Opcional | 500 | Text | Descripcio | Aplicació que s'integra | No | No | No | Si | Si | Si | -- |
| infoAddicional | Opcional | -- | Text | -- | Aplicació que s'integra | No | No | Si | No | No | Si | Llista de claus-valors que l’integrador pot fer servir per ampliar el model de metadades d’acord a les seves necessitats específiques |
| -- | -- | -- | -- | -- | -- | METADADES QUE CREA DESA'L AUTOMÀTICAMENT | -- | -- | -- | -- | -- | -- |
| UUIDExpedient | Obligatori | 36 | Text | SecuenciaIdentificador | DESA'L | Si | Si | No | Si | Si | No | Identificador únic de l'expedient |
| dataAlta | Obligatori | -- | Data i hora | -- | DESA'L | Si | No | No | Si | Si | No | Data d'alta de l'expedient a DESA'L |
| versioNTI | Obligatori | -- | URI | VersionNTI | DESA'L | Si | No | No | No | No | No | Valor per defecte: http://administracionelectronica.gob.es/ENI/XSD/v1.0/expediente-e |
| identificadorENI | Obligatori | 52 | Text | Identificador | DESA'L | Si | No | No | Si | No | No | Identificador utilitzat per a les exportacions ENI amb el format: ES_<Órgano> |
| organ | Obligatori | 20 | Text | Organo | DESA'L | Si | No | Si | Si | No | No | Equivalència codi INE amb el DIR3 |
A continuació detallem les diferents metadades i la seva definició per Exportació ENI:
| Nom element | Consignació | Longitud camp | Tipus de camp | Validació i procedència dades | Equivalencia DESA'L | Qui l'informa | Automàtic | Repetitiu | Cercable | Modificable en edició | Observacions |
|---|---|---|---|---|---|---|---|---|---|---|---|
| -- | -- | -- | -- | -- | METADADES QUE CREA DESA'L AUTOMÀTICAMENT AL FER UNA EXPORTACIÓ ENI | -- | -- | -- | -- | -- | -- |
| versionNTI | Obligatori | -- | URI | DESA'L | N/A | DESA'L | Si | No | N/A | N/A | Valor per defecte: http://administracionelectronica.gob.es/ENI/XSD/v1.0/expediente-e |
| identificador | Obligatori | 52 | Text | DESA'L | N/A | DESA'L | Si | No | N/A | N/A | L'element s'informa a partir d'altres metadades: ES_<Órgano> |
| organo | Obligatori | 20 | Text | DESA'L | N/A | DESA'L | Si | Si | N/A | N/A | Equivalència codi INE amb el DIR3 |
| fechaAperturaExpediente | Obligatori | -- | Data i hora | DESA'L | DataInici | DESA'L | Si | No | N/A | N/A | -- |
| clasificacion | Obligatori | -- | Text | DESA'L | CodiSIA/CodiClassificacio | DESA'L | Si | No | N/A | N/A | Si existeix el codi SIA s'agafa aquest sinó el codi de classificació |
| estado | Obligatori | -- | Text | DESA'L | EstatExpedient | DESA'L | Si | No | N/A | N/A | -- |
| interesado | Opcional | -- | Text | DESA'L | Interessat | DESA'L | Si | Si | N/A | N/A | -- |
DESA’L disposa de 2 models de metadades per als documents: el model bàsic i el model complet. Cada servei integrador utilitzarà un i només un d’aquests 2 models per a tots els documents que generi. Un cop donat d’alta el servei i definit el model de metadades dels seus documents no es podrà canviar de model. D’aquesta forma en el moment de crear el document aquest heretarà el model de metadades que ha d’utilitzar en funció del servei propietari al que pertanyi i aquest model de metadades es mantindrà al llarg de tot el seu cicle de vida (és a dir no podrà canviar de cap manera el model de metadades d’un document un cop aquest hagi estat creat).
Metadades de document bàsic.
Es tracta del model de metadades mínim per poder donar d'alta un document al repositori documental del DESA’L. Els serveis que utilitzin aquest model de metadades bàsic no podran realitzar l’exportació en format ENI de documents ni d’expedients (en cas de sol·licitar l’exportació ENI DESA’L retornarà un error). Aquest model de metadades tindrà un ús molt restringit i el seu ús ha de ser especialment consensuat amb els responsables del DESA’L.
Important: el model de metadades de document que haurà de fer servir el vostre servei s’ha de consensuar amb els responsables del DESA’L. Un cop escollit el model de metadades del servei, no es podrà canviar.
A continuació es detallen les diferents metadades del model bàsic:
| Nom element | Consignació | Longitud camp | Tipus de camp | Equivalencia ENI | Equivalencia MUX | Qui l'informa | Automàtic | Únic | Repetitiu | Indexable | Cercable | Modificable edició | Observacions |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| codiINE | Obligatori | 10 | Text | -- | -- | Aplicació que s'integra | No | No | No | Si | Si | No | Codi INE de l'ens propietari del document |
| codiServei | Obligatori | 10 | Taula | -- | -- | Aplicació que s'integra | No | No | No | Si | Si | No | Codi del servei propietari del document |
| nomFitxer | Obligatori i condicional | 250 | Text | NombreFichero | nomFitxer | Aplicació que s'integra | No | No | No | Si | No | Si | Nom del fitxer amb extensió. Només s'ha d’informar si contingut és 1 |
| nomNatural | Obligatori | 500 | Text | NombreNatural | nomNatural | Aplicació que s'integra | No | No | No | Si | Si | Si | Nom natural (sense extensió) |
| dataDocument | Obligatori | -- | Data i hora | FechaInicio | -- | Aplicació que s'integra | No | No | No | Si | Si | Si | -- |
| contingut | Obligatori | -- | Text | -- | -- | Aplicació que s'integra | No | No | No | Si | No | No |
|
| interessat | Opcional | 20 | Text | Interesado | -- | Aplicació que s'integra | No | No | Si | Si | Si | Si | Llista de ciutadans/persones jurídiques o administracions vinculades amb l’expedient
|
| usuari | Opcional | 250 | Text | -- | -- | Aplicació que s'integra | No | No | No | Si | No | No | Dades identificatives qui crea el document |
| numeroRegistre | Opcional | 100 | Text | -- | -- | Aplicació que s'integra | No | No | No | Si | Si | Si | -- |
| CSV | Opcional | 100 | Text | -- | -- | Aplicació que s'integra | No | Si | No | Si | Si | No | Si el servei integrador informa el CSV, DESA’L comprovarà que sigui únic i en cas contrari retornarà un error. |
| identificadorExpedientDesal | Opcional | 100 | Text | idEntidadRelacionada | -- | Aplicació que s'integra | No | No | No | No | No | Si | Identificador de l'expedient de DESA'L al que pertany el document. DESA’L comprovarà que l'expedient existeixi i en cas contrari retornarà un error. |
| identificadorExpedientExtern | Opcional | 100 | Text | idEntidadRelacionada | -- | Aplicació que s'integra | No | No | No | Si | Si | Si | Identificador informatiu, l'expedient no ha d'estar donat d'alta a DESA'L i DESA’L no farà cap tipus de valició d’aquest camp. |
| UUIDFitxer | Obligatori i condicional | 20 | Text | idEntidadRelacionada | -- | Aplicació que s'integra | No | No | No | Si | Si | Si | Pensat per aquells documents que están relacionats amb un fitxer. Només s'ha d’informar si contingut és 1. |
| URLDocumentExtern | Obligatori i condicional | -- | URI | idEntidadRelacionada | URL | Aplicació que s'integra | No | No | No | No | No | Si | Pensat per aquells documents que no tenen un fitxer associat i que el contingut del document está ubicat en un repositori extern. Només s'informa si contingut és 2 |
| identificadorDocumentExtern | Obligatori i condicional | 100 | Text | idEntidadRelacionada | identificador | Aplicació que s'integra | No | No | No | Si | Si | Si | Pensat per aquells documents que no tenen un fitxer associat i que el contingut del document está ubicat en un repositori extern. Només s'informa si contingut és 3 |
| infoAddicional | Opcional | -- | Text | -- | -- | Aplicació que s'integra | No | No | Si | No | No | Si | Llista de claus-valors que l’integrador pot fer servir per ampliar el model de metadades d’acord a les seves necessitats específiques |
| -- | -- | -- | -- | -- | -- | -- | METADADES QUE CREA DESA'L AUTOMÀTICAMENT | -- | -- | -- | -- | -- | -- |
| UUIDDocument | Obligatori | 36 | Text | SecuenciaIdentificador | uuid | DESA'L | Si | Si | No | Si | Si | No | Identificador únic del document |
| CSV | Obligatori i condicional | 100 | Text | -- | -- | DESA'L | Si | Si | No | Si | Si | No | CSV únic del document. Si l’integrador no l’inforna, DESA’L el generarà automàticament. |
| formatFitxer | Obligatori i condicional | 200 | Text | NombreFormato | tipusMIME | DESA'L | Si | No | No | Si | No | No | Content Type del fitxer. Només es retorna si contingut és 1. |
| hash | Obligatori i condicional | 100 | Text | Valor | hash | DESA'L | Si | No | No | No | No | Si | Valor hash del fitxer. Només es retorna si contingut és 1. |
| hashAlgoritme | Obligatori i condicional | 100 | Text | Algoritmo | -- | DESA'L | Si | No | No | No | No | Si | Algoritme de hash utilitzat per calcular el hash del fitxer. Només es retorna si contingut és 1 |
| tamany | Obligatori i condicional | 100 | Número | TamanoLogico | Mida | DESA'L | Si | No | No | Si | No | Si | Mida del fitxer. Només es retorna si contingut és 1 |
| dataAlta | Obligatori | -- | Data i hora | -- | dataCapturaDocument | DESA'L | Si | No | No | Si | Si | No | Data d'alta del document a DESA'L |
| identificadorExpedientDesal | opcional i condicional | 100 | Text | idEntidadRelacionada | -- | DESA'L | Si | No | Si | No | No | No | UUID de l’expedient amb el que està vinculat el document. |
| versioNTI | Obligatori | -- | URI | VersionNTI | VersionNTI | DESA'L | Si | No | No | No | No | No | Valor per defecte: http://administracionelectronica.gob. es/ENI/XSD/v1.0/documento-e |
| identificador | Obligatori | 52 | Text | Identificador | Identificador | DESA'L | Si | No | No | Si | No | No | Identificador del document en format ENI: ES_<Órgano> |
| organ | Obligatori | 20 | Text | Organo | Organo | DESA'L | Si | No | Si | Si | No | No | Equivalència codi INE amb el DIR3 del ens propietari del document. |
Metadades de document complert.
Es tracta del model de metadades que majoritàriament han d’utilitzar els serveis integradors. Aquest model inclou totes les metadades del document bàsic (amb les mateixes tipologies i validacions) i n’afegeix d’altres específiques que a continuació es detallen. El model complet sí que permet l’exportació en format ENI.
| Nom element | Consignació | Longitud camp | Tipus de camp | Equivalencia ENI | Equivalencia MUX | Qui l'informa | Automàtic | Únic | Repetitiu | Indexable | Cercable | Modificable edició | Observacions |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| estatElaboracio | Obligatori | -- | Text | EstadoElaboracion | estatElaboracio | Aplicació que s'integra | No | No | No | Si | No | Si |
|
| origen | Obligatori | -- | boolea | OrigenCiudadanoAdministracion | origen | Aplicació que s'integra | No | No | No | No | No | Si |
|
| tipusDocumental | Obligatori | -- | Text | TipoDocumental | tipusDocumentalNTI | Aplicació que s'integra | No | No | No | Si | No | Si |
|
| tipusSignatura | Obligatori | -- | Text | TipoFirma | tipusSignatura | Aplicació que s'integra | No | No | No | Si | No | Si |
|
| CSVSignatura | Obligatori i condicional | 100 | Text | ValorCSV | valorCSV | Aplicació que s'integra | No | No | No | Si | Si | Si | Només s’ha d’informar si TipoFirma és TF01 |
| regulacioGeneracioCSVSignatura | Obligatori i condicional | 500 | Text | RegulacionGeneracionCSV | regulacioGeneracioCSV | Aplicació que s'integra | No | No | No | No | No | Si | Només s’ha d'informar si TipoFirma és _TF01 |
| referenciaSignatura | Obligatori i condicional | 100 | Text | ReferenciaFirma | identificadorDocumentSignat | Aplicació que s'integra | No | No | No | No | No | Si | Referència al fitxer que inclou la signatura (UUID fitxer). Només s’ha d’informar si TipoFirma és TF02 o TF04. |
| identificadorDocumentOrigen | Opcional i condicional | 250 | Text | IdentificadorDocumentoOrigen | identificadorDocumentOrigen | Aplicació que s'integra | No | No | No | Si | No | Si | Identificador normalizat del document origen al que correspon la còpia. Només s’ha d’informar si EstadoElaboracion és EE02, EE03 o EE04. |
| descripcio | Opcional | 500 | Text | Descripcion | Observacions | Aplicació que s'integra | No | No | No | Si | Si | Si | -- |
| nivellAcces | Opcional | -- | Enum | NivelAcceso | -- | Aplicació que s'integra | No | No | No | Si | No | Si |
|
| clasificacioENS | Opcional | -- | Enum | ClasificacionENS | -- | Aplicació que s'integra | No | No | No | Si | No | Si | Baix, Mig, Alt |
| sensibilitatDadesCaracterPersonal | Opcional | -- | Enum | SensibilidadDatosCaracterPersonal | -- | Aplicació que s'integra | No | No | No | Si | No | Si | Basic, Mig, Alt |
| documentEssencial | Opcional | -- | boolea | DocumentoEsencial | -- | Aplicació que s'integra | No | No | No | Si | No | Si | True(si), False (NO) |
| idioma | Opcional | 50 | Text | Idioma | -- | Aplicació que s'integra | -- | No | -- | No | No | -- | -- |
| codiClassificacio | Opcional | 50 | Text | CodigoClasificacion | -- | Aplicació que s'integra | No | No | No | Si | Si | Si | -- |
| nomClassificacio | Opcional | 250 | Text | DenominacionClase | -- | Aplicació que s'integra | No | No | No | No | No | Si | -- |
| codiSIA | Opcional | 50 | Text | -- | -- | Aplicació que s'integra | No | No | No | Si | Si | Si | -- |
DESA’L implementa un mètode d’autenticació segur que permet garantir l’autenticitat del servei integrador, i la seva legitimitat per executar la petició, abans de procedir a executar qualsevol dels mètodes de l’API i abans d’accedir a qualsevol de les dades del repositori documental.
Cada petició realitzada pel servei integrador és tractada pel DESA’L de forma totalment independent i requereix per tant d’un procés d’autenticació propi que autoritzi l’execució. DESA’L per tant no manté cap tipus d’estat ni de sessió amb el servei integrador.
Important: cada servei integrador disposarà d’unes credencials pròpies que li permetran interactuar amb els diferents entorns del DESA’L (DEV, PRE i PRO). Els responsables del DESA’L us facilitaran els jocs de credencials per a cada entorn, però és responsabilitat del servei integrador custodiar aquestes credencials de forma segura i evitar comprometre-les o exposar-les en els repositoris de codi font.
Les credencials d’autenticació del servei integrador no es renovaran periòdicament, però sí que és possible generar unes noves credencials si aquestes han estat compromeses. En cas de necessitar-ho us haureu de posar en contacte amb els responsables del DESA’L.
En els següents enllaços s’adjunta la documentació que explica com s’ha de generar la signatura de les peticions que es realitzin a l’API del DESA’L:
https://docs.aws.amazon.com/es_es/general/latest/gr/signing_aws_api_requests.html
També estan disponibles els SDKs d’AWS en diferents tipus de llenguatge que faciliten el procés d’autenticació:
Important: l’AOC disposa d’un client Java que facilita molt tant la implementació del procés d’autenticació amb l’API del DESA’L com la pròpia invocació dels diferents mètodes. Si creieu que pot ser del vostre interès, sol·liciteu als responsables del DESA’L que us el facilitin.
Tot i que els serveis integradors amb DESA’L no us heu de preocupar de gestionar les autoritzacions i els permisos sobre els expedients i documents que doneu d’alta en el repositori documental del DESA’L, sí que creiem que és necessari que conegueu com funciona el sistema de permisos de DESA’L per tal que consensueu amb els responsables del DESA’L les autoritzacions que DESA’L haurà d’aplicar sobre els vostres expedients i documents.
Cada servei integrador que doni d’alta un nou expedient o un nou document esdevindrà el servei propietari d’aquest expedient o document. De forma anàloga, l’ens (organisme) que s’associï a l’expedient o document en el moment de la creació esdevindrà l’ens propietari de l’expedient o del document. Aquestes 2 dades, servei propietari i ens propietari, no es poden canviar al llarg del cicle de vida de l’expedient o document.
El servei propietari i l’ens propietari són la base per establir el sistema de permisos (model de control en terminologia DESA’L) que DESA’L aplicarà sobre els expedients i els documents. El funcionament del model de control és el següent: per defecte, tots els mètodes de l’API de DESA’L estan denegats, de forma que es requereix una autorització explícita al model de control de DESA’L per permetre qualsevol operació (fins i tot per al servei i ens propietaris!). Les autoritzacions es defineixen en base a 5 paràmetres:
| Camp | Descripció |
|---|---|
| Mètode API | Mètode específic de l'API que es vol autoritzar |
| Servei propietari | Servei propietari del document o expedient sobre el que actuarà la regla d'autorització |
| Ens propietari | Ens propietari del document o expedient sobre el que actuarà la regla d'autorització |
| Servei integrador | Servei integrador que vol executar el mètode API |
| Ens integrador | Ens integrador que vol executar el mètode API |
La taula del model de control no té cap limitació en quant al nombre de registres que pot contenir. Aquests 5 paràmetres permeten definir un nivell màxim de granularitat i es poden combinar en tantes regles com sigui necessari. En paral·lel també es permet l’ús del comodí TOTS tant a nivell de servei integrador com de l’ens integrador per facilitar la gestió d’aquesta taula fent públiques determinades operacions a qualsevol integrador del DESA’L.
Cal destacar que qualsevol petició a l’API de DESA’L requerirà que hi hagi com a mínim una regla al model de control que autoritzi de forma explícita la seva execució. Cada regla és totalment independent de la resta i DESA’L les avalua de forma individual una a una fins que troba una regla que autoritza l’execució. La validació del model de control es realitza un cop verificada l’autenticat de l’integrador, però abans de l’execució del mètode.
A mode de resum, i per facilitar l’enteniment de la configuració de permisos que permet el model de control del DESA’L, mostrem algunes de les opcions que DESA’L permet configurar:
- Configurar un servei, o també un organisme, de només lectura. Això es pot fer simplement no afegint cap permís a les operacions de modificació i esborrat d'un determinat servei (o organisme)
- Configurar un servei totalment com a públic associant el comodí TOTS al servei integrador i a l'ens integrador de tots els mètodes d'aquest servei. Aquest ús públic es pot també limitar a determinades operacions com la descàrrega, la cerca o la modificació.
- Permetre a un organisme realitzar qualsevol operació única i exclusivament sobre els documents/expedients que estiguin vinculats a aquest organisme. P. ex. això permetria a un organisme com l'Ajuntament de Terrassa accedir a qualsevol document/expedient seu.
- Permetre únicament a un conjunt reduït de serveis transversals (p. ex. el MyGov, el Portal de Transparència o el MUXv3) la cerca i/o descàrrega de documents o expedients d'un determinat servei (p. ex. l'eNotum), però no permetre en cap cas als serveis transversals la possibilitat de crear, modificar o esborrar els documents de l'eNotum.
- Garantir a un servei que ell gestioni de forma exclusiva els seus propis documents/expedients i que exclogui a qualsevol altre servei integrador (incloent els serveis transversals de l'AOC com MUXv3, MyGov o el Portal de Transparència) qualsevol tipus d'accés a aquests documents/expedients.
A continuació es descriu en detall la capa de fitxers que DESA’L ofereix als integradors. Aquesta capa és responsable de la gestió dels binaris (PDF, Word, ...) que hem d’hostatjar a DESA’L. Es tracta d’una capa de baix nivell que hem d’utilitzar exclusivament mentre no disposem del document de DESA’L.
La càrrega o descàrrega dels binaris dels fitxers es farà sempre a través de l’assignació d’una URL presignada d’S3 amb un temps d’expiració d’una hora. Passat aquest temps, l’URL presignada deixarà d’estar disponible i s’haurà de negociar una de nova amb DESA’L.
La capa de fitxer disposa únicament de 2 mètodes carregar fitxer i descarregar fitxer, tot i que el mètode descàrrega fitxer només estarà disponible mentre el fitxer no estigui vinculat a cap document. En cas d’estar vinculat a un document, la descàrrega del fitxer s’haurà de realitzar través del mètode de descàrrega de document que es detalla a l’apartat 6.4 Descarregar Document.
Important: la capa de fitxer de DESA’L no disposa de cap política de permisos o autoritzacions. Qualsevol integrador que conegui un UUIDFitxer podrà descarregar aquest fitxer fins que el fitxer es vinculi a un document. Aquesta decisió de disseny ve determinada per garantir la política de permisos del model de control.
En cas de voler pujar una nova versió d’un fitxer, s’haurà de carregar un nou fitxer, amb un nou identificador UUIDFitxer. Posteriorment s’haurà d’actualitzar el document per vincular-lo a aquest nou fitxer. D’aquesta forma DESA’L no permet la gestió del versionat de fitxers.
Important: DESA’L té definida una política de purga per als fitxers carregats que no estiguin vinculats a cap document. Aquesta purga esborra de forma automàtica, i sense cap tipus d’excepció, tots els fitxers més antics d’un any que no estiguin vinculats a documents.
Cal destacar que tot i que DESA’L podria arribar a permetre el seu ús com a simple capa d’emmagatzematge a través de l’ús exclusiu de la capa de Fitxer, realment no es tractaria d’un ús natural i el servei integrador hauria de tenir molt en compte aquesta política de purga automàtica.
La càrrega d’un fitxer a DESA’L s’ha de realitzar en 2 passos. Inicialment l’integrador ha d’executar el mètode de càrrega de fitxer del DESA’L per tal d’obtenir l'URL presignada de S3 i a continuació haurà de realitzar la posterior càrrega del fitxer al bucket de S3 de DESA’L a partir d’aquesta URL.
DESA’L té un límit de mida de fitxer màxim de 4.2GB. Si s’intenta carregar un fitxer més gran, DESA’L retornarà un codi d’error i no permetrà la càrrega.
Cada fitxer que és carregat a DESA’L ha de ser analitzat pel sistema d’antivirus (basat en la solució ClamAV) de manera asíncrona. Existeixen diversos estats pels que ha de passar un fitxer abans de poder estar totalment disponible per al servei integrador:
- Pendent – Fitxer pendent d’analitzar pel sistema d’antivirus. Es pot crear un document que referenciï aquest fitxer, però el fitxer no es podrà descarregar per cap mètode de l’API (Descàrrega Fitxer, Descàrrega Document modalitat 2, Descàrrega Expedient modalitat 2, cerca Document, cerca Expedient, etc.) fins que hagi finalitzat l’anàlisi. De mitjana, l’anàlisi de virus d’un document PDF/Word inferior als 10MB és d’uns 3 segons.
- Acceptat – Fitxer analitzat, fitxer lliure de virus i preparat per a ser utilitzat per l'integrador.
- Rebutjat – Fitxer analitzat, fitxer amb virus que ha estat eliminat pel DESA'L i que per tant no pot ser utilitzat per l'integrador.
A continuació es detallen els camps que el servei integrador ha d’informar en el primer pas per poder fer la càrrega d’un nou fitxer:
| Element | Tipus paràmetre | Obligatori | Tipus camps | Mida màxima | Observacions |
|---|---|---|---|---|---|
| codiINE | Body | Si | Text | 10 | N/A |
| codiServei | Body | Si | Text | 10 | N/A |
| nomFitxer | Body | Si | Text | 250 | N/A |
| mida | Body | Si | Número | - | Unitat en bytes |
| formatFitxer | Body | Si | Text | 200 | N/A |
I també un exemple de resposta:
A continuació es detallen els possibles codis d'error per càrrega de fitxer (per al codi d'error 10, XXXXXX especifica la metadada en qüestió i per al codi d'error 100 XXXXXX ofereix més detalls de l'error no controlat):
| Codi | Descripció |
|---|---|
| 0 | Operació realitzada correctament. |
| 10 | Error: la petició no és correcta. Hi ha metadades obligatòries sense informar o metadades informades no vàlides (XXXXXX). Operació NO realitzada. |
| 11 | Error: el codi INE indicat no és vàlid. Operació NO realitzada. |
| 12 | Error: el codi de servei indicat no és vàlid. Operació NO realitzada. |
| 13 | Error: la mida del fitxer supera el màxim permès. Operació NO realitzada. |
| 14 | Error: el nom del fitxer no és vàlid. Operació NO realitzada. |
| 15 | Error: el MIME/Type indicat no és vàlid. Operació NO realitzada. |
| 100 | Error no controlat: XXXXXX. Si us plau, reintenti l'operació en uns minuts. Operació NO realitzada. |
Aquest mètode permet demanar la descàrrega d’un fitxer allotjat al repositori documental del DESA’L, sempre i quan aquest fitxer no estigui encara referenciat per cap document de DESA’L. La descàrrega d’un fitxer es farà també en 2 passos: una primera petició síncrona a a l’API de DESA’L que a partir de l’UUIDFitxer retornarà l’URL presignada de S3 i a continuació la descàrrega pròpiament del binari a partir de l'URL presignada de S3.
Important: la descàrrega de fitxer només es pot executar mentre el fitxer no estigui referenciat per un document de DESA'L. Un cop el fitxer estigui vinculat a un document, la recuperació només es podrà fer a través dels mètodes de document (p. ex. _ 6.4Descarregar Document _)
A continuació es detallen els camps que han d'informar el servei integrador per poder realitzar la descàrrega del fitxer i un exemple de resposta:
| Element | Tipus paràmetre | Obligatori | Tipus camps | Mida màxima | Observacions |
|---|---|---|---|---|---|
| uuidFitxer | QueryParam | Si | Text | - | N/A |
| codiINE | QueryParam | Si | Text | 10 | N/A |
| codiServei | QueryParam | Si | Text | 10 |
A continuació detallem un exemple de petició per a descàrrega de fitxer:
A continuació detallem un exemple de resposta per a descàrrega de fitxer:
A continuació es detallen els possibles codis d’error per a la descàrrega del fitxer (XXXXXX ofereix més detalls de l’error no controlat):
| Codi | Missatge |
|---|---|
| 0 | Operació realitzada correctament. |
| 1 | Error: el contingut del fitxer està esperant a ser analitzat pel antivirus. |
| 2 | Error: No s'ha fet el put del fitxer a S3 (URL-Presigned) |
| 4 | Error: Petició mal informada. |
| 11 | Error: l'identificador del fitxer indicat no és vàlid. Operació NO realitzada. |
| 12 | Error: el codi de servei indicat no és vàlid. Operació NO realitzada. |
| 13 | Error: el codi INE especificat no és vàlid. Operació NO realitzada. |
| 14 | Error: el document físic conté virus i ha estat eliminat. Operació NO realitzada. |
| 100 | Error no controlat: XXXXXX. Si us plau, reintenti l'operació en uns minuts. Operació NO realitzada. |
L'expedient és una entitat d'alt nivell formada pel conjunt ordenat de documents i actuacions que serveixen d'antecedent i fonament a la resolució administrativa, així com les diligències encaminades a executar-la. De forma més pràctica podem veure-ho com una carpeta que conté les seves pròpies metadades i un conjunt ordenat de documents que estan relacionats amb el procediment administratiu al que dona resposta l'expedient. L'ús d'expedients és opcional, però recomanem encaridament el seu ús per les funcionalitats d'alt valor afegit que DESA'L ofereix. DESA'L no té cap limitació en quant al nombre de documents que pot contenir un únic expedient.
A continuació es detallen tots els mètodes de l'API de DESA'L que permeten la gestió d'expedients.
L'alta d'expedient és un mètode síncron que presenta 2 modalitats:
- Modalitat 1 : es dona d'alta únicament l'expedient i més endavant el servei integrador anirà vinculant els documents a través de l'UUIDExpedint que retorna DESA'L (bé donant d'alta aquests documents i associant-los a l'expedient, o bé actualitzant els documents ja existents per establir el vincle amb el seu expedient)
- Modalitat 2 : es dona d'alta l'expedient i de forma simultània en la mateixa operació la llista de documents associats a aquest expedient (posteriorment es podran associar més documents a aquest expedient). Aquesta modalitat s'executa de forma atòmica, és a dir, o bé es dona d'alta l'expedient i tots i cadascun dels documents indicats, o en cas d'error no es dona d'alta cap entitat a DESA'L.
A continuació es defineixen els camps que l'integrador ha d'informar per a donar d'alta un nou expedient en qualsevol de les dues modalitats i la resposta que retorna DESA'L:
| Element | Tipus paràmetre | Obligatori | Tipus camps | Mida màxima | Observacions |
|---|---|---|---|---|---|
| codiINE | Body | Sí | Text | 10 | N/A |
| codiServei | Body | Sí | Text | 10 | N/A |
| identificador | Body | -- | -- | 50 | N/A |
| titol | Body | Sí | Text | 500 | N/A |
| dataInici | Body | Sí | Data | - | Format: DD/MM/AAAA HH:mm:SS |
| dataFi | Body | No | Data | - | Format: DD/MM/AAAA HH:mm:SS |
| Usuari | Body | No | Text | 100 | N/A |
| unitatResponsable | Body | No | Text | 250 | N/A |
| codiClassificacio | Body | Sí | Text | 50 | N/A |
| nomClassificacio | Body | Sí | Text | 250 | N/A |
| codiSIA | Body | No | Text | 50 | N/A |
| nivellAccess | Body | No | Text | -- | N/A |
| clasificacioENS | Body | No | Text | -- | N/A |
| sensibilitatDadesCaracterPersonal | Body | No | Text | -- | N/A |
| estatExpedient | Body | Sí | Text | -- | N/A |
| interessat | Body | No | Llista | - | Llista d'interessats |
| descripció | Body | No | Text | 500 | N/A |
| infoAddicional | Body | No | Llista | - | Llista d'elements clau/valor |
A continuació es detalla un exemple de petició:
En aquest cas, prèviament a l'alta de l'expedient, l'integrador haurà d'haver pujat al repositori documental del DESA'L tots els fitxers que sigui necessari vincular als documents de l'expedient, invocant tantes vegades com sigui necessari el mètode _ 4.1Càrrega de fitxer _. D'altra banda, el detall de les metadades que s'han d'informar per a cada document es detallen a l'apartat _ 6.1Alta de Document _ d'aquest manual.
Abans de procedir a l'alta de l'expedient i del/s document/s, DESA'L comprovarà que tots els fitxers referenciats existeixin i estiguin en _ Estat __ Acceptat, _ i de forma anàloga comprovarà que tots els documents a donar d'alta compleixin les validacions que s'han d'aplicar en l'alta de document. Només que hi hagi un únic fitxer o document que no sigui vàlid, DESA'L rebutjarà tota l'operació (recordem que l'alta d'expedient és una operació que DESA'L ha d'executar de forma atòmica) i indicarà explícitament en la resposta quin document no és vàlid i el motiu pel qual no ho és.
| Element | Tipus paràmetre | Obligatori | Tipus camps | Mida màxima | Observacions |
|---|---|---|---|---|---|
| codiINE | Body | Sí | Text | 10 | N/A |
| codiServei | Body | Sí | Text | 10 | N/A |
| identificador | Body | -- | -- | 50 | N/A |
| titol | Body | Sí | Text | 500 | N/A |
| dataInici | Body | Sí | Data | -- | Format: DD/MM/AAAA HH:mm:SS |
| dataFi | Body | No | Data | -- | Format: DD/MM/AAAA HH:mm:SS |
| Usuari | Body | No | Text | 100 | N/A |
| unitatResponsable | Body | No | Text | 250 | N/A |
| codiClassificacio | Body | Sí | Text | 50 | N/A |
| nomClassificacio | Body | Sí | Text | 250 | N/A |
| codiSIA | Body | No | Text | 50 | N/A |
| nivellAccess | Body | No | Text | -- | N/A |
| clasificacioENS | Body | No | Text | -- | N/A |
| sensibilitatDadesCaracterPersonal | Body | No | Text | -- | N/A |
| estatExpedient | Body | Sí | Text | -- | N/A |
| interessat | Body | No | Llista | -- | Llista d'interessats |
| descripció | Body | No | Text | 500 | N/A |
| infoAddicional | Body | No | Llista | - | Llista d'elements clau/valor |
| documents | Body | -- | Llista | -- | Llista de documents. Model del document definit a l'apartat _ 6.1 _ |
Destaquem com en la Modalitat 2 tenim un codi de resposta i una descripció resposta global de tota l’operació (remarcada en color groc) i un codi de resposta i una descripció resposta individual (remarcada en color verd) per a cada document que, en cas d’error degut al document, permet a l’integrador saber exactament quin document no és vàlid i el motiu (d’acord als codis d’error del mètode Alta Document).
A continuació es detallen els possibles codis de resposta per l'alta d'expedient (per al codi d'error 11, XXXXXX especifica la metadada en qüestió i per al codi d'error 100 XXXXXX ofereix més detalls de l'error no controlat):
| Codi | Missatge |
|---|---|
| 0 | Operació realitzada correctament. |
| 4 | Error: Petició mal formada. |
| 10 | Error: no tens autorització per realitzar aquesta operació. Operació NO realitzada. |
| 11 | Error: la petició no és correcta. Hi ha metadades obligatòries sense informar o metadades informades no vàlides (XXXXXX). Operació NO realitzada. |
| 12 | Error: el número d'expedient ja existeix en el servei i organismo indicats. Operació NO realitzada. |
| 100 | Error no controlat: XXXXXX. Si us plau, reintenti l'operació en uns minuts. Operació NO realitzada.. |
Aquest mètode permet la modificació de qualsevol metadada identificada com a editable de l'expedient. Es permetrà la modificació de l'expedient independentment del seu estat (fins i tot si l'expedient es troba en Estat Tancat).
Es permetrà realitzar la modificació d'una o vàries metadades a la vegada. Les metadades que l'integrador no informi en la seva petició, no es modificaran i mantindran el seu valor original. En cas d'error, DESA'L no modificarà cap de les metadades.
En el cas que l'integrador necessiti esborrar una metadada, podrà fer-ho informant el valor null o una cadena buida si la metadada és de tipus Text. DESA'L validarà però, que aquesta metadada no sigui obligatòria i en cas afirmatiu rebutjarà la petició.
| Element | Tipus paràmetre | Obligatori | Tipus camps | Mida màxima | Observacions |
|---|---|---|---|---|---|
| uuidExpedient | PathParam | Sí | Text | -- | -- |
| codiINE | QueryParam | Sí | Text | 10 | -- |
| identificador | Body | No | -- | 50 | N/A |
| titol | Body | No | Text | 500 | N/A |
| dataInici | Body | No | Data | - | Format: DD/MM/AAAA HH:mm:SS |
| dataFi | Body | No | Data | - | Format: DD/MM/AAAA HH:mm:SS |
| unitatResponsable | Body | No | Text | 250 | N/A |
| codiClassificacio | Body | No | Text | 50 | N/A |
| nomClassificacio | Body | No | Text | 250 | N/A |
| codiSIA | Body | No | Text | 50 | N/A |
| nivellAccess | Body | No | Text | -- | N/A |
| clasificacioENS | Body | No | Text | -- | N/A |
| sensibilitatDadesCaracterPersonal | Body | No | Text | -- | N/A |
| estatExpedient | Body | No | Text | -- | N/A |
| interessat | Body | No | Llista | -- | Llista de literals |
| descripció | Body | No | Text | 500 | N/A |
| infoAddicional | Body | No | Llista | -- | Llista de literals |
A continuació es detallen els possibles codis de resposta per a la modificació de l'expedient (per al codi d'error 11, XXXXXX especifica la metadada en qüestió i per al codi d'error 100 XXXXXX ofereix més detalls de l'error no controlat):
| Codi | Missatge |
|---|---|
| 0 | Operació realitzada correctament. |
| 4 | Error: Petició mal formada. |
| 10 | Error: no tens autorització per realitzar aquesta operació. Operació NO realitzada. |
| 11 | Error: la petició no és correcta. Hi ha metadades obligatòries sense informar o metadades informades no vàlides (XXXXXX). Operació NO realitzada. |
| 12 | Error: l'expedient no existetix al servei o organisme indicats. Operació NO realitzada. |
| 100 | Error no controlat: XXXXXX. Si us plau, reintenti l'operació en uns minuts. Operació NO realitzada. |
Aquest mètode permet realitzar l'esborrat d'un expedient. L'esborrat de l'expedient es pot realitzar independentment de l'estat de l'expedient (fins i tot si l'expedient es troba en _ Estat Obert _).
En el procés d'eliminació de l'expedient també s'eliminaran en cascada tots els documents que aquest expedient tingui associats (és a dir, tots aquells documents amb la metadada _ IdentificadorExpedientDesal _ igual a l'_ UUIDExpedient _ informat per l'integrador) i de forma anàloga tots els fitxers referenciats per aquests documents que no estiguin referenciats per altres documents.
És important destacar que DESA'L no realitzarà cap doble validació per eliminar en cascada els documents i/o fitxers referenciats per l'expedient. Si en el model de control l'integrador disposa d'autorització per esborrar l'expedient, DESA'L realitzarà la operació en la seva totalitat tot i que no tingui permisos explícits per esborrar documents.
Important: l'operació d' eliminar expedient fa un esborrat físic de l'expedient i dels documents que aquest tingui associats. Aquesta operació per tant és irreversible i DESA'L no demanarà cap tipus de confirmació.
Així doncs, és responsabilitat del servei integrador implementar qualsevol política de confirmació amb l'usuari que demana l'operació i la implementació de qualsevol mecanisme de backup que pugui requerir, ja sigui dins el propi DESA'L o amb algun altre repositori extern.
| Element | Tipus paràmetre | Obligatori | Tipus camps | Mida màxima | Observacions |
|---|---|---|---|---|---|
| uuidExpedient | PathParam | Sí | Text | - | N/A |
| codiINE | QueryParam | Sí | Text | 10 | N/A |
| codiServei | QueryParam | Sí | Text | 10 | N/A |
A continuació es detallen els possibles codis de resposta de la petició d'eliminació d'expedient. Per al codi d'error 100, XXXXXX ofereix més detalls de l'error no controlat:
| Codi | Missatge |
|---|---|
| 0 | Operació realitzada correctament |
| 4 | Error: Petició mal formada. |
| 10 | Error: no tens autorització per realitzar aquesta operació. Operació NO realitzada. |
| 11 | Error: la petició no és correcta. Operació NO realitzada. |
| 12 | Error: l'expedient indicat no existeix al servei i organisme indicats. Operació NO realitzada. |
| 100 | Error no controlat: XXXXXX. Si us plau, reintenti l'operació en uns minuts. Operació NO realitzada. |
Aquest mètode síncron permet obtenir les metadades de l'expedient i dels documents associats a partir de l'UUIDExpedient.
La descàrrega d'expedients es pot realitzar independentment de l'estat en que es trobi l'expedient.
| Element | Tipus paràmetre | Obligatori | Tipus camps | Mida màxima | Observacions |
|---|---|---|---|---|---|
| uuidExpedient | PathParam | Sí | Text | - | N/A |
| codiINE | QueryParam | Sí | Text | 10 | N/A |
| codiServei | QueryParam | Sí | Text | 10 | N/A |
A continuació es detallen els possibles codis de resposta per a la descàrrega d'expedient:
| Codi | Missatge |
|---|---|
| 0 | Operació realitzada correctament. |
| 4 | Error: Petició mal formada. |
| 10 | Error: no tens autorització per realitzar aquesta operació. Operació NO realitzada. |
| 11 | Error: la petició no és correcta. Operació NO realitzada. |
| 12 | Error: l'expedient indicat no existeix en el servei i organisme indicats. Operació NO realitzada. |
| 100 | Error no controlat: XXXXXX. Si us plau, reintenti l'operació en uns minuts. Operació NO realitzada. |
Aquest mètode asíncron permet obtenir i descarregar en un fitxer ZIP les metadades de l'expedient i dels documents associats a partir de l'UUIDExpedient (Modalitat 1). De forma opcional permet també recuperar l'URL per poder descarregar tots els binaris dels documents (Modalitat 2). A diferència de la majoria de mètodes de l'API del DESA'L que treballen en format JSON, aquest mètode retorna la metadades en un fitxer XML que es troba dins el fitxer ZIP a descarregar.
La descàrrega d'expedients es pot realitzar independentment de l'estat en que es trobi l'expedient.
Tal i com indiquem, la descàrrega d'expedient es un procés asíncron. La resposta d'aquesta petició asíncrona retorna un codi de tiquet que ens servirà per poder consultar l'estat de la descàrrega i obtenir l'URL de descàrrega del fitxer ZIP tan bon punt estigui disponible. Per poder saber si el fitxer ZIP ja està disponible, DESA'L ofereix el mètode _ 5.6Consulta ticket _ que permet obtenir l'URL presignada per tal que l'integrador pugui descarregar el zip. Aquesta URL presignada té un temps d'expiració d'una hora, passat aquest temps no serà vàlida i s'haurà de tornar a realitzar una petició.
Aquesta modalitat permet descarregar un fitxer ZIP que conté únicament un fitxer XML amb totes les metadades de l'expedient i dels documents associats.
| Element | Tipus paràmetre | Obligatori | Tipus camps | Mida màxima | Observacions |
|---|---|---|---|---|---|
| uuidExpedient | PathParam | Sí | Text | -- | N/A |
| codiINE | QueryParam | Sí | Text | 10 | N/A |
| codiServei | QueryParam | Sí | Text | 10 | N/A |
| modality | QueryParam | Sí | Número | -- | Per a modalitat 1, indicar “1” |
Aquesta modalitat permet descarregar també un fitxer ZIP que conté el fitxer XML amb les metadades de l'expedient i dels documents associats, però el fitxer ZIP també conté el contingut dels fitxers vinculats amb els documents de l'expedient.
Important: Si l’antivirus no ha pogut finalitzar l’anàlisi d’algun dels fitxers, la descàrrega de l’expedient fallarà amb un codi d’error 1 - El contingut del fitxer està esperant a ser analitzat pel antivirus.
| Element | Tipus paràmetre | Obligatori | Tipus camps | Mida màxima | Observacions |
|---|---|---|---|---|---|
| uuidExpedient | PathParam | Sí | Text | - | N/A |
| codiINE | QueryParam | Sí | Text | 10 | N/A |
| codiServei | QueryParam | Sí | Text | 10 | N/A |
| modality | QueryParam | Sí | Número | - | Per a modalitat 2, indicar "2" |
A continuació es detallen els possibles codis de resposta per a la descàrrega de l'expedient en format ZIP:
| Codi | Missatge |
|---|---|
| 0 | Operació realitzada correctament. |
| 1 | Error: El contingut del fitxer està esperant a ser analitzat pel antivirus. |
| 4 | Error: Petició mal formada. |
| 10 | Error: no tens autorització per realitzar aquesta operació. Operació NO realitzada. |
| 11 | Error: la petició no és correcta. Operació NO realitzada. |
| 12 | Error: l'expedient indicat no existeix en el servei i organisme indicats. Operació NO realitzada. |
| 100 | Error no controlat: XXXXXX. Si us plau, reintenti l'operació en uns minuts. Operació NO realitzada. |
Per obtenir l'URL del fitxer ZIP dels mètodes asíncrons de l'API de DESA'L com la descàrrega d'expedient en format ZIP, la descàrrega d'expedient en format ENI o la descàrrega de document en format ENI, l'integrador haurà de realitzar un polling sobre el mètode de consulta de l'estat del ticket que retornen aquests mètodes asíncrons.
En el moment en que el fitxer ZIP estigui disponible, el mètode de consulta d'estat del ticket retornarà l'URL al fitxer ZIP. Si pel contrari el fitxer ZIP encara no està disponible.
| Element | Tipus paràmetre | Obligatori | Tipus camps | Mida màxima | Observacions |
|---|---|---|---|---|---|
| uuidExpedient | PathParam | Sí | Text | - | N/A |
| codiINE | QueryParam | Sí | Text | 10 | N/A |
| codiServei | QueryParam | Sí | Text | 10 | N/A |
| idTicket | QueryParam | Sí | Text | - | N/A |
A continuació es detallen els possibles codis de resposta per a la modificació de l'expedient (per al codi d'error 11, XXXXXX especifica la metadada informada malament i per al codi d'error 100 XXXXXX ofereix més detalls de l'error no controlat):
| Codi | Missatge |
|---|---|
| 0 | Petició disponible |
| 1 | Error: El contingut del fitxer està esperant a ser analitzat pel antivirus. |
| 4 | Error: Petició mal formada. |
| 10 | Error: no tens autorització per realitzar aquesta operació. Operació NO realitzada. |
| 11 | Error: la petició no és correcta (XXXXXX). Operació NO realitzada. |
| 100 | Error no controlat: XXXXXX. Si us plau, reintenti l`operació en uns minuts. Operació NO realitzada. |
Aquest mètode asíncron permet obtenir i descarregar l'expedient en format ENI (Esquema Nacional de Interoperabilidad) per poder exportar-ho i compartir-ho amb tercers. Les especificacions del format ENI per a expedients estan disponibles al següent enllaç:
DESA'L genera un XML d'acord a aquestes especificacions. L'XML inclou la informació detallada tant del propi expedient com de cadascun dels documents associats a aquest expedient. A més a més, s'inclou també un índex on es resumeix el contingut del fitxer ENI. D'aquesta forma si un expedient conté 10 documents associats, el fitxer XML amb format ENI contindrà les metadades de l'expedient, les metadades dels documents associats i l'índex (per exemple per un expedient amb 10 documents associats, tindríem 12 blocs de metadades: un per l'índex, un altre per a l'expedient i 10 per als documents).
De forma anàloga a la descàrrega de l'expedient en format ZIP, el procés de creació del fitxer ENI és asíncron. Per poder saber si el fitxer ENI ja està disponible i per poder recuperar-ho un cop ja ho estigui, el servei integrador ha d'executar la consulta d'estat del ticket (_ 5.6Consulta estat ticket _).
| Element | Tipus paràmetre | Obligatori | Tipus camps | Mida màxima | Observacions |
|---|---|---|---|---|---|
| uuidExpedient | PathParam | Sí | Text | - | N/A |
| codiINE | QueryParam | Sí | Text | 10 | N/A |
| codiServei | QueryParam | Sí | Text | 10 | N/A |
A continuació es detallen els possibles codis de resposta per a la descàrrega de l'expedient en format ENI:
| Codi | Missatge |
|---|---|
| 0 | Operació realitzada correctament. |
| 1 | Error: L'expedient existeix però alguns dels seus fitxers estan sent analitzats per l'antivirus. |
| 4 | Error: Petició mal formada. |
| 10 | Error: no tens autorització per realitzar aquesta operació. Operació NO realitzada. |
| 11 | Error: la petició no és correcta. Operació NO realitzada. |
| 12 | Error: l'expedient indicat no existeix en el servei i organisme indicats. Operació NO realitzada. |
| 100 | Error no controlat: XXXXXX. Si us plau, reintenti l'operació en uns minuts. Operació NO realitzada. |
Aquest mètode de l'API permet cercar tots aquells expedients que compleixen una sèrie de criteris de filtratge, informats a la petició.
La cerca es realitzarà aplicant tots aquests criteris de filtratge de manera conjuntiva (logical AND). No es suporta la realització de cerques aplicant els criteris de manera disjuntiva (logical OR) o la construcció de consultes complexes combinant ambdues lògiques.
El paràmetre modality indica si la cerca ha de retornar únicament les metadades dels expedients o si també ha de generar les URL pre-signades necessàries per a poder descarregar el contingut dels fitxers associats a aquests (per a aquells documents amb contingut = 1).
Amb la finalitat de garantir el rendiment i protegir el servei davant de sobrecàrregues no es retornaran més de 100 resultats per cerca.
L'URL corresponent a aquesta operació de l'API és:
https://{{host}}/expedient/search?codiServei={{codiServei}}&codiINE={{codiINE}}&modality={{modalitat}}| Element | Tipus paràmetre | Obligatori | Tipus camps | Observacions |
|---|---|---|---|---|
| codiINE | Query String | Si | Text | Codi d'organisme del requeridor |
| codiServei | Query String | Si | Text | Codi de servei del requeridor |
| modality | Query String | Si | Numèric |
|
| codiINE | Body | No | Text | -- |
| codiServei | Body | No | Text | -- |
| uuidExpedient | Body | No | Text | -- |
| sensibilitatDadesCaracterPersonal | Body | No | Text | -- |
| titol | Body | No | Text | -- |
| descripcio | Body | No | Text | -- |
| interessat | Body | No | Text | -- |
| dataAlta | Body | No | Bloc | Veure 5.8.1 |
| dataAlta.inici | Body | No | Numèric | -- |
| dataAlta.fi | Body | No | Numèric | -- |
| dataInici | Body | No | Bloc | Veure 5.8.2 |
| dataInici.inici | Body | No | Numèric | -- |
| dataInici.fi | Body | No | Numèric | -- |
| dataFi | Body | No | Bloc | Veure 5.8.3 |
| dataFi.inici | Body | No | Numèric | -- |
| dataFi.fi | Body | No | Numèric | -- |
| usuari | Body | No | Text | -- |
| unitatResponsable | Body | No | Text | -- |
| codiClassificacio | Body | No | Text | -- |
| nomClassificacio | Body | No | Text | -- |
| nivellAcces | Body | No | Text | -- |
| classificacioENS | Body | No | Text | -- |
| codiSIA | Body | No | Text | -- |
| infoAddicional | Body | No | Llista | Veure 5.8.4 |
| infoAddicional[].key | Body | No | Text | -- |
| infoAddicional[].value | Body | No | Text | -- |
| estatExpedient | Body | No | Text | -- |
| versioNTI | Body | No | Text | -- |
| identificador | Body | No | Text | -- |
| organ | Body | No | Text | -- |
| identificadorDesal | Body | No | Text | -- |
| documents[] | Body | No | Llista | Llista d'identificadors de documents Veure 5.8.5 |
NOTA: Per a la descripció dels camps dels expedients i el seu format consulteu l'apartat 2.2 d'aquest manual.
"dataAlta": {
"inici": 1652432260560,
"fi": 1652432264560
},"dataInici": {
"inici": 1652432260560,
"fi": 1652432264560
},"dataFi": {
"inici": 1652432260560,
"fi": 1652432264560
},"infoAddicional": [
{
"key": "clau_1",
"value": "valor_1"
}
]"documents": [
"11111111-1111-1111-1111-111111111111",
"22222222-2222-2222-2222-222222222222"
]{
"codiServei": "eVALISA",
"codiINE": "9821920002",
"dataAlta": {
"inici": 1658131385035,
"fi": 1658131405035
},
"dataInici": {
"inici": 1652432260560,
"fi": 1652432264560
},
"dataFi": {
"inici": 1652432250000,
"fi": 1652432270000
},
"infoAddicional": [
{
"key": "clau_1",
},
{
"value": "valor_1"
},
{
"key": "clau_3",
"value": "valor_3"
}
],
"documents": [
"11111111-1111-1111-1111-111111111111",
"22222222-2222-2222-2222-222222222222"
]
}| Element | Tipus paràmetre | Tipus camps | Observacions |
|---|---|---|---|
| totalResultats | Body | Text | -- |
| resultatsRecuperats | Body | Text | -- |
| codiResposta | Body | Text | -- |
| descripcioResposta | Body | Text | -- |
| expedients | Body | Llista | Llista d'expedients recuperats |
NOTA: Per a la descripció dels camps dels expedients i el seu format consulteu l'apartat 2.2 d'aquest manual.
{
"totalResultats": 1,
"resultatsRecuperats": 1,
"codiResposta": "0",
"descripcioResposta": "Operació realitzada correctament",
"expedients": [
{
"codiServei": "eVALISA",
"codiINE": "9821920002",
"uuidExpedient": "ef820562-9c7d-4ce6-b7a2-f6c716780739",
"titol": "Aquest és el títol de l'expedient amb una mida de fins a 500 caràcters",
"dataInici": 1628846943000,
"dataFi": 1640991599000,
"usuari": "11111111H - Usuari Peticionari Navegador",
"unitatResponsable": "Unitat responsable de l'expedient amb una mida màxima de 250 caràcters",
"codiClassificacio": "Codi de Classificació",
"nomClassificacio": "Nom Classificació",
"nivellAcces": "C",
"sensibilitatDadesCaracterPersonal": "Basic",
"estatExpedient": "E02",
"interessat": [
"82828282S",
"X4687141V"
],
"descripcio": "Aquesta és una descripció molt i molt llarga amb caràcters especials",
"infoAddicional": [
{
"key": "variableçÑ€%",
"value": "Paràmetre encoding conflictiu: çÑàa'()=?$€@ºª|!"
},
{
"key": "variable1Etiqueta",
"value": "Aquest és el literal"
}
],
"dataAlta": 1665062001619,
"versioNTI": "http://administracionelectronica.gob.es/ENI/XSD/v1.0/documento-e",
"identificador": "Aquest és l'identificador de l'expedient",
"organ": "A09018933",
"documents": [
{
"presentCSV": false,
"uuidFitxer": "f48a8443-d739-491a-905e-c13e111c2920",
"codiINE": "9821920002",
"codiServei": "eVALISA",
"nomNatural": "Primer document creat",
"infoAddicional": [
{
"key": "Clau Document1",
"value": "Encoding conflictiu: çÑàa'()=?$€@ºª|!"
}
],
"CSV": "9821920002061020222FD3E814B42D",
"formatFitxer": "plain/text",
"hash": "2CxqoTOg/CWwh/Rq1+0qMEJ3LmEuAVVx5hdT/1W6bag=",
"hashAlgoritme": "SHA-256",
"mida": 100,
"nomFitxer": "Primer document.pdf",
"dataAlta": 1665062001619,
"dataDocument": 1627131422000,
"contingut": "Fitxer",
"identificadorExpedientDesal": "ef820562-9c7d-4ce6-b7a2-f6c716780739",
"versioNTI": "http://administracionelectronica.gob.es/ENI/XSD/v1.0/documento-e",
"identificador": "ES_9821920002_2022_FBD38E4E-E2D4-4D27-B211-80229BF170FE",
"organ": "A09018933",
"estatElaboracio": "EE99",
"origen": true,
"tipusDocumental": "TD10",
"tipusSignatura": "TF06",
"interessat": [
"82828282S"
],
"codiResposta": "0",
"uuidDocument": "fbd38e4e-e2d4-4d27-b211-80229bf170fe"
},
{
"presentCSV": false,
"codiINE": "9821920002",
"codiServei": "eVALISA",
"nomNatural": "Segon document creat dins l'expedient amb el JSON de càrrega d'expedient",
"sensibilitatDadesCaracterPersonal": "Alt",
"documentEssencial": false,
"idioma": "fr_FR",
"codiClassificacio": "Codi de Classificació inventat per SGP amb 50 chrs",
"nomClassificacio": "Nom Classificació inventat per SGP amb una longitud de 250",
"codiSIA": "SIA inventat per SGP amb longitud de 50 caràcters",
"CSV": "9821920002061020226961679AE9B5",
"URLDocumentExtern": "https://www.URLExternaInventadaperSGP.com/234234a",
"dataAlta": 1665062001647,
"dataDocument": 1626269354000,
"contingut": "URL",
"identificadorExpedientDesal": "ef820562-9c7d-4ce6-b7a2-f6c716780739",
"versioNTI": "http://administracionelectronica.gob.es/ENI/XSD/v1.0/documento-e",
"identificador": "ES_9821920002_2022_EFEA840C-5287-407A-9924-BDAD2116BA7A",
"organ": "A09018933",
"estatElaboracio": "EE02",
"origen": false,
"tipusDocumental": "TD01",
"tipusSignatura": "TF01",
"CSVSignatura": "CSVSIG_1d8164ea-6a13-423c-9fde-5fa3e4288229",
"regulacioGeneracioCSVSignatura": "Sembla que la validació d'aquest camp es fa correctament. Aquest camp ha d'informar-se de forma obligatòria si el camp 'tipusSignatura' té el valor TF01.",
"identificadorDocumentOrigen": "06ca9170-9729-449c-bbc5-fe4c86e78cd8",
"tipusDocumentalSICRES": "03",
"descripcio": "Aquesta és una descripció molt i molt llarga amb caràcters especials ñÑçÇàÀüÜ{}[]()/&%$€·l'#ºª|!",
"nivellAcces": "B",
"classificacioENS": "Baix",
"usuari": "Nom Cognom1 Cognom2 del funcionari",
"numeroRegistre": "E/541412123/2021",
"codiResposta": "0",
"uuidDocument": "efea840c-5287-407a-9924-bdad2116ba7a"
}
],
"classificacioENS": "Mig"
}
]
}A continuació es detallen els possibles codis de resposta per a l'operació de cerca d'expedients:
| Codi | Missatge |
|---|---|
| 0 | Operació realitzada correctament. |
| 4 | Error: Petició mal formada. |
| 10 | Error: no tens autorització per realitzar aquesta operació. Operació NO realitzada. |
| 100 | Error no controlat: XXXXXX. Si us plau, reintenti l'operació en uns minuts. Operació NO realitzada. |
Aquest mètode asíncron permet obtenir i descarregar en un únic fitxer ZIP, un fitxer XML per a cada expedient indicat incloent tant les metadades de l'expedient com dels documents associats (Modalitat 1). De forma opcional (Modalitat 2) es permet recuperar també els binaris dels documents associats a cadascun dels expedients indicats. A diferència de la majoria de mètodes de l'API del DESA'L que treballen en format JSON, aquest mètode retorna les metadades en fitxers XML que es troben dins el fitxer ZIP a descarregar.
La descàrrega d'expedients es pot realitzar independentment de l'estat en que es trobi l'expedient.
Tal i com indiquem, la descàrrega d'expedients es un procés asíncron. La resposta d'aquesta petició asíncrona retorna un codi de tiquet que ens servirà per poder consultar l'estat de la descàrrega i obtenir l'URL de descàrrega del fitxer ZIP tan bon punt estigui disponible. Per poder saber si el fitxer ZIP ja està disponible, DESA'L ofereix el mètode 5.6 Consulta ticket que permet obtenir l'URL presignada per tal que l'integrador pugui descarregar el zip. Aquesta URL presignada té un temps d'expiració d'una hora (passat aquest temps, l'URL deixarà de ser vàlida).
Aquesta modalitat permet descarregar un fitxer ZIP que conté els fitxers XML amb totes les metadades dels expedients i dels documents associats.
| Element | Tipus paràmetre | Obligatori | Tipus camps | Mida màxima | Observacions |
|---|---|---|---|---|---|
| uuidExpedient | Body | Sí | Llista | -- | N/A |
| codiINE | QueryParam | Sí | Text | 10 | N/A |
| codiServei | QueryParam | Sí | Text | 10 | N/A |
| modality | QueryParam | Sí | Número | 1 | Per a modalitat 1, indicar “1” |
L'URL corresponent a aquesta operació de l'API és:
https://{{host}}/expedient/downloadExpedients?codiServei={{codiServei}}&codiINE={{codiINE}}&modality=1El body de la petició quedaria:
{
"uuidExpedient": ["b666bad8-89a3-4c31-9037-734ab6d4167c","2b147889-efb2-47cf-af56-d0c5b33204fe"]
}{
"codiResposta": "0",
"descripcioResposta": "Operació realitzada correctament",
"idTicket": "326f81a8-b51d-4b9d-875a-df33d117f7eb"
}Aquesta modalitat permet descarregar també un fitxer ZIP que conté els fitxers XML amb les metadades dels expedients i dels documents associats, i a més a més s'inclou dins el fitxer ZIP els binaris dels documents associats als expedients indicats per l'integrador.
Important: Si l'antivirus no ha pogut finalitzar l'anàlisi d'algun dels fitxers, la descàrrega dels expedients fallarà amb un codi d’error 1 - El contingut del fitxer està esperant a ser analitzat pel antivirus.
| Element | Tipus paràmetre | Obligatori | Tipus camps | Mida màxima | Observacions |
|---|---|---|---|---|---|
| uuidExpedient | Body | Sí | Llista | - | N/A |
| codiINE | QueryParam | Sí | Text | 10 | N/A |
| codiServei | QueryParam | Sí | Text | 10 | N/A |
| modality | QueryParam | Sí | Número | 1 | Per a modalitat 2, indicar “2” |
L'URL corresponent a aquesta operació de l'API és:
https://{{host}}/expedient/downloadExpedients?codiServei={{codiServei}}&codiINE={{codiINE}}&modality=2El contingut de la petició quedaria:
{
"uuidExpedient": ["4e2351aa-89d4-4c3f-b94d-5f137a02220c","717873d4-1632-432a-8bfc-c5837029c7a4"]
}{
"codiResposta": "0",
"descripcioResposta": "Operació realitzada correctament",
"idTicket": "9c92cfc2-7658-428b-9842-119946cc5061"
}
A continuació es detallen els possibles codis de resposta per a la descàrrega dels expedients en format ZIP:
| Codi | Missatge |
|---|---|
| 0 | Operació realitzada correctament. |
| 1 | Error: El contingut del fitxer està esperant a ser analitzat pel antivirus. |
| 4 | Error: Petició mal formada. |
| 10 | Error: no tens autorització per realitzar aquesta operació. Operació NO realitzada. |
| 11 | Error: la petició no és correcta. Operació NO realitzada. |
| 12 | Error: l'expedient indicat no existeix en el servei i organisme indicats. Operació NO realitzada. |
| 100 | Error no controlat: XXXXXX. Si us plau, reintenti l'operació en uns minuts. Operació NO realitzada. |
Aquest mètode permet afegir un conjunt de documents a un expedient existent. Els documents es poden crear de nou en la mateixa petició (Modalitat 1) o bé poden ser documents ja existents que es volen associar a l'expedient (Modalitat 2)
Tant la Modalitat 1 com la Modalitat 2, són mètodes atòmics i per tant o bé s'afegiran tots els documents indicats per l'integrador, o bé es retornarà un codi d'error i no s'afegirà cap.
Aquesta modalitat permet crear els documents i associar-los a l'expedient. El funcionament d'aquesta modalitat és molt similar al mètode 6.1 Alta de Document i en aquest apartat es pot consultar el contingut de la llista documents
| Element | Tipus paràmetre | Obligatori | Tipus camps | Mida màxima | Observacions |
|---|---|---|---|---|---|
| codiServei | QueryParam | Sí | Text | 10 | -- |
| codiINE | QueryParam | Sí | Text | 10 | -- |
| modality | QueryParam | Sí | Número | -- | Per a modalitat 1, indicar “1” |
| uuidExpedient | Body | Sí | Text | -- | -- |
| documents | Body | Sí | Llista | -- | -- |
L'URL corresponent a aquesta operació de l'API és:
https://{{host}}/expedient/addDocuments?codiServei={{codiServei}}&codiINE={{codiINE}}&modality=1El contingut de la petició quedaria:
{
"uuidExpedient": "ec86ee01-089f-4afd-95c6-eff95922197c",
"documents": [ {
"codiServei": "eVALISA",
"codiINE": "9611660009",
"contingut": "1",
"uuidFitxer": "ffbb106c-8fdd-476d-ade4-e1322f4c441f",
"nomFitxer": "Primer document.pdf",
"nomNatural": "Primer document creat",
"infoAddicional": [
{"key": "Clau Document1", "value": "Encoding conflictiu: çÑàa'()=?$€@ºª|!"}
],
"dataDocument": "24/07/2021 14:57:02",
"estatElaboracio": "EE99",
"origen": true,
"tipusDocumental": "TD10",
"tipusSignatura": "TF06",
"interessat": ["82828282S"]
}, {
"codiServei": "eVALISA",
"codiINE": "7515093734",
"contingut": "2",
"urlDocumentExtern": "https://www.URLExternaInventadaperSGP.com/234234a",
"nomNatural": "Segon document creat dins l'expedient amb el JSON de càrrega d'expedient",
"dataDocument": "14/07/2021 15:29:14",
"estatElaboracio": "EE02",
"identificadorDocumentOrigen": "06ca9170-9729-449c-bbc5-fe4c86e78cd8",
"origen": false,
"tipusDocumental": "TD01",
"tipusSignatura": "TF01",
"cSVSignatura" : "CSVSIG_123",
"regulacioGeneracioCSVSignatura": "Sembla que la validació d'aquest camp es fa correctament. Aquest camp ha d'informar-se de forma obligatòria si el camp 'tipusSignatura' té el valor TF01.",
"tipusDocumentalSICRESD": "03",
"usuari": "Nom Cognom1 Cognom2 del funcionari",
"numeroRegistre": "E/541412123/2021",
"descripcio": "Aquesta és una descripció molt i molt llarga amb caràcters especials ñÑçÇàÀüÜ{}[]()/&%$€·l'#ºª|!",
"nivellAcces": "B",
"clasificacioENS": "Baix",
"sensibilitatDadesCaracterPersonal": "Alt",
"documentEssencial": false,
"idioma": "fr_FR",
"codiClassificacio": "Codi de Classificació inventat per SGP amb 50 chrs",
"nomClassificacio": "Nom Classificació inventat per SGP amb una longitud de 250",
"codiSIA": "SIA inventat per SGP amb longitud de 50 caràcters"
}
]
}{
"uuidExpedient": "ec86ee01-089f-4afd-95c6-eff95922197c",
"codiServei": "eVALISA",
"codiINE": "9821920002",
"dataAlta": 1668095268640,
"versioNTI": "http://administracionelectronica.gob.es/ENI/XSD/v1.0/documento-e",
"organ": "A09018933",
"identificadorDesal": "ES_9821920002_2023_ec86ee01-089f-4afd-95c6-eff95922197c",
"codiResposta": "0",
"descripcioResposta": "Operació realitzada correctament",
"documents": [
{
"uuidDocument": "4b91eb53-b1d8-4a7b-9639-68e1e47090b7",
"uuidFitxer": "ffbb106c-8fdd-476d-ade4-e1322f4c441f",
"codiINE": "9611660009",
"codiServei": "eVALISA",
"nomNatural": "Primer document creat",
"infoAddicional": [
{
"key": "Clau Document1",
"value": "Encoding conflictiu: çÑàa'()=?$€@ºª|!"
}
],
"CSV": "9611660009040120231A2435680560",
"formatFitxer": "application/pdf",
"hash": "zkRAhVa0azZ6yg2j+C/3xilRaoGoY7jFnFrzmB1vCCM=",
"hashAlgoritme": "SHA-256",
"mida": 992029,
"nomFitxer": "Primer document.pdf",
"dataAlta": 1672851441957,
"dataDocument": 1627131422000,
"contingut": "1",
"identificadorExpedientDesal": "ec86ee01-089f-4afd-95c6-eff95922197c",
"versioNTI": "http://administracionelectronica.gob.es/ENI/XSD/v1.0/documento-e",
"identificador": "ES_9611660009_2023_4B91EB53-B1D8-4A7B-9639-68E1E47090B7",
"organ": "A09002979",
"estatElaboracio": "EE99",
"origen": true,
"tipusDocumental": "TD10",
"tipusSignatura": "TF06",
"codiResposta": "0",
"descripcioResposta": "Operació realitzada correctament",
"interessat": [
"82828282S"
]
},
{
"uuidDocument": "63eb19e3-7dfc-4fde-9b35-c9853b19f53f",
"codiINE": "7515093734",
"codiServei": "eVALISA",
"nomNatural": "Segon document creat dins l'expedient amb el JSON de càrrega d'expedient",
"sensibilitatDadesCaracterPersonal": "Alt",
"documentEssencial": false,
"idioma": "fr_FR",
"codiClassificacio": "Codi de Classificació inventat per SGP amb 50 chrs",
"nomClassificacio": "Nom Classificació inventat per SGP amb una longitud de 250",
"codiSIA": "SIA inventat per SGP amb longitud de 50 caràcters",
"CSV": "7515093734040120234D94B440C845",
"URLDocumentExtern": "https://www.URLExternaInventadaperSGP.com/234234a",
"dataAlta": 1672851442635,
"dataDocument": 1626269354000,
"contingut": "2",
"identificadorExpedientDesal": "ec86ee01-089f-4afd-95c6-eff95922197c",
"versioNTI": "http://administracionelectronica.gob.es/ENI/XSD/v1.0/documento-e",
"identificador": "ES_7515093734_2023_63EB19E3-7DFC-4FDE-9B35-C9853B19F53F",
"organ": "A09006457",
"estatElaboracio": "EE02",
"origen": false,
"tipusDocumental": "TD01",
"tipusSignatura": "TF01",
"CSVSignatura": "CSVSIG_123",
"regulacioGeneracioCSVSignatura": "Sembla que la validació d'aquest camp es fa correctament. Aquest camp ha d'informar-se de forma obligatòria si el camp 'tipusSignatura' té el valor TF01.",
"identificadorDocumentOrigen": "06ca9170-9729-449c-bbc5-fe4c86e78cd8",
"tipusDocumentalSICRES": "03",
"descripcio": "Aquesta és una descripció molt i molt llarga amb caràcters especials ñÑçÇàÀüÜ{}[]()/&%$€·l'#ºª|!",
"nivellAcces": "B",
"classificacioENS": "Baix",
"codiResposta": "0",
"descripcioResposta": "Operació realitzada correctament",
"usuari": "Nom Cognom1 Cognom2 del funcionari",
"numeroRegistre": "E/541412123/2021"
}
]
}Aquesta modalitat permet associar un conjunt de documents ja existents a un expedient.
| Element | Tipus paràmetre | Obligatori | Tipus camps | Mida màxima | Observacions |
|---|---|---|---|---|---|
| codiServei | QueryParam | Sí | Text | 10 | -- |
| codiINE | QueryParam | Sí | Text | 10 | -- |
| modality | QueryParam | Sí | Número | -- | Per a modalitat 2, indicar “2” |
| uuidExpedient | Body | Sí | Text | -- | -- |
| uuidDocument | Body | Sí | Llista | -- | -- |
L'URL corresponent a aquesta operació de l'API és:
https://{{host}}/expedient/addDocuments?codiServei={{codiServei}}&codiINE={{codiINE}}&modality=2El contingut de la petició quedaria:
{
"uuidExpedient": "dbcd48f4-2d8d-45ae-a130-a43b84eabef1",
"uuidDocument": [
"b00dd6b9-ef86-4911-a67f-ae476facd5e2","b00dd6b9-ef86-4911-a67f-ae476facd5e2"
]
}{
"uuidExpedient": "dbcd48f4-2d8d-45ae-a130-a43b84eabef1",
"codiServei": "eVALISA",
"codiINE": "9821920002",
"dataAlta": 1672829432502,
"versioNTI": "http://administracionelectronica.gob.es/ENI/XSD/v1.0/documento-e",
"identificadorDesal": "ES_9821920002_2023_dbcd48f4-2d8d-45ae-a130-a43b84eabef1",
"codiResposta": "0",
"descripcioResposta": "Operació realitzada correctament",
"documents": [
{
"uuidDocument": "b00dd6b9-ef86-4911-a67f-ae476facd5e2",
"codiINE": "1722660009",
"codiServei": "eNOTUM",
"codiResposta": "0",
"descripcioResposta": "Operació realitzada correctament"
}
]
}A continuació es detallen els possibles codis de resposta per a la modificació dels expedients (per al codi d'error 11, XXXXXX especifica la metadada en qüestió i per al codi d'error 100 XXXXXX ofereix més detalls de l'error no controlat):
| Codi | Missatge |
|---|---|
| 0 | Operació realitzada correctament. |
| 4 | Error: Petició mal formada. |
| 10 | Error: no tens autorització per realitzar aquesta operació. Operació NO realitzada. |
| 11 | Error: la petició no és correcta. Hi ha metadades obligatòries sense informar o metadades informades no vàlides (XXXXXX). Operació NO realitzada. |
| 12 | Error: l'expedient no existetix al servei o organisme indicats. Operació NO realitzada. |
| 100 | Error no controlat: XXXXXX. Si us plau, reintenti l'operació en uns minuts. Operació NO realitzada. |
El document és l'entitat essencial del DESA'L. Està format per un conjunt de metadades i la relació amb un i només un fitxer de DESA'L. DESA'L també permet gestionar documents on el binari no es custodia al propi repositori del DESA'L, sinó que està hostatjat en un repositori extern. En aquests casos al document de DESA'L només es guarda la referència al repositori extern ja sigui a través d'una URL externa o d'un CSV del repositori extern.
El document és l'entitat d'alt nivell amb la que realment han de treballar en tot moment els integradors. DESA'L permet que un mateix fitxer (binari PDF, Word, ...) estigui referenciat per més d'un document i que cadascun d'aquests documents pugui tenir uns permisos i unes polítiques de retenció pròpies. D'altra banda, un document de DESA'L pot pertànyer de forma opcional a un, i només un, expedient.
Per poder crear un document a DESA'L prèviament cal carregar el seu contingut com a fitxer amb el mètode de càrrega de fitxer (_ 4.1Càrrega de fitxer _), però un cop creat el document hem de realitzar totes les gestions a nivell de document i deixar totalment de banda la capa de fitxer que és de baix nivell.
DESA'L contempla 2 models de metadades a nivell de document: bàsic i complet (el model complet hereta del model bàsic i per tant incorpora totes les seves metadades). El servei integrador haurà de consensuar amb els responsables del DESA'L quin d'aquests 2 models de metadades ha de fer servir per a la creació dels seus documents. Aquesta decisió es molt important per què un cop enregistrat el servei integrador a DESA'L no es podrà modificar el model de metadades dels seus documents.
Aquest mètode de l'API permet la creació d'un nou document associat a un servei, incorporant les seves metadades.
Un document pot estar vinculat o no a un expedient. La relació entre el document i l'expedient amb el que està vinculat s'estableix amb la metadada _ IdentificadorExpedientDesal _ del document. Aquesta metadada és opcional perquè un document pot estar associat a un expedient DESA'L, a un expedient extern (en aquest cas el vincle s'estableix amb la metadada _ IdentificadorExpedientExtern _, cal destacar que DESA'L no realitza cap tipus de validació del contingut d'aquesta metadada) o directament no estar vinculat a cap tipus d'expedient. En qualsevol moment es poden modificar aquestes metadades per establir un nou vincle entre el document i l'expedient, o bé per eliminar el vincle entre ells.
La relació entre un document i el seu contingut (fitxer) es realitza a partir de la metadada _ Contingut _ que pot tenir 3 possibles valors i que requereix que el servei integrador informi una i només una de les següents metadades:
- És el cas més comú: el contingut del document està hostatjat al propi DESA'L amb un fitxer. El vincle entre el document i el fitxer s'estableix definint la metadada _ UUIDFitxer _ del document. És important destacar que abans de poder crear el document, el servei integrador ha d'haver carregat el fitxer a DESA'L.
- El contingut del document està hostatjat en algun repositori extern i és accessible a través d'una URL que s'informa en la metadada _ URLDocumentExtern _. DESA'L però, no realitza cap tipus de validació d'aquesta URL i tampoc comprova que l'URL estigui realment disponible.
- El contingut del document està hostatjat en algun repositori extern i és accessible a través d'un identificador únic, o CSV, extern que el servei integrador controla. Aquest CSV s'informa en la metadada _ URLDocumentExtern. _ DESA'L però no realitza cap tipus de validació d'aquest CSV i tampoc comprova que el CSV existeixi.
| Element | Tipus paràmetre | Obligatori | Tipus camps | Mida màxima | Observacions |
|---|---|---|---|---|---|
| codiINE | Body | Si | Text | 10 | -- |
| codiServei | Body | Si | Taula | 10 | -- |
| nomFitxer | Body | Condicional | Text | 250 | Només s'informa si contingut igual a 1 |
| nomNatural | Body | Si | Text | 500 | Nom natural (sense extensió) |
| dataDocument | Body | Si | Data i hora | -- | Format: DD/MM/AAAA HH:mm:SS |
| contingut | Body | Si | Text | -- | -- |
| interessat | Body | Si | Llista | 20 | Llista d'interessats |
| usuari | Body | Si | Text | 250 | Dades identificatives qui crea el document |
| numeroRegistre | Body | Si | Text | 100 | -- |
| CSV | Body | Si | Text | 100 | -- |
| identificadorExpedientDesal | Body | Si | Text | 100 | -- |
| identificadorExpedientExtern | Body | Si | Text | 100 | -- |
| UUIDFitxer | Body | Condicional | Text | 20 | Només s'informa si contingut igual a 1 |
| URLDocumentExtern | Body | Condicional | URI | Només s'informa si contingut igual a 2 | |
| identificadorDocumentExtern | Body | Condicional | Text | 100 | Només s'informa si contingut igual a 3 |
| infoAddicional | Body | No | Llista | -- | Llista d'elements clau/valor |
| Element | Tipus paràmetre | Obligatori | Tipus camps | Mida màxima | Observacions |
|---|---|---|---|---|---|
| codiINE | Body | Si | Text | 10 | -- |
| codiServei | Body | Si | Taula | 10 | -- |
| nomFitxer | Body | Condicional | Text | 250 | Només s'informa si contingut igual a 1 |
| nomNatural | Body | Si | Text | 500 | Nom natural (sense extensió) |
| dataDocument | Body | Si | Data i hora | -- | Format: DD/MM/AAAA HH:mm:SS |
| contingut | Body | Si | Text | -- | -- |
| interessat | Body | Si | Llista | 20 | Llista d'interessats |
| usuari | Body | Si | Text | 250 | Dades identificatives qui crea el document |
| numeroRegistre | Body | Si | Text | 100 | -- |
| CSV | Body | Si | Text | 100 | -- |
| identificadorExpedientDesal | Body | Si | Text | 100 | -- |
| identificadorExpedientExtern | Body | Si | Text | 100 | -- |
| UUIDFitxer | Body | Condicional | Text | 20 | Només s'informa si contingut igual a 1 |
| URLDocumentExtern | Body | Condicional | URI | Només s'informa si contingut igual a 2 | |
| identificadorDocumentExtern | Body | Condicional | Text | 100 | Només s'informa si contingut igual a 3 |
| infoAddicional | Body | No | Llista | -- | Llista d'elements clau/valor |
| estatElaboracio | Body | Si | Text | -- |
|
| origen | Body | Si | boolea | -- | false= Ciutadà, true=Administració |
| tipusDocumental | Body | Si | Text | -- |
|
| tipusSignatura | Body | Si | Text | -- |
|
| CSVSignatura | Body | Condicional | Text | 100 | S'informa si TipoFirma =TF01 |
| regulacioGeneracioCSVSignatura | Body | Condicional | Text | 500 | S'informa si TipoFirma =TF01 |
| referenciaSignatura | Body | Condicional | Text | 100 | Només cas TF02 i TF04. Referencia al fitxer que inclou la signatura (UUID - fitxer) |
| identificadorDocumentOrigen | Body | Condicional | Text | 250 | Només si s'ha indicat EE02,EE03 i EE04 a EstadoElaboracion |
| descripcio | Body | No | Text | 500 | -- |
| nivellAcces | Body | No | Enum | -- |
|
| clasificacioENS | Body | No | Enum | -- | Baix, Mig, Alt |
| sensibilitatDadesCaracterPersonal | Body | No | Enum | -- | Basic, Mig, Alt |
| documentEssencial | Body | No | boolea | -- | True (si), False (NO) |
| idioma | Body | No | Text | 50 | -- |
| codiClassificacio | Body | No | Text | 50 | -- |
| nomClassificacio | Body | No | Text | 250 | -- |
| codiSIA | Body | No | Text | 50 | -- |
A continuació es detallen els possibles codis de resposta per l'alta de document (per al codi d'error 11, XXXXXX especifica la metadada en qüestió i per al codi d'error 100 XXXXXX ofereix més detalls de l'error no controlat):
| Codi | Missatge |
|---|---|
| 0 | Operació realitzada correctament. |
| 1 | El document és correcte però el fitxer encara està sent analitzat per l'antivirus. |
| 2 | Error: El contingut del fitxer encara no ha estat carregat a S3. |
| 4 | Error: Petició mal formada. |
| 10 | Error: no tens autorització per realitzar aquesta operació. Operació NO realitzada. |
| 11 | Error: la petició no és correcta. Hi ha metadades obligatòries sense informar o metadades informades no vàlides (XXXXXX). Operació NO realitzada. |
| 12 | Error: el número d'expedient indicat no existeix en el servei i organisme indicats. Operació NO realitzada. |
| 13 | Error: el fitxer físic indicat no existeix. Operació NO realitzada. |
| 14 | Error: el fitxer físic conté virus i ha estat eliminat. Operació NO realitzada. |
| 100 | Error no controlat: XXXXXX. Si us plau, reintenti l'operació en uns minuts. Operació NO realitzada. |
| 101 | Error: el document físic indicat està en procés de validació. Si us plau, reintenta l'operació en uns minuts. Operació NO realitzada. |
Aquest mètode permet realitzar la modificació de les metadades editables d'un document. Donat que el vincle entre el document i l'expedient al que està associat (_ IdentificadorExpedientDesal ), o el vincle entre el document i el fitxer que defineix el contingut ( UUIDFitxer _) són metadades, aquest és el mètode que el servei integrador ha d'executar per poder actualitzar el contingut binari del document o l'expedient amb el que està associat el document.
DESA'L comprovarà que totes les metadades que el servei integrador vol actualitzar realment siguin editables i en cas contrari rebutjarà la totalitat de l'operació. El servei integrador només ha d'informar en aquesta petició les metadades que necessita actualitzar, doncs DESA'L no modificarà la resta de metadades.
Si el servei integrador vol eliminar una metadada (p. ex. per eliminar el vincle entre el document i l'expedient) podrà fer-ho informant explícitament un _ null _ en la metadada en qüestió (o una cadena buida si la metadada és de tipus Text).
Important: Si el servei integrador actualitza la metadada _ UUIDFitxer _ d'un document per actualitzar el contingut binari d'aquest, DESA'L comprovarà si hi ha algun altre document que referenciï a aquest fitxer. En cas contrari, eliminarà el fitxer de forma irreversible.
El següent diagrama mostra les 2 possibilitats amb les que es pot trobar DESA'L en el moment de modificar la metadada _ UUIDFitxer _ i com actua en cada cas:
En la resposta del mètode de modificació de document, DESA'L retorna totes les metadades del document tal i com han quedat després de l'execució d'aquest mètode.
| Element | Tipus paràmetre | Obligatori | Tipus camps | Mida màxima | Observacions |
|---|---|---|---|---|---|
| uuidDocument | PathParam | Sí | Text | -- | -- |
| codiINE | QueryParam | Sí | Text | 10 | -- |
| nomFitxer | Body | No | Text | 250 | -- |
| nomNatural | Body | No | Text | 500 | -- |
| dataDocument | Body | No | Data i hora | -- | Format: DD/MM/AAAA HH:mm:SS |
| interessat | Body | No | Text | -- | Llista d'interessats |
| numeroRegistre | Body | No | Text | -- | -- |
| identificadorExpedientDesal | Body | No | Text | -- | -- |
| identificadorExpedientExtern | Body | No | Text | -- | -- |
| UUIDFitxer | Body | No | Text | -- | -- |
| URLDocumentExtern | Body | No | Text | -- | -- |
| identificadorDocumentExtern | Body | No | Text | -- | -- |
| estatElaboracio | Body | No | Text | -- |
|
| origen | Body | No | Boolean | -- | false= Ciudadàtrue=Administració |
| tipusDocumental | Body | No | Text | -- |
|
| tipusSignatura | Body | No | Text | -- |
|
| CSVSignatura | Body | No | Text | -- | S'informa si a TipoFirma =TF01 |
| regulacioGeneracioCSVSignatura | Body | No | Text | -- | S'informa si a TipoFirma =TF01 |
| referenciaSignatura | Body | No | Text | -- | Només cas TF02 i TF04. Referencia al fitxer que inclou la signatura (uuidFitxer) |
| identificadorDocumentOrigen | Body | No | Text | -- | Identificador normalizat del document origen al que correspon la copia. Només si s'ha indicat EE02,EE03 i EE04 a EstadoElaboracion |
| descripcio | Body | No | Text | -- | -- |
| nivellAcces | Body | No | Text | -- |
|
| clasificacioENS | Body | No | Text | -- | Baix, Mig, Alt |
| sensibilitatDadesCaracterPersonal | Body | No | -- | -- | Basic, Mig, Alt |
| documentEssencial | Body | No | -- | -- | True (si), False (NO) |
| codiClassificacio | Body | No | -- | -- | -- |
| nomClassificacio | Body | No | -- | -- | -- |
| codiSIA | Body | No | -- | -- | -- |
| infoAddicional | Body | No | Llista | -- | Llista d'elements clau/valor |
A continuació es detallen els possibles codis de resposta per la modificació del document (per al codi d'error 11, XXXXXX especifica la metadada en qüestió i per al codi d'error 100 XXXXXX ofereix més detalls de l'error no controlat):
| Codi | Missatge |
|---|---|
| 0 | Operació realitzada correctament. |
| 1 | El document és correcte però el fitxer encara està sent analitzat per l'antivirus |
| 2 | Error: No s'ha fet el put del fitxer a S3 (URL-Presigned) |
| 4 | Error: Petició mal formada |
| 10 | Error: no tens autorització per realitzar aquesta operació. Operació NO realitzada. |
| 11 | Error: la petició no és correcta. Hi ha metadades obligatòries sense informar o metadades informades no vàlides (XXXXXX). Operació NO realitzada. |
| 12 | Error: el número d'expedient indicat no existeix en el servei i organisme indicats. Operació NO realitzada. |
| 13 | Error: el fitxer físic indicat no existeix. Operació NO realitzada. |
| 14 | Error: el fitxer físic conté virus i ha estat eliminat. Operació NO realitzada. |
| 100 | Error no controlat: XXXXXX. Si us plau, reintenti l'operació en uns minuts. Operació NO realitzada. |
| 101 | Error: el document físic indicat està en procés de validació. Si us plau, reintenta l'operació en uns minuts. Operació NO realitzada. |
Aquest mètode permet eliminar un document, i en cascada, el propi fitxer associat si aquest només està referenciat pel document en qüestió.
Important: Si el servei integrador elimina un document i aquest està associat a un fitxer a través de la metadada UUIDFitxer, DESA'L comprovarà si hi ha algun altre document que referenciï a aquest fitxer. En cas contrari, eliminarà el fitxer de forma irreversible.
El següent diagrama mostra les 2 possibilitats amb les que es pot trobar DESA'L en el moment d'eliminar el document si aquest està associat amb un fitxer a través de la metadada UUIDFitxer:
| Element | Tipus paràmetre | Obligatori | Tipus camps | Mida màxima | Observacions |
|---|---|---|---|---|---|
| uuidDocument | PathParam | Sí | Text | -- | -- |
| codiINE | QueryParam | Sí | Text | 10 | -- |
| codiServei | QueryParam | Sí | Text | 10 | -- |
A continuació es detallen els possibles codis de resposta per l'eliminació de document (per al codi d'error 11, XXXXXX especifica la metadada en qüestió i per al codi d'error 100 XXXXXX ofereix més detalls de l'error no controlat):
| Codi | Missatge |
|---|---|
| 0 | Operació realitzada correctament. |
| 4 | Error: Petició mal formada. |
| 10 | Error: no tens autorització per realitzar aquesta operació. Operació NO realitzada. |
| 11 | Error: la petició no és correcta. Hi ha metadades obligatòries sense informar o metadades informades no vàlides (XXXXXX). Operació NO realitzada. |
| 12 | Error: el número d'expedient indicat no existeix en el servei i organisme indicats. Operació NO realitzada. |
| 13 | Error: el fitxer físic indicat no existeix. Operació NO realitzada. |
| 14 | Error: el fitxer físic conté virus i ha estat eliminat. Operació NO realitzada. |
| 100 | Error no controlat: XXXXXX. Si us plau, reintenti l'operació en uns minuts. Operació NO realitzada. |
| 101 | Error: el document físic indicat està en procés de validació. Si us plau, reintenta l'operació en uns minuts. Operació NO realitzada. |
Aquest mètode permet eliminar diversos documents. De forma anàloga al mètode 6.3 Eliminació de Document , s'esborraran en cascada els fitxers que estiguin associats a un únic document.
Aquest mètode és atòmic i per tant o bé s'esborraran tots els documents indicats per l'integrador, o bé es retornarà un codi d'error i no s'esborrarà cap.
| Element | Tipus paràmetre | Obligatori | Tipus camps | Mida màxima | Observacions |
|---|---|---|---|---|---|
| uuidDocument | Body | Sí | Llista | -- | -- |
| codiINE | QueryParam | Sí | Text | 10 | -- |
| codiServei | QueryParam | Sí | Text | 10 | -- |
L'URL corresponent a aquesta operació de l'API és:
https://{{host}}/document/deleteDocuments?codiServei={{codiServei}}&codiINE={{codiINE}}El contingut de la petició quedaria:
{
"uuidDocument": ["1a6648d1-0e98-463f-93c4-cc468dbcd1e8","b6815ee4-b83f-4218-8240-54eae6be1d67"]
}{
"codiResposta": "0",
"descripcioResposta": "Operació realitzada correctament"
}A continuació es detallen els possibles codis de resposta per l'eliminació de documents (per al codi d'error 11, XXXXXX especifica la metadada en qüestió i per al codi d'error 100 XXXXXX ofereix més detalls de l'error no controlat):
| Codi | Missatge |
|---|---|
| 0 | Operació realitzada correctament. |
| 4 | Error: Petició mal formada. |
| 10 | Error: no tens autorització per realitzar aquesta operació. Operació NO realitzada. |
| 11 | Error: la petició no és correcta. Hi ha metadades obligatòries sense informar o metadades informades no vàlides (XXXXXX). Operació NO realitzada. |
| 12 | Error: el número d'expedient indicat no existeix en el servei i organisme indicats. Operació NO realitzada. |
| 13 | Error: el fitxer físic indicat no existeix. Operació NO realitzada. |
| 14 | Error: el fitxer físic conté virus i ha estat eliminat. Operació NO realitzada. |
| 100 | Error no controlat: XXXXXX. Si us plau, reintenti l'operació en uns minuts. Operació NO realitzada. |
| 101 | Error: el document físic indicat està en procés de validació. Si us plau, reintenta l'operació en uns minuts. Operació NO realitzada. |
Aquest mètode permet obtenir de forma síncrona les metadades d'un document a partir del seu _ UUIDDocument _ (Modalitat 1) i de forma opcional l'URL presignada per poder descarregar el contingut (Modalitat 2).
| Element | Tipus paràmetre | Obligatori | Tipus camps | Mida màxima | Observacions |
|---|---|---|---|---|---|
| uuidDocument | PathParam | Sí | Text | -- | -- |
| codiServei | QueryParam | Sí | Text | 10 | -- |
| codiINE | QueryParam | Sí | Text | 10 | -- |
| Modalitat | QueryParam | Sí | Número | 1 | Posar "1" per a modalitat 1 |
Important: Si l’antivirus no ha pogut finalitzar l’anàlisi d’algun dels fitxers, la descàrrega de l’expedient fallarà amb un codi d’error 1 - El contingut del fitxer està esperant a ser analitzat pel antivirus.
La modalitat 2 només es pot executar si el document té un contingut igual 1 (fitxer).
| Element | Tipus paràmetre | Obligatori | Tipus camps | Mida màxima | Observacions |
|---|---|---|---|---|---|
| uuidDocument | PathParam | Sí | Text | -- | -- |
| codiServei | QueryParam | Sí | Text | 10 | -- |
| codiINE | QueryParam | Sí | Text | 10 | -- |
| Modalitat | QueryParam | Sí | Número | 1 | Posar "2" per a modalitat 2 |
A continuació es detallen els possibles codis de resposta per a la descàrrega del document (per al codi d'error 100 XXXXXX ofereix més detalls de l'error no controlat):
| Codi | Missatge |
|---|---|
| 0 | Operació realitzada correctament. |
| 1 | Error: El contingut del fitxer està esperant a ser analitzat pel antivirus. |
| 4 | Error: Petició mal formada. |
| 10 | Error: no tens autorització per realitzar aquesta operació. Operació NO realitzada. |
| 11 | Error: la petició no és correcta. Operació NO realitzada. |
| 12 | Error: el document indicat no existeix en el servei i organisme indicats. Operació NO realitzada. |
| 100 | Error no controlat: XXXXXX. Si us plau, reintenti l'operació en uns minuts. Operació NO realitzada. |
| IMPORTANT |
|---|
| En la descàrrega de documents del codiServei=SIR trobareu documents de tipus referència (contingut=3). Per poder descarregar-los, cal tenir present: |
|
|
|
|
Aquest mètode permetrà obtenir i descarregar un document en format ENI per tal de poder compartir-ho amb un tercer.
Aquest mètode asíncron permet obtenir i descarregar el document en format ENI (Esquema Nacional de Interoperabilidad) per poder exportar-ho i compartir-ho amb tercers. Les especificacions del format ENI per a documents estan disponibles al següent enllaç:
DESA'L genera un XML d'acord a aquestes especificacions. De forma anàloga a la descàrrega de l'expedient en format ENI, el procés de creació del fitxer ENI és asíncron. Per poder saber si el fitxer ENI ja està disponible i per poder recuperar-ho un cop ja ho estigui, el servei integrador ha d'executar la consulta d'estat del ticket (_ 5.6 Consulta estat ticket _).
| Element | Tipus paràmetre | Obligatori | Tipus camps | Mida màxima | Observacions |
|---|---|---|---|---|---|
| uuidDocument | PathParam | Sí | Text | -- | -- |
| codiINE | QueryParam | Sí | Text | 10 | -- |
| codiServei | QueryParam | Sí | Text | 10 | -- |
A continuació es detallen els possibles codis de resposta per a la descàrrega del document en format ENI:
| Codi | Missatge |
|---|---|
| 0 | Operació realitzada correctament. |
| 1 | Error: El contingut del fitxer està esperant a ser analitzat pel antivirus. |
| 4 | Error: Petició mal formada. |
| 10 | Error: no tens autorització per realitzar aquesta operació. Operació NO realitzada. |
| 11 | Error: la petició no és correcta. Operació NO realitzada. |
| 12 | Error: l'expedient indicat no existeix en el servei i organisme indicats. Operació NO realitzada. |
| 100 | Error no controlat: XXXXXX. Si us plau, reintenti l'operació en uns minuts. Operació NO realitzada. |
Aquest mètode de l'API permet cercar tots aquells documents que compleixen una sèrie de criteris de filtratge, informats a la petició.
La cerca es realitzarà aplicant tots aquests criteris de filtratge de manera conjuntiva (logical AND). No es suporta la realització de cerques aplicant els criteris de manera disjuntiva (logical OR) o la construcció de consultes complexes combinant ambdues lògiques.
El paràmetre modality indica si la cerca ha de retornar únicament les metadades dels documents o si per contra també ha de generar les URL pre-signades per a poder descarregar el contingut dels fitxers associats als documents (per a aquells documents amb tipus de contingut=1).
Amb la finalitat de garantir el rendiment i protegir el servei davant de sobrecàrregues no es retornaran més de 100 resultats per cerca.
L'URL corresponent a aquesta operació de l'API és:
https://{{host}}/document/search?codiServei={{codiServei}}&codiINE={{codiINE}}&modality={{modalitat}}| Element | Tipus paràmetre | Obligatori | Tipus camps | Observacions |
|---|---|---|---|---|
| codiINE | Query String | Si | Text | Codi d'organisme del requeridor |
| codiServei | Query String | Si | Text | Codi de servei del requeridor |
| modality | Query String | Si | Numèric |
|
| codiINE | Body | No | Text | -- |
| codiServei | Body | No | Text | -- |
| uuidDocument | Body | No | Text | -- |
| sensibilitatDadesCaracterPersonal | Body | No | Text | -- |
| documentEssencial | Body | No | Booleà | -- |
| idioma | Body | No | Text | -- |
| codiClassificacio | Body | No | Text | -- |
| nomClassificacio | Body | No | Text | -- |
| codiSIA | Body | No | Text | -- |
| nomNatural | Body | No | Text | -- |
| infoAddicional | Body | No | Llista | Veure 6.6.1 |
| infoAddicional[].key | Body | No | Text | -- |
| infoAddicional[].value | Body | No | Text | -- |
| CSV | Body | No | Text | -- |
| formatFitxer | Body | No | Text | -- |
| hash | Body | No | Base64 | -- |
| hashAlgoritme | Body | No | Text | -- |
| mida | Body | No | Bloc | Veure 6.6.2 |
| mida.de | Body | No | Numèric | -- |
| mida.fins | Body | No | Numèric | -- |
| nomFitxer | Body | No | Text | -- |
| uuidFitxer | Body | No | Text | -- |
| URLDocumentExtern | Body | No | Text | -- |
| dataAlta | Body | No | Bloc | Veure 6.6.3 |
| dataAlta.inici | Body | No | Numèric | -- |
| dataAlta.fi | Body | No | Numèric | -- |
| dataDocument | Body | No | Bloc | Veure 6.6.4 |
| dataDocument.inici | Body | No | Numèric | -- |
| dataDocument.fi | Body | No | Numèric | -- |
| identificadorExpedientDesal | Body | No | Text | -- |
| identificadorExpedientExtern | Body | No | Text | -- |
| versioNTI | Body | No | Text | -- |
| identificador | Body | No | Text | -- |
| organ | Body | No | Text | -- |
| estatElaboracio | Body | No | Text | -- |
| origen | Body | No | Booleà | -- |
| tipusDocumental | Body | No | Text | -- |
| tipusSignatura | Body | No | Text | -- |
| CSVSignatura | Body | No | Text | -- |
| regulacioGeneracioCSVSignatura | Body | No | Text | -- |
| referenciaSignatura | Body | No | Text | -- |
| identificadorDocumentOrigen | Body | No | Text | -- |
| tipusDocumentalSICRES | Body | No | Text | -- |
| descripcio | Body | No | Text | -- |
| nivellAcces | Body | No | Text | -- |
| classificacioENS | Body | No | Text | -- |
| identificadorDocumentExtern | Body | No | Text | -- |
| interessat | Body | No | Text | -- |
| usuari | Body | No | Text | -- |
| numeroRegistre | Body | No | Text | -- |
| contingut | Body | No | Text | -- |
NOTA: Per a la descripció dels camps dels documents i el seu format consulteu l'apartat 2.3 d'aquest manual.
"infoAddicional": [
{
"key": "clau_1",
"value": "valor_1"
}
]"mida": {
"de": 370000,
"fins": 375000
}"dataAlta": {
"inici": 1652432260560,
"fi": 1652432264560
},"dataDocument": {
"inici": 1652432260560,
"fi": 1652432264560
},{
"codiServei": "SERVEI",
"codiINE": "9821920002",
"interessat": "22222222R",
"nomNatural": "natural",
"dataAlta": {
"inici": 1652432260560,
"fi": 1652432264560
},
"dataDocument": {
"inici": 1652432250000,
"fi": 1652432270000
},
"infoAddicional": [
{
"key": "clau_1",
"value": "valor_1"
}
],
"numeroRegistre": "E/999999-2022",
"CSVSignatura": "CSVSIG-1652432261048",
"CSV": "CSVFTX-1652432260985",
"identificadorExpedientExtern": "EXP/9999999/2022",
"uuidFitxer": "11111111-1111-1111-1111-111111111111",
"uuidDocument": "11111111-1111-1111-1111-111111111111"
}| Element | Tipus paràmetre | Tipus camps | Observacions |
|---|---|---|---|
| totalResultats | Body | Text | -- |
| resultatsRecuperats | Body | Text | -- |
| codiResposta | Body | Text | -- |
| descripcioResposta | Body | Text | -- |
| documents | Body | Llista | Llista de documents recuperats |
NOTA: Per a la descripció dels camps dels documents i el seu format consulteu l'apartat 2.3 d'aquest manual.
{
"totalResultats": 2,
"resultatsRecuperats": 2,
"codiResposta": "0",
"descripcioResposta": "Operació realitzada correctament",
"documents": [
{
"uuidDocument": "11111111-1111-1111-1111-111111111111",
"uuidFitxer": "22222222-2222-2222-2222-222222222222",
"codiINE": "9610420002",
"codiServei": "eVALISA",
"nomNatural": "curs_prevencio_riscos",
"documentEssencial": false,
"idioma": "ca_ES",
"CSV": "961042000222022022C261HF1KRL8",
"formatFitxer": "application/pdf",
"hash": "AtCnNoXBWaHQtRuXtkYce1lgKUu+cMFDHdyJjHLaNMA=",
"hashAlgoritme": "SHA-256",
"mida": 346778,
"nomFitxer": "curs_prevencio_riscos.pdf",
"dataAlta": 1645529469000,
"dataDocument": 1645525800000,
"contingut": "1",
"identificadorExpedientDesal": "99999999-9999-9999-9999-999999999999",
"versioNTI": "http://administracionelectronica.gob.es/ENI/XSD/v1.0/documento-e",
"identificador": "ES_9610420002_2022_11111111-1111-1111-1111-111111111111",
"organ": "A09018799",
"estatElaboracio": "EE01",
"origen": true,
"tipusDocumental": "TD99",
"tipusSignatura": "TF01",
"CSVSignatura": "961042000222022022C261HF1KRL8",
"regulacioGeneracioCSVSignatura": "Resolució sobre l'ús del sistema de codi segur de verificació del Consorci AOC",
"tipusDocumentalSICRES": "02",
"nivellAcces": "E",
"codiResposta": "0",
"interessat": [],
"usuari": "66666667V"
},
{
"uuidDocument": "22222222-2222-2222-2222-222222222222",
"uuidFitxer": "33333333-3333-3333-3333-333333333333",
"codiINE": "9610420002",
"codiServei": "eVALISA",
"nomNatural": "curs_prevencio_riscos",
"documentEssencial": false,
"idioma": "ca_ES",
"infoAddicional": [],
"CSV": "9610420002220220227S3708IDS7CK",
"formatFitxer": "application/pdf",
"hash": "AtCnNoXBWaHQtRuXtkYce1lgKUu+cMFDHdyJjHLaNMA=",
"hashAlgoritme": "SHA-256",
"mida": 346778,
"nomFitxer": "curs_prevencio_riscos.pdf",
"dataAlta": 1645528888000,
"dataDocument": 1645525260000,
"contingut": "1",
"identificadorExpedientDesal": "99999999-9999-9999-9999-999999999999",
"versioNTI": "http://administracionelectronica.gob.es/ENI/XSD/v1.0/documento-e",
"identificador": "ES_9610420002_2022_22222222-2222-2222-2222-222222222222",
"organ": "A09018799",
"estatElaboracio": "EE01",
"origen": true,
"tipusDocumental": "TD99",
"tipusSignatura": "TF01",
"CSVSignatura": "9610420002220220227S3708IDS7CK",
"regulacioGeneracioCSVSignatura": "Resolució sobre l'ús del sistema de codi segur de verificació del Consorci AOC",
"tipusDocumentalSICRES": "02",
"nivellAcces": "E",
"codiResposta": "0",
"interessat": ["11111111H"],
"usuari": "33333334D"
}
]
}A continuació es detallen els possibles codis de resposta per a l'operació de cerca de documents:
| Codi | Missatge |
|---|---|
| 0 | Operació realitzada correctament. |
| 4 | Error: Petició mal formada. |
| 10 | Error: no tens autorització per realitzar aquesta operació. Operació NO realitzada. |
| 100 | Error no controlat: XXXXXX. Si us plau, reintenti l'operació en uns minuts. Operació NO realitzada. |