ranjit

README

Ranjit

Um serviço open source em Go para integrar contas, saldos e transações ao seu backend.

Você instala o Ranjit uma vez e usa sua API pelo SDK Go. O serviço cuida dos conectores, importação de extratos, sincronização e armazenamento. Roda como binário ou container, com SQLite local ou PostgreSQL na hospedagem. SDKs para outras linguagens podem usar o mesmo contrato HTTP.

seu aplicativo → seu backend → SDK Go → Ranjit → APIs bancárias / extratos
                                          ↓
                                  SQLite ou PostgreSQL

As integrações diretas usam as credenciais da aplicação criada pelo titular no banco. Para compartilhamento entre bancos pelo Open Finance, ainda é necessária uma operação habilitada e outro adaptador. Os limites de acesso estão documentados com as referências oficiais.

Usar no backend

Para experimentar a integração completa com Docker:

git clone https://github.com/getcortexlabs/ranjit.git
cd ranjit
./scripts/quickstart.sh

O quickstart sobe o serviço, um backend Go e o receptor de webhooks, gera as chaves e testa importação e sandbox. Os dados persistem entre reinícios. Docker é opcional para integrar seu aplicativo.

Para começar localmente, instale o binário abaixo, rode ranjit serve e obtenha a chave com ranjit key. No seu backend:

go get github.com/getcortexlabs/ranjit@v0.4.0
export RANJIT_URL=http://localhost:8080
# Configure RANJIT_API_KEY com a chave da sua instalação.

client, err := ranjit.NewClientFromEnv()
if err != nil {
    return err
}
page, err := client.SearchTransactions(ctx, ranjit.TransactionFilter{
    CustomerID: authenticatedUserID,
    Limit:      100,
})

O SDK é um cliente HTTP: o Ranjit roda como processo separado do seu backend. A chave fica apenas no servidor. Seu aplicativo autentica os usuários e determina quais dados cada um pode acessar; customer_id sozinho não é uma permissão.

O exemplo de backend Go importa um CSV e consulta transações sem precisar de acesso bancário. O guia de instalação em servidor e Orbit cobre PostgreSQL, segredos e a configuração do SDK. O painel e os comandos locais continuam disponíveis como ferramentas de apoio.

Para repetir uma criação sem duplicar conexões, use client.ConnectWithKey. Webhooks assinados avisam sobre sincronizações e mudanças no estado das conexões. A chave da API pode ser trocada com um prazo para migrar os consumidores. O guia de integração confiável traz configuração, exemplos e recuperação de falhas. O guia do SDK cobre paginação automática, retentativas de leitura e tratamento de erros.

Para verificar a instalação pelo backend, basta configurar a mesma URL/chave e rodar ranjit doctor --remote. Use --json em automações. O comando consulta a API, o banco e os workers pelo serviço, sem precisar dos arquivos locais do Ranjit.

Instalar

macOS e Linux, sem Go e sem Docker:

curl -fsSL https://raw.githubusercontent.com/getcortexlabs/ranjit/main/install.sh -o /tmp/ranjit-install.sh
sh /tmp/ranjit-install.sh

O instalador baixa o binário da release, verifica o SHA-256 e instala em ~/.local/bin. Se essa pasta ainda não estiver no PATH, ele mostra o comando para executar. Não usa sudo nem altera arquivos do shell. Para escolher outra pasta, use RANJIT_INSTALL_DIR; para fixar uma versão, RANJIT_VERSION.

No Windows, baixe o ZIP correspondente ao processador em Releases, extraia e execute ranjit.exe. Os arquivos .tar.gz também permitem instalação manual no macOS/Linux. checksums.txt acompanha cada release.

Usar

O caminho mais curto é abrir o painel local:

ranjit ui

O comando cria a configuração, inicia o servidor e abre o navegador. Em Importar extrato, escolha um OFX ou CSV, confira a prévia e confirme. Para experimentar com dados fictícios:

ranjit demo
ranjit accounts
ranjit transactions

Para usar um extrato que você exportou do banco:

