Gestão de Beneficiários

Essa funcionalidade permite que os clientes da Celcoin consigam criar beneficiários, de forma que, possam declará-los como Beneficiários Originais ou Finais no momento da emissão do boleto.

Pré requisitos para implementação:

Possuir uma chave api da Celcoin, para mais informações acessar esse link
Ter familiaridade com o padrão REST usando o protocolo OAuth 2.0.
Ter o produto/solução contratado e habilitado em produção.
- Caso queira usar a funcionalidade em ambiente produtivo, por favor entre em contato com a nossa equipe comercial através do e-mail [email protected]. Para dúvidas técnicas, basta entrar em contato com o suporte através do link.

Passos para Integrar

Realizar autenticação na API - [API Reference]
Criar um Beneficiário - [API Reference]

Caso seja necessário você pode consultar um beneficiário cadastrado.

Consultar Cobrança - [API Reference]

cURL da chamada

curl --request POST \
     --url https://sandbox.openfinance.celcoin.dev/billissuance/v1/beneficiary \
     --header 'accept: application/json' \
     --header 'content-type: application/*+json' \
     --data '
{
  "documentType": "CPF",
  "document": "56440863053",
  "name": "Nome ou Razão Social do Beneficiário"
}
'

Descrição dos campos

Campo	Descrição	Tipo Campo
name	Nome ou Razão Social do beneficiário	string
documentType	Tipo de documento. Valores aceitos: CPF ou CNPJ	string
document	CPF ou CNPJ do beneficiário	string

Exemplo de retorno

👍
Sucesso 201

{
  "id": "662699d67b3a39e56b592db0",
  "documentType": "CPF",
  "document": "56440863053",
  "name": "Nome ou Razão Social do beneficiário",
  "status": "APTO",
  "created": "2025-10-16T13:29:49.630Z",
  "updated": "2025-10-16T13:29:49.630Z"
}

Descrição dos campos

Campo	Descrição	Tipo Campo
id	Identificador único do Beneficiário	string
documentType	Tipo de documento. Valores aceitos: CPF ou CNPJ	string
document	CPF ou CNPJ do beneficiário	string
name	Nome ou Razão Social do beneficiário	string
status	Situação do beneficiário. Valores retornado: APTO, EM_ANALISE, INAPTO, SEM_CADASTRO, PROCESSAMENTO, REJEITADO	string
created	Data de inclusão	date-time
updated	Data de alteração	date-time

❗
Error 400

{
  "code": "string",
  "statusCode": 0,
  "message": "string",
  "details": [
    {
      "field": "string",
      "description": [
        "string"
      ]
    }
  ]
}

Para validar os cenários de erro dessa API, acesse a tabela de erros.