Nordlet

← Documentacao / Guias

Importações de bancos e pagamentos

Extratos camt.053, CSV do Stripe, reconciliação de liquidações de PSP e feeds JSON personalizados.

Todas as importações entram como transações bancárias numa conta bancária (bank/accounts/create). As transações transportam um externalId; reimportar o mesmo ficheiro é seguro - as linhas cujos pares (bankAccountId, externalId) já existem são ignoradas e reportadas no contador skipped. As transações importadas começam com o estado new e só são lançadas na contabilidade quando são conciliadas (bank/transactions/match, com bank/transactions/suggest-matches para os candidatos).

A aplicação web disponibiliza as mesmas importações em Banco → Importar ficheiro (carregamento de ficheiros, seletor de modelos).

Uma conciliação incorreta é revertida com bank/transactions/unmatch (Anular conciliação em Banco → Transações). Os lançamentos contabilizados nunca são editados ou apagados: um pagamento conciliado com uma fatura, ou uma linha que um modelo de importação tenha lançado numa conta, recebe um lançamento de reversão com todos os registos do lado oposto, datado com date (predefinição: hoje, e nunca antes do lançamento original). O valor pago e o estado de pagamento da fatura recuam no montante dessa linha bancária. Uma linha associada a uma liquidação de um fornecedor de pagamentos é apenas desassociada, uma vez que o lançamento da liquidação pertence ao lote. A linha regressa ao estado new e pode ser conciliada novamente. A data de reversão deve situar-se num período contabilístico aberto.

Modelos de importação

Um modelo de importação nomeia uma fonte de dados, lista os campos fornecidos pela fonte e mapeia os campos que contêm valores monetários para as contas contábeis. Os modelos são geridos em Banco → Modelos de importação e através de bank/import-templates/create|update|delete|get|list.

