Centro de ayudaIntegraciones

Para: Administradores

Envía formularios y lee las respuestas con una clave central.

Crea un formulario para un caso a partir de una plantilla, publícalo para que lo rellenen las personas que deben hacerlo y lee sus respuestas.

En este artículo7 secciones

Antes de empezar

Esta página trata sobre cómo enviar formularios y leer las respuestas que se reciben, utilizando una clave de conexión. Los caminos para ello se encuentran bajo https://prd-api-app.caseactive.com/v1/<hub id>/<case id>.

Llamadas

LlamarLo que hace
GET /forms/templatesLista de los plantillas de formularios que tienes.
POST /formsSe crea un formulario relacionado con el caso, pero este formulario no está publicado todavía.
PUT /forms/<form_id>/publishSe publica, y luego se envía a los destinatarios.
GET /forms?filter=allEnumera las formas en que se presenta el caso.
GET /forms/<form_id>Lee un formulario.
PUT /forms/<form_id>Cambia el nombre, la fecha de vencimiento, los recordatorios o los destinatarios.
DELETE /forms/<form_id>Suprimirlo, junto con sus respuestas.
GET /forms/<form_id>/responsesLista de las respuestas.
GET /forms/<form_id>/responses/<response_id>Lee una de las respuestas.
DELETE /forms/<form_id>/responses/<response_id>Borra la respuesta de una persona, para que pueda rellenarla nuevamente.

Un formulario se crea en dos pasos: primero se lo crea y luego se lo publica. Hasta que se publique, los destinatarios no pueden verlo, y nadie se entera de su existencia.

Crear un formulario

GET /forms/templates Lista de su formato publicado. PlantillasPlantilla Un formulario, formulario, firma electrónica, nota o tarea reutilizable que se guarda en la biblioteca y se copia en los expedientes., Los más antiguos primero, y cada uno de ellos… asset_id, title, description, due_mins (¿Cuántos minutos después de que se envíe lo que se debe enviar?). rrule (Su repetición) notifications y instant_notify.

POST /forms acepta los siguientes valores:

CampoLo que haceRequeridoPor defecto
nameEl título del formulario. Letras, números, espacios y & ' - _ ( ) . /; sin comas ni puntos y coma.Sí.—
duration{"due_date": "2026-10-09T17:00:00-04:00", "rrule": "FREQ=MONTHLY"} La fecha de vencimiento necesita tener el desplazamiento en la zona horaria correspondiente. rrule Una regla de repetición es opcional. zoneinfo La zona horaria en la que se realiza la repetición, como America/New_York, también es opcional. Sin esta información, la repetición seguirá la zona horaria del centro de control, en el momento y día en que ocurra el cambio de hora.Sí.—
participants_idsLas personas que lo completan son los identificadores de los usuarios que están relacionados con el caso, desde GET /team.No, pero era necesario publicarlo.Nadie
template{"owner": "host", "template_id": "<asset_id>"} Para utilizar el documento de un plantilla.No.Ninguno.
descriptionUna nota que se incluye junto con el formulario.No.El modelo utilizado…
notificationsRecordatorios: {"names": ["days", "hours"], "values": [-1440, -60]}. Cada valor indica el número de minutos que faltan hasta la fecha de vencimiento.No.El modelo, o nada.
instant_notifyfalse No se envían ninguna solicitud durante el proceso de publicación; solo se envían los recordatorios.No.El modelo, o true

Un plantilla incluye el documento, la descripción, los recordatorios y instant_notify. Pero no incluye la fecha de vencimiento ni la opción de repetir el proceso. Es necesario calcular due_date a partir de due_mins. Además, se debe enviar rrule si este existe.

curl -X POST https://prd-api-app.caseactive.com/v1/ca-7e6d5c4b3a2f10/cc-1a2b3c4d5e6f70/forms \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Case intake form", "duration": {"due_date": "2026-10-09T17:00:00-04:00"}, "participants_ids": ["cu-4f1c2a9e8b7d60"], "template": {"owner": "host", "template_id": "form::20260915101500_3c2b1a0f9e8d70"}}'

Responde a 201 con form_id. El documento del plantilla se copia en segundo plano: se lee el formulario hasta que ya no haya más copying; luego, se publica el resultado.

Para enviar su propio documento, cree el formulario sin incluir la etiqueta template. Luego, cargue un archivo PDF como el documento a enviar. Espere hasta que todo esté listo. Para más información, vea Carga y adjunta archivos utilizando una clave de hub.

Publicación

PUT /forms/<form_id>/publish no toma ningún cuerpo y responde con 200.

  • A cada destinatario se le envía un correo electrónico con una solicitud para que lo complete, o se le envía un mensaje de texto si no tiene correo electrónico confirmado. Esto ocurre de inmediato, a menos que… instant_notify Es false. Aparece en ellos. Cosas que deben hacerseQue hacer La lista en el maletín de cosas que te esperan, como formularios para rellenar, documentos para firmar o eventos para confirmar. Y también en las notificaciones de su portal.
  • Las recordatorias se envían cada vez en el momento notifications, pero nada se envía a la hora establecida. Las respuestas solo se aceptan después de esa fecha.
  • Una forma de repetición se mueve hacia su próxima fecha de vencimiento en cada uno de los casos. Las respuestas son claras, y todos los participantes son preguntados nuevamente de inmediato, a menos que instant_notify sea igual a false.
  • Alguien que no está relacionado con el caso, es eliminado de la lista.

