A maioria dos aplicativos precisam utilizar campos da aplicação, isso pode acontecer de duas formas diferentes:

• Utilizar um campo já existente, seja fixo ou campo extra
• Criar um campo novo

Campo já existente

Caso seja um campo existente fixo o aplicativo deverá usar o nome do campo nas chamadas de API; este é o caso mais simples.

Para campos extras já existentes deve ser utilizada a sua identificação e não o nome do campo extra. Isso deve ser feito porque os campos extras podem ter nomes diferentes para diferentes instâncias a identificação, porém, é mantida a mesma. Por exemplo, suponha que é necessário recuperar o status de uma venda e temos duas instâncias (A e B); uma vez que a relação da venda com o status é feito através de um campo extra cada instância pode ter um nome diferente:

• Instância A - Nome: order_status_5_11 - Identificação: order-status
• Instância B - Nome: status_order_7_9 - Identificação: order-status

Perceba que apesar dos nomes serem diferentes a identificação é a mesma. Isso acontece pois esse campo é criado no genesis da aplicação então a identificação não pode ser alterada, porém o usuário pode mudar o nome da maneira que desejar.

Para ter acesso ao mapeamento basta verificar a structure da entidade, mais específicamente no dado mapping. Se fizermos uma requisição contra a URL api/orders/structure?data=mapping teremos algo assim:

{
    "data": {
        "mapping": {
            "extra_field": {
                "order-status": "order_status_5_11"
            }
        }
    }
}

 Assim utilizando o mapping da structure é possível descobrir que, para essa instância, o campo extra com a informação de status da venda é o order_status_5_11. A identificação order-status-status foi utilizada como exemplo.

Identificações

Alguns campos extras da venda existem na maioria dos casos, são eles:

• Status de venda: order-status
• Código de rastreio: order-tracking-code
• Horário da emissão de etiqueta de entrega: order-label-issued-datetime

Atenção: lembre-se que se trata de um campo extra, apesar de padrão, ele ainda pode ser excluído. É recomendado incluir uma verificação se o campo extra existe no mapeamento.

Campo novo

O aplicativo pode precisar de algum campo que não tenha atualmente no cadastro da entidade ou não seja obrigatório. Nesse caso o aplicativo deve criar um campo extra e associá-lo ao field-map. O seu objetivo é mapear um campo que o aplicativo precisa com o campo referente na aplicação.

Suponha que o aplicativo (ID 3) precisa de um campo chamado Descrição na entidade de Item (ID 5). Assim o aplicativo, no seu processo de deploy, deve criar esse campo (ID 7) e popular a um registro no field-map:

• entity_id = 5
• identification = description
• app_registry_id = 3
• form_extra_field = 7

A partir desse momento o usuário poderá alterar esse campo, caso tenha interesse, e utilizar um outro campo extra criado por ele ou um campo já existente na aplicação. O aplicativo não precisa fazer o gerenciamento disso apenas, de forma semelhante ao caso anterior, ao recuperar os dados via API verificar qual é o campo real. Para fazer isso basta verificar a structure da entidade, mais específicamente no dado mapping. Se fizermos uma requisição contra a URL api/orders/structure?data=mapping teremos algo assim:

{
    "data": {
        "mapping": {
            "field": [{
                "identification": "description",
                "entity_id": 5,
                "app_registry_id": 3,
                "field": "description_8_12"
            }]
        }
    }
}

Assim podemos identificar que quando o aplicativo ID 2 precisar do campo description deve verificar pelo campo description_8_12 do retorno da API.