ranjit import extrato.ofx
ranjit accounts
ranjit transactions
ranjit status

Isso funciona localmente, sem credenciais de API ou servidor rodando. CSV também funciona:

ranjit import --account pessoal extrato.csv
# CSV com valores como -12,34 e campos separados por ponto e vírgula:
ranjit import --account pessoal --decimal , extrato.csv

O CSV precisa de date,description,amount ou data,descrição,valor. A coluna id é recomendada. Sem IDs, repetir o mesmo arquivo é seguro; novos arquivos com períodos sobrepostos são recusados para evitar confundir lançamentos iguais. Datas aceitas: YYYY-MM-DD e DD/MM/YYYY. Veja o formato dos extratos.

Para conexão automática com a API de um banco:

ranjit configure
ranjit doctor --live
ranjit sync meu-perfil

O assistente pede o banco, o nome do perfil e os caminhos dos arquivos de credenciais. Rode novamente para adicionar outra conta. Se ranjit serve estiver rodando, reinicie-o depois de alterar os perfis. Os requisitos de acesso continuam sendo os de cada banco; o assistente configura uma integração já habilitada.

ranjit status mostra a última sincronização, os lançamentos armazenados e o progresso do job. ranjit doctor verifica a configuração local; --live consulta o saldo, sem imprimir valores ou credenciais. Essa consulta não equivale a homologar o extrato. Todos os conectores bancários estão marcados como experimental.

A configuração pessoal fica na pasta de configuração do sistema, dentro de ranjit/config.json. O SQLite fica em data/ ao lado desse arquivo. RANJIT_CONFIG=/outro/caminho/config.json permite uma instalação separada. Arquivos novos recebem permissão 0600 nos sistemas Unix.

No dia a dia

ranjit backup minha-copia.db
ranjit service install
ranjit update --check

O serviço inicia ao entrar no computador, sem exigir administrador. Para atualizar: ranjit service stop, ranjit update e ranjit service start. A atualização verifica o checksum, guarda o binário anterior e faz backup do banco existente. O painel e ranjit doctor avisam quando certificados estão perto de vencer.

ranjit pause ID interrompe a coleta e mantém o histórico. ranjit renew ID verifica novamente o acesso e retoma a mesma conexão. Para restaurar, pare o serviço e use ranjit restore --replace minha-copia.db; a restauração guarda uma cópia anterior e deixa conexões bancárias pausadas. Os detalhes estão em operação.

ranjit validate --report teste.json meu-perfil testa o acesso configurado e gera um relatório sem valores, identificadores de conta ou credenciais. A conferência com o extrato oficial continua manual; veja o procedimento.

API e sincronização periódica

ranjit serve

A API escuta em http://localhost:8080. O painel fica em /app/; ranjit ui abre uma sessão sem copiar a chave. ranjit key mostra a chave para integrar seu backend; guarde-a como segredo. Para consulta no terminal, os comandos acima dispensam a API. ranjit revoke ID revoga uma conexão e remove seus dados financeiros locais.

Docker

O instalador também baixa uma imagem pronta, verifica o checksum e carrega no Docker. Não exige conta em registry:

curl -fsSL https://raw.githubusercontent.com/getcortexlabs/ranjit/main/install.sh -o /tmp/ranjit-install.sh
sh /tmp/ranjit-install.sh --docker
cd ranjit-docker
docker compose up -d
docker compose exec ranjit /ranjit demo
docker compose exec ranjit /ranjit accounts

O servidor gera a configuração e a chave no primeiro uso. O volume mantém os dados; a porta é publicada apenas em loopback. Para obter a chave: docker compose exec ranjit /ranjit key. Para importar, monte a pasta dos extratos como volume de leitura e execute /ranjit import /caminho/extrato.ofx. A imagem usa um filesystem somente leitura; credenciais também devem ser montadas como volumes de leitura. O container roda sem root.

Compilar

Go 1.26 ou superior, com o patch mais recente da versão:

git clone https://github.com/getcortexlabs/ranjit.git
cd ranjit
make build
./bin/ranjit demo

