Skip to content

add request_changes endpoint#61

Merged
ryanarakawa merged 2 commits intomainfrom
CP-12657-request-changes-endpoint
Mar 11, 2026
Merged

add request_changes endpoint#61
ryanarakawa merged 2 commits intomainfrom
CP-12657-request-changes-endpoint

Conversation

@ryanarakawa
Copy link
Collaborator

Summary

Adds a new API endpoint to programmatically request changes from a submitter after they've completed a form. Foundation for next PR, nothing to demo here.

Changes

  • POST /api/submitters/:slug/request_changes clears completed_at, sets changes_requested_at, allowing the submitter to re-fill the form
  • Auth via API token, verifies the submitter belongs to the token's account
  • No webhook fired — the caller owns the state transition before invoking this endpoint, Docuseal simply receives the update

- submitter is found by slug and authorized
@ryanarakawa ryanarakawa marked this pull request as ready for review March 9, 2026 20:43
Copy link
Collaborator

@bernardodsanderson bernardodsanderson left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM! A few optional comments, nothing major.

)
end

describe 'POST /api/submitters/:slug/request_changes' do
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[optional] We're missing a test case for non-completed submitter?

expect(response).to have_http_status(:ok)
end

it 'is idempotent when changes already requested' do
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

TIL about idempotent 💡

config/routes.rb Outdated
resources :submitter_email_clicks, only: %i[create]
resources :submitter_form_views, only: %i[create]
resources :submitters, only: %i[index show update]
resources :submitters, only: %i[], param: 'slug' do
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[optional] I don't think you need the %i, either way though

Suggested change
resources :submitters, only: %i[], param: 'slug' do
resources :submitters, only: [], param: :slug do

before_action :load_submitter

def request_changes
@submitter.update!(changes_requested_at: Time.current, completed_at: nil) unless @submitter.changes_requested_at?
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[optional] So this endpoint modifies the submitter state without creating a SubmissionEvent. Not sure if that's something we want or not, but in other state transitions we seem to be doing that.

- Return 422 if submitter has not yet completed the form
- Wrap state update in a transaction and create a SubmissionEvent (with optional reason and requested_by) to match web controller behavior
- Add tests for: SubmissionEvent creation, reason param, non-completed submitter guard, and idempotent protection (duplicate creation on multiple calls)
- Clean up routes: replace %i[] with [] and 'slug' string with :slug symbol
@bernardodsanderson bernardodsanderson self-requested a review March 10, 2026 21:31
@ryanarakawa ryanarakawa merged commit 331ff92 into main Mar 11, 2026
5 checks passed
@ryanarakawa ryanarakawa deleted the CP-12657-request-changes-endpoint branch March 11, 2026 14:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants