POST
/v1/BankAccount/{id}/BeneficiaryBanking · Favorecidos
Solicitar a inclusão de novo favorecido
Cria um novo registro de Bank Account.
Visão geral
Solicitar a inclusão de novo favorecido
Autenticação e pré-requisitos
Requer autenticação. Envie o token no header Authorization: Bearer {{token}} (JWT do AWS Cognito). Integrações servidor-a-servidor podem usar X-Api-Key. Todo tráfego é HTTPS e a credencial nunca vai na URL nem em query string.
Pré-requisitos: a rota exige identificador(es) de recurso já existente(s):
id— —
Request
Parâmetros
| Nome | Em | Tipo | Obrigatório | Descrição | Exemplo |
|---|---|---|---|---|---|
id | path | string | obrigatório | — | 3fa85f64-5717-4562-b3fc-2c963f66afa6 |
Corpo da requisição
Envie no formato application/json. Corpo obrigatório.
Campos
| Campo | Tipo | Obrigatório | Descrição | Valores | Exemplo |
|---|---|---|---|---|---|
name | string | obrigatório | — | — | "Fulano de Tal" |
registrationNumber | string | opcional | — | — | "12345678909" |
bank | integer | opcional | — | — | 0 |
bankIspb | integer (int64) | opcional | — | — | 0 |
agency | integer | opcional | — | — | 0 |
accountNumber | string | opcional | — | — | "texto" |
accountType | objeto | opcional | — | varia conforme o tipo — ver exemplo | "NaturalCheckingAccount" |
operationTypeValue | string | obrigatório | — | Transfer, Pix | "Transfer" |
pixKeyTypeValue | objeto | opcional | — | varia conforme o tipo — ver exemplo | "NaturalRegistrationNumber" |
keyPix | string | opcional | — | — | "texto" |
Exemplo de corpo
{
"name": "Fulano de Tal",
"registrationNumber": "12345678909",
"bank": 0,
"bankIspb": 0,
"agency": 0,
"accountNumber": "texto",
"accountType": "NaturalCheckingAccount",
"operationTypeValue": "Transfer",
"pixKeyTypeValue": "NaturalRegistrationNumber",
"keyPix": "texto"
}Response
Resposta 201.
Campos
| Campo | Tipo | Obrigatório | Descrição | Valores | Exemplo |
|---|---|---|---|---|---|
id | string | opcional | — | — | "texto" |
createdAt | string (date-time) | opcional | — | — | "2025-08-11T13:45:00Z" |
createdBy | objeto | opcional | — | varia conforme o tipo — ver exemplo | { … } |
tenant | string | opcional | — | — | "texto" |
tenantDisplay | string | opcional | — | — | "texto" |
updatedAt | string (date-time) | opcional | — | — | "2025-08-11T13:45:00Z" |
updatedBy | objeto | opcional | — | varia conforme o tipo — ver exemplo | { … } |
ownerUser | objeto | opcional | — | varia conforme o tipo — ver exemplo | { … } |
ownerGroup | objeto | opcional | — | varia conforme o tipo — ver exemplo | { … } |
name | string | opcional | — | — | "Fulano de Tal" |
registrationNumber | string | opcional | — | — | "12345678909" |
bank | integer | opcional | — | — | 0 |
bankIspb | integer (int64) | opcional | — | — | 0 |
bankDisplay | string | opcional | — | — | "texto" |
agency | integer | opcional | — | — | 0 |
accountNumber | string | opcional | — | — | "texto" |
tenantName | string | opcional | — | — | "Fulano de Tal" |
accountType | objeto | opcional | — | varia conforme o tipo — ver exemplo | "NaturalCheckingAccount" |
accountTypeDisplay | string | opcional | — | — | "texto" |
status | string | opcional | — | Approved, Pending, Rejected, Timeout, Canceled, Error, Processing, Finished, Scheduled, Reversed, ComplianceApproval, CancellationRequested | "Approved" |
statusDisplay | string | opcional | — | — | "texto" |
operationTypeValue | string | opcional | — | Transfer, Pix | "Transfer" |
operationTypeValueDisplay | string | opcional | — | — | "texto" |
pixKeyTypeValue | objeto | opcional | — | varia conforme o tipo — ver exemplo | "NaturalRegistrationNumber" |
pixKeyTypeValueDisplay | string | opcional | — | — | "texto" |
keyPix | string | opcional | — | — | "texto" |
authorizedAt | string (date-time) | opcional | — | — | "2025-08-11T13:45:00Z" |
bankAccountId | string | opcional | — | — | "3fa85f64-5717-4562-b3fc-2c963f66afa6" |
requester | objeto | opcional | — | varia conforme o tipo — ver exemplo | { … } |
approvals | array de objeto | opcional | — | objeto — ver detalhe abaixo | [ … ] |
Detalhe de approvals
| Campo | Tipo | Obrigatório | Descrição | Valores | Exemplo |
|---|---|---|---|---|---|
level | objeto | opcional | — | varia conforme o tipo — ver exemplo | "Viewer" |
action | string | opcional | — | Approve, Reject, Cancel | "Approve" |
actionDisplay | string | opcional | — | — | "texto" |
user | objeto | opcional | — | varia conforme o tipo — ver exemplo | { … } |
Exemplo de resposta
{
"id": "texto",
"createdAt": "2025-08-11T13:45:00Z",
"createdBy": {
"userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"registrationNumber": "12345678909",
"userIdDisplay": "texto",
"tenantDisplay": "texto",
"tenantName": "Fulano de Tal"
},
"tenant": "texto",
"tenantDisplay": "texto",
"updatedAt": "2025-08-11T13:45:00Z",
"updatedBy": {
"userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"registrationNumber": "12345678909",
"userIdDisplay": "texto",
"tenantDisplay": "texto",
"tenantName": "Fulano de Tal"
},
"ownerUser": {
"userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"registrationNumber": "12345678909",
"userIdDisplay": "texto",
"tenantDisplay": "texto",
"tenantName": "Fulano de Tal"
},
"ownerGroup": {
"groupDisplay": "texto",
"tenantDisplay": "texto"
},
"name": "Fulano de Tal",
"registrationNumber": "12345678909",
"bank": 0,
"bankIspb": 0,
"bankDisplay": "texto",
"agency": 0,
"accountNumber": "texto",
"tenantName": "Fulano de Tal",
"accountType": "NaturalCheckingAccount",
"accountTypeDisplay": "texto",
"status": "Approved",
"statusDisplay": "texto",
"operationTypeValue": "Transfer",
"operationTypeValueDisplay": "texto",
"pixKeyTypeValue": "NaturalRegistrationNumber",
"pixKeyTypeValueDisplay": "texto",
"keyPix": "texto",
"authorizedAt": "2025-08-11T13:45:00Z",
"bankAccountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"requester": {
"userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"registrationNumber": "12345678909",
"userIdDisplay": "texto",
"tenantDisplay": "texto",
"tenantName": "Fulano de Tal"
},
"approvals": [
{
"level": "Viewer",
"action": "Approve",
"actionDisplay": "texto",
"user": {
"userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"registrationNumber": "12345678909",
"userIdDisplay": "texto",
"tenantDisplay": "texto",
"tenantName": "Fulano de Tal"
}
}
]
}Códigos de retorno
| Código | Significado | Detalhe do contrato |
|---|---|---|
201 | Recurso criado com sucesso. | — |
Exemplos
curl -X POST "{{baseUrl}}/v1/BankAccount/3fa85f64-5717-4562-b3fc-2c963f66afa6/Beneficiary" \
-H "Authorization: Bearer {{token}}" \
-H "Content-Type: application/json" \
-d '{
"name": "Fulano de Tal",
"registrationNumber": "12345678909",
"bank": 0,
"bankIspb": 0,
"agency": 0,
"accountNumber": "texto",
"accountType": "NaturalCheckingAccount",
"operationTypeValue": "Transfer",
"pixKeyTypeValue": "NaturalRegistrationNumber",
"keyPix": "texto"
}'var baseUrl = "{{baseUrl}}";
var token = "{{token}}";
using var http = new HttpClient { BaseAddress = new Uri(baseUrl) };
http.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", token);
var rota = "/v1/BankAccount/3fa85f64-5717-4562-b3fc-2c963f66afa6/Beneficiary";
var corpo = new StringContent(
"""
{
"name": "Fulano de Tal",
"registrationNumber": "12345678909",
"bank": 0,
"bankIspb": 0,
"agency": 0,
"accountNumber": "texto",
"accountType": "NaturalCheckingAccount",
"operationTypeValue": "Transfer",
"pixKeyTypeValue": "NaturalRegistrationNumber",
"keyPix": "texto"
}
""",
Encoding.UTF8, "application/json");
var resp = await http.PostAsync(rota, corpo);
resp.EnsureSuccessStatusCode();
var json = await resp.Content.ReadAsStringAsync();const baseUrl = '{{baseUrl}}';
const token = '{{token}}';
const payload = {
"name": "Fulano de Tal",
"registrationNumber": "12345678909",
"bank": 0,
"bankIspb": 0,
"agency": 0,
"accountNumber": "texto",
"accountType": "NaturalCheckingAccount",
"operationTypeValue": "Transfer",
"pixKeyTypeValue": "NaturalRegistrationNumber",
"keyPix": "texto"
};
const resp = await fetch(`${baseUrl}/v1/BankAccount/3fa85f64-5717-4562-b3fc-2c963f66afa6/Beneficiary`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(payload),
});
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
const data = await resp.json();Troque apenas {{baseUrl}} e {{token}}. No Postman, defina-os como variáveis de environment; o cURL importa em Import > Raw text.
Downloads
Este endpoint já vem configurado nas collections abaixo, na pasta da etapa correspondente.
Collection completaConsignado privado e FGTS, em pastas espelhando a documentação.Baixar →Environment do PostmanAs variáveis fora da collection, para versionar uma sem versionar o token.Baixar →Documentação consolidada para LLMToda a documentação em um arquivo de texto, na ordem da navegação.Baixar →Referência em MarkdownEste contrato, campo a campo, gerado do spec.Baixar →
Guia de importação: Como importar no Postman · Todos os downloads: Downloads