Carga

Cancelar carga

Descripción

Cancela la carga que se indique. Cancelar una carga, implica cancelar los ficheros, tanto los que se han terminado de subir como los que estén todavía en proceso.

Sólo se permite la cancelación de cargas en estado INICIADA, el resto no tienen efecto y provoca la aparición de un mensaje de error. Las cargas en estado CANCELADA también se pueden cancelar aunque no tenga efecto alguno.

id="cancelar_carga-Estructuradelaurl" Estructura de la url

Petición

Esta petición se debe enviar utilizando los métodos HTTP GET o DELETE.

Este método no tiene ningún documento JSON asociado en el cuerpo, sino que el identificador de la carga se incluye en la URI de la petición.

Ejemplo Petición

Respuesta

El método no contempla una respuesta específica. La cancelación de la carga se ha realizado correctamente si se recibe un código HTTP 200.

Errores epecíficos

Cancelar fichero

Descripción

Descarta y elimina la carga de un fichero que esté en marcha. Todos los datos ya cargados se perderán.

Estructura de la URL

Ejemplo URL

Petición

 Esta petición se debe enviar utilizando el método HTTP GET o DELETE.

El parámetro uuidUpload es el código que representa la subida, irá incluida dentro de la URI.

Respuesta

El método no contempla una respuesta especifica. El descarte del fichero se ha realizado correctamente si se recibe un código HTTP 200.

Errores 

Cargar fichero completo

Descripción

Carga un sólo fichero de una vez. Permite cargar ficheros de hasta 10 Gb. Ver Límites de tamaño de los ficheros.

Estructura de la URL

Petición

Esta petición recibirá los parámetros codificados en la URL. Estos no pueden ser enviados en el cuerpo de la petición. 

Esta petición se debe enviar utilizando el método HTTP PUT.

En el cuerpo de la petición contendrá los bytes del fichero (tamaño máximo indicado arriba).

Los parámetros de la petición son los siguientes:

• nifPresentador: Identificador que representa a la persona (física o jurídica) que presenta el fichero.
• nifEmpresa: Identificador de la empresa a la que pertenece el fichero.
• idProcedimiento: Identificador numérico del procedimiento al que está asociado el fichero.
• fechaEfecto: Este parámetro opcional. Fecha que identifica el periodo para el que se realiza la carga. El formato de esta fecha es MM/DD/YYYY, atención porque es distinto a iniciar_carga
• tipoFichero: Código que identifica el contenido del fichero. Identificador textual. Ej.: FICHERO_REMESAS
• nombreFichero: Este parámetro es opcional. Nombre del fichero origen.
• hash: Este parámetro es opcional. Resumen del fichero, en formato MD5.
• numeroBytes: Tamaño del fichero en bytes.
• observaciones: Parámetro opcional. Mensaje con observaciones que aparecerá en las cargas. No tiene tratamiento automatizado. (Opcional). 

Respuesta

La carga se ha realizado correctamente si se recibe un código HTTP 200.

El cuerpo de la respuesta contendrá un documento JSON con el siguiente atributo:

• uuidCarga: Identificador de la carga en formato UUID. Este identificador debe emplearse necesariamente en el resto de las operaciones asociadas a esta carga. 

Posteriormente, de manera asíncrona, se generará la notificación correspondiente, esta está descrita en: Notificaciones de cargas.

Ejemplo document JSON Respuesta

Errores

Confirmar carga

Descripción

Consolida la carga de ficheros. Este método cierra el procedimiento de presentación de ficheros asociados a una carga a todos los efectos, incluido el de notificación de la misma.

Estructura de la url

Petición

Esta petición se debe enviar utilizando el método HTTP GET.

El parámetro uuidCarga, que es el código que representa la carga, irá incluido dentro de la URI.

Ejemplo Petición

Respuesta

El método no contempla una respuesta específica. La solicitud de consolidación de la carga se ha realizado correctamente si se recibe un código HTTP 200.Posteriormente, de manera asíncrona, se generará la notificación correspondiente, esta está descrita en: Notificaciones de cargas.

Errores específicos

Confirmar subida fichero

Descripción

Informa de que la carga del fichero ha terminado y consolida el fichero dentro del sistema.

Estructura de la URL

<3 id="confirmar_subida_fichero-Petición"> Petición

Esta petición se debe enviar utilizando el método HTTP GET.

El parámetro uuidUpload como código que representa la subida del fichero, irá incluida dentro de la URI.

Ejemplo Petición

Respuesta

