Agregar informações em alguns recursos

Em alguns momentos, pode ser importante agregar alguns tipos de informações em alguns recursos. Alguns exemplos são:

  • Gravar um ID gerado no seu sistema para simplificar algum processo de consulta.

  • Garantir que um recurso foi criado, caso a requisição sofra algum problema de rede e não retorne.

  • Categorizar Contas, Ativos ou Transferências.

  • Melhorar a filtragem no momento de buscar informações.

Para resolver todos esses casos, alguns recursos possuem um campo fields, que permite salvar qualquer informação chave-valor.

Evite agregar informações confidenciais neste campo. Na maioria dos casos, é preferível armazenar um hash do dado.

Consultando pelos `fields`

Todos os endpoints de busca que retornem uma lista de recursos suportam um parâmetro de query fields, que espera um formato do tipo chave:valor.

São estes os recursos que atualmente suportam esta funcionalidade:

  • Conta

  • Ativo

  • Lote de Ações

  • Boleto - Cash-in

  • Boleto - Cash-out

  • TED - Cash-out

No exemplo a seguir, buscamos todas as Contas que se encaixem em uma classificação específica, que pode ser definida de acordo com as suas necessidades:

get
Filtrando Contas pelo campo `fields`

https://api.swipetech.io/ledger/accounts?fields=type:seller
Buscando todos as Contas 'classificadas' como "seller".
Request
Response
Request
Headers
x-swp-signature
required
string
Assinatura da requisição
x-swp-timestamp
required
string
Timestamp da requisição
x-api-key
required
string
Chave de API
Query Parameters
fields
optional
string
type:seller
Response
200: OK
{
"data": [
{
"id": "f85e226ba9c09c2b95905c591352019a0dc3a92d9e8232421ad289bacafb7a51",
"fields": {
"type": "seller"
},
"createdAt": "2020-06-16T19:09:36.000Z"
},
{
"id": "5208f1fe9bf258aafae92c0a0ce0b8be91c7e17e0078a4cf95c97bfc5eaa38ee",
"fields": {
"type": "seller"
},
"createdAt": "2020-06-16T19:09:36.000Z"
}
],
"status": 200,
"pagination": {
"itemCount": 2,
"limit": 10,
"cursor": 2
}
}

A informações devem ser do tipo chave-valor, sendo que ambos devem ser do tipo string. Portanto, não é possível salvar uma chave que contenha um objeto.