POST /v1/bank/import-templates/create
{
  "name": "Stripe payments export",
  "type": "stripe",
  "fields": [
    { "name": "id" },
    { "name": "Created date (UTC)" },
    { "name": "Amount" },
    { "name": "Fee", "accountCode": "6800" },
    { "name": "Amount Refunded" }
  ],
  "metaFields": ["order_id"]
}
  • O type pode ser stripe, iso20022, bank_connection ou revolut.
  • Cada campo tem um name e um accountCode opcional. Apenas os campos que contêm valores monetários aceitam uma conta: Amount, Fee e Amount Refunded do Stripe; Ntry/Amt do camt.053; transaction_amount.amount do feed bancário. A conta deve existir no plano de contas (crie-a com ledger/accounts/create).
  • O parâmetro fields pode ser omitido; nesse caso, assume por predefinição a lista de campos standard do tipo: os nomes das colunas do ficheiro Payments → Export do Stripe (sem as 19 colunas Card …, que o formulário também deixa desmarcadas por predefinição), os elementos camt.053 presentes em todos os extratos (Stmt/Id, Stmt/Acct/Id/IBAN, Stmt/Bal/…, Ntry/Amt, Ntry/CdtDbtInd, Ntry/Sts, Ntry/BookgDt), ou os atributos devolvidos por um feed bancário PSD2 por transação. Adicione ou remova entradas para corresponder ao seu ficheiro: o importador também lê os elementos camt.053 opcionais Ntry/ValDt, Ntry/NtryRef, Ntry/AcctSvcrRef, Ntry/AddtlNtryInf, TxDtls/Refs/EndToEndId, TxDtls/Refs/TxId, TxDtls/RltdPties/Dbtr/Nm, TxDtls/RltdPties/DbtrAcct/Id/IBAN, TxDtls/RltdPties/Cdtr/Nm, TxDtls/RltdPties/CdtrAcct/Id/IBAN, TxDtls/RmtInf/Ustrd e TxDtls/AddtlTxInf.
  • Um campo Customer Email do Stripe pode conter "createPartner": true. A importação cria então um cliente (parceiro do tipo pessoa, assinalado como cliente) para cada endereço de correio eletrónico no ficheiro que não corresponda a nenhum parceiro existente, utilizando Customer Description como nome (o endereço de correio eletrónico quando este estiver vazio) e as colunas Card Address … como morada quando o ficheiro as contiver. Os parceiros existentes são identificados pelo endereço de correio eletrónico, ignorando maiúsculas e minúsculas. A resposta reporta a contagem em customersCreated.
  • metaFields (apenas para o Stripe) lista as chaves de metadados associadas às suas cobranças. O Stripe exporta cada chave como uma coluna <key> (metadata); a lista é de formato livre e pode ser extensa.
  • invoiceItemId (apenas para o Stripe, opcional) é um artigo de catálogo. Quando definido, cada linha de fatura e nota de crédito criada pela importação faz referência a esse artigo (o respetivo lançamento e, se invoiceVatRatePercent estiver vazio, a respetiva taxa de IVA); o texto da linha continua a vir da cobrança.
  • companyMetaField (apenas para o Stripe) designa uma dessas chaves como o indicador de empresa. Quando uma cobrança contém true, 1, yes, company, business ou b2b nessa coluna, o cliente criado para a mesma passa a ser um parceiro do tipo empresa em vez de pessoa.
  • invoiceMetaField (apenas para o Stripe) designa uma dessas chaves, por exemplo um número de encomenda, e invoiceVatRatePercent define a taxa de IVA para as faturas criadas a partir da mesma. Na importação, cada linha de cobrança e reembolso é agrupada pelo valor dessa chave:
    • um valor que corresponda a uma fatura de venda existente - uma encomenda de venda cujo externalRef seja esse valor (ecommerce/orders/create, qualquer canal) ou uma fatura cujo fullNumber seja esse valor - associa o grupo a essa fatura;
    • um valor sem fatura cria uma nova: parceiro a partir de Customer Email (criado caso não exista, tal como para createPartner), uma linha por cobrança (Checkout Line Item Summary ou Description como texto, o montante da cobrança como preço com IVA incluído a invoiceVatRatePercent), data de emissão = a data da primeira cobrança, tratamento de IVA com base na empresa e no país do cartão. A fatura é emitida e lançada de imediato, sendo registada uma encomenda de venda com o canal stripe e esse valor como externalRef para que as importações futuras façam a associação em vez de criar uma nova;
    • cada cobrança do grupo é depois conciliada com a fatura como um pagamento (lançando o recebimento); cada reembolso cria uma nota de crédito emitida contra a fatura pelo montante reembolsado e concilia o reembolso com a mesma. As contagens são devolvidas em invoicesCreated, invoicesLinked, creditNotesCreated e paymentsMatched; os grupos que não puderam ser processados (sem endereço de correio eletrónico de cliente, moedas mistas, uma fatura associada que ainda seja um rascunho ou já se encontre totalmente paga) são listados em warnings e mantidos como transações bancárias no estado new. Não mapeie também o campo Amount para uma conta contábil no mesmo modelo: uma cobrança conciliada com uma fatura não é lançada uma segunda vez, mas uma cobrança não conciliada sê-lo-ia.
  • Os nomes dos modelos são únicos por empresa.
  • Os modelos camt.053 e de ligação bancária contêm as mesmas opções, lidas a partir do extrato em vez das colunas do Stripe:
    • Criar parceiros em falta: createPartner na linha do nome do devedor (TxDtls/RltdPties/Dbtr/Nm, feed debtor.name) cria um cliente para cada pagador desconhecido de dinheiro recebido; na linha do nome do credor (TxDtls/RltdPties/Cdtr/Nm, feed creditor.name) cria um fornecedor para cada beneficiário desconhecido de dinheiro enviado. Os parceiros são reconhecidos por IBAN (armazenado em partner_bank_accounts) e, em seguida, por nome exato; um novo parceiro é uma empresa se o nome contiver uma forma jurídica (UAB, MB, SIA, GmbH, Ltd, …), caso contrário, é uma pessoa. A contagem é devolvida em customersCreated (importação de ficheiro) ou partnersCreated (sincronização de feed).
    • Associar faturas por referência: invoiceMetaField definido para uma linha de remessa ou referência (TxDtls/RmtInf/Ustrd, TxDtls/RmtInf/Strd/CdtrRefInf/Ref, TxDtls/Refs/EndToEndId; feed remittance_information, reference_number) concilia cada nova linha bancária cuja referência, remessa ou descrição contenha o número de uma fatura de venda emitida em aberto (entrada de dinheiro) ou de uma fatura de compra registada (saída de dinheiro), e lança o pagamento. Quando o IBAN do pagador está guardado num parceiro, ou o nome do pagador é igual ao nome ou código de um parceiro, a fatura tem de pertencer a esse parceiro. Um pagamento de um pagador desconhecido só é associado quando coincide com o saldo remanescente da fatura e o número da fatura contém o respetivo prefixo de série, garantindo que um número isolado, como um montante, nunca é tomado como referência. Um pagamento superior ao saldo remanescente nunca é associado. As linhas que falham estas verificações permanecem no estado novo para conciliação manual e são listadas nos avisos (warnings). Com advanceInvoices: true, um pagamento recebido não conciliado de um parceiro conhecido cria uma fatura de adiantamento emitida (tipo advance) pelo montante à taxa invoiceVatRatePercent ou à taxa de invoiceItemId e concilia o pagamento com a mesma; o parceiro tem de ser conhecido, pelo que deve marcar também a linha do devedor.
    • Regras de lançamento por código de transação: além de Ntry/Amt / transaction_amount.amount, a lista de campos possui linhas de regras Ntry/BkTxCd=CHRG, =INTR, =TAXE, Ntry/CdtDbtInd=DBIT, =CRDT (feed: bank_transaction_code=…, credit_debit_indicator=…). Uma linha é lançada na conta da primeira regra com a qual coincide: a respetiva família de códigos de transação bancária, depois a direção e, por fim, a linha de montante simples. As linhas de regras não são validadas contra o ficheiro.
    • Parceiro de encargos bancários: createPartner na linha de regra …=CHRG cria um fornecedor com o nome do banco (extrato Stmt/Acct/Svcr/FinInstnId/Nm, ou o banco da ligação, ou o nome da conta bancária na contabilidade) e regista cada encargo com esse parceiro.
    • Os modelos de ligação bancária são escolhidos por conta de feed com bank/feeds/accounts/configure (Banco → Ligações na aplicação), que também define syncSchedule (manual, daily, weekly, monthly): a API sincroniza automaticamente as contas com uma programação assim que o respetivo período expira. Os modelos são aplicados em cada bank/feeds/sync; a resposta de sincronização reporta também posted, partnersCreated, invoicesLinked, invoicesCreated, paymentsMatched e warnings.

