Assinantes da newsletter
O que é um assinante, o ciclo de situações, os ids e o mapa das quatro operações /subscribers.
Um assinante é um e-mail que pediu para receber a newsletter da loja. A vitrine inscreve pessoas pelo formulário do rodapé e no cadastro de clientes; estas rotas deixam um sistema externo (CRM, ferramenta de e-mail marketing) fazer o mesmo: inscrever, listar, consultar e remover, com o contrato da API 1.0.
Como funciona
Situações do assinante
| Letra | Significado |
|---|---|
P | Pendente. A loja usa confirmação em duas etapas: a pessoa recebeu um e-mail e ainda não confirmou. |
A | Ativo. Recebe a newsletter. É a situação inicial quando a confirmação em duas etapas está desligada. |
U | Cancelou a inscrição (pelo link do e-mail). |
B | Suprimido depois de uma devolução (bounce) definitiva do e-mail. |
Quem cancelou (U) volta a A (ou P) se o mesmo e-mail for inscrito de novo por Inscrever assinante. Respeite o consentimento da pessoa antes de reinscrever.
Fluxo típico
- Inscrever
Inscrever assinante com o e-mail e, se tiver, o nome.
- Conferir
Listar assinantes com
?email=para achar o registro e ver a situação. - Remover
Remover assinante com o UUID, quando a pessoa pedir exclusão dos dados.
Conceitos importantes
Ids
O subscriber_id é um UUID em /api/v1.0/subscribers. Em /api/subscribers ele sai como um número decimal em string (por exemplo "544316720"), mas GET e DELETE em /{id} só aceitam o UUID e respondem 500 para o decimal. Leia o UUID em /api/v1.0/subscribers.
Origem
Todo assinante criado por aqui fica marcado com a origem compat_api no painel, para separar do que veio da vitrine.
Endpoints
| Método | Caminho | Para que serve | Autenticação |
|---|---|---|---|
| GET | /api/v1.0/subscribers | Listar assinantes | Administrador |
| GET | /api/v1.0/subscribers/{id} | Consultar assinante | Administrador |
| POST | /api/v1.0/subscribers | Inscrever assinante | Administrador |
| DELETE | /api/v1.0/subscribers/{id} | Remover assinante | Administrador |
Cada linha vale também sem /v1.0 (/api/subscribers...).
Erros comuns
- Usar o id decimal de
/api/subscribersem/{id}. Dá 500. Use o UUID. - Esperar 404 para um assinante inexistente. A rota responde 500 com a mensagem
subscriber not found. - Esperar validação do e-mail. Nada é validado; lixo entra na lista.
- Mandar
limitouper_page. O nome do parâmetro éitems_per_page. - Pedir mais de 100 por página. Volta com 20 itens.