O fluxo por variáveis de ambiente continua disponível: make setup gera .env, make run inicia a API e make example demonstra o SDK. O Compose principal do repositório usa esse .env e compila a imagem com docker compose up --build. make smoke testa a API já em execução.

Conectar a própria conta Efí

O guia Efí mostra como configurar Client ID, Client Secret e certificado para homologação ou produção. A modalidade Pro admite empreendedores sem CNPJ. O conector usa apenas leitura, e cada instalação mantém suas credenciais localmente.

O histórico inicial cobre Pix recebidos e suas devoluções concluídas. Compras, Pix enviados e o extrato completo não estão incluídos. O conector foi testado com respostas simuladas da API; a validação com uma conta habilitada ainda está pendente.

Conectar a própria conta Inter Empresas

O guia Inter explica como configurar a API Banking para consultar saldo disponível e lançamentos do extrato. A integração atende contas PJ; o banco não disponibiliza essas APIs para PF ou MEI. A instalação seleciona explicitamente a conta e solicita apenas extrato.read.

Os testes locais usam respostas simuladas. A validação com uma conta Inter habilitada ainda está pendente.

Sicoob, C6 Empresas e Santander Empresas

Os guias de Sicoob, C6 Empresas e Santander Empresas explicam como configurar cada aplicação para consultar saldo e extrato da própria conta. Cada banco tem seus requisitos de habilitação e seu ambiente de testes.

Os três conectores têm testes locais com respostas simuladas. A homologação com credenciais bancárias está pendente. No Santander, o guia registra uma divergência entre o Swagger e a coleção Postman que precisa ser conferida nessa etapa.

Provedor	Acesso	Cobertura
file	Arquivo OFX/CSV exportado pelo titular	Lançamentos e saldo quando informado no OFX
sandbox	Local, sem credenciais bancárias	Contas e transações fictícias
efi	Aplicação Efí habilitada	Saldo, Pix recebidos e suas devoluções
inter	Aplicação Inter Empresas PJ habilitada	Saldo disponível e extrato da conta
sicoob	Aplicação do cooperado habilitada	Saldo e extrato mensal
c6	Aplicação C6 Empresas PJ habilitada	Saldo disponível e extrato
santander	Aplicação Santander Empresas habilitada	Saldo disponível e lançamentos efetivados

Integrar

Integrações com /v1 usam Authorization: Bearer <RANJIT_API_KEY>. Essa chave pertence ao backend da aplicação. Ela permite acessar todos os clientes daquela instalação; customer_id é um identificador de agrupamento, não uma barreira de autorização entre usuários.

set -a
. ./.env
set +a

curl http://localhost:8080/v1/connections \
  -H "Authorization: Bearer $RANJIT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"customer_id":"user-42","institution_id":"sandbox-bank"}'

No sandbox, a resposta traz a conexão e authorization_url. O link vence em dez minutos e só pode ser usado uma vez. A aprovação enfileira a primeira sincronização. O consentimento simulado dura 90 dias, contados da criação da conexão; esse prazo não pretende reproduzir a regra de um banco. Nos conectores diretos, a conexão usa api_credentials, é criada ativa após verificar o acesso e não retorna link de autorização.

O exemplo Go mostra o fluxo completo. O contrato HTTP está em docs/openapi.json, e os detalhes de paginação, erros e estados em docs/api.md.

