Enviar archivos PDF directamente a Storage

Creada por Wenderson Cotta Sansão, Modificado el Jue., 11 Jun. a las 5:04 P. M. por Wenderson Cotta Sansão

Para grandes volúmenes de archivos PDF, es posible realizar el envío directamente al storage.

Antes del envío, es necesario que exista un pedido registrado en el sistema. Para ello, puede utilizar un ID de pedido ya existente o crear uno nuevo mediante la API.

Al crear un pedido, es obligatorio informar:

ID de la clínica;
ID del estado del pedido.

Con el ID del pedido y la información de metadatos del archivo PDF, es posible solicitar al servidor los datos necesarios para el envío al storage.

La solicitud debe realizarse a la URL:

https://max.cfaz.net/api/v1/archives/signed_url

El cuerpo de la solicitud debe contener:

request_id → ID del pedido al que se vinculará el PDF.
file_name → Nombre del archivo PDF.
file_size → Tamaño del archivo en bytes.
content_type → Para PDF, use application/pdf.
checksum → MD5 del archivo codificado en Base64.

Archivo interno:

Para registrar el PDF como archivo interno, informe is_hidden=true en la etapa final de actualización del archivo en Cfaz.

is_hidden=false → El PDF aparece en la documentación del pedido.
is_hidden=true → El PDF aparece en la pestaña de archivos internos.

Cálculo del checksum:

El cálculo del checksum debe realizarse de la siguiente manera:

Leer el contenido binario del archivo.
Calcular el hash MD5 de ese contenido.
Codificar el resultado en Base64.
Enviar ese valor como checksum.

Ejemplo con CURL:

curl -X POST "https://max.cfaz.net/api/v1/archives/signed_url" \
  -H "Authorization: Bearer 62ed05b2bd52b20e5a1eff01a0b862e6" \
  -d "request_id=300196" \
  -d "file_name=arquivo.pdf" \
  -d "file_size=529058" \
  -d "checksum=KPnqX2hT1xqxyvR6BvaPjA==" \
  -d "content_type=application/pdf"

El retorno esperado es:

{
  "id": 875413,
  "headers": {
    "Content-MD5": "XE6RuyZgdUBewbbBjyx5g==",
    "Content-Disposition": "inline; filename=\"1544_paciente_last_Laudo_Ilustrado.pdf\"; filename*=UTF-8''1544_paciente_last_Laudo_Ilustrado.pdf",
    "Cache-Control": "public, max-age=31536000, immutable"
  },
  "signed_id": "eyJfcmFpbHMiOnsiZGF0YSI6MTI4MTUyNSwicHVyIjoiYmxvYl9pZCJ9fQ==--0f6f0c5a19f18be089f3192b40eb368beb296c12",
  "signed_url": "https://storage.googleapis.com/...",
  "download_url": "https://storage.googleapis.com/..."
}

Cada campo contiene:

id → Identificador único del archivo dentro del sistema. Este es el ID del archive creado en Cfaz y será usado en la URL de la etapa final: /api/v1/archives/:id.
headers → Encabezados HTTP que deben utilizarse al enviar el PDF al storage. Use exactamente los headers retornados en esta clave.
signed_id → Identificador firmado del archivo en ActiveStorage. No se usa en el upload al storage; guarde este valor para la etapa de actualización del archivo en Cfaz.
signed_url → URL para el envío del PDF al storage.
download_url → URL temporal para la descarga del PDF.

Enviar el PDF al Storage:

Tras recibir la respuesta de la URL firmada, envíe el contenido binario del PDF con PUT directamente al signed_url retornado por la API.

No construya otra URL y no envíe este upload a /api/v1/archives/:id.

Utilice también todos los headers retornados en el campo headers exactamente como aparezcan en la respuesta. Si la respuesta retorna Content-MD5, Content-Disposition y Cache-Control, los tres headers deben enviarse en el PUT.

En esta etapa, use únicamente:

signed_url → Como destino del PUT.
headers → Como encabezados del PUT, usando todos los campos retornados.
archivo PDF → Como cuerpo de la solicitud.

El signed_id no debe enviarse al storage. Se usará únicamente en la próxima etapa, en archive[document], para indicar a Cfaz qué archivo enviado al storage debe vincularse al pedido.

Ejemplo:

curl -X PUT "<signed_url retornado pela API>" \
  -H "Content-MD5: XE6RuyZgdUBewbbBjyx5g==" \
  -H "Content-Disposition: inline; filename=\"1544_paciente_last_Laudo_Ilustrado.pdf\"; filename*=UTF-8''1544_paciente_last_Laudo_Ilustrado.pdf" \
  -H "Cache-Control: public, max-age=31536000, immutable" \
  --upload-file "arquivo.pdf"

En el ejemplo anterior, los headers Content-MD5, Content-Disposition y Cache-Control se utilizaron porque aparecieron en headers en el retorno de la API.

Actualizar el archivo en Cfaz:

Tras completar el envío al storage, es necesario actualizar Cfaz para vincular el archivo enviado al pedido.

Esta etapa utiliza dos valores retornados en la primera solicitud, en /api/v1/archives/signed_url:

id → Usado en la URL /api/v1/archives/:id.
signed_id → Usado en el campo archive[document].

También es necesario informar nuevamente:

