What Is a Double-Entry Ledger API for Marketplaces?

Um marketplace pode parecer perfeitamente saudável na sua tabela de orders e, ainda assim, estar totalmente equivocado em relação ao seu dinheiro. A encomenda diz "pago". O painel do vendedor mostra um saldo. No entanto, nada nessa tabela prova quanto dinheiro em caixa a plataforma detém, quanto deve a cada vendedor, quanto do pagamento corresponde a receitas de comissão ou quanto IVA é agora exigível. Uma API de livro razão de partida dupla (double-entry ledger API) existe precisamente para registar essas consequências financeiras de forma correta, uma transação equilibrada de cada vez.

Dito de forma simples: uma API de livro razão de partida dupla (double-entry ledger API) é um sistema de contabilidade programável. A sua aplicação envia-lhe um evento financeiro, como um pagamento capturado ou um pagamento a vendedor aprovado, e o livro razão escreve esse evento como um diário com débitos e créditos iguais em contas com nome atribuído. O livro razão não movimenta dinheiro; ele regista a verdade sobre o dinheiro que foi movimentado noutro lugar.

O que significa "livro razão de partida dupla" neste contexto

Um livro razão (ledger) é o registo das alterações efetuadas nas contas, e não uma tabela que guarda apenas o saldo mais recente. Um livro razão funcional baseia-se em três ideias interconectadas:

• Conta (account): uma posição financeira com um nome atribuído, como por exemplo, a receber de processador de pagamentos, a pagar a vendedor, receitas de comissão ou IVA a pagar.
• Transação (journal): um único evento financeiro atómico que contém várias linhas equilibradas.
• Lançamento (posting): uma única linha de débito ou crédito dentro dessa transação.

O invariante que mantém toda a arquitetura coesa é simples: o total de débitos é igual ao total de créditos, para cada transação e para cada moeda. As APIs de livro razão rejeitam tipicamente uma gravação desequilibrada antes mesmo de esta chegar ao armazenamento. A documentação da Modern Treasury define uma transação de livro razão como envolvendo duas ou mais contas com pelo menos um débito e um crédito de montantes totais iguais, e trata uma transação lançada como imutável.

Partida dupla não significa exatamente duas linhas. Uma única venda num marketplace requer frequentemente um débito e vários créditos. Esta é a parte que as pessoas interpretam incorretamente com maior frequência.

Porque é que os marketplaces precisam de um livro razão e não apenas de uma tabela de pagamentos

Um marketplace gere várias relações financeiras em simultâneo. Um comprador paga. Um processador liquida. A plataforma pode controlar os fundos temporariamente. O vendedor obtém uma percentagem. A plataforma retém uma comissão. O imposto torna-se exigível. Pode ser retida uma reserva. Posteriormente, um pagamento transfere o dinheiro para fora, e os reembolsos ou estornos revertem partes do processo.

Uma tabela de payments consegue indicar o estado comercial de uma encomenda. No entanto, não consegue indicar com fiabilidade:

• quanto existe a receber do processador ou em dinheiro
• quanto é devido a cada vendedor
• quanta receita pertence à plataforma
• quanto IVA é exigível e em que país
• qual o montante retido como reserva para reembolsos ou litígios
• se um pagamento reduziu corretamente a responsabilidade perante o vendedor
• se as liquidações do processador coincidem com o que a plataforma esperava

O guia da Nordlet sobre APIs de livro razão de partida dupla para contabilidade de marketplaces traça uma linha clara: as tabelas da aplicação descrevem o estado do produto, enquanto o livro razão regista as consequências financeiras desse estado. O guia destaca também um ponto que vale a pena repetir: os relatórios dos processadores de pagamentos servem de inputs para a reconciliação, e não como livros de partida dupla completos.

Uma venda de marketplace passo a passo

Considere que um comprador paga €100, o vendedor tem direito a €85 e a comissão da plataforma é de €15. Para maior clareza, ignore o IVA e as taxas do processador.

Conta	Débito	Crédito	Motivo
A receber do processador de pagamentos	€100		O processador deve o pagamento capturado à plataforma
A pagar a vendedor		€85	A plataforma deve ao vendedor
Receitas de comissão		€15	A plataforma gerou a sua comissão
Total	€100	€100	Equilibrado