Método	Caminho	Uso
POST	/v1/imports?customer_id=...&format=ofx	Importar extrato local
POST	/v1/imports/preview	Conferir extrato sem gravar
GET	/v1/transactions	Buscar por conta, descrição e período
POST	/v1/connections/{id}/pause	Pausar coleta e manter histórico
POST	/v1/connections/{id}/renew	Verificar acesso e retomar coleta
GET	/v1/connections/{id}/status	Ver progresso, contagens e datas dos lançamentos
GET	/v1/institutions	Instituições configuradas e cobertura de dados
POST	/v1/connections	Criar conexão; link de autorização no sandbox
GET	/v1/connections?customer_id=...	Listar conexões do cliente
GET	/v1/connections/{id}	Consultar estado e última sincronização
POST	/v1/connections/{id}/sync	Enfileirar sincronização
GET	/v1/jobs/{id}	Acompanhar execução e tentativas
GET	/v1/webhooks/deliveries	Inspecionar notificações e tentativas
POST	/v1/webhooks/deliveries/{id}/retry	Reenviar notificação que falhou
GET	/v1/connections/{id}/accounts	Consultar contas e saldos
GET	/v1/accounts/{id}/transactions	Consultar transações
DELETE	/v1/connections/{id}	Revogar e remover dados normalizados

Decisões do projeto

Um binário, um banco e workers para sincronização e notificações. net/http faz o transporte; SQLite ou PostgreSQL guarda os dados e a fila; o provedor só entrega lotes normalizados. O painel usa HTML, CSS e JavaScript embutidos no executável, sem etapa de build do frontend. Não há Redis, ORM ou framework web. O driver SQLite funciona sem CGO.

Os valores monetários usam centavos inteiros. As importações são atômicas e fazem upsert por identificador estável do provedor. As respostas de leitura já recebidas ficam temporariamente no banco de dados, vinculadas ao job. A retomada mantém o período solicitado e reaproveita essas respostas; tokens e headers não entram nesse armazenamento. Os registros temporários são removidos ao concluir, falhar definitivamente, expirar ou revogar. O resultado de uma tentativa antiga é rejeitado, mesmo se chegar depois da nova tentativa.

Revogar uma conexão cancela seus jobs e apaga contas e transações na mesma transação. Em conexões diretas, pausar ou vencer o prazo local interrompe a coleta e preserva o histórico para consulta. O consentimento simulado continua bloqueando leitura e removendo dados quando vence.

A arquitetura explica os limites dos pacotes e os motivos dessas escolhas. O guia de provedores descreve o contrato que uma futura integração precisa cumprir.

Desenvolvimento

make check     # testes com detector de corrida, go vet e formatação
make build     # bin/ranjit, sem CGO

Os testes usam SQLite em diretórios temporários e exercitam os handlers HTTP reais com transporte em memória. Cobrem consentimento, autenticação, paginação, isolamento dos IDs entre conexões, rollback, repetição de sincronização, concorrência, expiração e retomada após reinício.

Antes de operar fora da máquina local, leia operação. A versão atual tem um operador por instalação e permite trocar a chave com um período de sobreposição. O banco não tem criptografia em repouso. A configuração pessoal admite vários perfis; cada perfil direto acessa a conta vinculada às suas credenciais. O modo legado por variáveis de ambiente seleciona um provedor por processo. PostgreSQL, webhooks e idempotência estão disponíveis. Múltiplos operadores e outros produtos bancários ficam para mudanças com casos de uso definidos.

Contribuições: CONTRIBUTING.md. Licença: MIT.

Documentation

Overview

Package ranjit defines the public API types and Go client.

Index

• Variables
• func NewID(prefix string) string
• func StableID(prefix, owner, externalID string) string
• func ValidIdempotencyKey(key string) bool
• type APIError
  • func (e *APIError) Error() string
  • func (e *APIError) Is(target error) bool
  • func (e *APIError) Unwrap() error
