API atual/Referência completa/Engajamento: extras

Respostas de formulário

Lê, muda o status e apaga uma resposta enviada por um visitante a um formulário personalizado da loja.

A loja pode publicar formulários personalizados (contato, orçamento, cadastro de parceiro). Cada vez que um visitante envia um, a plataforma grava uma resposta (submission) com o conteúdo preenchido, o IP e o navegador, e avisa a equipe por e-mail. As três rotas desta página tratam uma resposta individual: abrir, marcar como lida ou respondida e apagar.

Para chegar ao id de uma resposta, use a lista de respostas do formulário (GET /api/v1/admin/forms/{id}/submissions, documentada na seção de formulários) ou o e-mail de aviso.

Ler uma resposta

GET/api/v1/admin/form-submissions/{id}Admin

Ler uma resposta de formulário

Devolve a resposta completa, incluindo os campos preenchidos em data e o nome do formulário de origem.

Parâmetros de caminho

iduuidobrigatório

Id da resposta.

bash

curl "$BASE_URL/api/v1/admin/form-submissions/7c9e1a44-5b0d-4e3a-9d1f-2b8a6c3e0f55" \
  -H "Authorization: Bearer $TOKEN"

200Resposta encontrada

json

{
  "id": "7c9e1a44-5b0d-4e3a-9d1f-2b8a6c3e0f55",
  "form_id": "e1a7f3b2-0c64-4d8e-b5a1-93f2d6c8a470",
  "form_name": "Fale com a gente",
  "data": { "nome": "Maria Souza", "email": "maria.souza@example.com", "mensagem": "Quero um orçamento." },
  "ip_address": "203.0.113.10",
  "user_agent": "Mozilla/5.0 (Linux; Android 14)",
  "status": "new",
  "created_at": "2026-10-11T14:22:05.123456Z"
}

Campos da resposta

iduuid

Id da resposta.

form_iduuid

Formulário de origem.

form_namestring

Nome do formulário. Ausente se o formulário foi apagado.

dataobject

Campos preenchidos pelo visitante. As chaves são as definidas no formulário.

ip_addressstring

IP de quem enviou. Ausente quando não foi registrado.

user_agentstring

Navegador de quem enviou. Ausente quando não foi registrado.

statusstring

newreadreplied

Situação do atendimento.

created_atstring

Quando foi enviada, RFC 3339, UTC.

Mudar o status

PATCH/api/v1/admin/form-submissions/{id}/statusAdmin

Marcar a resposta como nova, lida ou respondida

Atualiza só o status da resposta. Serve para a equipe organizar a fila de atendimento. Exige manage_content. Não envia nenhum e-mail ao visitante: replied é só uma marca.

Parâmetros de caminho

iduuidobrigatório

Id da resposta.

Corpo da requisição

statusstringobrigatório

newreadreplied

Novo status, em palavra. Letras (P, A, C) e qualquer outro valor são recusados.

bash

curl -X PATCH "$BASE_URL/api/v1/admin/form-submissions/7c9e1a44-5b0d-4e3a-9d1f-2b8a6c3e0f55/status" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status":"read"}'

200Status atualizado

json

{ "status": "ok" }

Apagar uma resposta

DELETE/api/v1/admin/form-submissions/{id}Admin

Apagar uma resposta de formulário

Remove a resposta de forma definitiva, sem lixeira. Exige manage_content.

Parâmetros de caminho

iduuidobrigatório

Id da resposta.

bash

curl -X DELETE "$BASE_URL/api/v1/admin/form-submissions/7c9e1a44-5b0d-4e3a-9d1f-2b8a6c3e0f55" \
  -H "Authorization: Bearer $TOKEN"

204Apagada

Sem corpo.

Erros

Status	Quando	Corpo de exemplo
400	Corpo do `PATCH` não é JSON.	`{"error":"INVALID_JSON","detail":"..."}`
400	`status` fora de `new`, `read`, `replied`.	`{"error":"INVALID_STATUS"}`
401	Sem token ou token expirado.	`{"error":"invalid or expired token"}`
403	Sem privilégio de conteúdo.	`{"error":"insufficient privileges","required":"manage_content"}`
404	A resposta não existe.	`{"error":"SUBMISSION_NOT_FOUND"}`
500	Id que não é UUID, ou falha ao gravar.	`{"error":"SUBMISSION_GET_FAILED","detail":"..."}`