A classificação importante aqui é que os €85 devidos ao vendedor representam um passivo, e não uma receita da plataforma. Ao abrigo da estrutura concetual das IFRS, um passivo é uma obrigação presente de transferir um recurso económico. Um marketplace não deve registar a totalidade dos proveitos de venda do vendedor como o seu próprio rendimento apenas porque o comprador pagou através dele. A qualificação da plataforma como agente, principal ou fornecedor presumido altera o tratamento contabilístico, mas o mecanismo do livro razão permanece o mesmo.

Quando o vendedor se torna elegível para receber o pagamento, não é reconhecida nenhuma nova receita. O passivo é liquidado:

Conta	Débito	Crédito
A pagar a vendedor	€85
Banco ou câmara de liquidação de pagamentos		€85
Total	€85	€85

Se o processador cobrar uma taxa de €3 antes de efetuar a liquidação, o movimento de dinheiro passa a ser um diário de três linhas: €97 para o dinheiro no banco, €3 para gastos com comissões de processamento e €100 a sair da conta a receber do processador. Cada alteração de posição tem uma origem e um destino.

Como funciona a API, passo a passo

1. A sua aplicação deteta um evento de negócio. Um pagamento é capturado, uma encomenda é cumprida, um pagamento a vendedor é aprovado, um reembolso é emitido, um estorno é aberto ou uma liquidação é creditada. A sua base de dados continua a gerir o estado operacional, enquanto o livro razão regista o efeito monetário.

2. Envia um pedido estruturado. Este inclui habitualmente o tipo de evento, o montante e a moeda, o ID da encomenda ou do pagamento, os identificadores do comprador e do vendedor, a comissão, os dados fiscais, as contas envolvidas, as datas de efeitos e de lançamento, uma chave de idempotência e metadados que remetem para os registos do processador e do produto. O exemplo da API pública da Nordlet demonstra um pedido conceptual de venda com o ID do vendedor, o tipo de venda, o montante, a moeda, bem como o país e a taxa de IVA.

3. A API valida o pedido. Verifica se os débitos e créditos estão equilibrados, se as contas existem e aceitam lançamentos, se a moeda é suportada, se o montante utiliza um tratamento preciso de unidades subsidiárias, se a chave de idempotência não foi reutilizada para um resultado diferente, se o período está aberto e se os metadados obrigatórios estão presentes. Uma validação falhada não deixa nenhum diário parcial para trás.

4. A publicação ocorre de forma atómica. A transação completa é escrita numa única operação. Nunca deve ser possível registar o débito enquanto o crédito correspondente falha. Num marketplace, uma divisão parcial pode criar um saldo aparente de vendedor sem o dinheiro correspondente, ou contabilizar uma comissão sem a respetiva obrigação perante o vendedor.

5. Os saldos e relatórios derivam do livro razão. Após o lançamento, pode consultar os saldos das contas, os saldos pendentes e disponíveis dos vendedores, um balancete de verificação, a atividade do razão geral, os resumos de IVA e o histórico reportado a uma data passada. O saldo do vendedor deve poder ser recalculado a partir dos lançamentos, em vez de depender de um campo mutável.

6. Os webhooks notificam o seu produto. Eventos como sale_invoice.paid, um diário lançado, um pagamento disponível ou uma exceção de reconciliação são enviados para si. Processe-os de forma idempotente. Um webhook é uma notificação, e não uma autorização para aplicar o evento financeiro uma segunda vez. As convenções da API abordam em detalhe os âmbitos (scopes), as chaves de idempotência, as estruturas de erro e a assinatura de webhooks.

Os saldos dos vendedores não se resumem a um único número

A maioria dos marketplaces enfrenta problemas por tratar o saldo de um vendedor como um valor único. O dinheiro deve encontrar-se distribuído por diferentes estados:

Estado	Significado
Pendente (pending)	O vendedor poderá ter direito, mas as condições de libertação ainda não foram cumpridas
Disponível (available)	Elegível para pagamento
Reservado (reserved)	Retido face a reembolsos, devoluções ou litígios
Pago (paid out)	Obrigação liquidada através de transferência
Negativo (negative)	Reembolsos, estornos ou taxas excedem os fundos disponíveis

Os modelos dos processadores refletem esta lógica. O fluxo de cobranças e transferências separadas do Stripe permite que uma plataforma cobre na sua própria conta e, em seguida, transfira partes para contas associadas, com as taxas, reembolsos e estornos a recaírem sobre o saldo da plataforma. O modelo de marketplace da Adyen distingue as contas de saldo de utilizador, que retêm fundos até ao pagamento, de uma conta de saldo passiva capaz de absorver saldos negativos decorrentes de reembolsos ou estornos. Estes dados constituem inputs úteis para o seu livro razão, mas não representam o seu modelo contabilístico completo.