• type Account
• type CertificateStatus
• type Client
  • func NewClient(baseURL, apiKey string) (*Client, error)
  • func NewClientFromEnv() (*Client, error)
  • func (c *Client) Accounts(ctx context.Context, connectionID, cursor string, limit int) (Page[Account], error)
  • func (c *Client) Connect(ctx context.Context, input ConnectRequest) (ConnectResponse, error)
  • func (c *Client) ConnectWithKey(ctx context.Context, input ConnectRequest, key string) (ConnectResponse, error)
  • func (c *Client) Connection(ctx context.Context, id string) (Connection, error)
  • func (c *Client) Connections(ctx context.Context, customer, cursor string, limit int) (Page[Connection], error)
  • func (c *Client) Diagnostics(ctx context.Context) (Diagnostics, error)
  • func (c *Client) Health(ctx context.Context) error
  • func (c *Client) Import(ctx context.Context, input io.Reader, opts ImportOptions) (ImportResult, error)
  • func (c *Client) Institutions(ctx context.Context) (Page[Institution], error)
  • func (c *Client) IterAccounts(ctx context.Context, connectionID string, limit int) iter.Seq2[Account, error]
  • func (c *Client) IterConnections(ctx context.Context, customer string, limit int) iter.Seq2[Connection, error]
  • func (c *Client) IterSearchTransactions(ctx context.Context, filter TransactionFilter) iter.Seq2[Transaction, error]
  • func (c *Client) IterTransactions(ctx context.Context, accountID string, limit int) iter.Seq2[Transaction, error]
  • func (c *Client) Job(ctx context.Context, id string) (Job, error)
  • func (c *Client) Pause(ctx context.Context, id string) error
  • func (c *Client) PreviewImport(ctx context.Context, input io.Reader, opts ImportOptions) (ImportPreview, error)
  • func (c *Client) Ready(ctx context.Context) error
  • func (c *Client) Renew(ctx context.Context, id string) (Connection, error)
  • func (c *Client) RetryWebhook(ctx context.Context, eventID string) error
  • func (c *Client) Revoke(ctx context.Context, connectionID string) error
  • func (c *Client) SearchTransactions(ctx context.Context, f TransactionFilter) (Page[Transaction], error)
  • func (c *Client) Status(ctx context.Context, connectionID string) (ConnectionStatus, error)
  • func (c *Client) Sync(ctx context.Context, connectionID string) (Job, error)
  • func (c *Client) Transactions(ctx context.Context, accountID, cursor string, limit int) (Page[Transaction], error)
  • func (c *Client) WebhookDeliveries(ctx context.Context, cursor string, limit int) (Page[WebhookDelivery], error)
• type ConnectRequest
• type ConnectResponse
• type Connection
  • func (c Connection) HistoryAvailable() bool
• type ConnectionStatus
• type Diagnostics
• type ImportOptions
• type ImportPreview
• type ImportResult
• type ImportSample
• type Institution
• type Job
• type Money
  • func (m Money) Validate() error
• type OperationsStatus
• type Page
• type QueueStatus
• type RetryPolicy
• type Transaction
• type TransactionFilter
• type WebhookData
• type WebhookDelivery
• type WebhookEvent
  • func VerifyWebhook(body []byte, signature, secret string, now time.Time) (WebhookEvent, error)
• type WorkerStatus

Variables

var (
	ErrUnauthorized        = errors.New("unauthorized")
	ErrRateLimited         = errors.New("rate limited")
	ErrResponseTooLarge    = errors.New("response exceeds 1 MiB")
	ErrInvalidResponse     = errors.New("invalid response")
	ErrWebhookState        = errors.New("webhook is not failed or does not belong to the configured endpoint")
	ErrIdempotency         = errors.New("idempotency key was already used with a different request")
	ErrNotFound            = errors.New("not found")
	ErrConflict            = errors.New("connection is not active")
	ErrInvalid             = errors.New("invalid input")
	ErrConsent             = errors.New("authorization link is invalid, expired or already used")
	ErrLease               = errors.New("job lease is no longer valid")
	ErrProviderCredentials = errors.New("provider credentials are invalid, missing required scopes or have changed")
	ErrProviderUnavailable = errors.New("provider is unavailable")
)

Functions

func NewID

func NewID(prefix string) string

func StableID

func StableID(prefix, owner, externalID string) string

func ValidIdempotencyKey

func ValidIdempotencyKey(key string) bool

Types

type APIError

type APIError struct {
	Cause      error
	StatusCode int
	Code       string
	Message    string
	RequestID  string
}

func (*APIError) Error

func (e *APIError) Error() string

func (*APIError) Is

func (e *APIError) Is(target error) bool

func (*APIError) Unwrap

