,
message: String(result.error.message),
values,
},
{ status: response.status },
);
}
export default function Report({ actionData }: Route.ComponentProps) {
const sending = useNavigation().state === "submitting";
if (actionData?.sent) return Thanks. We'll look at that page today.
;
const fields = actionData?.fields ?? {};
const values = actionData?.values;
return (
);
}
```
**SvelteKit**
A form action padrão devolve `fail()` com o status e os erros de campo do Ikiform. Sem JavaScript a página é renderizada de novo com eles; com `use:enhance` ela se atualiza no lugar. Declare `IKIFORM_SECRET_KEY` em `src/env.ts` com `defineEnvVars` para que `$app/env/private` consiga lê-la.
`src/routes/report/+page.server.ts`:
```ts
import { fail } from "@sveltejs/kit";
import { IKIFORM_SECRET_KEY } from "$app/env/private";
import type { Actions } from "./$types";
export const actions = {
default: async ({ request, fetch, url }) => {
const form = await request.formData();
const values = {
email: String(form.get("email") ?? "").trim(),
page: String(form.get("page") ?? "").trim(),
severity: String(form.get("severity") ?? ""),
details: String(form.get("details") ?? "").trim(),
};
const response = await fetch("https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx", {
method: "POST",
headers: {
Accept: "application/json",
"Content-Type": "application/json",
Authorization: `Bearer ${IKIFORM_SECRET_KEY}`,
Origin: request.headers.get("origin") ?? url.origin,
},
body: JSON.stringify({ ...values, _gotcha: String(form.get("_gotcha") ?? "") }),
});
const result = await response.json();
if (!result.ok) {
return fail(response.status, { values, fields: (result.error.fields ?? {}) as Record });
}
return { sent: true };
},
} satisfies Actions;
```
`src/routes/report/+page.svelte`:
```svelte
{#if form?.sent}
Thanks. We'll look at that page today.
{:else}
{/if}
```
**Nuxt**
Uma server route encaminha o relato com `runtimeConfig.ikiformSecretKey`, definido a partir de `NUXT_IKIFORM_SECRET_KEY`. Ela lança `createError` com os erros de campo em `data`, que o `$fetch` devolve no cliente.
`server/api/report.post.ts`:
```ts
export default defineEventHandler(async (event) => {
const body = await readBody>(event);
const { ikiformSecretKey } = useRuntimeConfig(event);
const origin = getRequestHeader(event, "origin");
const response = await fetch("https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx", {
method: "POST",
headers: {
Accept: "application/json",
"Content-Type": "application/json",
Authorization: `Bearer ${ikiformSecretKey}`,
...(origin ? { Origin: origin } : {}),
},
body: JSON.stringify({
email: body.email ?? "",
page: body.page ?? "",
severity: body.severity ?? "",
details: body.details ?? "",
_gotcha: body._gotcha ?? "",
}),
});
const result = await response.json();
if (!result.ok) {
throw createError({
status: response.status,
message: String(result.error.message),
data: { fields: result.error.fields ?? {} },
});
}
return { sent: true };
});
```
`app/components/ReportForm.vue`:
```vue
Thanks. We'll look at that page today.
```
**React**
Uma single-page app envia a partir do navegador, então não há chave secreta aqui; quem protege o formulário é **Allowed domains**. `Accept: application/json` recebe uma resposta JSON em vez de um redirecionamento.
`src/ReportForm.tsx`:
```tsx
import { type FormEvent, useState } from "react";
const ENDPOINT = "https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx";
const SEVERITIES = [
["cosmetic", "Looks wrong"],
["broken", "Something doesn't work"],
["blocking", "I can't continue"],
];
export function ReportForm() {
const [sent, setSent] = useState(false);
const [sending, setSending] = useState(false);
const [fields, setFields] = useState>({});
const [problem, setProblem] = useState("");
async function onSubmit(event: FormEvent) {
event.preventDefault();
setSending(true);
setFields({});
setProblem("");
try {
const response = await fetch(ENDPOINT, {
method: "POST",
headers: { Accept: "application/json" },
body: new FormData(event.currentTarget),
});
const result = await response.json();
if (result.ok) setSent(true);
else if (result.error.fields) setFields(result.error.fields);
else setProblem(result.error.message);
} catch {
setProblem("Couldn't reach the server. Check your connection and try again.");
} finally {
setSending(false);
}
}
if (sent) return Thanks. We'll look at that page today.
;
return (
);
}
```
**Vue**
O mesmo envio pelo navegador num componente Vue. O formulário mantém um `action` e um `method` reais, então ainda envia do jeito tradicional se o script não carregar.
`src/components/ReportForm.vue`:
```vue
Thanks. We'll look at that page today.
```
> As versões no servidor enviam com uma chave secreta, então o Ikiform pula **Allowed domains** e a verificação humana. Todo envio passa a vir do IP do seu servidor, e o limite Standard de 5 por minuto por visitante conta todos os seus visitantes juntos. Escolha o [limite de taxa](https://ikiform.com/pt-br/docs/rate-limits.md) Relaxed ou Custom para um formulário que você envia por um servidor, e mantenha `IKIFORM_SECRET_KEY` em variáveis de ambiente só do servidor.
Cada versão de servidor encaminha o header `Origin` do navegador quando existe, porque um `fetch` no servidor não manda nenhum e o Ikiform o usa para reconhecer testes gratuitos de `localhost` num workspace sem plano.
- Toda versão mantém um `method` real e, onde envia direto ao Ikiform, um `action` real. Com scripts desligados o formulário ainda envia e recebe o `303`.
- O `name` de cada input é o `id` do campo na definição. Uma divergência, como `url` em vez de `page`, recebe `422` com `Unknown field "url"`.
- O input oculto `_gotcha` é o honeypot. Bots que o preenchem são armazenados como spam, sem alarde.
- As versões em JavaScript mostram `error.fields` embaixo de cada input, usando a primeira mensagem de cada campo. A versão em HTML puro deixa isso para a página de erro do Ikiform.
A documentação vai mais fundo por framework: [Next.js](https://ikiform.com/pt-br/docs/guides/nextjs.md), [Astro](https://ikiform.com/pt-br/docs/guides/astro.md), [SvelteKit](https://ikiform.com/pt-br/docs/guides/sveltekit.md), [Nuxt](https://ikiform.com/pt-br/docs/guides/nuxt.md), [React](https://ikiform.com/pt-br/docs/guides/react.md), [Vue](https://ikiform.com/pt-br/docs/guides/vue.md) e [a partir de um servidor](https://ikiform.com/pt-br/docs/guides/server.md).
## Duas camadas de validação
A validação no navegador e a validação no servidor fazem trabalhos diferentes. A checagem de restrições do navegador (`required`, `type="email"`, `minlength`, `pattern`) dá feedback instantâneo, mas qualquer um pode pulá-la: um bot envia direto, e um script pode chamar `form.submit()`, que nunca roda a checagem. O servidor é o único lugar onde uma regra realmente vale.
| Regra | No navegador | Na definição de campos do Ikiform |
| --- | --- | --- |
| Obrigatório | `required` | `"required": true` |
| E-mail | `type="email"` | `"type": "email"`, com `allowed_domains` opcional |
| URL | `type="url"` | `"type": "url"`, com `https_only` opcional |
| Tamanho | `minlength`, `maxlength` | `validation.min_length`, `max_length` |
| Só as opções listadas | Um ``, que um bot ignora | `options`; qualquer outra coisa é recusada |
| Sem campos extras | Não é possível | Qualquer campo fora da definição é recusado |
Sem definição, o Ikiform aceita quaisquer campos e os armazena como chegam. Publique uma e ele valida, armazena números e checkboxes como números e booleanos de verdade, e recusa o envio com `422 validation_failed` antes de armazenar qualquer coisa. [Validação](https://ikiform.com/pt-br/guides/html-form-submission/validation.md) mostra como manter as duas camadas dizendo a mesma coisa.
## Enviando com JavaScript
Para manter o visitante na página, escute o `submit`, chame `preventDefault()` e envie `new FormData(form)` com `fetch`. Alguns detalhes decidem se isso funciona de primeira:
- Não defina o `Content-Type` você mesmo quando o corpo é `FormData`. O navegador define `multipart/form-data` com o boundary; um header escrito à mão não tem boundary e o corpo não pode ser interpretado.
- Envie `Accept: application/json`. O Ikiform escolheria JSON pelo `Sec-Fetch-Mode` de qualquer forma, mas o header deixa isso explícito, e é um dos headers de requisição que os navegadores podem mandar cross-site sem preflight.
- Um corpo `FormData` ou `URLSearchParams` é uma requisição cross-site simples, então não há preflight. Um corpo JSON com `Content-Type: application/json` dispara um preflight antes; o Ikiform responde, mas custa uma ida e volta.
- `form.submit()` pula a validação e o evento `submit`. `form.requestSubmit()` roda os dois, como um clique faria.
- Passe o botão clicado como segundo argumento, `new FormData(form, event.submitter)`, se o `name` e o `value` dele importam.
O padrão completo, com estado de carregamento, foco e erros de rede, está em [sem recarregar a página](https://ikiform.com/pt-br/guides/html-form-submission/without-page-reload.md). A documentação de [JavaScript e fetch](https://ikiform.com/pt-br/docs/frameworks.md) lista todos os headers e formatos de corpo que o endpoint aceita.
## Escolha o seu caso
Cada uma destas páginas pega uma parte do envio e vai além da visão geral acima, com código para aquele caso.
- [Sem recarregar a página](https://ikiform.com/pt-br/guides/html-form-submission/without-page-reload.md): Envie um formulário com fetch e FormData para o visitante continuar na página, com erros de campo, estado de carregamento, novas tentativas e um plano B quando scripts falham.
- [Redirecionar após o envio](https://ikiform.com/pt-br/guides/html-form-submission/redirect-after-submit.md): Mande visitantes para sua própria página de agradecimento depois do envio: o redirecionamento 303, o campo _redirect, quais domínios são permitidos e o que o refresh faz.
- [O atributo action](https://ikiform.com/pt-br/guides/html-form-submission/action-attribute.md): O que o atributo action de um formulário faz, como valores relativos e vazios são resolvidos, como formaction manda um formulário a dois lugares e por que hosts estáticos respondem 405.
- [Validação de formulários](https://ikiform.com/pt-br/guides/html-form-submission/validation.md): Valide um formulário com required, type, pattern e min, estilize erros com :user-invalid e aplique as mesmas regras no servidor com definições de campos.
## Confira se funciona
Faça isto uma vez por formulário, numa janela anônima. O Ikiform não tem plano gratuito. Testar é grátis: um workspace sem plano aceita 50 envios de teste por mês a partir de `localhost`. Para entrar no ar, escolha o Pro a partir de US$ 6/mês para 500 envios, ou pague uma vez: 10.000 envios por US$ 49 ou 50.000 envios por US$ 149, com créditos que nunca expiram. Veja os [preços](https://ikiform.com/pt-br/pricing).
1. Em **Allowed domains** do formulário, adicione o domínio do seu site, mais `localhost` enquanto desenvolve. Deixe vazio para aceitar envios de qualquer lugar.
2. Desligue o JavaScript nas ferramentas de desenvolvedor do navegador e envie o formulário. Ele ainda deve chegar à sua página de agradecimento com um `303`.
3. Com o JavaScript ligado, abra o painel Network e envie de novo. A requisição para `/f/` deve responder `201` com JSON, e a página não deve recarregar.
4. Envie com uma mensagem curta demais. O envio simples mostra a página de erro do Ikiform com o rótulo do seu campo; o envio por script mostra a mensagem embaixo do campo.
5. Na página de agradecimento, aperte refresh. Nada deve ser reenviado, e nenhum segundo envio deve aparecer.
6. Abra **Submissions** no painel. O novo envio está lá com todos os campos que você enviou.
7. Envie com o honeypot preenchido, `_gotcha=bot`. Ele ainda recebe uma resposta de sucesso, mas o envio é armazenado como spam e não dispara e-mail nem webhook.
## Solução de problemas
| Problema | O que fazer |
| --- | --- |
| `405 Method Not Allowed` depois de enviar | O formulário enviou para o seu próprio host estático, que não aceita POST. Confira o `action`: ele precisa ser a URL completa `https://ikiform.com/f/`, não um caminho relativo nem vazio. |
| Abrir o endpoint numa aba mostra `404 not_found` | É o esperado. Uma aba manda GET, e o endpoint só aceita POST. Confira se o `method` do formulário é `post`; um formulário sem method manda GET com os campos na URL. |
| `415 unsupported_media_type` | O formulário tem `enctype="text/plain"`, ou um script enviou um tipo que o Ikiform não lê. Remova o `enctype`, ou use `multipart/form-data`. |
| `422 validation_failed` | O envio não corresponde à definição de campos do formulário. `error.fields` aponta cada campo e o motivo. Faça o `name` do input bater com o id do campo. |
| O navegador cai na página de agradecimento do Ikiform em vez da sua | O `_redirect` é ignorado, a menos que o domínio dele esteja em **Allowed domains** e ele seja uma URL `https:`. Adicione o domínio, ou defina **Redirect after submit** nas configurações do formulário. |
| Um campo está faltando no envio | Ele não tem `name`, está `disabled` ou é um checkbox desmarcado. Dê um `name` a ele, use `readonly` em vez de `disabled`, ou defina um campo `checkbox` para que uma caixa desmarcada seja armazenada como `false`. |
| O refresh pede para reenviar o formulário | A página respondeu ao POST com `200`. Envios direto ao Ikiform sempre recebem um `303`; se o seu próprio servidor fica no meio, redirecione depois de tratar o envio. |
| `403 origin_not_allowed`, ou todo envio cai no spam | O domínio da página não está em **Allowed domains** do formulário. Adicione-o, mais `localhost` para testes locais. Subdomínios de um domínio listado são permitidos. |
## Perguntas
### O que o atributo action faz num formulário HTML?
É a URL que recebe os dados do formulário. Um valor relativo é resolvido a partir do endereço da página, e um formulário sem action envia para a própria página. Um botão de envio pode sobrescrevê-lo com formaction.
### Um formulário deve usar GET ou POST?
POST para qualquer coisa que envie dados pessoais ou mude estado, como formulários de contato, inscrição ou pedido. GET é para formulários de busca e filtro, em que os campos fazem parte de uma URL que as pessoas podem compartilhar.
### Por que recarregar a página envia meu formulário de novo?
A página que você vê é a resposta direta a um POST, então o navegador se oferece para repeti-lo. Em vez disso, responda a um POST bem-sucedido com um redirecionamento 303 para uma página de agradecimento. O Ikiform faz isso em todo envio do navegador.
### Um formulário HTML pode enviar JSON?
Não sozinho. Um formulário envia dados urlencoded ou multipart. Para enviar JSON, leia o formulário com FormData num handler de submit e envie JSON.stringify(Object.fromEntries(data)) com fetch. O Ikiform aceita os três.
### O atributo required basta para validar um formulário?
Não. Ele ajuda as pessoas, mas bots enviam direto e o pulam. Valide no servidor também. Com o Ikiform, defina os campos e cada envio é conferido com base neles antes de ser armazenado.
### Dá para enviar um formulário sem backend?
Você precisa de algo que receba o POST, mas não precisa ser o seu servidor. Aponte o action do formulário para um backend de formulários como o Ikiform, e a página pode continuar totalmente estática.
### O formulário aceita upload de arquivos?
Ainda não. Um envio que contém um arquivo é recusado com 422 files_not_supported. Peça um link para o arquivo, como a URL de um drive compartilhado.
## Mais guias
- [Sem recarregar a página](https://ikiform.com/pt-br/guides/html-form-submission/without-page-reload.md): Envie um formulário com fetch e FormData para o visitante continuar na página, com erros de campo, estado de carregamento, novas tentativas e um plano B quando scripts falham.
- [Redirecionar após o envio](https://ikiform.com/pt-br/guides/html-form-submission/redirect-after-submit.md): Mande visitantes para sua própria página de agradecimento depois do envio: o redirecionamento 303, o campo _redirect, quais domínios são permitidos e o que o refresh faz.
- [O atributo action](https://ikiform.com/pt-br/guides/html-form-submission/action-attribute.md): O que o atributo action de um formulário faz, como valores relativos e vazios são resolvidos, como formaction manda um formulário a dois lugares e por que hosts estáticos respondem 405.
- [Validação de formulários](https://ikiform.com/pt-br/guides/html-form-submission/validation.md): Valide um formulário com required, type, pattern e min, estilize erros com :user-invalid e aplique as mesmas regras no servidor com definições de campos.
- [Inscrição em eventos](https://ikiform.com/pt-br/guides/event-registration.md): Receba confirmações de presença na página do seu evento: formulário, limite de convidados, contagem honesta, encerramento ao lotar e lista de check-in, sem app de ingressos.
- [Verificar assinaturas de webhook](https://ikiform.com/pt-br/guides/webhook-signature-verification.md): Confira se um webhook de formulário veio mesmo do Ikiform: o esquema HMAC-SHA256 do Standard Webhooks, um vetor de teste, corpos brutos, timestamps e rotação de segredo.
- [Lista de espera para um novo SaaS](https://ikiform.com/pt-br/guides/waitlist.md): Monte uma lista de espera pré-lançamento na sua própria landing page: o formulário, proteção contra spam, duplicados, e-mails de confirmação e uma exportação limpa no dia do lançamento.