El documento no puede cambiarse una vez que se publica el formulario. Su nombre, fecha de vencimiento, recordatorios, destinatarios y descripción pueden ser modificados. Con PUT /forms/<form_id>, se puede enviar un mensaje nuevamente, pero sin necesidad de utilizar zoneinfo. Esto mantiene el huso horario actual del documento. Al cambiar la fecha de vencimiento, los recordatorios se envían nuevamente a todos aquellos que aún no hayan respondido. Las personas a las que se agregan también reciben el mensaje de inmediato. Con instant_notify y false, ninguno de estos elementos se ejecuta hasta que los recordatorios sean enviados.

Respuestas de lectura

En GET /forms/<form_id>/responses se listan las respuestas de cada persona, ordenadas por fecha de nacimiento, todas en una sola página. Una forma de presentación repetitiva solo muestra las respuestas de la fecha actual; las respuestas de fechas anteriores siguen siendo mostradas mediante su response_id.

{
  "data": {
    "items": [
      {
        "response_id": "response::20261003153012_9f8e7d6c5b4a30",
        "parent_id": "form::20261002150000_1a2b3c4d5e6f70",
        "user_id": "cu-4f1c2a9e8b7d60",
        "created_on": "2026-10-03T15:30:12+00:00",
        "response": {
          "format": "https://pspdfkit.com/instant-json/v1",
          "formFieldValues": [
            {"v": 1, "type": "pspdfkit/form-field-value", "name": "client_name", "value": "Jane Sample"},
            {"v": 1, "type": "pspdfkit/form-field-value", "name": "accident_date", "value": "2026-09-14"}
          ]
        }
      }
    ],
    "currentItemCount": 1,
    "selfLink": "https://prd-api-app.caseactive.com/v1/ca-7e6d5c4b3a2f10/cc-1a2b3c4d5e6f70/forms/form::20261002150000_1a2b3c4d5e6f70/responses"
  }
}
  • formFieldValues contiene los datos que la persona ha ingresado en cada campo, según lo indicado en el campo correspondiente a name. Una firma o dibujo se encuentra bajo los campos annotations y attachments.
  • La forma en que se lee el formulario indica quién ha respondido: responses asigna el ID de usuario de cada persona a su response_id.
  • Cuando alguien envía el formulario, al personal encargado del caso se le informa de ello, tal como lo harían si fueran ellos mismos quienes enviaran el formulario.

Eliminar la respuesta de una persona, utilizando {"user_id": "<their ID>"} como cuerpo del formulario, hace que el formulario vuelva a aparecer en la lista de tareas pendientes de esa persona. Nadie es informado al respecto. Una llave no puede llenar un formulario por sí sola.

Formularios de listado

GET /forms necesita filter.

filterLo que enumera
allCada forma de presentación del caso, incluyendo aquellas que aún no han sido publicadas. Lo más reciente primero.
selfEl asistente virtual se envía mediante cualquiera de las claves que usted utilice, o mediante automatizaciones.
completed, uncompletedLos formularios que se le pide al llamante que llene siempre están vacíos cuando no hay ninguna clave disponible.

Cada forma contiene sus valores form_id, name, participants_ids, due_date, published (y 1 una vez que se publique), responses, responses_ct, además de su documento correspondiente, que se encuentra bajo el identificador media.

DELETE /forms/<form_id> puede eliminar un formulario en cualquier momento, junto con las respuestas que contiene. De esa manera, ese formulario queda fuera de la lista de tareas pendientes de todos. Nadie se entera de esto.

Si se rechaza una llamada

EstadomessagePor qué
400SchemaFieldsExceptionFalta un campo o el campo es inválido. Por ejemplo, puede haber una coma en name, una fecha de vencimiento sin desplazamiento, o alguien que no está en el caso. En errors se indica su nombre.
400SchemaFieldsException, con ItemCopyNotAllowedException en templateEl plantilla no está publicada, no está disponible para las herramientas automáticas, o sus archivos aún están siendo procesados.
403PublishAlreadyPublishedExceptionYa se ha publicado.
403PublishAlreadyAnsweredExceptionAlguien ya ha respondido a esa pregunta.
403PublishMediaMissingExceptionTodavía no tiene ningún documento relacionado con esto.
403PublishMediaNotReadyExceptionSu documento aún está siendo copiado o convertido.
403PublishMediaFailedExceptionSu documento no pudo ser convertido.
403PublishDueTimePassedExceptionFecha de vencimiento ya pasada.
403PublishRecipientsMissingExceptionNo tiene a nadie a quien se pueda enviarla.
403BotNotAllowedExceptionUna llave intentó abrirlo.
403CaseClosedExceptionEl caso está cerrado.
404ItemNotFoundExceptionLa forma o respuesta en cuestión no existe.

Para información sobre el cuerpo de error y los demás códigos, vea Como manejar los errores de la API y los códigos de estado.

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.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.IntegracionesCarga 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.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