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 email 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). Estamos trabalhando para atender estas necessidades.
Melhorias
Além dos metadados nos relatórios personalizados, incluiremos também novos tipos de campos personalizados, como listas e caixas de seleção. A edição e inclusão também estará disponível através de formulários no painel de administração.
Atualmente apenas clientes, planos e produtos suportam metadados. O objetivo é disponibilizar a mesma funcionalidade nas assinaturas e faturas.
Comentários
0 comentário
Artigo fechado para comentários.