Centro de ayudaIntegraciones

Para: Administradores

Carga y adjunta archivos con una clave de hub.

Obtén una dirección de carga, sube un archivo, adjúntalo a una publicación, nota, tarea, formulario o firma electrónica, y descarga los archivos de un caso.

En este artículo10 secciones

Antes de empezar

Esta página describe cómo cargar archivos en un caso, adjuntarlos y descargarlos, utilizando una clave de hub. Los caminos de acceso se encuentran bajo https://prd-api-app.caseactive.com/v1/<hub id>/<case id>.

Cómo funciona

Un archivo requiere tres pasos: primero se debe solicitar una dirección de carga para el archivo; luego, se carga el archivo en esa dirección; y finalmente, se adjunta el archivo al elemento correspondiente.

ArtículoDirección de cargaAdjuntarEliminar
Una publicación/artículoGET /posts/<post_id>/drivePUT /posts/<post_id>/mediaDELETE /posts/<post_id>/media
Una nota/ComentarioGET /notes/<note_id>/drivePUT /notes/<note_id>/mediaDELETE /notes/<note_id>/media
Una tareaGET /tasks/<task_id>/drivePUT /tasks/<task_id>/mediaDELETE /tasks/<task_id>/media
Una tarea infantilGET /subtasks/<subtask_id>/drivePUT /subtasks/<subtask_id>/mediaDELETE /subtasks/<subtask_id>/media
Un documento en formato electrónico, firmado o notificado por escrito.Con GET /<forms, signs or notes>/<id>/drive y media_group=schemasPUT /<forms, signs or notes>/<id>/schema/media—
  • Un clave solo puede asociar archivos a los mensajes que haya creado el Asistente Virtual. Puede asociar archivos a cualquier nota, tarea o tarea secundaria.
  • Para adjuntar un archivo a un comentario, especifique la dirección correspondiente al comentario o tarea, utilizando el tag /drive. Luego, utilice el tag PUT /<posts, signs, tasks or subtasks>/<id>/comments/<comment_id>/media para indicar el archivo que se va a adjuntar. Un clave solo puede ser asignada a los propios comentarios.
  • Un formulario o firma electrónica contiene un único documento, y no otros archivos. Una vez que recibe el documento deseado, toma otro solo si el primero no pudo ser convertido a su formato deseado.

1. Obtén una dirección de carga

ParámetroLo que haceRequeridoPor defecto
media_groupEl tipo de archivo puede ser: docs, images, audios, videos o files. En el caso de documentos relacionados con formularios, firmas electrónicas o notas, también puede ser schemas.Sí.—
media_extensionLa extensión del archivo es, por ejemplo, pdf. Debe ser una de las extensiones permitidas; files permite utilizar cualquier extensión.Sí.—
tag_idEl nombre en el que se guarda el archivo, escrito con letras, números y guiones, como por ejemplo: repair-estimateSí.—
AmableExtensiones
docs y schemascsv, doc, docx, odt, pdf, ppt, pptx, rtf, txt, xls, xlsx
imagesBMP, GIF, JPEG, JPG, PNG, SVG, TIFF, WebP
audiosaac, aiff, amr, flac, m4a, mp3, oga, opus, wav, wma… y otros formatos de audio menos comunes.
videosFormatos de video menos comunes: 3GP, AVI, FLV, M4V, MKV, MOV, MP4, MPEG, MPG, OGG, WebM, WMV.
filesCualquiera
curl "https://prd-api-app.caseactive.com/v1/ca-7e6d5c4b3a2f10/cc-1a2b3c4d5e6f70/posts/post::20261002154134_b0accfaac139a9/drive?media_group=docs&media_extension=pdf&tag_id=repair-estimate" \
  -H "Authorization: Bearer YOUR_API_KEY"

Responde a los valores url, que indican la dirección a la cual se debe cargar el archivo, y fields, que indica los campos del formulario que deben enviarse junto con el archivo. fields.key es la ubicación donde se guardará el archivo. La dirección funciona durante una hora.

2. Sube el archivo

Envíe un mensaje. multipart/form-data Enviar por correo electrónico a url, con cada entrada en fields Según lo indicado, entonces el archivo se encuentra en el último lugar. file. fields Tiene un espacio vacío. Content-Type: Rellénelo con el tipo de archivo correspondiente, por ejemplo: application/pdf, En lugar de enviar una segunda llamada, esta llamada se envía al almacén de archivos, y no a la API. Por lo tanto, no se necesita ninguna clave para realizarla.

curl -X POST "<url>" \
  --form-string "key=<fields.key>" \
  --form-string "Content-Type=application/pdf" \
  --form-string "<every other entry of fields, as given>" \
  -F "file=@repair-estimate.pdf"

Envíe los registros de fields junto con --form-string, no con -F. Algunos de estos registros comienzan con <; -F interpreta esto como un archivo.

Responde a la pregunta 201. El archivo más grande es el límite establecido para las funciones del Asistente Virtual en este caso: 5,000 MB por defecto. Un administrador puede reducir ese límite en la sección Configuraciones › Roles. Se rechaza la carga de archivos que superan ese límite. Los archivos cargados pero nunca adjuntados se eliminan después de tres días.

3. Adjúntalo

