O que é uma API de contabilidade? Um guia prático para criadores de plataformas

Uma definição em linguagem acessível da API de contabilidade, o que a distingue de uma API fiscal ou de pagamentos, e o que deve verificar antes de integrar uma.

Uma API de contabilidade é uma interface que permite que um programa mantenha a contabilidade de outro programa. O seu software envia um evento financeiro através de HTTP. A API converte esse evento em lançamentos de partidas dobradas (double-entry) equilibrados num plano de contas (chart of accounts), armazena-os de forma a que não possam ser alterados silenciosamente, aplica o tratamento fiscal adequado e devolve-lhe relatórios, documentos e exportações através da mesma interface.

Essa definição resume a maior parte do trabalho. Tudo o resto neste artigo é uma consequência da mesma.

A versão numa frase

Uma API de contabilidade aceita eventos financeiros da sua aplicação, converte cada um num lançamento contabilístico equilibrado, armazena-os de forma imutável com o respetivo tratamento fiscal e comprovativos de suporte, e disponibiliza o razão (ledger), os documentos e os relatórios resultantes através de pontos de acesso programáveis.

Se um produto se designa por API de contabilidade, mas não produz lançamentos contabilísticos (journal entries), trata-se de outra coisa com um bom nome. Isso não é necessariamente mau; significa apenas que não fará o trabalho que lhe vai pedir.

O que uma API de contabilidade não é

Há quatro categorias de produtos adjacentes que são frequentemente confundidas com APIs de contabilidade, habitualmente numa fase avançada de um projeto.

Categoria	O que faz	O que não faz
API de cálculo de impostos (Tax calculation API)	Devolve a taxa ou o valor de imposto correto para uma transação	Manter a sua contabilidade ou armazenar os comprovativos que fundamentam a decisão durante o período de retenção legal
API de pagamentos (Payments API)	Transfere dinheiro entre partes e reporta sobre esses movimentos	Registar a comissão obtida, o IVA devido ou a responsabilidade perante um vendedor entre o pagamento e a transferência (payout)
API unificada ou agregadora (Aggregator API)	Lê e escreve dados no software de contabilidade existente do seu cliente	Agir como o sistema de registo principal (system of record); a sua contabilidade permanece na ferramenta que cada cliente já utiliza
API de relatórios ou BI (Reporting or BI API)	Lê valores de um razão existente e visualiza-os	Criar os lançamentos a partir dos quais os valores são derivados

Cada uma destas opções tem utilidades reais. Uma plataforma que precise de ser o sistema de registo principal necessita da API de contabilidade na base, e não em substituição da mesma.

As cinco funções essenciais de uma API de contabilidade

1. Registar lançamentos equilibrados. Cada evento traduz-se em débitos e créditos cuja soma resulta no mesmo montante. Quando um comprador paga 100 € num marketplace que cobra uma comissão de 15 €, o lançamento debita uma conta de clearing no valor de 100 €, credita a conta a pagar ao vendedor em 85 € e credita proveitos de comissões em 15 €. Isto não é um formalismo burocrático, mas sim um controlo estrutural que deteta toda uma classe de erros de integração antes de chegarem a um relatório.

2. Reter o histórico. Um lançamento validado (posted) não é editado. Um erro corrige-se através de um estorno seguido de um lançamento corrigido, ambos associados ao original. Os meses encerrados ficam bloqueados para impedir que sejam efetuados novos lançamentos com data nesses períodos.

3. Apurar impostos. No contexto de transações intracomunitárias na UE, isto abrange o local de tributação (place of supply), a autoliquidação (reverse charge), a validação de números de identificação de IVA no VIES e o armazenamento dos comprovativos que justificaram a decisão junto da transação, em vez de os descartar após o cálculo.

4. Conciliar com fluxos bancários. Contas que nunca cruzam dados com um extrato bancário resumem-se a estimativas. A API tem de ingerir extratos ou liquidações de fornecedores e cruzá-los com o que foi registado.

5. Exportar. Relatórios, documentos e ficheiros de auditoria em formatos aceites por contabilistas e autoridades tributárias.

Um produto que cumpra os primeiros três pontos, mas falhe os dois últimos, continuará a exigir trabalho manual em folhas de cálculo todos os meses.

Como é uma chamada na prática

A mecânica é mais simples do que a contabilidade em si. Na API da Nordlet, cada operação é um pedido POST do tipo RPC com uma estrutura previsível:

POST /v1/{module}/{resource}/{action}
Authorization: Bearer <api key>
Idempotency-Key: <your event id>

Cria uma fatura de venda e, em seguida, emite-a. A emissão é o momento em que a contabilidade ocorre: o documento obtém a sua numeração sequencial sem saltos, o lançamento equilibrado é efetuado e as linhas de IVA ficam registadas. A sua plataforma nunca monta débitos e créditos manualmente.

Três detalhes nesse exemplo são mais importantes do que o nome do ponto de acesso (endpoint):

O âmbito (scope) da chave. Uma chave transporta permissões como sales:write, garantindo que uma integração obtém apenas o acesso estritamente necessário.
A chave de idempotência (Idempotency-Key). Se repetir o mesmo pedido com os mesmos dados, obtém a resposta armazenada em vez de uma segunda fatura. Se enviar a mesma chave com dados diferentes, o pedido é rejeitado com o erro idempotency_key_reuse em vez de ser aceite silenciosamente.
Valores monetários representados como strings. Os montantes são strings decimais e não números de vírgula flutuante (floats), uma vez que estes últimos perdem cêntimos de formas que se tornam visíveis no fecho de contas anual.