El método no contempla una respuesta especifica. La carga del ficheroha realizado correctamente si se recibe un código HTTP 200.

Errores

Consultar estado carga

Descripción

Permite consultar el estado de una carga.

Estructura de la URL

https://api.cnmc.gob.es/carga/v1/consultar_estado_carga/<uuidCarga>

Petición

Esta petición se debe enviar utilizando el método HTTP GET.

Este método no tiene ningún documento JSON asociado en el cuerpo, sino que el identificador de la carga se debe incluir en la URI de la petición.

Ejemplo Petición

https://api.cnmc.gob.es/carga/v1/consultar_estado_carga/550e8400-e29b-41d4-a716-446655440000

Respuesta

El cuerpo de la respuesta contendrá un documento JSON que contendrá un estado descrito en: Estados de una carga y la información adicional necesaria, en caso de haber sido rechazada: 

• estado: estado de la carga, valores posibles: Estados de una carga
• registrosProcesados: parámetro opcional, con el número de entradas recibidas por el procesador de la carga
• registrosErrores: parámetro opcional, informa del número de entradas erróneas detectadas
• numeroRegistroGeneral: parámetro opcional, informa del identificador del registro de entrada de la carga en el registro general de la CNMC
• posicionEnColaCargas: en caso de que la carga esté en estado CONFIRMADA se rellena con la posición ordinal en dicha cola
• justificante: fichero de justificante de presentación de los ficheros remitidos en la carga
• uuidUpload. Identificación del fichero del justificante.
• url. URL de descarga del fichero del justificante
• longitudBytes. Con el tamaño del fichero en bytes
• mensajeError: En caso de que exista un error general en el tratamiento del fichero se incluirá en este atributo
• errores: parámetro opcional. Lista de información de los errores asociados a los ficheros correspondientes a una carga:
  • uuidUpload. Identificación del fichero subido, sobre el que se listan los errores.
  • url. URL de descarga del fichero de descripción de los errores
  • longitudBytes. Con el tamaño del fichero de errores en bytes

Ejemplo documento JSON Respuesta

Iniciar carga

Descripción

Inicia una transacción de subida de ficheros asociados a un procedimiento. En posteriores operaciones se asociarán las subidas de ficheros correspondientes a dicha transacción, componiendo la carga completa. Se permitirá un número máximo de 10 cargas simultáneas por empresa y procedimiento

Estructura de la url

Petición

Esta petición se debe enviar utilizando los métodos HTTP POST y HTTP PUT.

En el cuerpo de la petición contendrá un documento JSON con la siguiente estructura: 

• nifPresentador: Identificador que representa a la persona (física o jurídica) que presenta los ficheros.
• nifEmpresa: Identificador de la empresa a la que pertenecen los ficheros.
• idProcedimiento: Identificador del procedimiento al que están asociados los ficheros.
• fechaEfecto: Parámetro opcional. Fecha que identifica el periodo para el que se realiza la carga. (Opcional). 
• observaciones: Parámetro opcional. Mensaje con observaciones que aparecerá en las cargas. No tiene tratamiento automatizado. (Opcional). 

Por defecto, permitirá un número máximo de 10 cargas simultáneas por empresa y procedimiento. 

Ejemplo documento JSON Petición

Respuesta

El cuerpo de la respuesta contendrá un documento JSON con los siguientes parámetros:

• uuidCarga: Identificador de la carga en formato UUID. Este identificador debe emplearse necesariamente en el resto de las operaciones asociadas a esta carga. 
• expiracionSegundos: Segundos para que caduque esta carga. Durante este tiempo es posible realizar operaciones sobre esta carga, incluida confirmar_carga. El valor por defecto es 172.800s (48h). En caso de alcanzar la caducidad sin la confirmación de la carga, se descartarán las operaciones, ficheros y datos asociados. 

Ejemplo document JSON Respuesta

Errores específicos

Iniciar subida fichero

Descripción

Inicia una transacción de subida de un fichero indicando.  El sistema responderá dando un identificador para controlar la carga.

Estructura de la url

Petición

Esta petición se debe enviar utilizando el método HTTP POST o PUT.

En el cuerpo de la petición contendrá un documento JSON con la siguiente estructura: 

• uuidCarga: Identificación de la carga.
• tipoFichero: Código que identifica el contenido del fichero.
• nombreFichero: Este parámetro es opcional. Nombre del fichero origen.
• numeroBytes: Este parámetro es opcional. Tamaño del fichero en bytes. 
• hash: Este parámetro es opcional. Resumen fichero  SHA-1.