func (e *APIError) Unwrap() error

type Account

type Account struct {
	ID           string     `json:"id"`
	ConnectionID string     `json:"connection_id"`
	Name         string     `json:"name"`
	Type         string     `json:"type"`
	Balance      *Money     `json:"balance"`
	BalanceAt    *time.Time `json:"balance_at,omitempty"`
	UpdatedAt    time.Time  `json:"updated_at"`
}

type CertificateStatus

type CertificateStatus struct {
	Profile       string     `json:"profile"`
	Level         string     `json:"level"`
	ExpiresAt     *time.Time `json:"expires_at,omitempty"`
	DaysRemaining int        `json:"days_remaining"`
}

type Client

type Client struct {
	ReadRetries RetryPolicy

	HTTPClient *http.Client
	// contains filtered or unexported fields
}

func NewClient

func NewClient(baseURL, apiKey string) (*Client, error)

func NewClientFromEnv

func NewClientFromEnv() (*Client, error)

NewClientFromEnv reads the service address and key from backend configuration. The key belongs on the server; never expose it in a browser or mobile client.

func (*Client) Accounts

func (c *Client) Accounts(ctx context.Context, connectionID, cursor string, limit int) (Page[Account], error)

func (*Client) Connect

func (c *Client) Connect(ctx context.Context, input ConnectRequest) (ConnectResponse, error)

func (*Client) ConnectWithKey

func (c *Client) ConnectWithKey(ctx context.Context, input ConnectRequest, key string) (ConnectResponse, error)

ConnectWithKey retries a logical creation safely for 24 hours. Persist a random key per operation in your backend and reuse it with the same request on retry.

func (*Client) Connection

func (c *Client) Connection(ctx context.Context, id string) (Connection, error)

func (*Client) Connections

func (c *Client) Connections(ctx context.Context, customer, cursor string, limit int) (Page[Connection], error)

func (*Client) Diagnostics

func (c *Client) Diagnostics(ctx context.Context) (Diagnostics, error)

func (*Client) Health

func (c *Client) Health(ctx context.Context) error

func (*Client) Import

func (c *Client) Import(ctx context.Context, input io.Reader, opts ImportOptions) (ImportResult, error)

Import uploads a local OFX/CSV export. Requests are limited to 8 MiB.

func (*Client) Institutions

func (c *Client) Institutions(ctx context.Context) (Page[Institution], error)

func (*Client) IterAccounts

func (c *Client) IterAccounts(ctx context.Context, connectionID string, limit int) iter.Seq2[Account, error]

func (*Client) IterConnections

func (c *Client) IterConnections(ctx context.Context, customer string, limit int) iter.Seq2[Connection, error]

IterConnections fetches pages lazily. Breaking the loop stops further requests.

func (*Client) IterSearchTransactions

func (c *Client) IterSearchTransactions(ctx context.Context, filter TransactionFilter) iter.Seq2[Transaction, error]

func (*Client) IterTransactions

func (c *Client) IterTransactions(ctx context.Context, accountID string, limit int) iter.Seq2[Transaction, error]

func (*Client) Job

func (c *Client) Job(ctx context.Context, id string) (Job, error)

func (*Client) Pause

func (c *Client) Pause(ctx context.Context, id string) error

func (*Client) PreviewImport

func (c *Client) PreviewImport(ctx context.Context, input io.Reader, opts ImportOptions) (ImportPreview, error)

func (*Client) Ready

func (c *Client) Ready(ctx context.Context) error

func (*Client) Renew

func (c *Client) Renew(ctx context.Context, id string) (Connection, error)

func (*Client) RetryWebhook

func (c *Client) RetryWebhook(ctx context.Context, eventID string) error

func (*Client) Revoke

func (c *Client) Revoke(ctx context.Context, connectionID string) error

func (*Client) SearchTransactions

func (c *Client) SearchTransactions(ctx context.Context, f TransactionFilter) (Page[Transaction], error)

func (*Client) Status

func (c *Client) Status(ctx context.Context, connectionID string) (ConnectionStatus, error)

