v1

latestOpenAPI 3.1.02026-07-249043961.2 KB

Carteiras de Cobrança

Criar Carteira de Cobrança

Cria uma nova carteira de cobrança para emissão de boletos bancários. A carteira precisa ser homologada antes de poder ser utilizada em produção.

post/v1/bank_billet_accounts

Headers

User-Agentstring

Informar um e-mail válido para contatos.

X-Idempotency-Keystring

Chave de idempotência para evitar replay de processamento.

Request body

idinteger

ID da carteira

bank_contract_slugstring required

Slug da Carteira

financial_account_uidstring uuid nullable required

UID da Conta Financeira. Quando informado, os dados de agência e conta serão preenchidos automaticamente a partir da conta financeira.

next_our_numberinteger nullable

Próximo Nosso Número. Default: 1

next_remittance_numberinteger nullable

Último sequencial da remessa Default: 1

agency_numberstring

Agência. Preenchido automaticamente quando financial_account_uid é fornecido.

agency_digitstring

Dígito da Agência. Preenchido automaticamente quando financial_account_uid é fornecido.

account_numberstring

Conta. Preenchida automaticamente quando financial_account_uid é fornecido.

account_digitstring

Dígito da Conta. Preenchido automaticamente quando financial_account_uid é fornecido.

extra1string nullable

Campo extra 1. Dependendo da carteira escolhida poderá ser obrigátorio.

extra1_digitstring nullable

Digito do Campo extra 1. Dependendo da carteira escolhida poderá ser obrigátorio.

extra2string nullable

Campo extra 2. Dependendo da carteira escolhida poderá ser obrigátorio.

extra2_digitstring nullable

Dígito do Campo extra 2. Dependendo da carteira escolhida poderá ser obrigátorio.

extra3string nullable

Código de Remessa

payment_placestring nullable

Local de Pagamento

contractstring

Contrato

contract_typestring

Tipo do Contrato

beneficiary_namestring required

Nome do Beneficiário

beneficiary_cnpj_cpfstring required

CNPJ/CPF do Beneficiário

beneficiary_address_streetstring nullable required

Rua do Beneficiário

beneficiary_address_street_numberstring nullable required

Numero da rua do Beneficiário

beneficiary_address_complementstring nullable required

Complemento do endereço do Beneficiário

beneficiary_address_neighborhoodstring nullable required

Bairro do Beneficiário

beneficiary_address_citystring nullable required

Cidade do Beneficiário

beneficiary_address_statestring nullable required

Estado do Beneficiário

beneficiary_address_zipcodestring nullable required

CEP do Beneficiário (formato 99999999)

beneficiary_addressstring nullable required

Endereço completo do Beneficiário.

bolepix_enabled_atstring nullable

Data e Hora em que o boleto híbrido foi habilitado.

namestring

Nome da Conta. Não é recebido na criação e nem na atualização, só é retornado na consulta e listagem

status'pending' | 'homologating' | 'validating' | 'active'

Situação da carteira: Quando a carteira acaba de ser cadastrada, ela ganha o status pending.

Nesse momento o usuário deve aceitar os termos e iniciar a homologação.

Ao clicar em “Prosseguir com a Homologação”, o status passa para homologating.

Será gerado um boleto e uma remessa de Homologação para ser enviada ao banco. Após o término, o status passa para validating.

A partir desse momento o usuário precisa informar o valor do boleto que foi gerado ou enviar o retorno processado pelo banco.

Quando o valor é informado corretamente, ou no retorno processado, o banco diz estar tudo certo, o status passa para active.

pending Homologação não iniciada
homologating Em homologação, aguardando pagamento do boleto
validating Boleto pago, aguardando validação
active Ativa e pronta para uso

defaultboolean nullable

Padrão. O campo default determina a carteira de cobrança que será usada na criação do boleto quando nenhuma carteira for informada.

No momento que a primeira carteira é homologada (passa para o status = active), ela recebe o valor default = true

configurationobject nullable

Configuração de dados padrões para boleto

bank_contractobject

Dados da Carteira. Não é recebido na criação e nem na atualização, só é retornado na consulta e listagem.

custom_namestring

Nome da Carteira para identificação dentro da Kobana.

kind'cnab400' | 'cnab240'

Tipo de CNAB:

cnab400 CNAB 400
cnab240 CNAB 240

remittance_disabledboolean nullable

Desabilita geração de remessas.

remittance_disabled_atstring date-time nullable

Data e hora em que a geração de remessa foi desabilitada.

allow_expiration_on_weekendsboolean nullable

Permitir vencimento em fim de semana e feriados

created_atstring date-time nullable

Data e hora de criação da carteira

updated_atstring date-time nullable

Data e hora da última atualização da carteira

created_via_apiboolean nullable

Indica se a carteira foi criada por API

Example request

{
  "next_our_number": 1,
  "next_remittance_number": 1,
  "beneficiary_address_zipcode": "01310100",
  "bolepix": {
    "pix_mode": 2,
    "pix_account": {
      "custom_name": "Conta Pix Kobana",
      "key": "+55999999999",
      "financial_provider_slug": "bradesco",
      "enabled": true,
      "beneficiary": {
        "document": "12345678901",
        "address": {
          "street": "Rua do Beneficiário",
          "number": "123",
          "complement": "Apto 101",
          "neighborhood": "Bairro do Beneficiário",
          "city_name": "Cidade do Beneficiário",
          "state": "SP",
          "zip_code": "01310100"
        }
      }
    },
    "pix_billing_options": {
      "kind": "instant",
      "interest": true,
      "fine": true,
      "discount": true,
      "revoke_days": true
    }
  }
}

Response

Carteira de cobrança criada com financial_account_uid