GuidesAPI ReferenceCommunity
GuidesCommunityLog In

Cadastro de Beneficiário

Um Beneficiário, é o nome dado para que uma wallet ativa de um cliente, tenha permissão para emissão de Boletos e permissão de recebimento dos pagamentos destes boletos em sua wallet.

Wallets não registradas como um beneficiário não estão aptas a emitir/receber valores de boletos pagos.

Usado para

  • Registar uma wallet como um beneficiário de valores de Boletos pagos;
  • Permitir que uma wallet possa emitir boletos na plataforma;

Request

POST {{BASE_URL}}/boletos/emission/beneficiary

Body Request

{
    "user": {
        "firstName": "EMPRESA",
        "lastName": "LTDA",
        "name": "EMPRESA LTDA",
        "email": "[email protected]",
        "consumer": {
            "taxId": "38749049000116",
            "type": "corporate",
            "phones": [
                {
                    "countryCode": "+55",
                    "code": "19",
                    "number": "999666888"
                }
            ],
            "addresses": [
                {
                    "code": "88303430",
                    "street": "Rua Alfredo Contato",
                    "number": "340",
                    "neighborhood": "Orestes Ongaro",
                    "city": "Hortolândia",
                    "state": "SP",
                    "country": "BR"
                }
            ]
        }
    }
}
curl --location --request POST 'http://{{APÌ_BASEURL}}/boeltos/emission/beneficiary' \
--header 'Content-Type: application/json' \
--data-raw '{
    "user": {
        "firstName": "EMPRESA 38749049000114 LTDA",
        "lastName": "EMPRESA",
        "name": "EMPRESA 38749049000114 LTDA",
        "email": "[email protected]",
        "consumer": {
            "taxId": "38749049000116",
            "type": "corporate",
            "phones": [
                {
                    "countryCode": "+55",
                    "code": "19",
                    "number": "999666888"
                }
            ],
            "addresses": [
                {
                    "code": "88303430",
                    "street": "Rua Alfredo Contato",
                    "number": "340",
                    "neighborhood": "Orestes Ongaro",
                    "city": "Hortolândia",
                    "state": "SP",
                    "country": "BR"
                }
            ]
        }
    }
}'

Principais campos

campo

tipo

descrição

user.name

string (40 chars)

  • Nome concatenado do beneficiário

user.firstName

string (20 chars)

  • primerio nome

user.lastName

string (20 chars)

  • sobrenome ( se o beneficiário for Pessoa Jurídica, o nome da Razão Social pode ser dividido entre os campos firstName e lastName

user.email

string

  • E-mail do beneficiario
  • Tipo de e-mail

user.id.consumer.taxId

string

  • 11 caracteres se for beneficiário CPF
  • 14 caractres se for neneficiário CNPJ

user.id.consumer.type

enum ( personal | corporate )

  • Personal caso seja pessoa física
  • Corporate caso seja pessoa jurídica

user.id.createdAt

string (AAAA-MM-DD)

  • ISO 8601
  • Data de registro do beneficiário

user.id.updatedAt

string (AAAA-MM-DD)

  • ISO 8601
  • Data de registro do beneficiário

Body response

{
    "id": "58097204-409d-472a-aea3-2a778c08d2f9"
}
{
    "statusCode": 400,
    "message": [
        "user.name must be shorter than or equal to 40 characters",
        "user.name must be longer than or equal to 1 characters",
        "user.name should not be empty"
    ],
    "error": "Bad Request"
}

📘

Melhores Práticas

Na emissão de boleto, o nome do beneficiário é concatenado com "taxID + user.name" para ser exibido na impressão do boleto. Com isso, como melhor prática, sugere-se abreviar o nome do beneficiário até 20 caracteres. O limite de caracteres para exibição dos 2 campos concatenados é de 40 caracteres.


Did this page help you?