Saltar al contenido principal

​
Por qué Projection es importante

Las respuestas de webhooks y GET/Submission incluyen cada campo que el solicitante ingresó o que Argos generó durante el procesamiento. A medida que los envíos crecen, el tamaño del payload, las obligaciones de almacenamiento de PII y la complejidad de la gestión de datos escalan juntos. Projection le permite persistir políticas de exclusión por proyecto para que sus aplicaciones solo reciban las porciones de datos que les interesan, habilitando flujos de datos con privilegios mínimos sin modificar los flujos de trabajo principales.
Las políticas de Projection se crean y gestionan exclusivamente a través de la API POST /projection en lugar del dashboard.

​
Alcance y restricciones

  • Projection actualmente se aplica solo a envíos creados a través de Liveform.
  • La política afecta los eventos de webhook vinculados a esos envíos (submission.submit, submission.approved, submission.rejected) y la API GET/Submission por igual.
  • GET/Submission devuelve datos basados en la Projection asignada en el momento del envío. Editar una política después no cambia retroactivamente los envíos existentes.
Cada proyecto puede almacenar hasta 10 políticas de Projection. Crear una undécima política devuelve 409 Projection count limit exceeded.

​
Componentes de la política

ComponenteDescripciónConsideraciones clave
nameIdentificador legible por humanosSolo letras minúsculas, dígitos y guiones bajos; único por proyecto.
modeCómo se manejan los datosSolo la opción exclude está disponible actualmente.
fieldsArray de campos a ocultarDebe usar valores de la lista permitida en POST /projection.
projection_idID generado por el sistemaReferenciado por URLs de Liveform, registros de webhook y payloads de GET/Submission para confirmar qué política fue aplicada.
Incluya intención o versionado en el campo name (por ejemplo, aml_minimal_v1) para que los equipos puedan reutilizar políticas con confianza.

​
Cómo funciona el flujo

  1. Llame a POST /projection para definir el conjunto de exclusión y recibir un projection_id.
  2. Cifre ese projectionId (o projectionName) dentro de la URL de Liveform o el payload del token.
  3. Una vez que el usuario finaliza el envío, los webhooks y GET/Submission emiten respuestas ya filtradas por la Projection elegida.
curl --location 'https://rest-api.argosidentity.com/v3/projection' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: spearmint_project_key' \
  --data-raw '{
    "name": "kyc_minimal_v1",
    "mode": "exclude",
    "fields": ["date_of_birth","address_formatted","cf3"]
  }'

{
  "data": [
    {
      "submissionId": "subm_8zg6kp9",
      "status": "approved",
      "projection": {
        "projectionId": "proj_123abc",
        "projectionName": "kyc_minimal_v1"
      },
      "data": {
        "first_name": "Minty",
        "nationality": "KOR",
        "identityNumber": null
      }
    }
  ]
}
Los campos listados en fields, como identityNumber aquí, se omiten o se establecen como null tanto en los payloads de webhook como en las respuestas de GET/Submission, aunque Argos aún retiene los valores subyacentes.

​
Flujo de trabajo de Projection

1

Crear la política

Use POST /projection para definir la lista de exclusión. Las políticas se activan inmediatamente.
La respuesta debe contener "message": "Create projection success" y un projection_id.
2

Adjuntar la política a Liveform

Agregue el projectionId cifrado a la URL de Liveform o al payload del token, por ejemplo:
https://form.argosidentity.com?pid=proj_x1yz&encrypted={'projectionId':'proj_123abc'}
projectionId y projectionName son mutuamente excluyentes, y ambos deben estar cifrados. Consulte la guía de query string y token para detalles de cifrado.
3

Validar mediante webhooks o Get Submission

Los payloads de webhook y las respuestas de GET/Submission incluyen projection.projectionId. Confirme que el payload ahora solo muestra los campos previstos.
Registre projection.projectionId en sus servicios downstream para rastrear qué política dio forma a cada payload.
4

Monitorear y retirar políticas

GET /projection y GET /projection/{projectionId} le ayudan a revisar las políticas activas. Elimine entradas no utilizadas mediante DELETE /projection/{projectionId} para liberar espacios o re-exponer datos.

​
Enlaces rápidos de la API Projection

POST/Projection

Crear nuevas políticas y definir el conjunto de exclusión.

GET/Projection

Consultar todas las Projection configuradas para el proyecto.

GET/Projection/{projectionId}

Inspeccionar una política individual, incluyendo campos y marca de tiempo de creación.

DELETE/Projection

Eliminar políticas obsoletas para re-exponer campos o mantenerse dentro del límite de 10 espacios.

​
Mejores prácticas operacionales

  • Recopile listas de campos requeridos de cada equipo consumidor antes de implementar Projection y documente las aprobaciones.
  • Almacene projectionId junto con los payloads de webhook o registros de análisis para simplificar auditorías y resolución de problemas.
  • Reutilice políticas existentes cuando sea posible para no alcanzar innecesariamente el límite de 10 políticas.
  • Defina esquemas explícitos por Projection en servicios downstream para evitar excepciones de puntero nulo cuando los campos desaparezcan.
Prefije los nombres de las políticas por entorno (por ejemplo, dev_payment_v1) para evitar confundir políticas de staging y producción.

​
Resolución de problemas

  • Confirme que el payload encrypted de Liveform está realmente cifrado; los valores en texto plano son rechazados.
  • Al usar projectionName, verifique que la ortografía sigue la regla de minúsculas y guiones bajos.
  • Llame a GET /projection para asegurar que el ID referenciado aún existe y la marca de tiempo coincide con sus expectativas.
Argos aún almacena el envío completo. Sin embargo, mientras la Projection esté adjunta, los webhooks y GET/Submission seguirán ocultando esos campos. Elimine la política con DELETE /projection/{projectionId} y active un nuevo envío para recibir payloads completos nuevamente.
Si alcanza el límite de 10 políticas, audite la lista actual mediante GET /projection. Elimine políticas no utilizadas o consolide combinaciones de campos en un conjunto compartido más pequeño antes de crear nuevas.