Os pagamentos e os ganhos dos vendedores ocorrem em momentos diferentes

Um vendedor pode faturar numa segunda-feira e receber na segunda-feira seguinte. Entre esses dois momentos, uma encomenda é processada, uma reserva é retida, um lote de pagamentos é gerido, um processador efetua a liquidação líquida de taxas e um depósito bancário é creditado. O livro razão tem de preservar cada etapa em vez de substituir a encomenda por um estado final de "pago". É isto que lhe permite justificar as diferenças temporais entre a atividade da encomenda, o direito do vendedor, a liquidação, a iniciação do pagamento e o recebimento bancário.

Reembolsos e estornos: reverter, nunca reescrever

Os reembolsos e estornos são novos eventos associados ao pagamento original. Num livro razão imutável, a correção é feita através de um lançamento de reversão seguido de um lançamento corrigido, permitindo que o registo original permaneça visível para efeitos de auditoria. A Modern Treasury trata as transações publicadas como imutáveis e suporta chaves de idempotência para evitar objetos duplicados em caso de nova tentativa.

Um reembolso reduz tipicamente o dinheiro ou a conta a receber do comprador, reverte o saldo a pagar ao vendedor, pode reverter parte da comissão dependendo da política aplicada, ajusta o imposto e pode consumir uma reserva de reembolsos. Um estorno reduz o dinheiro ou a conta a receber do processador, pode reativar um montante devido pelo vendedor ou pela plataforma, regista um gasto por litígio e uma taxa do processador, e movimenta fundos através de uma conta de reserva.

Reconciliação: ligar o livro razão ao dinheiro real

Um livro razão pode estar equilibrado internamente e, ainda assim, estar incorreto em relação ao mundo exterior. A reconciliação compara os registos internos com as evidências externas: relatórios de liquidação do processador, extratos bancários, ficheiros de pagamento e registos de reembolsos e litígios.

Um ciclo de trabalho viável funciona da seguinte forma:

1. Importar o lote de liquidação ou extrato bancário.
2. Cruzar cada linha com uma encomenda, pagamento, reembolso, taxa, pagamento a vendedor ou litígio.
3. Comparar o valor bruto esperado, as deduções, as reservas e o valor líquido.
4. Registar os movimentos confirmados no livro razão.
5. Enviar os itens não correspondidos para uma conta suspensa com nome atribuído.
6. Investigar as exceções.
7. Fechar o período.

O material de reconciliação da Nordlet descreve exatamente este processo: importar lotes de liquidação, cruzar linhas de cobrança e reembolso, e encaminhar recebimentos sem correspondência para uma conta suspensa em vez de adivinhar uma fatura. Duas verificações são fundamentais e nenhuma substitui a outra: a validação de partida dupla verifica se cada diário está equilibrado, enquanto a reconciliação valida se o registo coincide com o processador, o banco e o evento de negócio.

Aspetos de design que determinam o sucesso da implementação

Idempotência. Associe a chave a um evento estável, como payment_captured:pi_123. Uma nova tentativa devolve o resultado original, e não um segundo diário.

Atomicidade. Todas as linhas de um evento são lançadas em conjunto ou nenhuma o é.

Imutabilidade e reversões. O histórico publicado não pode ser editado através de atualizações comuns. As correções criam entradas associadas que preservam o montante original, a data, a classificação, o motivo e o autor.

Precisão monetária. Evite a representação binária de vírgula flutuante. Utilize unidades subsidiárias inteiras ou decimais exatos, uma moeda explícita e uma regra de arredondamento determinística para divisões. Se dividir €100 por vários vendedores e taxas sem uma regra definida, um cêntimo extraviado quebrará o seu saldo.

Datas de efeitos vs datas de lançamento. A data em que o comprador pagou, a data em que o vendedor obteve o ganho, a data em que o banco liquidou e a data em que o lançamento foi efetuado são diferentes. Confundir estas datas torna a prestação de contas periódica e o apuramento de impostos pouco fiáveis.

Multi-moeda. O débito e o crédito devem equilibrar-se dentro da mesma moeda. A conversão requer um evento de taxa de câmbio explícito com contas para a taxa, arredondamento e eventuais ganhos ou perdas cambiais. A aceitação de um campo de currency não transforma um livro razão num motor de câmbio.

