Como criar Campos Personalizados através da API da MailerWeb
Você poderá criar variáveis de forma programática utilizando a nossa API de gestão de Campos Customizados, utilize os métodos abaixo para começar a criar conteúdo em nossa plataforma de envio de SMS marketing,
Para se integrar à API é necessário que você esteja autenticado e para isso é importante que você tenha acesso ao artigo "Como se integrar a API da MailerWeb?".
Passo 1 - Criando uma Campo Personalizado
Com esse método você poderá armazenar informações em seus contatos de forma personalizada e criar segmentações em seus envios. Caso você queira saber mais como funciona os Campos Personalizados, clique aqui
Para interagir com os campos personalizados, vamos criar o objeto com os seguintes parâmetros e com o seguinte endpoint /metadata/customfield/:
- Campo "data_type" é o tipo de dado que você vai armazenar na sua base de contatos. Os valores possíveis seguem abaixo:
DATA_TYPE_CHOICES = ( ('varchar', _(u'Caracter (linha simples)')), ('text', _(u'Texto (múltiplas linhas)')), ('integer', _(u'Inteiro')), ('decimal', _(u'Decimal')), ('list', _(u'Lista Seleção Única')), ('multiplelist', _(u'Lista com Multipla Seleção')), ('boolean', _(u'Booleano (checkbox Sim/Não)')), ('date', _(u'Data')), ('time', _(u'Hora')), ('datetime', _(u'Data e Hora')), ('email', _(u'E-mail')), ('url', _(u'URL')), ('ipaddress', _(u'Endereço IP')), ('slug', _(u'Slug')), ) - Campo "decimal_places", do tipo Inteiro, é utilizado apenas se você definir que se "data_type" for do tipo decimal.
- Campo "empty_selection_list", do tipo Booleando (true/false) é utilizado apenas quanto o "data_type" for do tipo "list", designa que o campo terá um menu de seleção, mas o primeiro valor será "Selecione um Item da Lista".
- Campo "list_values", do tipo Caracter, é utilizado para armezenar os valores das listas, quando definido que o tipo data_type é list ou multiplelist. Obrigatório nesses casos
- Campo "help_text", do tipo Caracter, é utilizado para escrever um texto de ajuda quando exibir o campo em um formulário, é opcional.
- Campo "label", do tipo Caracter, é utilizado para definir o texto que irá apresentar o campo, por exemplo Nome do Contato, é obrigatório,
- Campo "max_length", do tipo inteiro, é utilizado para definir o tamanho máximo em caracter do campo. Somente pode armazenar até 1000 caracteres, é obrigatório.
- Campo "name", do tipo Caracter, é o nome do campo que será armazenado no contato, uma vez criado, não poderá ser mais alterado. Se colocado em branco, o campo "label" será convertido em slug e seu valor será colocado nesse campo.
- Campo "ordering" do tipo Inteiro, é a ordem que o campo irá aparecer no formulário de contatos, se não souber a ordem, informe 0. Campo obrigatório.
- Campo "required", do tipo Booleano (true/false), é utilizado para definir se o preenchimento desse campo deverá ser obrigatório.
- Campo "searchable", do tipo Booleano (true/false), é utilizado para definir se o campo poderá ser utilizado no processo de busca de contatos.
- Campo "staff_only, do tipo Booleano (true/false), é utilizado para definir se os dados armazenados nesse campo, somente podem ser visiveis ao usuário que o criou.
- Campo "threat_as_list, do tipo Booleano (true/false), é utilizado para definir se os dados armazenados nesse campo, deverão ser tratados como uma lista e não como um caracter do tipo único.
POST: /api/v1/metadata/customfield/
data = {
"data_type": "varchar",
"help_text": "",
"label": "CPF",
"max_length": 50,
"name": "cpf",
"ordering": 1,
"required": false,
"searchable": true,
"staff_only": false
}
curl --dump-header - -H "Content-Type: application/json" \ -H "Authorization: ApiKey username:API_KEY"\ -X POST --data data https://painel.mailerweb.com.br/api/v1/metadata/custom_field/
O resultado esperado será semelhante ao JSON abaixo:
{
"data_type": "varchar",
"date_created": "2021-05-26",
"decimal_places": null,
"empty_selection_list": false,
"help_text": "",
"id": 6028,
"label": "CPF",
"last_updated": "2021-05-26",
"list_values": "",
"max_length": 50,
"name": "cpf",
"ordering": 1,
"required": false,
"resource_uri": "/api/v1/metadata/customfield/id-do-campo-customizado/",
"searchable": true,
"staff_only": false,
"threat_as_list": false
}
Repare que o ID do novo Campo Personalizado está no atributo ID e no atributo resource_url, onde você poderá acessar os detalhes desse campo a partir do endpoint entregue por esse parâmetro. A partir de agora, grave esse ID, para fazer o acesso à essas informações.
Agora que você está de posse do ID do Campo Personalizado , vamos ao Passo 2:
Passo 2 - Listando os Campos Personalizados existentes
Para visualizar todos campos Personalizados
GET: /api/v1/metadata/customfield/
curl --dump-header - -H "Content-Type: application/json" \ -H "Authorization: ApiKey username:API_KEY"\ -X GET https://painel.mailerweb.com.br//api/v1/metadata/customfield/
O resultado será semelhante a esse
{
"meta": {
"limit": 50,
"next": null,
"offset": 0,
"previous": null,
"total_count": 1
},
"objects": [
{
"data_type": "varchar",
"date_created": "2021-05-26",
"decimal_places": null,
"empty_selection_list": false,
"help_text": "",
"id": 6028,
"label": "CPF",
"last_updated": "2021-05-26",
"list_values": "",
"max_length": 50,
"name": "cpf",
"ordering": 1,
"required": false,
"resource_uri": "/api/v1/metadata/customfield/id-do-campo-customizado/",
"searchable": true,
"staff_only": false,
"threat_as_list": false
}
]
}
Importante notar que será exibido um objeto no formato JSON, onde virão 2 dicionários: meta e objects, a saber:
- Em "meta" você terá uma visão geral de quantos objetos você possui e ainda o link da próxima página do objeto, isso estará no atributo "next" do dicionário;
- Em objects, você terá um detalhe completo do objeto carregado no campo resource_uri, terá o link para chamar para a atualização desse objeto.
Você também poderá consultar objetos de acordo com os atributos existentes nesse formulário, por exemplo:
Listando por ID da Campo Personalizado:
GET: /api/v1/metadata/customfield/?id=xxx
curl --dump-header - -H "Content-Type: application/json" \ -H "Authorization: ApiKey username:API_KEY"\ -X GET https://painel.mailerweb.com.br/api/v1/metadata/customfield/?id=xxx
Listando por nome:
GET: /api/v1/metadata/customfield/?name=teste
curl --dump-header - -H "Content-Type: application/json" \ -H "Authorization: ApiKey username:API_KEY"\ -X GET https://painel.mailerweb.com.br/api/v1/metadata/customfield/?name=teste
Listando pela Label:
GET: /api/v1/metadata/customfield/?label=Teste
curl --dump-header - -H "Content-Type: application/json" \ -H "Authorization: ApiKey username:API_KEY"\ -X GET https://painel.mailerweb.com.br/api/v1/metadata/customfield/?label=Teste
Passo 3 - Atualizando um Campo Personalizado
Você pode necessitar alterar um Campo Personalizado como por exemplo o Label, nesse caso você utilizar o método PATCH com os parâmetros abaixo:
PATCH: /api/v1/customfield/metadata/XXX58/
data = {
"label": "CPF2",
"searchable": false,
"staff_only": true,
"threat_as_list": true
}
curl --dump-header - -H "Content-Type: application/json" \ -H "Authorization: ApiKey username:API_KEY"\ -X PATCH --data data https://painel.mailerweb.com.br/api/v1/customfield/metadata/XXX58/
IMPORTANTE: O Campo "name" não poderá ser atualizado, somente o label, que será alterado e mantido a criação original para não perder o relacionamento com a base de contatos.
Passo 4 - Excluindo um Campo Personalizado
Você pode excluir um Campo Personalizado, nesse caso você utilizar o método DELETE com os parâmetros abaixo:
DELETE: /api/v1/customfield/metadata/XXX58/
curl --dump-header - -H "Content-Type: application/json" \ -H "Authorization: ApiKey username:API_KEY"\ -X DELETE https://painel.mailerweb.com.br/api/v1/customfield/metadata/XXX58/
IMPORTANTE: O Campo "name" não poderá ser atualizado, somente o label, que será alterado e mantido a criação original para não perder o relacionamento com a base de contatos.
Agora você poderá criar campos customizados de forma rápida para atender a sua aplicação.