Ledger

Este é o nosso módulo principal. Para interagir com os outros, é necessário compreender os conceitos a seguir.

Conta

Uma Conta possui um ID único e saldo de um ou mais Ativos. Quando uma Conta pode criar Contas-filhas, através de um par de Credenciais de acesso, damos o nome de "Conta-pai".

Na maioria das aplicações, Contas-filhas costumam representar os usuários ou empresas clientes da sua aplicação.

A imagem a seguir demonstra o cenário mais simples:

O proximo exemplo mostra uma configuração para casos de marketplace:

Ativo

Um Ativo pode ser criado para representar valores físicos ou digitais, que podem ser transferidos entre pessoas ou empresas. Alguns exemplos:

  • Moedas fiduciárias (BRL, USD)

  • Moedas digitais

  • Pontos de um programa de fidelidade

  • Milhas

  • Títulos financeiros (ações, debêntures)

  • Commodities

Para as integrações de Cash-in e Cash-out, nós automaticamente disponibilizamos um Ativo chamado 'BRL' e marcado com a flag isBacked, que reflete o saldo disponível na instituição bancária parceira.

Credenciais

A sua Conta-pai possui um par de Credenciais, que é composto de uma Chave de API (apiKey) e um Segredo (secret), e é utilizado para autenticar todas as requisições feitas à nossa API.

Suas Credenciais não devem ser compartilhadas ou expostas indevidamente! Qualquer um que tenha acesso à elas poderá realizar Ações em seu nome. Confira a seção de Segurança para recomendações e dicas importantes.

Ação

É maneira a única maneira de modificar o saldo de uma ou mais Contas. Existem 3 tipos de Ações:

  • ISSUE_ASSET

  • BURN_ASSET

  • TRANSFER

ISSUE_ASSET

Emite uma quantidade de um Ativo criado para uma Conta. Pode ser utilizada para creditar sua Conta-pai ou uma Conta-filha.

BURN_ASSET

Destrói uma quantidade de um Ativo de uma Conta. Na prática, pode ser utilizado para remover saldo da sua Conta-pai ou de uma Conta-filha.

Você só pode emitir ou queimar um valor de um Ativo criado pela sua Conta-pai.

TRANSFER

Executa uma transferência de um Ativo entre duas Contas-filhas, ou entre a Conta-pai e uma Conta-filha.

Lote de Ações (batch)

Todas as Ações são enviadas e processadas em lote, de modo que todas elas sejam processadas em ordem, de forma transacional. Portanto, se alguma falhar por algum motivo, todas as outras também falharão.

Um Lote pode incluir até 20 Ações de qualquer tipo.

Todo batch possui um status. São estes seus possíveis valores:

  1. PENDING: Execução pendente. Este é o status inicial, pelo fato de todas as execuções serem assíncronas.

  2. SUCCESS: Foi executado com sucesso.

  3. FAILED: Falhou por algum motivo. Neste caso, ele possuirá um campo error com mais detalhes sobre o ocorrido.

Através da combinação de Ações em um mesmo Lote, é possível:

  • Converter saldo entre Ativos (ISSUE_ASSET + BURN_ASSET);

  • Realizar uma transferência P2P com split (TRANSFER + TRANSFER);

  • Coletar taxas de uma transferência, ou conversão (TRANSFER + TRANSFER).

Contas, Ativos e Lotes de Ações podem agregar informações adicionais.

Todos os Lotes são executados de forma assíncrona. Para mais detalhes, clique aqui.