Campos personalizados e metadados

Entidades específicas na plataforma podem receber metadados através 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 metadada 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 à um campo personalizado (metafield) previamente cadastrado através do 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 20 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 no cliente). 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.

Tem mais dúvidas? Envie uma solicitação

Comentários

Powered by Zendesk