NueForm

API de Versões

Visualize o histórico de publicações e os snapshots de versão dos seus formulários.

A API de Versões permite que você visualize o histórico de publicações de um formulário. Toda vez que você publica um formulário, o NueForm cria um snapshot versionado contendo a configuração completa do formulário e todas as perguntas naquele momento. As versões também incluem um registro de alterações resumindo o que mudou desde a publicação anterior.

Todos os corpos de resposta usam nomes de campo em snake_case.

Endpoints
GET/api/v1/forms/:id/versions

Listar Versões do Formulário

GET/api/v1/forms/:id/versions

Retorna todas as versões publicadas de um formulário, ordenadas por número de versão (mais recente primeiro). Cada versão inclui o snapshot completo do formulário e um registro de alterações do que foi modificado.

Parâmetros de Caminho

idstringobrigatório

O ID do formulário

Campos da Resposta

idstring

ID único da versão

form_idstring

O formulário ao qual esta versão pertence

versioninteger

Número sequencial da versão (1, 2, 3, ...)

published_bystring

ID do usuário da pessoa que publicou esta versão

published_by_namestring

Nome de exibição da pessoa que publicou

created_atstring

Timestamp ISO 8601 de quando esta versão foi publicada

changelogarray

Lista de mudanças desde a versão anterior

changelog[].typestring

Tipo de mudança (veja Tipos de Entrada do Registro de Alterações abaixo)

changelog[].descriptionstring

Descrição legível da mudança

snapshotobject

Estado completo do formulário no momento da publicação (inclui todos os campos do formulário e as perguntas)

Tipos de Entrada do Registro de Alterações

form_createdstring

O formulário foi criado inicialmente

publishedstring

Um evento de publicação (inclui o número da versão)

question_addedstring

Uma nova pergunta foi adicionada

question_updatedstring

Uma pergunta existente foi modificada

question_deletedstring

Uma pergunta foi removida

question_reorderedstring

As perguntas foram reordenadas

theme_changedstring

Uma propriedade do tema foi modificada

settings_changedstring

Uma configuração do formulário foi modificada

title_changedstring

O título do formulário foi alterado

description_changedstring

A descrição do formulário foi alterada

Resposta

json
{
  "versions": [
    {
      "id": "66c3d4e5f6a7b8c9d0e1f2a3",
      "form_id": "665a1b2c3d4e5f6a7b8c9d0e",
      "version": 3,
      "published_by": "665a0a1b2c3d4e5f6a7b8c9d",
      "published_by_name": "Alice Johnson",
      "created_at": "2026-02-28T14:00:00.000Z",
      "changelog": [
        {
          "type": "question_updated",
          "description": "Updated question: \"How did you hear about us?\""
        },
        {
          "type": "question_added",
          "description": "Added question: \"Would you recommend us to a friend?\""
        },
        {
          "type": "theme_changed",
          "description": "Changed theme color from #6366f1 to #2563eb"
        }
      ],
      "snapshot": {
        "title": "Customer Feedback Survey",
        "description": "Help us improve our product",
        "theme_color": "#2563eb",
        "background_color": "#ffffff",
        "show_progress_bar": true,
        "questions": [
          {
            "id": "66a1b2c3d4e5f6a7b8c9d001",
            "type": "short_text",
            "title": "What is your name?",
            "required": true,
            "order": 0,
            "properties": {}
          },
          {
            "id": "66a1b2c3d4e5f6a7b8c9d002",
            "type": "multiple_choice",
            "title": "How did you hear about us?",
            "required": true,
            "order": 1,
            "properties": {
              "choices": [
                { "label": "Search engine" },
                { "label": "Social media" },
                { "label": "Friend or colleague" },
                { "label": "Other" }
              ]
            }
          },
          {
            "id": "66a1b2c3d4e5f6a7b8c9d004",
            "type": "yes_no",
            "title": "Would you recommend us to a friend?",
            "required": false,
            "order": 2,
            "properties": {}
          }
        ]
      }
    },
    {
      "id": "66c2d3e4f5a6b7c8d9e0f1a2",
      "form_id": "665a1b2c3d4e5f6a7b8c9d0e",
      "version": 2,
      "published_by": "665a0a1b2c3d4e5f6a7b8c9d",
      "published_by_name": "Alice Johnson",
      "created_at": "2026-02-15T10:30:00.000Z",
      "changelog": [
        {
          "type": "question_added",
          "description": "Added question: \"How did you hear about us?\""
        }
      ],
      "snapshot": { ... }
    },
    {
      "id": "66c1d2e3f4a5b6c7d8e9f0a1",
      "form_id": "665a1b2c3d4e5f6a7b8c9d0e",
      "version": 1,
      "published_by": "665a0a1b2c3d4e5f6a7b8c9d",
      "published_by_name": "Alice Johnson",
      "created_at": "2026-01-15T10:30:00.000Z",
      "changelog": [
        {
          "type": "form_created",
          "description": "Created form"
        }
      ],
      "snapshot": { ... }
    }
  ]
}

Exemplos de Código

bash
curl -X GET "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e/versions" \
  -H "Authorization: Bearer YOUR_API_KEY"

Como Funciona o Versionamento

  1. Editar -- Faça alterações no seu formulário (adicione perguntas, atualize o tema, modifique as configurações). A flag has_unpublished_changes do formulário é definida como true.
  2. Publicar -- Chame POST /api/v1/forms/:id/publish para criar uma nova versão. O NueForm tira um snapshot do estado atual do formulário, grava o registro de alterações e incrementa o número da versão.
  3. Formulário no ar -- Os respondentes sempre veem a versão publicada mais recente. O published_version_id do formulário aponta para a versão ativa.
  4. Despublicar -- Chame DELETE /api/v1/forms/:id/publish para tirar o formulário do ar. O histórico de versões é preservado.

O estado atual do formulário (editável via API de Formulários) pode diferir da versão publicada mais recente se edições tiverem sido feitas desde a última publicação.

Respostas de Erro

Respostas de erro padrão retornadas por este endpoint.

Códigos de Erro

401Unauthorized

Chave de API ausente ou inválida

403Forbidden

Permissões insuficientes para formulários de equipe

404Not Found

Formulário não encontrado

500Server Error

Erro interno do servidor

Exemplo de Erro

json
{
  "error": "Form not found"
}
Última atualização: 20 de julho de 2026