func (*Client) Sync

func (c *Client) Sync(ctx context.Context, connectionID string) (Job, error)

func (*Client) Transactions

func (c *Client) Transactions(ctx context.Context, accountID, cursor string, limit int) (Page[Transaction], error)

func (*Client) WebhookDeliveries

func (c *Client) WebhookDeliveries(ctx context.Context, cursor string, limit int) (Page[WebhookDelivery], error)

type ConnectRequest

type ConnectRequest struct {
	CustomerID    string `json:"customer_id"`
	InstitutionID string `json:"institution_id"`
}

type ConnectResponse

type ConnectResponse struct {
	Connection             Connection `json:"connection"`
	AuthorizationURL       string     `json:"authorization_url,omitempty"`
	AuthorizationExpiresAt time.Time  `json:"authorization_expires_at,omitzero"`
}

type Connection

type Connection struct {
	ID                string     `json:"id"`
	CustomerID        string     `json:"customer_id"`
	InstitutionID     string     `json:"institution_id"`
	Provider          string     `json:"provider"`
	Status            string     `json:"status"`
	CreatedAt         time.Time  `json:"created_at"`
	ConsentExpiresAt  time.Time  `json:"consent_expires_at,omitzero"`
	LastSyncedAt      *time.Time `json:"last_synced_at,omitempty"`
	AuthorizationMode string     `json:"authorization_mode"`
	CredentialID      string     `json:"-"`
}

func (Connection) HistoryAvailable

func (c Connection) HistoryAvailable() bool

type ConnectionStatus

type ConnectionStatus struct {
	Connection   Connection `json:"connection"`
	LatestJob    *Job       `json:"latest_job,omitempty"`
	Accounts     int        `json:"accounts"`
	Transactions int        `json:"transactions"`
	DataFrom     string     `json:"data_from,omitempty"`
	DataThrough  string     `json:"data_through,omitempty"`
}

type Diagnostics

type Diagnostics struct {
	Version             string              `json:"version"`
	Certificates        []CertificateStatus `json:"certificates"`
	UnavailableProfiles []string            `json:"unavailable_profiles"`
	Operations          *OperationsStatus   `json:"operations,omitempty"`
}

type ImportOptions

type ImportOptions struct {
	Columns    map[string]string
	Delimiter  string
	CustomerID string
	Account    string
	Format     string
	Decimal    string
	DateFormat string
}

type ImportPreview

type ImportPreview struct {
	Result  ImportResult   `json:"result"`
	From    string         `json:"from"`
	Through string         `json:"through"`
	Sample  []ImportSample `json:"sample"`
}

ImportPreview describes a dry run. Its connection ID may not exist yet.

type ImportResult

type ImportResult struct {
	New           int    `json:"new"`
	Updated       int    `json:"updated"`
	Unchanged     int    `json:"unchanged"`
	ConnectionID  string `json:"connection_id"`
	Accounts      int    `json:"accounts"`
	Transactions  int    `json:"transactions"`
	Duplicate     bool   `json:"duplicate"`
	Deduplication string `json:"deduplication"`
}

type ImportSample

type ImportSample struct {
	PostedOn    string `json:"posted_on"`
	Description string `json:"description"`
	Amount      Money  `json:"amount"`
}

type Institution

type Institution struct {
	ID             string   `json:"id"`
	Name           string   `json:"name"`
	Provider       string   `json:"provider"`
	Sandbox        bool     `json:"sandbox"`
	ConnectionMode string   `json:"connection_mode"`
	DataCoverage   []string `json:"data_coverage"`
	Validation     string   `json:"validation"`
	Profile        string   `json:"profile,omitempty"`
}

type Job

type Job struct {
	ID                string    `json:"id"`
	ConnectionID      string    `json:"connection_id"`
	Status            string    `json:"status"`
	Attempts          int       `json:"attempts"`
	ErrorCode         string    `json:"error_code,omitempty"`
	CreatedAt         time.Time `json:"created_at"`
	UpdatedAt         time.Time `json:"updated_at"`
	LeaseToken        string    `json:"-"`
	RequestsCompleted int       `json:"requests_completed"`
}

