Ejemplo n°5: Validar Inline XBRL
En este ejemplo usamos PowerShell en Windows con la tramitación US-GAAP de https://www.sec.gov/Archives/edgar/data/815097/000081509723000012/0000815097-23-000012-xbrl.zip para realizar una validación de Inline XBRL.
Requisitos
•Descargue 0000815097-23-000012-xbrl.zip (URL entero más arriba)
•Instale la taxonomía US-GAAP-2023 en el servidor
| Nota: | El uso de comillas puede ser diferente en otros shells ('bash' funciona con el ejemplo cuando se utiliza 'curl' en lugar de 'curl.exe'). |
Enviar una solicitud POST de validación de Inline XBRL usando CURL
A continuación puede ver un comando CURL de muestra para enviar una solicitud de validación de Inline XBRL.
curl.exe -F 'msg={"command": "ixbrl", "args": ["additional-files:///0000815097-23-000012-xbrl.zip%7Czip/ccl-20221130.htm"], "options": {"verbose": true}};type=application/json' -F "additional-files=@0000815097-23-000012-xbrl.zip;type=application/octet-stream" http://localhost:8087/v1/queue
Para facilitar la lectura:
(1) -F 'msg={
(2) "command": "ixbrl",
(3) "args": ["additional-files:///0000815097-23-000012-xbrl.zip%7Czip/ccl-20221130.htm"],
(4) "options": {"verbose": true}
(5) };type=application/json'
(6) -F "additional-files=@0000815097-23-000012-xbrl.zip;type=application/octet-stream"
(7) http://localhost:8087/v1/queue
Entrada
A continuación se explican las distintas partes del comando CURL, en función de los complementos del listado anterior.
(1) -F 'msg={...}’ especifica un campo de formulario con el nombre 'msg'
La opción -F hace que: (i) CURL genere una publicación de un formulario multiparte con Content-Type: multipart/form-data y (ii) este campo de formulario se añada automáticamente al encabezado de la solicitud. Usamos un objeto JSON para describir el comando que RaptorXML+XBRL Server debería ejecutar.
Content-Type: multipart/form-data; boundary=--------------------...
Con el comando CURL esta opción en la solicitud HTTP se convierte en:
Content-Disposition: form-data; name="msg"
Content-Type: application/json
{"command": "ixbrl", "args": ["additional-files:///0000815097-23-000012-xbrl.zip%7Czip/ccl-20221130.htm"], "options": {"verbose": true}}
(2) El comando de RaptorXML+XBRL Server que se debe ejecutar en el servidor. Consulte la sección Interfaz de la línea de comandos (ILC) para obtener más información sobre los comandos que se admiten. En nuestro ejemplo, el comando para la validación de Inline XBRL es valinlinexbrl (ixbrl). Se permite tanto la forma más larga (valinlinexbrl) como la más corta (ixbrl).
(3) Los argumentos del comando (tal y como se aceptan en la línea de comandos de RaptorXML+XBRL Server) se codifican como matrices JSON. RaptorXML+XBRL Server usa un esquema additional-files:// explícito para hacer referencia a recursos adicionales en el formulario dentro de un campo separado additional-files. En nuestro ejemplo hacemos referencia al documento Inline XBRL ccl-20221130.htm que está dentro del archivo ZIP 0000815097-23-000012-xbrl.zip.
| Nota: | El elemento | en |zip que se usa en los productos de Altova para hacer referencia a archivos dentro de un archivo .zip se tiene que codificar en URL como %7C. El archivo 0000815097-23-000012-xbrl.zip se envía como contenido de otro campo de formulario en (6). Todos los recursos en la matriz args deben estar disponibles en el servidor o enviarse con la solicitud, similar al punto (6). |
(4) Las opciones del comando (tal y como se aceptan en la línea de comandos de RaptorXML+XBRL Server) se codifican como matrices JSON. Si los valores predeterminados de estas opciones son como los desea (véase la sección ILC), puede omitir este paso. En nuestro ejemplo solicitamos un registro detallado de los resultados configurando la opción Modo detallado en true (el valor predeterminado es false).
(5) El Content-Type del campo de formulario msg se especifica después de la definición del campo de formulario y se separa de ella por un punto y coma. En nuestro ejemplo, el Content-Type de msg se indica en type=application/json.
(6) Puede especificar los archivos que contienen recursos adicionales para el comando usando el campo de formulario additional-files. En nuestro ejemplo especificamos @0000815097-23-000012-xbrl.zip como recurso adicional, seguido de un separador de punto y coma y, al final, su Content-Type, que indicamos como type=application/octet-stream.
| Nota: | Utilice @ como prefijo del nombre de archivo para indicar a CURL que use (i) el nombre de archivo como valor de la propiedad filename y (ii) el contenido del archivo como valor del formulario. Puede rellenar el campo de formulario ‘additional-files’ varias veces, una por cada recurso adicional requerido por el comando. Con el comando CURL esta opción en la solicitud HTTP se convierte en: |
Content-Disposition: form-data; name="additional-files"; filename="0000815097-23-000012-xbrl.zip"
Content-Type: application/octet-stream
<<content of 0000815097-23-000012-xbrl.zip>>
Salida
El resultado de RaptorXML+XBRL Server es un objeto JSON:
{"jobid": "4B7CFC80-13B3-4558-B8CC-D312EA00BA74", "result": "/v1/results/4B7CFC80-13B3-4558-B8CC-D312EA00BA74"}
El objeto JSON contiene una clave jobid y una clave result. El valor de la clave result es la ruta de acceso del resultado. Esta ruta de acceso debe añadirse a la parte <scheme>://<host>:<port> utilizada para enviar la solicitud. En nuestro ejemplo, el resultado URL entero sería: http://localhost:8087/v1/results/4B7CFC80-13B3-4558-B8CC-D312EA00BA74. La URL del resultado también se utiliza para solicitar el resultado de la ejecución del comando. Consulte el apartado Obtener el documento de resultados.
Obtener documentos de errores/mensajes/salida de la solicitud POST
El comando de entrada que se envía para obtener el error/mensaje/salida de la solicitud POST (véase Obtener los documentos de errores/mensajes/salida) tendría más o menos este aspecto:
curl.exe http://localhost:8087/v1/results/4B7CFC80-13B3-4558-B8CC-D312EA00BA74
En nuestro ejemplo, este comando devuelve el siguiente objeto JSON:
{"jobid":"4B7CFC80-13B3-4558-B8CC-D312EA00BA74","state":"OK","error":{},"jobs":[{"file":["additional-files:///0000815097-23-000012-xbrl.zip%7Czip/ccl-20221130.htm"],"jobid":"94968597-3234-4D0A-A3FF-BCDE50A0E4E6","output":{"verbose-log":["file:///C:/ProgramData/Altova/RaptorXMLXBRLServer2024/output/94968597-3234-4D0A-A3FF-BCDE50A0E4E6/verbose.log"],"xbrl-output-file":["file:///C:/ProgramData/Altova/RaptorXMLXBRLServer2024/output/94968597-3234-4D0A-A3FF-BCDE50A0E4E6/output.xbrl"]},"state":"OK","output-mapping":{"file:///C:/ProgramData/Altova/RaptorXMLXBRLServer2024/output/94968597-3234-4D0A-A3FF-BCDE50A0E4E6/verbose.log":"verbose.log","file:///C:/ProgramData/Altova/RaptorXMLXBRLServer2024/output/94968597-3234-4D0A-A3FF-BCDE50A0E4E6/output.xbrl":"output.xbrl"},"error":{}}]}
A continuación se transcribe este objeto en líneas separadas para facilitar la lectura y con acentuación para facilitar las referencias:
(1) {
(2) "jobid":"4B7CFC80-13B3-4558-B8CC-D312EA00BA74",
(3) "state":"OK",
(4) "error":{},
(5) "trabajos":[{
(6) "file":["additional-files:///0000815097-23-000012-xbrl.zip%7Czip/ccl-20221130.htm"],
(7) "jobid":"94968597-3234-4D0A-A3FF-BCDE50A0E4E6",
(8) "output":{
(9) "verbose-log":[file:///C:/ProgramData/Altova/RaptorXMLXBRLServer2024/output/94968597-3234-4D0A-A3FF-BCDE50A0E4E6/verbose.log"],
(10) "xbrl-output-file":["file:///C:/ProgramData/Altova/RaptorXMLXBRLServer2024/output/94968597-3234-4D0A-A3FF-BCDE50A0E4E6/output.xbrl"]},
(11) "state":"OK",
(12) "output-mapping":{
(13) "file:///C:/ProgramData/Altova/RaptorXMLXBRLServer2024/output/94968597-3234-4D0A-A3FF-BCDE50A0E4E6/verbose.log":"verbose.log",
(14) "file:///C:/ProgramData/Altova/RaptorXMLXBRLServer2024/output/94968597-3234-4D0A-A3FF-BCDE50A0E4E6/output.xbrl":"output.xbrl"
(15) },
(16) "error":{}
(17) }]
(18) }
A continuación explicamos el listado de arriba:
(1) El resultado se devuelve como objeto JSON.
(2) El elemento jobid en el primer nivel es el identificador de trabajo principal.
(3) El estado de este trabajo es ‘OK’. Los posibles estados de trabajo son: none (ninguno); Dispatched (distribuido); Running (en ejecución); Canceled (cancelado); Crashed (bloqueado); OK; Failed (error).
(4) En nuestro ejemplo, el objeto de error JSON está vacío. Podría que contenga la serialización JSON del error, tal y como aparece en el registro de RaptorXML+XBRL Server.
(5) El trabajo principal (en el primer nivel) genera trabajos subordinados (p.ej. uno por cada argumento).
(6) Para este trabajo el argumento es la instancia Inline XRBL que se encuentra en el archivo ZIP: additional-files:///0000815097-23-000012-xbrl.zip%7Czip/ccl-20221130.htm.
(7) Los trabajos subordinados también tienen un identificador de trabajo que se puede utilizar para consultar el estado u obtener los resultados. La ejecución de trabajos es asincrónica. Por tanto, es posible que trabajos cortos enviados después de otros trabajos más largos terminen antes.
De (8) a (15) El objeto JSON de salida output contiene las claves para los archivos de salida generados por el servidor que se pueden solicitar a través de HTTP. Algunas claves (p.ej. verbose-log) especifican URLs a los archivos generados almacenados en el servidor. Estas rutas de acceso locales del servidor se pueden asignar a nombres que se pueden usar como objetos JSON output-mapping en las URLs HTTP. Estas URL sirven para obtener archivos de salida a través de HTTP y están constituidas de la siguiente manera:
<scheme>://<host>:<port>/v1/results/<jobid>/output/<output-mapping-value>
Por lo tanto, en nuestro ejemplo la ruta de acceso para obtener el registro detallado sería el siguiente:
curl.exe http://localhost:8087/v1/results/94968597-3234-4D0A-A3FF-BCDE50A0E4E6/output/verbose.log
Tenga en cuenta que en el objeto output-mapping (12), el primer valor (13) es el registro detallado file:///C:/ProgramData/Altova/RaptorXMLXBRLServer2024/output/94968597-3234-4D0A-A3FF-BCDE50A0E4E6/verbose.log que hemos asignado al valor verbose.log. Esto nos permite usar el valor verbose.log para hacer referencia al archivo.