O que uma API de livro razão não fará por si

Não definirá o seu plano de contas. Continua a ser necessário determinar se atua como principal ou agente, em que momento a comissão é gerida, qual das partes suporta as taxas do processador, de que forma os reembolsos afetam a comissão e como o IVA é calculado e reportado. A própria orientação da Nordlet passa por mapear primeiro os fluxos de dinheiro, redigir o plano de contas, submetê-lo à revisão de um contabilista e só depois implementar um fluxo completo desde a encomenda até ao pagamento e reconciliação antes de escalar.

Não resolverá questões fiscais. O IVA depende da localização do comprador e do vendedor, do tipo de produto, do estatuto de registo e das regras aplicáveis ao fornecedor presumido; o guia de IVA da UE detalha o que o motor calcula e o que assinala para verificação humana. A cobertura de IVA da Nordlet foca-se na UE e no EEE, pelo que não se estende ao imposto sobre as vendas nos EUA (sales tax) nem à faturação eletrónica na América Latina. Igualmente, não resolverá ambiguidades operacionais, tais como saber se o prazo de devolução terminou, se um pagamento deve ser bloqueado ou se um pagamento é fraudulento. Essas decisões são da sua responsabilidade; o livro razão limita-se a registar o respetivo resultado financeiro.

Onde a Nordlet se enquadra

A Nordlet é uma API de contabilidade criada para plataformas e marketplaces, dispondo de um livro razão de partida dupla imutável, gestão de pagamentos, tratamento de IVA na UE, endpoints REST, SDKs tipados e webhooks acessíveis através de uma única interface. A sua escolha distintiva consiste em incorporar a contabilidade no seu próprio produto, em vez de recorrer a um serviço de checkout de terceiros. À data em que este artigo é escrito, o produto encontra-se em acesso antecipado com um sandbox para parceiros de design, pelo que deve ser encarado como um forte exemplo da categoria, exigindo a avaliação da maturidade de produção, do tempo de atividade (uptime) e da cobertura jurisdicional adequada ao seu caso específico antes de qualquer compromisso.

Para os programadores de marketplaces e plataformas, o modelo mental útil reside na divisão entre o movimento de pagamentos e a verdade financeira. O seu processador movimenta o dinheiro, enquanto uma API de livro razão de partida dupla regista quem deve o quê, o que geriu como receita, que impostos e reservas detém e se o mundo exterior reconcilia com os seus registos contabilísticos.

FAQ

Uma API de livro razão de partida dupla é o mesmo que um processador de pagamentos?

Não. Um processador autoriza, captura, liquida e, por vezes, transfere fundos. Uma API de livro razão regista as consequências contabilísticas desses eventos. A maioria dos marketplaces utiliza ambos: um processador como o Stripe ou a Adyen para o movimento de fundos e um livro razão para a contabilidade.

Posso utilizar o painel do meu processador como razão geral?

Pode tentar, mas acabará por falhar numa auditoria. Os relatórios dos processadores mostram cobranças, taxas, transferências e liquidações, mas habitualmente não refletem a totalidade das obrigações perante os vendedores, os passivos fiscais, os gastos alheios ao processador ou os ajustamentos contabilísticos. Deve encará-los apenas como um input para a reconciliação.

Um livro razão equilibrado significa que a contabilidade está correta?

Significa apenas que os lançamentos cumprem a regra do débito e do crédito. Uma transação perfeitamente equilibrada pode ainda assim ter sido lançada na conta errada, atribuída ao vendedor errado ou com o tratamento fiscal incorreto. O equilíbrio é necessário, mas não suficiente. A reconciliação serve precisamente para detetar o resto.

Se o livro razão é imutável, como posso corrigir erros?

Faz um lançamento de reversão e, em seguida, um lançamento corrigido. O registo original permanece visível, o que constitui precisamente o objetivo principal. A imutabilidade protege a trilha de auditoria sem bloquear a correção de erros.

Uma API de contabilidade garante a conformidade legal automaticamente?

Não. A API impõe a estrutura contabilística e produz registos utilizáveis. A conformidade legal continua a depender da sua jurisdição, do papel contratual, do tratamento fiscal, dos regulamentos de pagamentos, dos processos de KYC e AML e das obrigações de reporte.

Leitura complementar

• APIs de livro razão de partida dupla para contabilidade de marketplaces
• Defining double-entry ledgers, Formance