API, webhooks y SSO de sugerencias

La API de integración recibe incidencias o sugerencias desde su servidor mediante claves vinculadas a un proyecto. Las integraciones de incidencias pueden enviar webhooks firmados; el SSO de visitantes utiliza un secreto separado del tablero. Compruebe el endpoint, la identidad y la entrega. Las claves permanecen en el servidor y los tokens de redirección SSO no deben aparecer en registros compartidos.

Crear incidencias o feedback y recibir webhooks firmados

El propietario crea una integración con Nueva integración en la línea de título de Configuración del proyecto → Integraciones. Elija issues para trabajo interno que entra en triage o feedback para solicitudes de usuarios con votos y estado público. La clave mdy_ en texto claro se muestra una sola vez. Guárdela únicamente en el servidor, normalmente como MINDDY_API_KEY o MINDDY_FEEDBACK_KEY, nunca en el navegador, Git o registros compartidos. Cada integración aparece con su nombre, el prefijo de su clave, su fecha de creación, su último uso y una insignia Incidencias o Sugerencias. Para revocar una, el propietario elige Revocar en su menú ⋯ y confirma; entonces lleva la insignia Revocado y pasa al final de la lista, atenuada. La revocación es definitiva; las claves desconocidas o revocadas devuelven 401 invalid_api_key. Cada clave pertenece a un proyecto y un tipo: usarla en la otra familia de endpoints devuelve 403 wrong_key_kind. Una integración no es una persona: no tiene rol en el proyecto y conserva los permisos fijos de su tipo cuando cambian los roles de los miembros. Los lectores no ven las integraciones.

Enviar los campos correctos

GET /api/v1/issues/options proporciona los identificadores de categorías y los valores de prioridad y esfuerzo. Envíe después POST /api/v1/issues con un título no vacío y, opcionalmente, una descripción Markdown, prioridad, esfuerzo y categorías.

La incidencia siempre entra en triage; desde el exterior no se pueden definir estado, responsable o incidencia padre. Una respuesta 201 contiene id, number, identifier y status. Para los campos de sugerencias, la verificación de identidad y la moderación, siga el procedimiento de recepción de sugerencias.

curl --fail-with-body --request POST "$MINDDY_ORIGIN/api/v1/issues" \
  --header "Authorization: Bearer $MINDDY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"title":"Informe de demostración","description":"Reproducir con datos de demostración","priority":"low","effort":"s"}'

Verificar y deduplicar eventos

Una integración issues puede enviar issue.created, issue.status_changed e issue.updated. El propietario debe elegir cualquier nueva URL de destino webhook con Configurar el webhook… en el menú ⋯ de la integración. Una vez definido el destino, la línea Webhook bajo la integración muestra la última entrega, aceptada o rechazada con su fecha, o Todavía no se ha entregado. Los agentes pueden ajustar los eventos o el ámbito existentes o desactivarlo, pero no abrir un nuevo canal de salida. El ámbito integration incluye solo las incidencias de esa clave; all incluye todas las del proyecto.

Verifique X-minddy-Signature: el prefijo sha256= seguido de HMAC-SHA256 sobre los bytes originales recibidos. La clave HMAC es el digest SHA-256 de la clave API, representado como una cadena hexadecimal en minúsculas. Compare en tiempo constante antes de confiar en el contenido. No analice y vuelva a serializar JSON antes de calcular el hash. X-minddy-Delivery corresponde a delivery_id; elimine duplicados mediante ese UUID.

Tratar fallos y límites

La entrega es de mejor esfuerzo: tiene un timeout de cinco segundos y un único reintento inmediato tras un error de red o una respuesta 5xx; después se descarta definitivamente. Puede haber duplicados y cambios de orden. Guarde el contenido verificado, responda 2xx pronto y procéselo después. issue.updated agrupa cambios; description y plan identifican el campo sin incluir su valor. Consulte el último estado de entrega en la configuración. Para 429, respete Retry-After. Los errores de validación devuelven 422 y una cuota de incidencias alcanzada devuelve 403 issue_limit_reached, una negativa definitiva. Una creación con timeout puede haber tenido éxito: compruebe el resultado antes de repetirla. El voto mediante POST /api/v1/feedback/<post_id>/vote es idempotente para cada identidad.