Onde se posiciona na sua arquitetura

A sua aplicação continua a ser a interface (front-end) e a fonte de eventos de negócio. A API de contabilidade passa a ser o sistema de registo financeiro subjacente. O fluxo habitual decorre da seguinte forma:

Ocorre um evento no seu produto: uma encomenda, um reembolso, um pagamento (payout) ou a renovação de uma subscrição.
O seu sistema de suporte (back-end) chama a API de contabilidade enviando o evento e uma chave de idempotency.
A API regista o lançamento contabilístico, aplica o IVA e devolve identificadores que armazena junto dos seus próprios registos.
Um webhook, como sale_invoice.paid, avisa o seu sistema quando o estado é alterado, permitindo-lhe reagir a eventos em vez de efetuar consultas periódicas (polling).
As transações bancárias entram através de uma conexão bancária (bank feed) ou da importação de um extrato e são cruzadas com os documentos registados.
No final do período, os relatórios e os mapas de IVA são gerados a partir dos mesmos dados, procedendo-se ao bloqueio do mês encerrado.

Nada nesta lista exige que um humano abra uma aplicação de contabilidade. Esse é precisamente o objetivo desta categoria de produtos.

Como se compara com as alternativas

Abordagem	Esforço inicial	Posição de auditoria	Escalabilidade com o volume de transações
Folhas de cálculo e registo manual	Mais baixo	Fraca; o histórico é editável	Não
Software de contabilidade mais exportações CSV	Baixo	Depende inteiramente da disciplina interna	Reduzida; requer a importação manual de ficheiros
API agregadora ligada à contabilidade de cada cliente	Médio	Herda as características da ferramenta do cliente	Sim, mas nunca detém a propriedade do registo
API de contabilidade integrada (Embedded accounting)	Médio	Forte, desde que o razão seja imutável e os períodos bloqueiem	Sim
Criar o seu próprio razão	Mais elevado	Forte apenas se também desenvolver os controlos internos	Sim, exigindo manutenção contínua

Desenvolver a sua própria solução é uma escolha legítima para algumas equipas, sendo analisada em detalhe no nosso guia de build-versus-buy para marketplaces.

O que deve verificar antes de integrar uma API

O saldo é derivado ou armazenado? Averigue se o saldo de um vendedor resulta de uma consulta sobre as linhas do razão ou de uma coluna atualizada diretamente. Apenas uma destas opções resiste a uma auditoria.
O que acontece numa nova tentativa (retry)? Envie o mesmo pedido duas vezes e conte os lançamentos gerados.
É possível editar um lançamento validado? A resposta deve ser negativa, devendo existir um caminho de correção documentado.
Um período bloqueado rejeita efetivamente novos lançamentos? Teste esta situação num ambiente de testes (sandbox). A Nordlet devolve o código 409 para lançamentos com data num período bloqueado.
Como são representados os valores monetários? Através de strings decimais ou subunidades inteiras. Nunca utilize floats.
O que inclui o registo de auditoria (audit record)? O autor, a ação, a entidade e a própria alteração, consultáveis em vez de perdidos em ficheiros de registo (logs).
Quais são os limites de pedidos (rate limits)? A Nordlet permite 300 pedidos por minuto por chave de API e indica o orçamento restante nos cabeçalhos de resposta. Conheça este limite antes de desenhar a sua sincronização.
Como obtém os seus dados de volta? Relatórios, documentos e diários em formatos que possam ser entregues a um contabilista.

Cada um destes pontos pode ser testado numa tarde contra uma empresa em ambiente de sandbox. As listas de funcionalidades dos fornecedores não servem de prova; um teste reprodutível sim.

FAQ

Uma API de contabilidade é o mesmo que um software de contabilidade?

Trata-se de um software de contabilidade com uma interface diferente. O software tradicional coloca um operador humano em frente ao razão; a API de contabilidade coloca o seu código nesse papel. As obrigações subjacentes, a estrutura de partidas dobradas e os relatórios mantêm-se inalterados.

Continuo a precisar de um contabilista se utilizar uma API?

Sim. Uma API automatiza o registo, o cálculo e a produção de relatórios. Não toma decisões de julgamento sobre enquadramento fiscal, provisões ou o tratamento específico de um contrato e, na maioria dos países, não assina nem submete as suas contas anuais.

Posso utilizar uma API de contabilidade sem compreender partidas dobradas?

Em parte. Uma boa API constrói os lançamentos contabilísticos a partir de um documento comercial, como uma fatura. No entanto, continua a precisar de compreender o significado das contas ao ler um relatório ou ao explicar um saldo a um auditor.

Qual é a diferença entre uma API de contabilidade e uma API de razão (ledger API)?

Uma API de razão regista movimentos equilibrados entre contas. Uma API de contabilidade faz isso mesmo e acrescenta a camada legal e estatutária: documentos com numeração legal, tratamento de IVA, registos fiscais, ativos fixos, fecho de período e os relatórios exigidos por jurisdição. Todas as APIs de contabilidade contêm um razão, mas nem todos os razões constituem um sistema de contabilidade.

Quanto tempo demora a efetuar a integração?

Para um primeiro fluxo funcional – criar um cliente, emitir uma fatura, receber um pagamento e visualizar o lançamento contabilístico –, preveja dias em vez de semanas utilizando um SDK tipado e um ambiente de sandbox. Uma integração em ambiente de produção que abranja reembolsos, correções, multimoeda, conciliação e fecho de período exige um esforço maior, sendo que a estimativa realista depende da quantidade de casos que o seu produto efetivamente gera.