Uso

Sintaxe

kobana banking <recurso> [sub-recurso…] <metodo> [flags]

• <recurso> pode ser aninhado: bank-billets, charge pix, charge automatic-pix recurrences, financial accounts statement-transactions.
• <metodo> é a ação: list, get, create, update, delete, ou uma ação do recurso, como cancel, approve ou send-email.

A versão da API não entra no comando: o CLI resolve a URL pela spec embutida. Recursos da API v1 ficam no nível de cima (bank-billets, customers, webhooks), e os da v2 dentro da família (charge, payment, transfer, financial, admin, mailbox).

Parâmetros de caminho e de query vão em --params; o corpo da requisição vai em --json. Na API v1 o identificador do caminho é id; na v2, uid.

Toda a superfície se descobre pelo --help, em qualquer nível:

kobana banking --help                 # recursos do Gateway Bancário
kobana banking charge --help          # sub-recursos de cobrança
kobana banking charge pix --help      # métodos de um recurso

Recursos de banking

Recurso	API	Conteúdo
bank-billets, bank-billet-accounts, bank-billet-payments, bank-billet-batches, installments, customer-subscriptions	v1	Boletos, carteiras, pagamentos, lotes, carnês e assinaturas
remittances, discharges, bank-billet-registrations, bank-billet-remittances, bank-billet-discharges	v1	Remessa e retorno CNAB
customers, events, imports, reports	v1	Clientes, eventos, importações e relatórios
webhooks, webhook-deliveries, email-deliveries, sms-deliveries	v1	Webhooks e histórico de entregas
charge	v2	Pix, contas Pix, Pix Automático e recebimentos
payment, payments	v2	Pagamentos de boleto, Pix, tributos e concessionárias, lotes e DDA
transfer, transfers	v2	TED, Pix e transferência interna
financial	v2	Contas financeiras, saldos e extrato
data	v2	Consultas de boleto e de QR Code Pix
mailbox, edi	v2	Caixa postal e caixas EDI
admin, security, me	v2	Subcontas, usuários, conexões, certificados, tokens e o usuário autenticado

A tabela completa de comandos, recurso a recurso, está no catálogo.

Exemplos

# Boletos vencidos, em tabela
kobana banking bank-billets list \
  --params '{"status": "overdue"}' \
  --fields "id,our_number,amount,expire_at" \
  --output-format table

# Emitir uma cobrança Pix (confira antes com --dry-run)
kobana banking charge pix create --dry-run \
  --json '{"pix_account_uid": "PIX_ACCOUNT_UID", "amount": 99.9}'

# Cancelar um boleto
kobana banking bank-billets cancel --params '{"id": 123}'

# Transferências Pix, um registro por linha (NDJSON), até 10 páginas (--page-limit)
kobana banking transfer pix list --page-all

# Extrato de uma conta financeira, salvo em arquivo
kobana banking financial accounts statement-transactions list \
  --params '{"financial_account_uid": "FINANCIAL_ACCOUNT_UID"}' --output extrato.json

Idempotência

Todo POST sai com o cabeçalho X-Idempotency-Key. Sem --idempotency-key, o CLI gera um UUID novo a cada execução, então rodar o comando de novo é outra requisição e pode criar um segundo registro. Num script que pode repetir uma criação, passe a sua própria chave: por 24 horas, a API devolve o resultado da primeira requisição em vez de executá-la de novo.

kobana banking bank-billets create --idempotency-key "pedido-4512" --json '{ … }'

PUT e PATCH levam a chave só quando você a informa. Veja Idempotência.

Próximos passos

• Introspecção de schema: os parâmetros e o corpo de qualquer endpoint.
• Flags globais: todas as flags que um comando aceita.
• Helpers: atalhos +verbo.
• Recursos: o catálogo completo.