Os códigos de erro desta área são palavras em maiúsculas, não frases.

Veja também

API atual/Referência completa/Engajamento: extras

Respostas de formulário

Lê, muda o status e apaga uma resposta enviada por um visitante a um formulário personalizado da loja.

Para chegar ao id de uma resposta, use a lista de respostas do formulário (GET /api/v1/admin/forms/{id}/submissions, documentada na seção de formulários) ou o e-mail de aviso.

Ler uma resposta

GET/api/v1/admin/form-submissions/{id}Admin

Ler uma resposta de formulário

Devolve a resposta completa, incluindo os campos preenchidos em data e o nome do formulário de origem.

Parâmetros de caminho

iduuidobrigatório

Id da resposta.

bash

curl "$BASE_URL/api/v1/admin/form-submissions/7c9e1a44-5b0d-4e3a-9d1f-2b8a6c3e0f55" \
  -H "Authorization: Bearer $TOKEN"

200Resposta encontrada

json

{
  "id": "7c9e1a44-5b0d-4e3a-9d1f-2b8a6c3e0f55",
  "form_id": "e1a7f3b2-0c64-4d8e-b5a1-93f2d6c8a470",
  "form_name": "Fale com a gente",
  "data": { "nome": "Maria Souza", "email": "maria.souza@example.com", "mensagem": "Quero um orçamento." },
  "ip_address": "203.0.113.10",
  "user_agent": "Mozilla/5.0 (Linux; Android 14)",
  "status": "new",
  "created_at": "2026-10-11T14:22:05.123456Z"
}

Campos da resposta

iduuid

Id da resposta.

form_iduuid

Formulário de origem.

form_namestring

Nome do formulário. Ausente se o formulário foi apagado.

dataobject

Campos preenchidos pelo visitante. As chaves são as definidas no formulário.

ip_addressstring

IP de quem enviou. Ausente quando não foi registrado.

user_agentstring

Navegador de quem enviou. Ausente quando não foi registrado.

statusstring

newreadreplied

Situação do atendimento.

created_atstring

Quando foi enviada, RFC 3339, UTC.

Mudar o status

PATCH/api/v1/admin/form-submissions/{id}/statusAdmin

Marcar a resposta como nova, lida ou respondida

Atualiza só o status da resposta. Serve para a equipe organizar a fila de atendimento. Exige manage_content. Não envia nenhum e-mail ao visitante: replied é só uma marca.

Parâmetros de caminho

iduuidobrigatório

Id da resposta.

Corpo da requisição

statusstringobrigatório

newreadreplied

Novo status, em palavra. Letras (P, A, C) e qualquer outro valor são recusados.

bash

curl -X PATCH "$BASE_URL/api/v1/admin/form-submissions/7c9e1a44-5b0d-4e3a-9d1f-2b8a6c3e0f55/status" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status":"read"}'

200Status atualizado

json

{ "status": "ok" }

Apagar uma resposta

DELETE/api/v1/admin/form-submissions/{id}Admin

Apagar uma resposta de formulário

Remove a resposta de forma definitiva, sem lixeira. Exige manage_content.

Parâmetros de caminho

iduuidobrigatório

Id da resposta.

bash

curl -X DELETE "$BASE_URL/api/v1/admin/form-submissions/7c9e1a44-5b0d-4e3a-9d1f-2b8a6c3e0f55" \
  -H "Authorization: Bearer $TOKEN"

204Apagada

Sem corpo.

Erros

Status	Quando	Corpo de exemplo
400	Corpo do `PATCH` não é JSON.	`{"error":"INVALID_JSON","detail":"..."}`
400	`status` fora de `new`, `read`, `replied`.	`{"error":"INVALID_STATUS"}`
401	Sem token ou token expirado.	`{"error":"invalid or expired token"}`
403	Sem privilégio de conteúdo.	`{"error":"insufficient privileges","required":"manage_content"}`
404	A resposta não existe.	`{"error":"SUBMISSION_NOT_FOUND"}`
500	Id que não é UUID, ou falha ao gravar.	`{"error":"SUBMISSION_GET_FAILED","detail":"..."}`

Os códigos de erro desta área são palavras em maiúsculas, não frases.