curl -X PUT https://prd-api-app.caseactive.com/v1/ca-7e6d5c4b3a2f10/cc-1a2b3c4d5e6f70/posts/post::20261002154134_b0accfaac139a9/media \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"media": [{"media_key": "<fields.key>"}]}'
{
  "data": {
    "items": [{"media_key": "hosts/ca-7e6d5c4b3a2f10/cases/cc-1a2b3c4d5e6f70/posts/post::20261002154134_b0accfaac139a9/media/docs/20261002154512_5f4e3d2c1b0a99/20261002154512_5f4e3d2c1b0a99.pdf", "media_id": "20261002154512_5f4e3d2c1b0a99"}],
    "currentItemCount": 1
  }
}
  • media toma varios archivos al mismo tiempo. Cada uno de ellos debe haber sido cargado con una dirección que pertenece a ese mismo elemento.
  • La función de adjuntar archivos simplemente permite agregarlos al documento; nunca los reemplaza.
  • En un mensaje, se envían los webhooks asociados. add_post_media Para cada archivo, se envía un correo electrónico que indica cuántos archivos contiene ese archivo.

Después de adjuntar

Los archivos se procesan después de su adjuntamiento: las imágenes se redimensionan, el audio y el video se preparan para su reproducción, y los documentos se convierten a formato PDF, incluyendo las imágenes de las páginas. Los archivos del tipo files se mantienen tal como están.

La lectura de cada elemento, como GET /posts/<post_id>, enumera sus archivos bajo media.<kind>.items.<media_id>.

CampoLo que contiene
execution_statusRUNNING Mientras está siendo procesado… SUCCEEDED O FAILED
originalEl archivo ha sido cargado.
pdfUn documento convertido a formato PDF, una vez listo.
flatLa copia en formato electrónico, una vez que todos hayan firmado…
tag_id, content_type, media_sizeSu nombre, tipo y tamaño en bytes.

Mientras cualquier archivo esté siendo procesado, el elemento encoding indica que dicho archivo aún no está listo para su publicación. Un formulario o firma electrónica no puede ser publicada hasta que el documento esté listo.

Descargando un archivo

Descargue un archivo desde https://privcdn.caseactive.com/, seguido de sus original, pdf o flat. Utilice su clave en el mismo encabezado que para cada llamada.

curl "https://privcdn.caseactive.com/hosts/ca-7e6d5c4b3a2f10/cases/cc-1a2b3c4d5e6f70/posts/post::20261002154134_b0accfaac139a9/media/docs/20261002154512_5f4e3d2c1b0a99/20261002154512_5f4e3d2c1b0a99.pdf" \
  -H "Authorization: Bearer YOUR_API_KEY" -o repair-estimate.pdf

Las verificaciones relacionadas con la clave se aplican como en cualquier llamada telefónica; incluye además el rango de IP correspondiente. También es posible descargar información desde cualquier área donde esté ubicado el asistente virtual.

Eliminar un archivo

DELETE /<item>/media toma un cuerpo JSON que contiene los valores media_id y media_group, y devuelve el valor 200. En un post, los webhooks reciben el valor delete_post_media. Los documentos generados por formularios, firmas electrónicas o notas no pueden eliminarse; en lugar de eso, es necesario eliminar el elemento en cuestión.

Ejemplo: un PDF en una nueva publicación

  1. POST /posts Con el mensaje de correo electrónico. message. Se publica de inmediato, junto con una notificación por parte del portal. El correo electrónico se envía aproximadamente 30 segundos después, y en ese momento ya se cuenta el número de archivos adjuntos. Por lo tanto, adjúntelos dentro de ese tiempo.
  2. GET /posts/<post_id>/drive?media_group=docs&media_extension=pdf&tag_id=repair-estimate.
  3. Suba el archivo a url, utilizando el nombre fields.
  4. Con PUT /posts/<post_id>/media y fields.key.
  5. Lea. GET /posts/<post_id> Hasta que el archivo esté completo. execution_status Es SUCCEEDED O FAILED.

Si se rechaza una llamada

EstadomessagePor qué
400SchemaFieldsExceptionFaltan o no son válidos algunos parámetros. Por ejemplo, puede haber una extensión que no es aceptable, o un elemento del tipo tag_id que contiene espacios. El elemento errors se refiere a algo que no fue cargado. En el punto media.<n>.media_key, el archivo no se encontró; probablemente se tratara de otro elemento. En el punto /schema/media, el archivo no se cargó como se indica en schemas. Esto también ocurre cuando el elemento que se está adjuntando no existe. No hay nada adjunto en la solicitud.
403ItemUpdateFailedExceptionEl archivo ya está adjunto, o bien, el formulario, la firma electrónica o la nota ya contienen el documento correspondiente.
403ItemAuthorOnlyExceptionLa persona que intentó hacerlo quería adjuntar un archivo a algún mensaje o comentario escrito por otra persona.
403CaseClosedExceptionEl caso está cerrado.
404ItemNotFoundExceptionEl elemento no existe cuando se solicita su dirección de carga, o el archivo que se desea eliminar tampoco existe.

La subida del archivo se realiza en el formato propio del almacenamiento de archivos: EntityTooLarge para los archivos que superan el límite establecido, y AccessDenied cuando la dirección de acceso ya no es válida. Para obtener información sobre el cuerpo de error de la API y los demás códigos, consulte manejo de errores y códigos de estado de la API.

Artículos relacionados

Entienda lo que la API puede hacerDescubre qué funciones pueden alcanzar una clave de administración y una clave de concentrador, por qué cada clave actúa como asistente virtual y dónde encontrar la lista técnica completa.IntegracionesAgregue publicaciones y comentarios con una clave central.Como asistente virtual, puedes añadir publicaciones al feed de un caso, responder con comentarios y leerlos, editarlos o eliminarlos desde tu propio software.IntegracionesEnvíe firmas electrónicas y lea firmas con una clave central.Crea una firma electrónica para un caso a partir de una plantilla, elige quién firma cada campo, publícala para su firma y descarga la copia bloqueada una vez que todos hayan firmado.IntegracionesGestionar errores de API y códigos de estadoLea el cuerpo del error, qué significan los códigos 400, 401, 403, 404, 500 y 503, y por qué un elemento que su clave no puede ver responde con el código 404.Integraciones