Helpers

Helpers são comandos com prefixo + para os fluxos mais comuns do Gateway Bancário, com flags nomeadas em português no lugar do JSON de --json. Eles chamam os mesmos endpoints dos comandos de banking.

Helper	O que faz	Endpoint
+emitir	Emite um boleto	POST /v1/bank_billets
+cobrar	Cria uma cobrança Pix	POST /v2/charge/pix
+cancelar-lote	Cancela vários boletos, um a um, pelos ids	PUT /v1/bank_billets/{id}/cancel

+emitir

Flag	Obrigatória	Vira
--valor	sim	amount
--vencimento	sim	expire_at (YYYY-MM-DD)
--nome	sim	customer_person_name
--cpf-cnpj	sim	customer_cnpj_cpf
--carteira	sim	bank_billet_account_id
--descricao	não	description

kobana +emitir --valor 150.50 --vencimento 2026-12-01 \
  --nome "Maria Silva" --cpf-cnpj "012.345.678-90" --carteira 1

+cobrar

Flag	Obrigatória	Vira
--valor	sim	amount
--conta-pix	sim	pix_account_uid
--nome	não	nome em payer
--cpf-cnpj	não	payer.document: hoje a API ignora esse campo (veja abaixo)
--descricao	não	description: hoje a API ignora esse campo (veja abaixo)

kobana +cobrar --valor 99.90 --conta-pix "PIX_ACCOUNT_UID" --nome "João"

:::caution Documento do pagador e descrição +cobrar manda o documento em payer.document e a descrição em description, mas a API espera payer.document_number e message, e os dois valores se perdem. Para cobrar com eles, use o comando completo:

kobana banking charge pix create --json \
  '{"pix_account_uid": "PIX_ACCOUNT_UID", "amount": 99.9, "message": "Pedido 4512", "payer": {"name": "João", "document_number": "012.345.678-90"}}'

:::

+cancelar-lote

kobana +cancelar-lote --ids "123,456,789"

Cada id vira um pedido de cancelamento ao banco. Para cancelar por filtro, em segundo plano, use kobana banking bank-billets cancel-all create.

:::tip Confira antes Os três aceitam --dry-run. +emitir e +cobrar mostram o método, a URL e o corpo que seriam enviados; +cancelar-lote mostra os ids que seriam cancelados. Os helpers não usam --idempotency-key: cada execução de +emitir e +cobrar sai com uma chave nova. :::

Próximos passos

• Uso: os comandos de banking, para tudo o que os helpers não cobrem.
• Introspecção de schema: o endpoint que cada helper chama.