Conectar ingestión de feedback y SSO

El propietario crea una clave de integración de feedback en la configuración del proyecto. Guarde la clave, que se muestra una sola vez, como MINDDY_FEEDBACK_KEY en la configuración secreta del backend. Nunca la incorpore al código del navegador. Defina MINDDY_ORIGIN con el origen de la instancia de destino, sin barra final.

curl -i "$MINDDY_ORIGIN/api/v1/feedback"   -H "Authorization: Bearer $MINDDY_FEEDBACK_KEY"   -H 'Content-Type: application/json'   --data '{"title":"Mostrar fecha de entrega","body":"Soporte necesita la fecha prevista.","user":{"external_id":"demo-user-1","name":"Lector de demostración"}}'

Proporcione un título no vacío de hasta 200 caracteres, un cuerpo opcional de hasta 10.000 y user.external_id y/o user.email. user.name es opcional. El ID externo admite 255 caracteres, el email 254 y el nombre 200. El backend responde por la identidad; la recepción anónima se rechaza. El éxito devuelve HTTP 201 con id, status, review_state, votos y pseudónimo. El tablero no tiene que estar activado para recibir solicitudes. analyze es un booleano con true por defecto; la cadena "false" se rechaza. false omite moderación, categorización y fusión de duplicados para esa solicitud y establece el estado de revisión published sin espera. Ese estado de revisión no activa el tablero ni evita las reglas de visibilidad o el estado de spam. La API crea solicitudes públicas por defecto y no acepta un parámetro de visibilidad privada.

Votos, errores y webhooks

Envíe {"user":{"external_id":"demo-user-1"}} por POST a /api/v1/feedback/<id>/vote, con los mismos encabezados. Cada identidad tiene un voto; repetirlo es idempotente. Una solicitud unida a otra devuelve 409 post_merged e indica su destino canónico.

La creación permite 20 llamadas por minuto y clave; los votos, 60. Respete Retry-After ante 429. Compruebe 401 invalid_api_key, 403 wrong_key_kind, 400 invalid_json y los errores de campos 422 antes de reintentar. La creación no es una actualización idempotente: si se pierde la respuesta, consulte la bandeja de feedback del equipo antes de repetir. Las claves de feedback no ofrecen un webhook saliente de incidencias. Una integración de incidencias configurada por separado proporciona ese canal con su propia firma y un contrato de entrega sin garantía.

Identificar por SSO

Como propietario, active el tablero y configure su secreto SSO independiente. El backend firma un JWT HS256 con sub estable, exp obligatorio y email y nombre opcionales. Use como máximo 600 segundos de validez y un jti único; la comprobación tolera 60 segundos de desfase de reloj. Redirija inmediatamente a /f/<board-token>?sso=<jwt>. Un token se consume una sola vez por tablero; volver a entrar requiere otro token recién firmado. Nunca reutilice la clave de recepción como secreto SSO. Mantenga los tokens fuera de registros y capturas compartidas.

Compruebe que el visitante abra Mis sugerencias con la identidad prevista. Un token caducado exige una nueva redirección. Si el secreto queda comprometido, rótelo mediante la confirmación del tablero y actualice el backend a la vez. El flujo por código de email sigue siendo la alternativa cuando el SSO no está disponible.

Elegir un objetivo para un comentario

Para una integración feedback, el propietario puede elegir el objetivo al crearla, o más tarde en la línea Objetivo de los nuevos comentarios bajo la integración existente en Configuración del proyecto → Integraciones; ese selector también puede crear un objetivo nuevo. Solo se aceptan objetivos activos del mismo proyecto. Cada nuevo envío POST /api/v1/feedback hereda el ajuste, incluso con analyze: false; no envíes objective_id en el cuerpo de la API. La respuesta 201 incluye el objective_id asignado o null. Cambiar o quitar el ajuste solo afecta a futuros envíos. Un objetivo no disponible devuelve 422 objective_not_found: elige uno activo o elimina el ajuste antes de reintentar. La revisión de Numo no deduce objetivos. La conversión hereda el objetivo y las categorías del comentario.