O que são e como configurar os campos personalizados e metadados?

Entidades específicas na plataforma podem receber metadados por meio do parâmetro metadata em sua criação ou atualização através da API.

Metadados são úteis para incluir informações adicionais sobre uma entidade que são específicas para seu negócio.

Você pode, por exemplo, adicionar um metadado categoria em um cliente e usar esse atributo em relatórios, cálculos internos ou aproveitar a informação em outro tipo de integração.

{  "customer": {    "id": 59,    "name": "ABC Sports Ltda.",    "email": "leandro@abc.com",    (...)    "metadata": {      "categoria": "Clientes VIP",      "regime_tributario": "simples"    }  }}

Incluir, atualizar e remover metadados

Ao criar uma nova entidade, informe o parâmetro metadata usando os nomes dos campos personalizados previamente cadastrados no formato "chave": "valor", conforme o exemplo abaixo:

"metadata": {  "codigo_loja": "svx-137",  "contato_financeiro": "João da Silva"}

Para atualizar um metadado, simplesmente atribua um novo valor:

"metadata": {  "codigo_loja": "rxt-891"}

No exemplo acima, o atributo contato_financeiro existente não será alterado. Para atribuir um novo metadado em uma entidade existente, informe apenas o novo atributo na atualização.

Para remover um metadado, atributa explicitamente um valor nulo na atualização:

"metadata": {  "codigo_loja": null}

No exemplo acima, apenas o atributo codigo_loja será removido. O atributo contato_financeiro permanecerá cadastrado, mesmo que não seja informado na atualização.

Para não alterar os metadados durante uma atualização de entidade, simplesmente omita o atributo metadata, use "metadata": null ou "metadata": {}. Qualquer um desses parâmetros será ignorado pela plataforma e não irá remover todos os atributos da entidade.

Campos personalizados

Metadados devem obrigatoriamente pertencer a um campo personalizado (metafield) previamente cadastrado pelo painel de administração em Configurações > Campos personalizados. Os campos personalizados podem ser exibidos nas páginas de pagamento da plataforma.

Atualmente os campos personalizados devem respeitar os seguintes limites:

• Código igual ou inferior a 40 caracteres. Esse é o código que será a referência da API;
• Valor igual ou inferior a 255 caracteres;
• Limite total de 25 campos personalizados por conta na plataforma (considerando todas as entidades).

Note que ao remover um campo personalizado, todos os metadados associados serão removidos de forma permanente.

Notificações

As notificações por e-mail e SMS da plataforma também podem conter metadados. Utilize esta funcionalidade para personalizar ainda mais suas mensagens:

Olá {{customer.first_name}}, Sua compra foi aprovada. Atenciosamente,  {{customer.metadata.nome_gerente_comercial}}

Limitações

Por ora não é possível utilizar os metadados em buscas ou editá-los através do painel (exceto nas entidades cliente e produto, para criação dos demais campos a criação somente é possível via API.). Estamos trabalhando para atender estas necessidades.

Atualmente apenas clientes, planos e produtos suportam metadados. O objetivo é disponibilizar a mesma funcionalidade nas assinaturas e faturas.

Como configurar "Campos Personalizados" na plataforma?

Na plataforma da Vindi é possível criar campos personalizados para cadastro de informações adicionais.

Para configurar campos personalizados, na plataforma no menu principal acesse : 

Configurações > Campos Personalizados:

Após, clique em "Novo campo personalizado":

No campo "Entidade",  a criação de campos diretamente criados na plataforma da Vindi está limitado para  Cliente e Produto, para criação dos demais campos a criação somente é possível via API.

Vale ressaltar que a entidade cliente, os campos personalizados ficam vinculados no cadastro do cliente e a entidade produto é utilizada para configuração em caso de extensão de Notas Fiscais de Serviço ativadas.

Após selecionar a entidade "Cliente" ou "Produto" selecione o tipo.

No campo "Tipo": você pode criar campo de texto livre para preenchimento, ou listas de tags para escolhas definidas.

Para o tipo texto ou lista de tags, o preenchimento será o mesmo, as opções de escolhas da lista é criado por nossa equipe de Suporte, através de uma solicitação no Suporte com as informações que devem constar na lista de escolhas.

Uma dica: o tipo lista de tags é mais utilizado quando o campo personalizado é adicionado nas páginas de pagamento.

Escolha o "Nome, Texto para dica (opcional) e Código externo", caso seja é necessário utilizar espaço entre as palavras no código externo utilize "_".