Zum Hauptinhalt springen
Simbioza

API: ejemplos con cURL

Las capturas de pantalla muestran la interfaz en inglés.

Para desarrolladores: API

Preparación

El administrador habilita API y emite una clave cuyo propietario tiene permisos de encuesta. El ejemplo completo utiliza surveys:read, surveys:write, surveys:publish y surveys:results. Agregue surveys:export solo para CSV. Otorgar sólo los alcances necesarios para una integración más estrecha.

Necesita curl y Python 3. Desde Plantilla y ejemplos, copie la plantilla y el asistente en api-feedback-template.json y prepare_api_survey.py en la misma carpeta de trabajo. Los idiomas de plantilla deben estar instalados y activos en el destino.

1. Crea un borrador y guarda las preguntas.

export SURVEY_API_TOKEN='YOUR_SCOPED_API_KEY'
BASE='https://simbioza.example/api/v1/surveys'
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $SURVEY_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"title":"Workshop feedback","primary_language":"en"}' \
  "$BASE" > created.json
SURVEY_ID=$(python3 -c 'import json; print(json.load(open("created.json"))["data"]["uuid"])')
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $SURVEY_API_TOKEN" "$BASE/$SURVEY_ID" > draft.json
VERSION=$(python3 -c 'import json; print(json.load(open("draft.json"))["data"]["survey"]["lock_version"])')
python3 prepare_api_survey.py --survey "$SURVEY_ID" --version "$VERSION" > definition.json
curl --fail-with-body --silent --show-error -X PATCH \
  -H "Authorization: Bearer $SURVEY_API_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @definition.json "$BASE/$SURVEY_ID" > saved.json

POST devuelve HTTP 201 y la nueva encuesta UUID. Utilice ese identificador, no un ejemplo de documentación UUID. PATCH envíe una definición completa con la versión actual. El asistente asigna nuevos identificadores de preguntas y opciones.

2. Revisar y publicar

Antes de confirmar, abra el nuevo borrador en el navegador agregando /surveys/edit/ y su UUID a su dirección de instalación. Consulte su contenido y flujo de prueba. Después de revisar, enviar y publicar como cuenta autorizada:

python3 - <<'PY' > transition.json
import json
saved = json.load(open('saved.json'))['data']
print(json.dumps({'version': saved['survey']['lock_version'],
                  'revision': saved['revision']['uuid'], 'confirmed': True}))
PY
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $SURVEY_API_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @transition.json "$BASE/$SURVEY_ID/submit-review"
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $SURVEY_API_TOKEN" "$BASE/$SURVEY_ID" > review.json
python3 - <<'PY' > approval.json
import json
r = json.load(open('review.json'))['data']
print(json.dumps({'version': r['survey']['lock_version'],
                  'revision': r['revision']['uuid'], 'confirmed': True}))
PY
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $SURVEY_API_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @approval.json "$BASE/$SURVEY_ID/publish"

Lea la versión nuevamente después del envío porque el flujo de trabajo la cambió. Si la clave no se puede publicar, una persona autorizada la aprueba a través de la interfaz.

3. Abra la encuesta y lea los resultados.

Encuentra la encuesta publicada en Encuestas. En su propia instalación, su página es /surveys/participate/ más su UUID. Esto explica el patrón de dirección; no es un vínculo prueba-encuesta.

Una encuesta creada por API aparece como un cuestionario normal en el navegador.
Una encuesta creada por API aparece como un cuestionario normal en el navegador.
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $SURVEY_API_TOKEN" \
  "$BASE/$SURVEY_ID/results?lang=en&page=1&per_page=10"

Resultado: su propia encuesta nueva, publicada mediante el flujo de trabajo normal. La lectura de los resultados aún verifica los derechos, la audiencia y el momento del propietario de la clave. Las respuestas reales se recopilan a través del formulario web habitual.

Kommentare

0

Es liegen noch keine Kommentare vor.

Sie müssen sich anmelden, um einen Kommentar hinzuzufügen.

Erstellt: Krešimir Mihalj 27 oct 2026, 9:43 · Letzte Änderung: Krešimir Mihalj 27 oct 2026, 12:57