Faturamento Automático

Native integration · Read-only (pull) · Syncs automatically every 60 min (configurable) + on demand · Real-time settlement via webhook

Faturamento Automático is Kobana's subscriptions and recurring billing product. When your operation bills through it, Dunning connects to it to collect on open invoices — bringing the customers and generated invoices into the collection rule, the portal and the agreements.

Prerequisites

• A Faturamento Automático account with customers and invoices.
• An API token for Faturamento Automático.
• Access to the Faturamento Automático panel to register the inbound webhook (optional, but recommended for real-time settlement).

How to connect

:::note No dedicated panel screen (yet) Today only the Kobana Gateway has a ready connect screen in the panel. For this ERP, the connection is made through the API (/api/v1/integrations/... routes) — the steps below describe the authorization flow; the equivalent self-service screen in the panel is on the roadmap. :::

Faturamento Automático uses a static key — you paste a token, with no redirect.

1. In the Faturamento Automático panel, copy the API token.
2. In Dunning, open Settings → Integrations and choose Faturamento Automático.
3. Paste the API token and select the environment (production or sandbox).
4. Click Connect. Dunning validates the token with a test call; an invalid token is rejected before saving.
5. For real-time settlement: the setup returns Dunning's webhook URL. Register a webhook in the Faturamento Automático panel pointing to that URL and paste the endpoint's signing secret in the indicated field — it is what validates the signature of each delivery.

Field mapping (source → Dunning)

Faturamento Automático field	Dunning field
Invoice	Charge
total	Original amount
amount_remaining (open balance)	Current amount
amount_paid / paid_at	Amount paid / payment date
due_date	Due date
finalized_at / created_at	Issue date
number	Document number
hosted_invoice_url / invoice_pdf_url	Payment URL
Status open	pending (or overdue if past due)
Status paid	paid (settlement + exit from the collection rule)
Status void / uncollectible	cancelled (write-off exits the collection rule)
Status draft	ignored (not yet chargeable)
Billing account customer	Person in the portfolio
document_number, name, legal_name	Document, name, legal name
emails, phones	Person's emails and phones
custom_metadata (custom fields)	customData.kobanaBilling.custom_metadata

The custom fields (custom_metadata) you define in Faturamento Automático, both on the customer and on the invoice, travel to Dunning under the customData.kobanaBilling key. The sync merges this block and preserves the rest of the person's/charge's customData — that is, fields you have defined through the Dunning API are not overwritten on each sync round.

Real-time and pull

When an invoice is paid, Dunning settles the charge and removes it from the collection rule; cancelled invoices (void/uncollectible) exit for good. With the webhook registered, these changes arrive in real time (invoice.paid, invoice.voided, among others); without it, the sync every 60 min (or the sync button) keeps everything consistent.

What it does not do / limitations

• Does not issue invoices. Issuance and the billing rule stay in Faturamento Automático.
• Does not write back. It is pull-only: settling or cancelling in Dunning does not change the source invoice.
• Draft invoices do not enter until they are finalized.
• Without a webhook, there is a delay of up to one sync cycle.

Disconnecting or reconfiguring

Redo the setup to change the token. A reconfiguration without providing the signing secret does not erase the secret already registered — this avoids silently dropping the webhook signature validation. To rotate credentials, generate a new token/endpoint in the source panel and update it in Dunning.

Troubleshooting

• The sync is out of date. Check the interval (default 60 min) and use Sync now.
• A paid invoice did not settle. Check in the integration log whether the invoice.paid webhook arrived and whether the signing secret is correct; without a webhook, the next pull reconciles it.
• A customer did not appear. The customer sync runs alongside; billing accounts with no associated customer are skipped.
• A charge appears duplicated. Dunning deduplicates by externalId (billing:invoice:{id}); a real duplicate only occurs if the same charge comes from another source.
• Webhooks return a signature error. The signing secret registered in Dunning does not match the endpoint's — re-register the secret in the setup/reconfiguration.

Security

The API token is encrypted at rest and is never returned by the API. The webhook signing secret is preserved across reconfigurations so as not to interrupt signature validation.