Conta bancária do fornecedor

Cadastra, lista e altera as contas que recebem os pagamentos das despesas do fornecedor. Um fornecedor pode ter várias contas, mas sempre exatamente uma principal (main_account: true). A primeira conta cadastrada é a principal; para trocar a principal, promova outra conta.

As contas não têm a trava da análise: podem ser cadastradas e alteradas com o fornecedor em qualquer status e não são exigidas para enviar a análise.

Cadastrar conta bancária

Disponível em

Perfil	Host	Permissão exigida
Gestora	manager-api	Escrita
Consultoria	consultant-api	Integração ativa

URL base de cada host: Ambientes (Hosts).

ENDPOINT

/vendor_registry/vendor/{vendor_key}/bank_account

MÉTODO

POST

Parâmetros de caminho

Parâmetro	Tipo	Descrição
vendor_key	string	Chave do fornecedor (UUID).

Corpo da requisição — Pix por chave

{
    "transfer_type": "pix",
    "pix_key": "44555666000181",
    "main_account": true
}

Corpo da requisição — TED

{
    "transfer_type": "ted",
    "financial_institution_code": "341",
    "account_branch": "0001",
    "account_number": "123456",
    "account_digit": "7"
}

Atributos do corpo

Campo	Tipo	Obrigatório	Descrição
transfer_type	string	Sim	pix ou ted.
pix_key	string	Condicional	Chave Pix, de 1 a 77 caracteres. Só com transfer_type = pix, e sem os dados de conta.
financial_institution_code	string	Condicional	Código COMPE do banco, exatamente 3 dígitos (341), não todos zero.
account_branch	string	Condicional	Agência, exatamente 4 dígitos, não todos zero.
account_number	string	Condicional	Número da conta, de 1 a 20 dígitos, não todos zero.
account_digit	string	Condicional	Dígito da conta, exatamente 1 dígito.
main_account	boolean	Não	Torna esta a conta principal, rebaixando a anterior. Padrão: false. A primeira conta do fornecedor é sempre principal.

Combinações válidas:

• pix com pix_key e sem dados de conta.
• pix com os quatro dados de conta e sem pix_key (Pix para a conta).
• ted com os quatro dados de conta.

Com dados de conta, a API identifica o banco pelo financial_institution_code e devolve o ISPB na resposta.

Resposta

STATUS

201

Corpo da resposta

{
    "bank_account_key": "0f9e8d7c-6b5a-4f3e-2d1c-0b9a8f7e6d5c",
    "transfer_type": "ted",
    "main_account": false,
    "status": "active",
    "financial_institution_code": "341",
    "financial_institution_ispb": "60701190",
    "account_branch": "0001",
    "account_number": "123456",
    "account_digit": "7"
}

Atributos da resposta

Campo	Tipo	Descrição
bank_account_key	string	Chave da conta (UUID).
transfer_type	string	pix ou ted.
main_account	boolean	Conta principal.
status	string	active ou inactive.
pix_key	string	Chave Pix. Presente só quando informada.
financial_institution_code	string	Código COMPE do banco. Presente só com dados de conta.
financial_institution_ispb	string	ISPB do banco, 8 dígitos. Presente só com dados de conta.
account_branch	string	Agência. Presente só com dados de conta.
account_number	string	Número da conta. Presente só com dados de conta.
account_digit	string	Dígito da conta. Presente só com dados de conta.

Campos sem valor não vêm como null: são omitidos da resposta.

Alterar conta bancária

Promove uma conta a principal ou muda seu status. Pelo menos um dos dois campos é obrigatório.

Disponível em

Perfil	Host	Permissão exigida
Gestora	manager-api	Escrita
Consultoria	consultant-api	Integração ativa

URL base de cada host: Ambientes (Hosts).

ENDPOINT

/vendor_registry/vendor/{vendor_key}/bank_account/{bank_account_key}

MÉTODO

PUT

Corpo da requisição

{
    "main_account": true
}

Campo	Tipo	Obrigatório	Descrição
main_account	boolean	Não	Só true é aceito: promove esta conta e rebaixa a principal atual. false devolve 400 (VRG000074).
status	string	Não	inactive desativa a conta; active reativa.

Resposta

STATUS

200

A conta atualizada, na mesma estrutura do cadastro.

Listar contas bancárias

Disponível em

Perfil	Host	Permissão exigida
Gestora	manager-api	Leitura
Consultoria	consultant-api	Integração ativa

URL base de cada host: Ambientes (Hosts).

ENDPOINT

/vendor_registry/vendor/{vendor_key}/bank_account

MÉTODO

GET

Parâmetros de consulta

Parâmetro	Tipo	Obrigatório	Descrição
limit	integer	Não	Itens por página, de 0 a 1000. Padrão: 10.
page	integer	Não	Página, a partir de 0. Padrão: 0.

Devolve todas as contas, ativas e inativas, da mais recente para a mais antiga.

Resposta

STATUS

200

Corpo da resposta

{
    "data": [
        {
            "bank_account_key": "0f9e8d7c-6b5a-4f3e-2d1c-0b9a8f7e6d5c",
            "transfer_type": "pix",
            "main_account": true,
            "status": "active",
            "pix_key": "44555666000181"
        }
    ],
    "limit": 10,
    "page": 0,
    "is_last_page": true
}

Erros

STATUS

400

code	Quando acontece
VRG000059	pix_key enviada com transfer_type = ted.
VRG000028	pix_key enviada junto com dados de conta.
VRG000048	transfer_type = pix sem pix_key e sem os quatro dados de conta.
VRG000019	transfer_type = ted sem os quatro dados de conta.
VRG000021	financial_institution_code não corresponde a nenhum banco.
VRG000074	main_account: false enviado na alteração.
VRG000078	Você tentou promover a principal uma conta inativa, ou uma conta que está sendo inativada na mesma chamada.
VRG000075	Você tentou inativar a conta principal enquanto há outra conta ativa. Promova outra conta antes.

Exemplo

{
  "title": "Pix Key Or Account Data Required",
  "description": "For a pix transfer, either pix_key or the full account data (financial_institution_code, account_branch, account_number, account_digit) must be provided.",
  "translation": "Para uma transferencia pix, e necessario informar a pix_key ou os dados completos da conta (financial_institution_code, account_branch, account_number, account_digit).",
  "code": "VRG000048"
}

STATUS

404

code	Quando acontece
VRG000014	A vendor_key não existe ou o fornecedor não é visível para você.
VRG000073	A bank_account_key não pertence a este fornecedor.

Erros de autenticação, permissão e host: veja Erros da API.

Próximo passo

Grupo de assinantes, ou vá para o envio da análise.