O que é uma conta virtual
Uma conta virtual é um sublivro contábil vinculado a uma conta unificada. Ela existe para que a plataforma consiga responder “quanto deste saldo bancário pertence ao vendedor X?” sem precisar abrir uma conta bancária separada por vendedor. O dinheiro entra (quando um recebível é pago, quando um depósito chega) e sai (quando o vendedor paga um boleto, transfere para um terceiro ou move valores entre contas virtuais). Cada movimentação é um lançamento — uma linha do livro contábil, imutável em espírito, comkind=IN ou kind=OUT.
Contas virtuais existem apenas para subcontas. A conta pai (master) é a entidade pública que mantém a relação com o banco — seu dinheiro é o próprio saldo bancário real. Subcontas são as carteiras dos vendedores, e cada subconta possui exatamente uma conta virtual principal, cujo id é igual ao id da subconta.
Todos os valores são inteiros em centavos de BRL.
15000 significa R$ 150,00.Os atores
Provisionamento automático
Não existe endpointPOST para criar uma conta virtual. A linha é criada na primeira leitura.
Quando o painel ou uma integração chama:
- Garante que
account.is_sub_accountseja verdadeiro; caso contrário, devolve um erro400informando que a conta não é uma subconta. - Localiza a conta administrada da conta pai e a vincula.
- Cria uma conta virtual cujo
idé idêntico ao id da subconta. É idempotente — chamadas subsequentes retornam a linha existente e só preenchem o vínculo administrado caso esteja faltando.
Saldo, calculado a partir do livro contábil
Uma conta virtual não tem uma coluna de saldo armazenada. Ele é sempre recalculado:WAITING_CONFIRMATION), já é deduzida do saldo disponível — o vendedor não pode gastar duas vezes o mesmo dinheiro enquanto uma transferência está em curso.
O caminho principal
1
Provisionar e ler
GET …/virtualaccounts/{sub_account_id}/ para provisionar automaticamente e ler o saldo.2
Movimentar dinheiro
POST …/pay/, POST …/transfer/ ou POST …/deposit/ para empurrar dinheiro para fora ou puxar para dentro. Use GET …/known-transfer-destinations/ para preencher o formulário a partir de TEDs anteriores.3
Inspecionar o livro contábil
GET …/entries/ para ler as linhas IN/OUT. GET …/entries/{id}/ para detalhar o recebível, o pagamento ou a transferência que produziu o lançamento.Etapa 1 — Listar as contas virtuais de um vendedor
A view de lista devolve todas as contas virtuais cujaaccount corresponda ao vendedor. Nenhum saldo é incluído na lista — a linha é leve por design. Use o endpoint de detalhe para ler saldos.
Etapa 2 — Ler o saldo
id == account_id, a view faz o provisionamento automático da linha antes de serializar (ver Provisionamento automático). O payload inclui balance em centavos.
Veja detalhe de conta virtual.
Etapa 3 — Movimentar dinheiro
O viewset expõe quatro açõesPOST mais um auxiliar GET:
POST .../pay/ — pagar um boleto
POST .../pay/ — pagar um boleto
Body:
bank_slip_code (linha digitável), target_date (data em que o boleto deve ser pago) e amount (centavos).Cria um lançamento com kind=OUT, source=PAYMENT, status=PLANNED e, em seguida, um registro de pagamento que vincula os dois. A submissão de fato ao banco acontece quando o pagamento é executado — tipicamente por meio de um worker dedicado de execução de transferências ou de uma ação administrativa. Em caso de sucesso, o lançamento passa para WAITING_CONFIRMATION e um webhook do parceiro bancário externo o move depois para PAID, REVERSED ou FAILED.Se a conta administrada tiver BANK_SLIP em notify_on_actions, a requisição também dispara um e-mail para notify_actions_to.POST .../transfer/ — enviar dinheiro para fora
POST .../transfer/ — enviar dinheiro para fora
Os campos do body dependem do
transfer_type:-
TED(padrão) —receiver_name,receiver_tax_id,receiver_tax_id_type(PF/PJ),receiver_bank(código de 3 dígitos),receiver_agency,receiver_account,receiver_account_type(CHECKING_ACCOUNT/SAVINGS_ACCOUNT),target_date,amount. Cria um registro de transferência e um lançamentoOUT. A submissão ao banco é feita ao executar a transferência e, depois, confirmada por webhook. -
PIX—receiver_name,receiver_tax_id,pix_key,pix_key_type(CPF/CNPJ/EMAIL/PHONE/RANDOM),target_date,amount. Mesmo padrão contábil do TED, mas o trilho bancário é o PIX. -
BETWEEN_ACCOUNTS—destination_account(id de outra conta virtual),amount. É o único fluxo que efetiva de forma atômica: a requisição valida se a origem tem saldo suficiente, depois grava dois lançamentos (OUTna origem,INno destino) e um único registro de transferência dentro de uma transação de banco comstatus=PAID. Sem chamada ao banco. Sem webhook.
transfer_type escolhido.POST .../deposit/ — puxar dinheiro via PIX
POST .../deposit/ — puxar dinheiro via PIX
Body:
amount (decimal em reais, mínimo 0.01) e name (rótulo, no máximo 32 caracteres).Cria uma venda online avulsa (a primitiva de checkout do vendedor) sob um plano oculto chamado PIX Only - Uniconta, com cartão de crédito e boleto desabilitados. Retorna { "id": "<online_sell_id>" }. O vendedor então compartilha a URL de checkout resultante com quem deve pagar; quando o pagamento é liquidado, o pipeline normal de recebíveis registra um lançamento IN na conta virtual (veja Reconciliação).Use quando o vendedor quiser depositar valores na conta virtual a partir de uma origem externa.GET .../known-transfer-destinations/ — auxiliar de autopreenchimento
GET .../known-transfer-destinations/ — auxiliar de autopreenchimento
Retorna os 10 destinos de TED mais usados desta conta virtual, calculados a partir de todos os registros de transferência com
status=PAID e transfer_type=TED, agrupados por (receiver_bank, receiver_agency, receiver_account). Cada item traz usage_count, last_used_at e os campos do destinatário necessários para montar um body de POST .../transfer/.Use para alimentar uma UI de “destinatários recentes”; não há validação contra o banco de destino — é apenas uma busca por frequência baseada em transferências bem-sucedidas anteriores.Etapa 4 — Inspecionar lançamentos
CANCELED e PREDICTED filtrados (esses status são ruído contábil — a plataforma escreve linhas PREDICTED para recebíveis que ainda não foram pagos; ficam visíveis pelo id, mas não na lista). Cada lançamento carrega:
O endpoint de detalhe adiciona três objetos aninhados — somente um deles é preenchido, conforme o
source do lançamento:
Veja lista de lançamentos e detalhe de lançamento.
Há também uma ação de exportação sob o endpoint de lista:
GET …/entries/report/ retorna até 1000 linhas em CSV / XLSX / TXT (o formato é selecionado pelo cabeçalho Accept).
Reconciliação
A reconciliação tem duas metades — colocar dinheiro dentro de uma conta virtual e confirmar dinheiro saindo. Entradas (recebíveis → lançamentos IN). Quando o pipeline unificado atualiza um recebível pertencente a uma subconta, ele dispara um job de sincronização do lançamento. O job:- Mapeia o status do recebível para o status do lançamento (
paid→PAID,pending/scheduled→PREDICTED,deleted→CANCELED,refunded→REVERSED). - Se já existe um lançamento para aquele recebível, atualiza o status.
- Caso contrário, provisiona a conta virtual, monta um
nameamigável (rótulo de venda de ingressos, rótulo do checkout, dados da parcela) e escreve um novo lançamentoINcomsource=RECEIVABLE.
PAID de forma síncrona. O fluxo é:
- A API grava um lançamento
PLANNEDe os respectivos registros de transferência / pagamento. - Um processo em segundo plano (ou uma ação administrativa manual) executa a operação, submetendo-a ao parceiro bancário externo. Em uma resposta 2xx, o lançamento transita para
WAITING_CONFIRMATIONe umexternal_idé armazenado. - O parceiro bancário envia um webhook de volta ao listener do módulo. Com base no
eventType(payment.COMPLETED,transfer.REFUNDED,payment.CANCELED, …) o listener marca o registro e o lançamento como pago, estornado ou cancelado.
BETWEEN_ACCOUNTS não passam por isso — são efetivadas atomicamente dentro de uma transação de banco e nunca entram em WAITING_CONFIRMATION.
Verificação de saldo total. Operadores administrativos podem comparar a soma de todos os saldos virtuais com o saldo bancário real:
Operações administrativas
Superusuários gerenciam contas administradas e inspecionam todas as contas virtuais por meio de endpoints dedicados sob/uniconta/admin/. O viewset não administrativo é somente leitura; o administrativo adiciona atualização, métricas e relatórios.
- Lista admin de contas administradas, detalhe, criação.
- Lista admin de contas virtuais — todas as contas virtuais sob uma conta administrada, com
balancee a identidade do vendedor vinculada. GET /uniconta/admin/managed-accounts/total-balance/— soma dos saldos virtuais contra o saldo bancário real.GET /uniconta/admin/managed-accounts/{id}/metrics/— contagens de transferências e boletos agrupadas por status, mais o saldo agregado daquela conta administrada.POST /uniconta/admin/managed-accounts/{id}/export-report/— body{ "statuses": ["PLANNED", ...] }. Gera um relatório.xlsm(Excel com macros) de boletos e TEDs no formato esperado pelo parceiro bancário externo, pronto para upload no portal corporativo.
false mantém tudo em PLANNED até que um operador atue.
Exemplo de ponta a ponta
Um backend de vendedor recupera a conta virtual do vendedor, transfereR$ 100,00 para uma conta virtual irmã e, em seguida, lista os lançamentos resultantes.
OUT com source=TRANSFER e status=PAID, e o livro contábil de destino ganha um lançamento espelho IN com status=PAID. Ambos apontam para o mesmo registro de transferência.
Armadilhas
Onde ir em seguida
Modelo de dados unificado
Como recebíveis se tornam lançamentos
IN nas contas virtuais.Webhooks e jobs
O mecanismo que move lançamentos de
WAITING_CONFIRMATION para PAID.Referência da API Uniconta
Todos os endpoints expostos pelo módulo uniconta.
Autenticação e acesso
Acesso legado, permissões de superusuário e o que cada viewset verifica.