type Money

type Money struct {
	AmountMinor int64  `json:"amount_minor"`
	Currency    string `json:"currency"`
}

Money uses signed minor units. BRL 12.34 is 1234; debits are negative. Values are restricted to the exact integer range supported by JSON clients.

func (Money) Validate

func (m Money) Validate() error

type OperationsStatus

type OperationsStatus struct {
	ObservedAt   time.Time               `json:"observed_at"`
	Database     string                  `json:"database"`
	Workers      map[string]WorkerStatus `json:"workers"`
	SyncQueue    QueueStatus             `json:"sync_queue"`
	WebhookQueue QueueStatus             `json:"webhook_queue"`
}

type Page

type Page[T any] struct {
	Data       []T    `json:"data"`
	NextCursor string `json:"next_cursor,omitempty"`
}

type QueueStatus

type QueueStatus struct {
	Counts          map[string]int64 `json:"counts"`
	OldestDueAt     *time.Time       `json:"oldest_due_at,omitempty"`
	LastSucceededAt *time.Time       `json:"last_succeeded_at,omitempty"`
	LastFailedAt    *time.Time       `json:"last_failed_at,omitempty"`
	RecentSucceeded int64            `json:"recent_succeeded"`
	RecentFailed    int64            `json:"recent_failed"`
}

QueueStatus is a database snapshot. Recent outcomes cover the last 24 hours; worker step counters are process-local and reset on restart.

type RetryPolicy

type RetryPolicy struct {
	MaxAttempts    int
	MaxElapsedTime time.Duration
	BaseDelay      time.Duration
	MaxDelay       time.Duration
}

RetryPolicy applies only to GET requests. Configure it before sharing a Client. The zero value makes one attempt, preserving the default client behavior.

type Transaction

type Transaction struct {
	ID          string `json:"id"`
	AccountID   string `json:"account_id"`
	Description string `json:"description"`
	Amount      Money  `json:"amount"`
	PostedOn    string `json:"posted_on"`
	Status      string `json:"status"`
}

type TransactionFilter

type TransactionFilter struct {
	CustomerID, AccountID, Query, From, Through, Cursor string
	Limit                                               int
}

type WebhookData

type WebhookData struct {
	Status       string `json:"status,omitempty"`
	JobID        string `json:"job_id,omitempty"`
	ConnectionID string `json:"connection_id"`
	CustomerID   string `json:"customer_id,omitempty"`
	ErrorCode    string `json:"error_code,omitempty"`
}

type WebhookDelivery

type WebhookDelivery struct {
	Event         WebhookEvent `json:"event"`
	Status        string       `json:"status"`
	Attempts      int          `json:"attempts"`
	HTTPStatus    int          `json:"http_status,omitempty"`
	ErrorCode     string       `json:"error_code,omitempty"`
	UpdatedAt     time.Time    `json:"updated_at"`
	NextAttemptAt *time.Time   `json:"next_attempt_at,omitempty"`
}

type WebhookEvent

type WebhookEvent struct {
	ID        string      `json:"id"`
	Type      string      `json:"type"`
	CreatedAt time.Time   `json:"created_at"`
	Data      WebhookData `json:"data"`
}

func VerifyWebhook

func VerifyWebhook(body []byte, signature, secret string, now time.Time) (WebhookEvent, error)

VerifyWebhook authenticates the unmodified request body and rejects signatures older than five minutes. The receiver must also deduplicate event IDs durably.

type WorkerStatus

type WorkerStatus struct {
	State          string     `json:"state"`
	Healthy        bool       `json:"healthy"`
	LastStartedAt  *time.Time `json:"last_started_at,omitempty"`
	LastFinishedAt *time.Time `json:"last_finished_at,omitempty"`
	LastSuccessAt  *time.Time `json:"last_success_at,omitempty"`
	Steps          uint64     `json:"steps"`
	Errors         uint64     `json:"errors"`
}