request_id → ID del pedido al que se vinculará el PDF.
archive[is_hidden] → Define si el PDF será archivo común o archivo interno.

Ejemplo usando los valores retornados anteriormente:

{
  "id": 875413,
  "signed_id": "eyJfcmFpbHMiOnsiZGF0YSI6MTI4MTUyNSwicHVyIjoiYmxvYl9pZCJ9fQ==--0f6f0c5a19f18be089f3192b40eb368beb296c12"
}

En este caso:

Use 875413 en la URL: /api/v1/archives/875413.
Use el signed_id en archive[document].

El archivo solo aparecerá en el pedido después de que esta actualización se realice con éxito.

Archivo común, visible en la documentación del pedido:

curl -X PUT "https://max.cfaz.net/api/v1/archives/875413" \
  -H "Authorization: Bearer 62ed05b2bd52b20e5a1eff01a0b862e6" \
  -d "archive[request_id]=300196" \
  -d "archive[document]=eyJfcmFpbHMiOnsiZGF0YSI6MTI4MTUyNSwicHVyIjoiYmxvYl9pZCJ9fQ==--0f6f0c5a19f18be089f3192b40eb368beb296c12" \
  -d "archive[is_hidden]=false"

Archivo interno:

curl -X PUT "https://max.cfaz.net/api/v1/archives/875413" \
  -H "Authorization: Bearer 62ed05b2bd52b20e5a1eff01a0b862e6" \
  -d "archive[request_id]=300196" \
  -d "archive[document]=eyJfcmFpbHMiOnsiZGF0YSI6MTI4MTUyNSwicHVyIjoiYmxvYl9pZCJ9fQ==--0f6f0c5a19f18be089f3192b40eb368beb296c12" \
  -d "archive[is_hidden]=true"

Tras esta actualización, el PDF quedará registrado en el pedido.

Ejemplo funcional con Python:

import base64
import hashlib
import os

import requests


# ====== Configuraciones ======

CFAZ_URL = "https://max.cfaz.net/api/v1"
TOKEN = ""
REQUEST_ID = 300196
CAMINHO_PDF = "arquivo.pdf"

# false = aparece en la documentación del pedido
# true = aparece en archivos internos
IS_HIDDEN = False


# ====== Utilidades ======

def calcular_checksum(caminho_arquivo):
    md5 = hashlib.md5()

    with open(caminho_arquivo, "rb") as arquivo:
        for bloco in iter(lambda: arquivo.read(1024 * 1024), b""):
            md5.update(bloco)

    return base64.b64encode(md5.digest()).decode("ascii")


def info_pdf(caminho_arquivo):
    return {
        "file_name": os.path.basename(caminho_arquivo),
        "file_size": os.path.getsize(caminho_arquivo),
        "checksum": calcular_checksum(caminho_arquivo),
        "content_type": "application/pdf",
    }


# ====== Etapa 1: solicitar URL firmada ======

def solicitar_url_assinada(cfaz_url, token, request_id, caminho_pdf):
    payload = {
        "request_id": request_id,
        **info_pdf(caminho_pdf),
    }

    response = requests.post(
        f"{cfaz_url}/archives/signed_url",
        json=payload,
        headers={"Authorization": f"Bearer {token}"},
        timeout=30,
    )

    response.raise_for_status()
    return response.json()


# ====== Etapa 2: enviar PDF al storage ======

def enviar_para_storage(caminho_pdf, signed_url, headers):
    with open(caminho_pdf, "rb") as arquivo:
        response = requests.put(
            signed_url,
            data=arquivo,
            headers=headers,
            timeout=120,
        )

    response.raise_for_status()


# ====== Etapa 3: actualizar archivo en Cfaz ======

def atualizar_arquivo_no_cfaz(cfaz_url, token, archive_id, request_id, signed_id, is_hidden=False):
    payload = {
        "archive": {
            "request_id": request_id,
            "document": signed_id,
            "is_hidden": is_hidden,
        }
    }

    response = requests.put(
        f"{cfaz_url}/archives/{archive_id}",
        json=payload,
        headers={"Authorization": f"Bearer {token}"},
        timeout=30,
    )

    response.raise_for_status()
    return response.json()


# ====== Flujo completo ======

def enviar_pdf_para_cfaz(cfaz_url, token, request_id, caminho_pdf, is_hidden=False):
    dados_upload = solicitar_url_assinada(cfaz_url, token, request_id, caminho_pdf)

    enviar_para_storage(
        caminho_pdf,
        dados_upload["signed_url"],
        dados_upload.get("headers", {}),
    )

    return atualizar_arquivo_no_cfaz(
        cfaz_url,
        token,
        dados_upload["id"],
        request_id,
        dados_upload["signed_id"],
        is_hidden=is_hidden,
    )


# ====== Ejecución ======

if __name__ == "__main__":
    resultado = enviar_pdf_para_cfaz(
        CFAZ_URL,
        TOKEN,
        REQUEST_ID,
        CAMINHO_PDF,
        is_hidden=IS_HIDDEN,
    )

    print("PDF enviado y registrado con éxito.")
    print(resultado)

Antes de ejecutar, instale la dependencia: pip install requests

Para enviar como archivo interno, cambie:

IS_HIDDEN = True

Para enviar como archivo común de la documentación, mantenga:

IS_HIDDEN = False