Ejemplo Petición

Respuesta

En el cuerpo de la respuesta contendrá un documento JSON con el identificador de la subida.

Ejemplo Respuesta

Errores

Listar cargas

Descripción

Lista las cargas realizadas o en proceso, dependiendo del filtro establecido.

Estructura de la url

Petición

Esta petición se debe enviar utilizando los métodos HTTP POST o PUT.

El cuerpo de la petición contendrá un documento JSON con la siguiente estructura: 

• nifPresentador: Parámetro opcional. Identificador que representa a la persona (física o jurídica) que presenta los ficheros.
• nifEmpresa: Parámetro opcional. Identificador de la empresa a la que pertenecen los ficheros.
• idProcedimiento: Parámetro opcional. Identificador del procedimiento al que están asociados los ficheros.
• uuidCarga:  Parámetro opcional. Permite la consulta del detalle de una carga.
• estado: Parámetro opcional. Los valores permitidos se pueden consultar en Estados de una carga. También se puede usar TODAS, que es el valor por defecto.

Ejemplo documento JSON Petición

Respuesta

Como máximo, devolverá las últimas 1000 cargas. El cuerpo de la respuesta contendrá un documento JSON que contiene una lista y cada entrada de la lista contiene los siguientes datos: 

• uuidCarga: Identificador de la carga.
• nifPresentador: Documento de identificación del presentador.
• nifEmpresa: Identificador de la empresa que presenta el procedimiento.
• idProcedimiento: Código que identifica el procedimiento para el que se esta realizando la carga.
• estado:{INICIADA|CANCELADA|CONFIRMADA|PROCESADA|RECHAZADA}.
• fechaInicio: Fecha de creación e inicio de la carga. 
• fechaFin: Fecha de finalización de subida de los ficheros y confirmación de la carga, en su caso.  
• fechaFinProceso: Fecha de procesamiento interno de la carga, en su caso.  
• fechaEfecto: Fecha de valor de la carga, en caso de que sea periódica, en su caso.
• expiracionSegundos: Tiempo en segundos que restan a la sesión de carga, sólo en cuando esta esté en estado iniciada.
• ficheros: Lista de ficheros asociados a la carga. Cada entrada en la lista contendrá los siguientes datos:
  • uuidUpload: Código que identifica la subida del fichero. 
  • fechaInicioUpload: Fecha de inicio de la subida del fichero. 
  • fechaFinUpload: Fecha de fin de la subida del fichero, en su caso. 
  • tipo: Código que identifica el tipo de fichero subido. Por ejemplo "SGDA", "SIPS_GAS_CONSUMOS", etc..
  • nombre: Nombre del fichero subido, si  se indicó al llamar al método /iniciar_subida_fichero.
  • hash: Resumen fichero  MD5. Si la subida del fichero no se ha completado, el HASH corresponderá  a la parte cargada.
  • numeroBytes: Tamaño del fichero en bytes, correspondiente a la parte ya subida.
  • estado: Estado en el que se encuentra el fichero: {CARGANDO,CARGADO,RECHAZADO,EN_PROCESO,PROCESADO_OK,PROCESADO_ERROR}. 

Listar chunks fichero

Descripción

Lista la información de un fichero concreto e informa de las partes cargadas.

Estructura de la URL

Petición

Esta petición se debe enviar utilizando el método HTTP GET.

El parámetro uuidUpload es el código que representa la subida del fichero, irá incluida dentro de la URI.

Respuesta

El cuerpo de la respuesta contendrá un documento JSON que contiene una lista y cada entrada de la lista contiene los siguientes datos: 

• uuidUpload: Código que identifica el fichero.
• tipoFichero: Nombre corto que identifica el contenido del fichero.
• numeroBytes: Tamaño del fichero completo en bytes.
• partes: Un lista de las partes cargadas. Cada entrada de la lista contendrá los siguientes datos:
  • numeroParte: Número de parte cargada.
  • numeroBytes: Número de bytes que contiene la parte.

Ejemplo Petición

Ejemplo Respuesta

Errores

Subir chunk fichero

Descripción

Permite cargar ficheros grandes en múltiples trozos. Esta operación ofrece la posibilidad de continuar la carga, si esta se interrumpiese.

Los contenidos se subirán usando el tipo de contenido: multipart/form-data

https://www.ietf.org/rfc/rfc2388.txt

Uso:

