Newsletter e formulários
Rascunhos de e-mail marketing do seller e formulários de captação de contatos, com a leitura dos contatos recebidos.
Duas ferramentas para falar com quem visita o microsite do seller (lojista): a newsletter, e-mail marketing escrito pelo seller, e os formulários, páginas de captação (Fale conosco, Peça um orçamento) cujas respostas, os leads, chegam ao seller. As rotas ficam em /api/v1/vendor/newsletter e /api/v1/vendor/forms.
Como funciona
Newsletter. O status da campanha é uma letra:
status | Significado | Edita? | Apaga? |
|---|---|---|---|
R | Rascunho (estado inicial) | Sim | Sim |
P | Agendada | Não | Não |
S | Enviando | Não | Não |
A | Enviada | Não | Não |
F | Falhou | Não | Sim |
Formulários. O ciclo é draft (rascunho) > active (publicado, recebe leads) > archived. Os visitantes enviam o formulário pela rota pública da vitrine, POST /api/v1/storefront/forms/{slug}/submit, e cada envio vira um lead com status new, read ou replied.
Conceitos-chave
Dono e privilégios
Tudo é filtrado pelo seller do token. Pedir o id de outro seller responde 404. Os privilégios aceitos são os do grupo de configurações (vendor_settings e afins).
Erros em formulários
Os erros de formulário voltam como códigos em maiúsculas no campo error, às vezes com o campo problemático depois de dois pontos (INVALID_FIELD_TYPE:cor). Veja a lista em cada página.
Endpoints
| Método | Caminho | Para que serve | Autenticação |
|---|---|---|---|
| GET | /api/v1/vendor/newsletter/campaigns | Lista as campanhas. | vendor |
| GET | /api/v1/vendor/newsletter/campaigns/{id} | Devolve uma campanha. | vendor |
| POST | /api/v1/vendor/newsletter/campaigns | Cria um rascunho. | vendor |
| PUT | /api/v1/vendor/newsletter/campaigns/{id} | Altera um rascunho. | vendor |
| DELETE | /api/v1/vendor/newsletter/campaigns/{id} | Apaga um rascunho ou campanha com falha. | vendor |
| GET | /api/v1/vendor/forms | Lista os formulários. | vendor |
| GET | /api/v1/vendor/forms/{id} | Devolve um formulário. | vendor |
| POST | /api/v1/vendor/forms | Cria um formulário. | vendor |
| PUT | /api/v1/vendor/forms/{id} | Altera um formulário. | vendor |
| DELETE | /api/v1/vendor/forms/{id} | Apaga o formulário e os leads. | vendor |
| GET | /api/v1/vendor/forms/{id}/submissions | Lista os leads de um formulário. | vendor |
Erros comuns
- Procurar a rota de envio da newsletter. Ela não existe para o seller; o seller prepara o rascunho.
- Editar uma campanha já enviada.
400 can only edit draft campaigns. - Apagar uma campanha enviada e receber
404. A rota responde "não encontrada" também quando o status não permite apagar. - Slug de formulário repetido. O slug é único na loja toda; outro seller pode já usá-lo (
SLUG_ALREADY_EXISTS). - Slug com maiúsculas, acento ou sublinhado. Só
a-z,0-9e hífen entre blocos. - Esquecer
optionsemselect,radioecheckbox. O campo é recusado (FIELD_OPTIONS_REQUIRED).