Introduction

You're a dev — have fun! ✨

The Smart Finance API is REST over HTTPS, with JSON and Bearer authentication. Everything the screens do with payables, receivables, transactions, records, and reconciliations is available to your systems — under the same per-workspace isolation as the product.

Getting started

1. Generate a token in the platform, under Integrations → API Token — see Authentication.

2. Make your first call:

   export KOBANA_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxx
   
   curl -H "Authorization: Bearer $KOBANA_TOKEN" \
     -H 'User-Agent: My System (contact@mycompany.com)' \
     'https://api.finance.kobana.com.br/v1/financial-accounts'

3. Explore the resources — the Resources category in the sidebar documents every endpoint with examples. Or import the OpenAPI specification / the Postman collection.

tip

Prefer the sandbox (https://api.finance.sandbox.kobana.com.br/v1) for development — see Endpoints.

Format

The API accepts only the JSON format. All requests must use Content-Type: application/json. All responses use snake_case.

Field type	Format
DateTime	ISO8601 format. Examples — Date: 2026-01-24. Date and Time: 2026-01-24T10:07Z
Money	Decimal string with 2 places and a dot as the separator, in BRL. e.g.: "100.00". Always sent/received as a string (never a number), to preserve cent precision; up to 13 integer digits. Transactions and bills are always positive — the direction (debit/credit, cost/revenue) goes in type/polarity, never in the sign. Account balances may be negative
UUID	Resource identifiers in UUID v4 format

Conventions

Conventions used in this documentation:

Convention	Description
:variable	Variable name that must be replaced in a URL.
#{variable}	Variable name that must be replaced with values from your account.
...	Response content truncated for readability.
$KOBANA_TOKEN	Access token. For command-line testing, export it: export KOBANA_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxx and paste the documentation commands into your terminal.

HTTP status codes

The API returns standard HTTP codes:

	Code	Description
✅	200 OK	Successful request with response body.
✅	201 Created	Resource created successfully.
✅	204 No Content	Successful request, no response body.
❌	400 Bad Request	Invalid request, generally malformed content.
❌	401 Unauthorized	Missing or invalid access token.
❌	403 Forbidden	API access blocked or user lacks permission.
❌	404 Not Found	The requested address does not exist.
❌	409 Conflict	Conflict with the current state of the resource — e.g. reusing an X-Idempotency-Key with a different body.
❌	422 Unprocessable Entity	Valid request, but the submitted data is not.
❌	429 Too Many Requests	Rate limit reached.
❌	500 Internal Server Error	Internal processing error. Check the server status.

The envelope and the stable vocabulary of error codes are in Errors.

Request IDs (Request-Id)

Each request has an associated identifier, available in the Request-Id response header. This value helps with debugging and auditing — requests and their IDs can be looked up in the system panel. The request log is available for 30 days. When opening a support ticket about a specific request, provide the Request-Id to speed up the investigation.

Security

The Smart Finance API uses 2048-bit SSL certificates. Every request must be made over HTTPS — calls on port 80 are redirected to 443.

Clients must support TLSv1.2 or TLSv1.3 with one of the following ciphers: TLS_AES_128_GCM_SHA256, TLS_AES_256_GCM_SHA384, TLS_CHACHA20_POLY1305_SHA256, ECDHE-RSA-AES128-GCM-SHA256, ECDHE-RSA-AES128-SHA256, ECDHE-RSA-AES256-GCM-SHA384, ECDHE-RSA-CHACHA20-POLY1305, ECDHE-RSA-AES256-SHA384. TLSv1 and TLSv1.1 are not supported.

HTTP Cache

Use HTTP cache headers to reduce load and gain speed. Most responses include ETag and/or Last-Modified — store these values and resend them in subsequent requests via If-None-Match and If-Modified-Since. If the resource has not changed, the response will be 304 Not Modified, with no body and no reprocessing. More information: HTTP Cache Docs.

Error handling

5xx errors indicate server failures: 500 Internal Server Error (application unavailable), 502 Bad Gateway, 503 Service Unavailable, and 504 Gateway Timeout (transient infrastructure failures). Your application should identify these codes and reschedule the request after a few minutes with backoff. Server status: https://status.kobana.com.br.

Next steps

• Specifications — OpenAPI 3.1 in YAML for download.
• Endpoints — production and sandbox URLs.
• User-Agent — header to identify your application.
• Rate limiting — throttling and response headers.
• Listing and pagination — cursor and collection envelope.
• Filtering and sorting — grammar for ?field[operator]= and ?sort=.
• Field selection — ?fields= to return only the columns you use.
• Idempotency — X-Idempotency-Key for safe retries.
• Errors — envelope and vocabulary of error codes.
• Data retention — retention policy by resource type.