1. Se hace una peticion a /iniciar_carga para abrir una sesión de subida de ficheros. En la respuesta se recibe un uuidCarga que identifica la carga.
2. Se hace una petición a /iniciar_subida_fichero para abrir la transacción en el sistema para un fichero. En la respuesta recibirás un uuidUpload que identifica el fichero.
3. Se hacen repetidas peticiones  a /subir_chunk_fichero usando el uuidUpload para identificar la subida.
4. Se hará una llamada a /confirmar_subida_fichero para consolidar la subida del fichero.
5. Se repetirá del punto 2 al 4 tantas veces como ficheros se asocien a la carga.
6. Se hace una petición a /confirmar_carga usando el uuidCarga, para consolidar presentación de todos los ficheros asociados a una carga.

Estructura de la URL

Petición

Esta petición recibirá los parámetros codificados en la URL. Estos no pueden ser enviado en el cuerpo de la petición. El tamaño de chunck estará limitado a un máximo de 150 MB y un mínimo de 5 MB, con excepción del tamaño del último chunk. En caso de que sea una subida completa de un solo chunk (numeroParte no enviado) el tamaño máximo se amplia hasta 10 Gb.

Esta petición se debe enviar utilizando el método HTTP POST o PUT.

En el cuerpo de la petición contendrá los bytes del chunk, usando la codificación "multipart/form-data".

Los parámetros de la petición son los siguientes:

• uuidUpload: El identificador obtenido de la petición /iniciar_subida_fichero
• numeroParte: Posición del chunk en el fichero. En caso de consignarse, se presupone que el fichero se sube completamente con esta operación.
• tamanoParte: Tamaño en bytes del chunk.

Respuesta

El método no contempla una respuesta especifica. La carga del chunk ha realizado correctamente si se recibe un código HTTP 200.

Errores

Subir fichero completo

Descripción

Permite subir ficheros en una única operación en el ámbito de una carga ya iniciada.

Uso:

1. Se hace una petición a /iniciar_carga para abrir una sesión de subida de ficheros. En la respuesta se recibe un uuidCarga que identifica la carga.
2. Se hace una petición a /isubir_fichero_completo.
3. Se podrá repetir el punto 2 tantas veces como ficheros se asocien a la carga.
4. Se hace una petición a /confirmar_carga usando el uuidCarga, para consolidar todos los ficheros.

Estructura de la URL

Petición

Esta petición recibirá los parámetros codificados en la URL. Estos no pueden ser enviado en el cuerpo de la petición. El tamaño máximo del fichero a enviar es de 10 Gb. Ver Límites de tamaño de los ficheros

Esta petición se debe enviar utilizando el método HTTP POST o PUT.

En el cuerpo de la petición contendrá los bytes del fichero.

Los parámetros de la petición son los siguientes:

• uuidCarga: Identificación de la carga.
• tipoFichero: Código que identifica el contenido del fichero.
• nombreFichero: Este parámetro es opcional. Nombre del fichero origen.
• numeroBytes: Tamaño del fichero en bytes. 
• hash: Este parámetro es opcional. Resumen fichero  MD5

Respuesta

El cuerpo de la respuesta contendrá un documento JSON con el identificador de la subida. 

Ejemplo Respuesta

Errores

Estados de una carga

El ciclo de vida de una carga, como se puede ver en los Casos de uso de carga de ficheros, incluye una serie de estados por los que puede pasar una carga de ficheros:

• INICIADA. La carga ha sido iniciada, por ejemplo con: iniciar_carga.
• CONFIRMADA. La carga ha sido incorporada al sistema pero todavía no se ha iniciado su tratamiento. Ej. al lanzar: confirmar_carga
• CANCELADA. La carga ha sido cancelada por el solicitante y todos sus ficheros eliminados. Llamando al servicio: cancelar_carga
• EN_PROCESO. El sistema receptor final (SGDA u otro) ha recibido la tarea de procesamiento de la carga.
• PROCESADA. El sistema receptor ha finalizado, sin especificar si ha sido exitosa o con fallo.
• ACEPTADA. El sistema receptor ha procesado la carga completa y todos los registros son correctos.
• ACEPTADA_PARCIALMENTE. El sistema receptor ha procesado la carga completa y ha incorporado algunos pero no en su totalidad. Los errores se pueden consultar en el fichero adjunto.
• RECHAZADA. El sistema receptor ha procesado la carga pero no ha incorporado ningún registro. Puede ser por algún error general de formato, en cualquier caso los errores se pueden consultar en el fichero adjunto. Esto se puede ver llmando a consultar_estado_carga