[API FE CRI] Nueva integración de la generación de documentos para los comprobantes electrónicos

Nuevo Endpoint: Obtener PDF de Documentos

GET /document-files/pdf

Se incorpora un nuevo endpoint que permite obtener el archivo PDF de un documento electrónico en formato base64. El PDF se genera bajo demanda al momento de la consulta.

Parámetros de consulta (Query Parameters)

Ejemplo de solicitud

GET /document-files/pdf?idDocument=01G1K58RYAYZ8RRQRWWR66XPXN&documentType=invoice&idCompany=01ABCDEF123456

Respuesta exitosa (200 OK)

{
  "pdf": "JVBERi0xLjQKMS..."
}

Nota: El contenido retornado en el campo pdf es una cadena en base64 que representa el archivo PDF completo. Para visualizarlo, debe decodificar la cadena base64 y guardarlo como archivo .pdf.

Requisitos para la disponibilidad del PDF

El PDF de un documento estara disponible unicamente cuando se cumplan las siguientes condiciones:

1. El estado del comprobante debe ser FINISHED: El documento debe haber completado todo su flujo de procesamiento.
2. El estado legal del documento debe ser ACCEPTED: El documento debe haber sido aceptado por el Ministerio de Hacienda.

Si el documento no cumple con estas condiciones, el endpoint retornara un error indicando que el documento no se encuentra en un estado final.

Generacion bajo demanda

Si al momento de la consulta el PDF aun no ha sido generado previamente, el sistema lo generara automaticamente en ese instante (generacion bajo demanda). Esto significa que:

• No es necesario esperar un proceso adicional despues de que el documento sea aceptado.
• La primera consulta puede tomar un poco mas de tiempo mientras se genera el PDF.
• Las consultas posteriores seran mas rapidas ya que el PDF quedara almacenado.

Cambios en los endpoints de consulta de documentos existentes

URLs pre-firmadas con vigencia de 60 minutos

Al consultar un documento a traves de los endpoints de consulta individuales (por ejemplo GET /invoices/{id}, GET /credit-notes/{id}, GET /tickets/{id}, etc.) utilizando el query parameter documents, los campos xml, xmlHacienda y pdf ahora retornan URLs pre-firmadas que permiten descargar los archivos directamente.

Estas URLs tienen una vigencia de 60 minutos desde el momento en que se genera la respuesta. Despues de este periodo, las URLs expiraran y sera necesario realizar una nueva consulta para obtener URLs vigentes.

Ejemplo de consulta con documentos adjuntos

GET /invoices/{id}?documents=pdf-xml-xmlHacienda

Ejemplo de respuesta

{
  "warnings": [
  ],
  "document": {
    "id": "01G1K58RYAYZ8RRQRWWR66XPXN",
    "key": "50623082200123456789000100002010000000011114229000",
    "status": "FINISHED",
    "legalStatus": "ACCEPTED",
    "governmentResponse": "Este comprobante fue aceptado...",
    "errorMessage": null,
    "xml": "https://pre-signed-url-valid-60-min.example.com/document.xml",
    "pdf": "https://pre-signed-url-valid-60-min.example.com/document.pdf",
    "xmlHacienda": "https://pre-signed-url-valid-60-min.example.com/hacienda-response.xml"
  }
}

Importante: Las URLs de los campos xml, pdf y xmlHacienda son enlaces pre-firmados temporales. Se recomienda descargar los archivos inmediatamente despues de obtener la respuesta, ya que expiran en 60 minutos.

Disponibilidad del PDF en la respuesta de consulta

El campo pdf (URL pre-firmada) en la respuesta de consulta de documentos estara disponible unicamente cuando:

• El estado legal (legalStatus) del documento sea ACCEPTED.
• El estado (status) del comprobante sea FINISHED.

Si se solicita el PDF (documents=pdf) pero el documento no esta en estado legal ACCEPTED, no se incluira el campo pdf en la respuesta y en su lugar se retornara una advertencia en el campo warnings.

Campo warnings (array de advertencias)

La respuesta de consulta de documentos ahora incluye el campo warnings, que es un array de objetos de advertencia. Cada objeto contiene:

Ejemplo con advertencias

{
  "warnings": [
    {
      "message": "The document is not in a final state",
      "code": "AP1020"
    }
  ],
  "document": {
    "id": "01G1K58RYAYZ8RRQRWWR66XPXN",
    "key": "50623082200123456789000100002010000000011114229000",
    "status": "FINISHED",
    "legalStatus": "REJECTED",
    "governmentResponse": "...",
    "errorMessage": null
  }
}

Posibles escenarios de advertencia

Tipos de documento soportados

Codigos de error

Resumen de cambios

• Nuevo endpoint GET /document-files/pdf para obtener el PDF de cualquier documento en formato base64, generado bajo demanda.
• URLs pre-firmadas en los endpoints de consulta de documentos individuales (xml, pdf, xmlHacienda) con vigencia de 60 minutos.
• El PDF solo esta disponible cuando el legalStatus es ACCEPTED y el status del comprobante es FINISHED.
• El campo warnings en las respuestas de consulta es ahora un array de advertencias. Se mantiene warning (singular) por retrocompatibilidad.
• Generacion de PDF bajo demanda: si el PDF no existe al momento de la consulta, se genera automaticamente.

Estos cambios se encuentran en nuestro ambiente sandbox y dentro de poco en el ambiente productivo.