Transmita templateId para bank/statements/import em vez de format: o tipo do modelo seleciona o analisador sintático (parser), e o ficheiro deve conter todos os campos listados no modelo; um ficheiro em que falta qualquer um deles é rejeitado com o código HTTP 422 e os nomes das colunas ou elementos em falta. Os campos de metadados não precisam de estar presentes. Os modelos de ligação bancária descrevem um feed PSD2 em direto e não podem ser utilizados para importação de ficheiros.

Um modelo ISO 20022 também lê ficheiros MT940: um ficheiro que comece por {1: ou :20: (ou seja enviado com "format": "mt940") é analisado como MT940 e a correspondência de referências e as regras de lançamento do modelo são aplicadas às respetivas linhas. A verificação de elementos é ignorada para o formato MT940, e as regras Ntry/BkTxCd=… nunca se aplicam a linhas MT940 porque este formato não contém códigos de transação bancária ISO 20022; utilize antes as regras Ntry/CdtDbtInd=….

Uma conta bancária detém uma única moeda. Um extrato numa moeda diferente é rejeitado com o código HTTP 422 (num ficheiro camt.053 com extratos em várias moedas para o mesmo IBAN, apenas o extrato na moeda da conta é importado), tal como uma linha enviada para bank/transactions/import com uma currency diferente da da conta.

Cada movimento produzido a partir de um campo que possui um accountCode é lançado no momento da importação como um único lançamento contabilístico: a entrada de dinheiro a débito na conta contábil da conta bancária e a crédito na conta mapeada; a saída de dinheiro a débito na conta mapeada e a crédito na conta contábil da conta bancária. Os montantes são convertidos para a moeda base à data do movimento. A transação bancária é então conciliada (matched) com esse lançamento contabilístico (matchedDocumentType = journal_transaction) e deixa de ser proposta para conciliação de faturas. A resposta reporta a contagem em posted. Os movimentos de campos não mapeados permanecem no estado new e são conciliados com faturas como anteriormente; por exemplo, mapeie Fee para a conta de gastos com comissões de PSP e deixe Amount por mapear para que as cobranças continuem a ser conciliadas com as faturas de venda.

POST /v1/bank/statements/import
{
  "bankAccountId": "…",
  "templateId": "…",
  "content": "id,Created date (UTC),Amount,…"
}

ISO 20022 camt.053 (XML de open banking)

Os bancos lituanos (Swedbank, SEB, Luminor, Šiaulių bankas, …) permitem transferir extratos de conta em formato XML camt.053 ISO 20022 a partir do homebanking, habitualmente na secção de exportação/transferência de extratos, com o formato "ISO XML" ou "camt.053". O mesmo formato é devolvido pelas APIs de informação de contas PSD2.

POST /v1/bank/statements/import
{
  "bankAccountId": "…",
  "format": "camt053",
  "content": "<?xml version=\"1.0\"…>…"
}
  • Um ficheiro pode conter vários extratos; o IBAN de cada extrato deve corresponder ao IBAN da conta bancária (os extratos sem IBAN, ou as contas sem este elemento, são aceites tal como estão).
  • As referências de movimentos (AcctSvcrRef/NtryRef, recorrendo a um hash de conteúdo como alternativa) tornam-se o externalId.
  • A resposta devolve metadados por extrato: ID do extrato, período, saldos inicial e final, número de transações.
  • O nome da contraparte, o IBAN e a descrição do pagamento são extraídos por movimento para efeitos de conciliação.

Os pagamentos na direção oposta são exportados como pain.001 através de bank/payments/export.

Revolut Business CSV

Transfira o extrato de transações de uma conta Revolut Business em formato CSV e importe-o com o modelo integrado Revolut Business (templateId: "builtin-revolut"). Todas as empresas dispõem deste modelo sem necessidade de o criar: bank/import-templates/list-builtin lista-o, bank/import-templates/get devolve-o, e bank/import-templates/update e bank/import-templates/delete rejeitam-no com o código HTTP 400. Na aplicação, surge listado em primeiro lugar em Banco → Modelos de importação; ao abri-lo, são exibidas as respetivas definições, e ao guardá-lo é criado um modelo próprio da empresa que pode modificar.

POST /v1/bank/statements/import
{
  "bankAccountId": "…",
  "templateId": "builtin-revolut",
  "content": "Date started (UTC),Date completed (UTC),ID,Type,State,…"
}
  • Apenas são importadas as linhas com State = COMPLETED. As restantes linhas (por exemplo, PENDING) são excluídas e contadas em warnings; serão importadas numa importação posterior de um ficheiro onde já se encontrem concluídas.
  • Cada linha torna-se numa transação bancária com a data de Date completed (UTC), o montante de Total amount, a moeda de Payment currency, o campo ID como externalId e Description como descrição.
  • A contraparte numa saída de dinheiro é constituída por Beneficiary name e Beneficiary IBAN; num pagamento com cartão sem beneficiário, corresponde ao comerciante indicado em Description. A contraparte numa entrada de dinheiro é constituída por Sender name e Sender account.
  • As linhas são agrupadas por conta e moeda. O campo International account number deve coincidir com o IBAN da conta bancária, sendo apenas importadas as linhas na moeda da conta bancária.
  • Para cada linha, o importador verifica se o saldo da linha anterior somado a Total amount é igual a Balance, listando em warnings todas as linhas onde esta condição não se verifique.
  • O ficheiro deve conter obrigatoriamente as colunas Date completed (UTC), ID, Type, State, Description, Payment currency, Total amount, Reference, Sender name e Beneficiary name.

Em cada importação, o modelo integrado:

  • cria um cliente para cada remetente desconhecido de dinheiro recebido, e um fornecedor para cada beneficiário ou comerciante de cartão desconhecido em saídas de dinheiro, conforme descrito na secção Criar parceiros em falta acima;

  • concilia cada linha cuja referência (Reference) ou descrição (Description) contenha o número de uma fatura de venda ou compra em aberto, e lança o pagamento, aplicando as verificações da secção Associar faturas por referência acima;

  • lança as linhas cuja fatura não tenha sido encontrada com base no respetivo Type, para a conta de uma regra de lançamento:

    Type Regra de lançamento Conta predefinida Plano romeno Lançamento
    FEE bank.fees 6800 627 a débito da conta da regra, a crédito da conta contábil da conta bancária; parceiro: fornecedor com o nome da conta bancária
    CARD_PAYMENT bank.cardPayments 6209 628 a débito da conta da regra, a crédito da conta contábil da conta bancária, sem IVA
    TOPUP bank.topUps 3010 1012 a débito da conta contábil da conta bancária, a crédito da conta da regra

    As linhas de outros tipos, tais como TRANSFER, permanecem no estado new para efeitos de conciliação.

Altere as contas através de ledger/posting-rules/update; o modelo integrado passa a utilizar as novas contas a partir da importação seguinte. Uma regra de lançamento não pode ser desativada: para importar pagamentos com cartão ou carregamentos (top-ups) sem os lançar, crie um modelo de empresa do tipo revolut sem as linhas Type=CARD_PAYMENT ou Type=TOPUP e efetue a importação com o mesmo. Um pagamento com cartão lançado desta forma não é conciliado com a fatura do fornecedor caso esta venha a ser registada mais tarde; lance apenas um dos dois, nunca ambos.

Um modelo de empresa do tipo revolut utiliza as mesmas colunas e pode lançar linhas por tipo utilizando as linhas de regras Type=FEE, Type=CARD_PAYMENT, Type=TRANSFER e Type=TOPUP. A importação efetuada com "format": "revolut-csv" sem nenhum modelo importa as linhas sem executar nenhum destes passos.

Stripe CSV

Exportação a partir do painel de controlo do Stripe (qualquer um dos relatórios é compatível):

  • Reports → Balance → Itemized balance change from activity (recomendado): colunas balance_transaction_id, created_utc, currency, gross, fee, net, reporting_category, description.
  • Payments → Export: colunas id, Created (UTC), Amount, Fee, Currency, Description, Customer Description.
POST /v1/bank/statements/import
{
  "bankAccountId": "…",
  "format": "stripe-csv",
  "content": "balance_transaction_id,created_utc,currency,gross,fee,net,…"
}

Crie uma conta bancária dedicada para o Stripe (por exemplo, com o nome "Stripe", conta contábil 2710 ou uma subconta própria) - o saldo do Stripe comporta-se como uma conta bancária: as cobranças entram, as comissões são deduzidas e as transferências (payouts) movem o saldo para a sua conta bancária real.

Comportamento da importação:

  • Cada transação de saldo torna-se numa transação bancária pelo montante bruto (gross) (externalId = ID da transação de saldo).
  • Uma comissão (fee) diferente de zero origina uma segunda transação com o sinal oposto (externalId = <id>:fee, contraparte "Stripe") - permitindo que as comissões sejam conciliadas/lançadas como gastos separadamente das receitas. As comissões devolvidas em reembolsos entram como montantes positivos.
  • As linhas de transferência (payout) são importadas como transações negativas únicas; concilie-as com a correspondente transação de entrada no extrato da sua conta bancária real.
  • As linhas com montante zero são ignoradas; a data é obtida a partir de created_utc (UTC).
  • As linhas de exportação de pagamentos que não movimentaram dinheiro são ignoradas: Captured = false (autorizações/capturas diferidas) e Status igual a Failed/Canceled.
  • Um montante reembolsado (Amount Refunded) diferente de zero gera uma terceira transação, negativa (externalId = <id>:refund), datada de Refunded date (UTC) - para que os reembolsos parciais e totais integrados nas linhas de pagamento não se percam.

Reconciliação de liquidações de PSP (relatórios de transferência do Stripe)

Para desagregar uma transferência de montante global (lump-sum) nas respetivas encomendas, reembolsos, comissões e reversões subjacentes, utilize os endpoints de liquidação em vez da importação de extratos simples. São aceites dois tipos de exportações do Stripe (detetados automaticamente):

  • Reports → Payouts → Payout reconciliation, itemized (tipos de relatório payout_reconciliation.itemized.* ou payout_reconciliation.by_id.itemized.*) - exato, uma linha por transação de saldo; preferencial em contas ativas.
  • Payments → Export (unified payments) - a exportação ao nível da cobrança; funciona no modo de teste/sandbox onde a reconciliação de transferências não está disponível. As cobranças capturadas são agrupadas pelo ID da transferência na coluna Transfer; as linhas não capturadas/falhadas são ignoradas (skippedNotSettled); um montante reembolsado (Amount Refunded) diferente de zero gera uma linha de reembolso sintética no lote de transferência da cobrança - uma aproximação, uma vez que o reembolso pode ter sido efetivamente liquidado numa transferência posterior. As referências de conciliação provêm do ID da cobrança, PaymentIntent ID, Invoice Number, Client Reference ID e de todas as colunas … (metadata) (por exemplo, um número de encomenda nos metadados).

Um único ficheiro CSV pode abranger várias transferências. O Stripe transfere o relatório detalhado um ficheiro por secção (…_charge_…, …_refund_…, …_fee_…); importe-os todos - as linhas referentes a uma transferência já importada fundem-se no lote existente (reportado no contador updated), desde que este ainda não tenha sido lançado, e os totais do lote são recalculados.

POST /v1/bank/settlements/import
{
  "bankAccountId": "…",
  "provider": "stripe",
  "content": "balance_transaction_id,created_utc,…,reporting_category,…,automatic_payout_id,…"
}

Comportamento da importação:

  • As linhas são agrupadas por automatic_payout_id em lotes de liquidação - um lote por transferência, com os totais bruto/comissão/líquido (a soma do campo net de cada linha corresponde ao montante que entra no seu banco). A reimportação de uma transferência é ignorada (contador skipped). As linhas ainda não atribuídas a uma transferência e as próprias linhas de transferência (payout) são ignoradas e contadas separadamente.
  • Cada linha de cobrança, reembolso ou litígio é conciliada automaticamente com uma fatura de venda utilizando, por ordem: o campo externalRef de uma encomenda de comércio eletrónico (qualquer valor de order_id, payment_intent_id, source_id, charge_id ou de qualquer coluna *_metadata[...]), o fullNumber de uma fatura presente nessas colunas e, para reembolsos e litígios, o charge_id de uma cobrança previamente conciliada (do mesmo ficheiro ou de importações anteriores).
  • Reveja os dados com bank/settlements/list / bank/settlements/get; corrija os pendentes com bank/settlements/match { lineId, invoiceId } (ou invoiceId: null para anular a conciliação).

POST /v1/bank/settlements/post { id, date?, commissionPercent? } lança todo o lote como um único lançamento contabilístico equilibrado e liquida as faturas conciliadas (paidAmount/paymentStatus, webhooks sale_invoice.paid):

  • Débito na conta contábil da conta bancária pelo montante líquido da transferência; débito nas comissões de PSP (settlements.fees, predefinição 6800) pelas comissões retidas e linhas de comissão.
  • Crédito nas contas a receber por cada cobrança conciliada; os reembolsos e litígios revertem este lançamento. A aplicação está limitada ao montante remanescente de cada fatura - qualquer excesso é canalizado para a conta de suspensão com um aviso.
  • Cobranças não conciliadas: se commissionPercent estiver definido, são divididas entre receita de comissões (settlements.commissionRevenue, predefinição 5001) e uma responsabilidade perante o vendedor (settlements.sellerPayable, predefinição 4499) - o fluxo de mercado (marketplace) em que o dinheiro recolhido pertence maioritariamente aos vendedores. Caso contrário, são alocadas temporariamente a settlements.suspense (predefinição 4440, adiantamentos recebidos).
  • As linhas platform_earning (comissões da aplicação Stripe Connect) são lançadas na receita de comissões; as linhas transfer (transferências para vendedores associados) reduzem a responsabilidade perante o vendedor.
  • As quatro contas podem ser substituídas por empresa através de regras de lançamento (ledger/posting-rules).
  • Uma linha cuja cobrança, comissão ou reembolso já tenha sido importada para outra conta bancária a partir da exportação de pagamentos do Stripe (bank/statements/import) não é lançada nas contas de comissões, clientes ou suspensão. O respetivo valor net é lançado a crédito na conta contábil dessa conta bancária, permitindo que a conta bancária do Stripe seja liquidada transferência a transferência. summary.clearedAmount corresponde ao total movimentado desta forma; uma linha cujo montante difira do detido por essa conta é identificada em warnings. Se não restar nada para lançar, o lote é contabilizado com journalTransactionId a nulo.

bank/settlements/list e /get devolvem, por lote, clearedNet, clearingDifference (linhas de transferência menos os montantes que a outra conta bancária detém para as mesmas; zero quando coincidem) e clearingOpenCount (linhas com diferença ou com um movimento não lançado); /get devolve os mesmos indicadores por linha sob as designações clearingBankAccountId, clearingBooked, clearingDifference e clearingUnposted. As linhas de reembolso de uma mesma cobrança são comparadas em conjunto, uma vez que a exportação de pagamentos contém apenas o total reembolsado. Uma exportação de pagamentos do Stripe importada após a respetiva transferência ter sido lançada ignora os movimentos dessa transferência e identifica-os em warnings.

O IVA aplicável à própria comissão é faturado separadamente (emitindo uma fatura de comissão ao vendedor); a divisão serve apenas para alocar o numerário recolhido.

Transferências noutra moeda

O diário é sempre escriturado na moeda base da empresa, mas uma transferência numa moeda diferente é lançada automaticamente, sem necessidade de introdução manual:

  • O lote é convertido à taxa de câmbio aplicável à data do lançamento (date, recorrendo à data da transferência e, por fim, a hoje como alternativas). A taxa utilizada é a taxa própria da empresa para essa moeda (reference/exchange-rates/set) quando for pelo menos tão recente quanto a oficial; caso contrário, utiliza-se a taxa oficial mais recente anterior ou igual a essa data. Se não existir nenhuma taxa à data ou antes dela, a chamada falha com o código 422 e indica reference/exchange-rates/sync.
  • Todas as contas são convertidas à taxa de câmbio do lote, com exceção das contas a receber, que são baixadas à taxa de câmbio (fxRate) em vigor à data de emissão de cada fatura. A diferença entre as duas taxas é lançada em bank.fxGain (predefinição 5803) ou bank.fxLoss (predefinição 6803) como uma diferença de câmbio realizada, garantindo que o lançamento contabilístico se mantém equilibrado.
  • O objeto summary da resposta devolve a taxa de câmbio utilizada (fxRate) e a diferença de câmbio resultante (exchangeDifference), mantendo o lote a taxa com que foi lançado. Uma fatura conciliada cuja moeda seja diferente da moeda do lote não é liquidada: o respetivo montante é encaminhado para a conta de suspensão com um aviso.
  • Subsiste um limite de importação: uma única transferência cujas linhas misturem várias moedas é rejeitada com o código 422, tal como uma reimportação cuja moeda difira da do lote já armazenado para essa transferência.

Feeds manuais / personalizados

Qualquer outro dado pode ser enviado em formato JSON simples:

POST /v1/bank/transactions/import
{
  "bankAccountId": "…",
  "transactions": [
    { "date": "2026-07-01", "amount": "-25.00", "currency": "EUR",
      "counterpartyName": "…", "description": "…", "externalId": "unique-ref-1" }
  ]
}

Forneça um externalId estável por transação para garantir que as reimportações são idempotentes.