Antecipação de Recebíveis

A solução de antecipação de recebíveis do BaaS, permite antecipar os valores das cobranças realizadas via cartão de crédito antes do prazo acordado inicialmente. Abaixo iremos explicar como se integrar com esse módulo do BaaS.

❗️
A antecipação de recebíveis é liberada mediante aprovação da Celcoin por políticas próprias e não está disponível para todos os clientes.
Consulte um especialista para melhor entendimento sobre o funcionamento.

Caso de uso:

Como Fintech quero antecipar meu recebível de cartão de crédito para melhorar meu fluxo de caixa.

Nesse artigo você irá aprender sobre:

Simular Antecipação de Recebíveis
Antecipar recebíveis
Listar simulações de antecipação

Pré requisitos para implementação:

Possuir uma chave api da Celcoin, para mais informações acessar esse link
Ter familiaridade com apis Rest usando o protocolo OAuth 2.0.
Ter o produto/solução de sub Celcoin contratado, 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.

Regras de Negócio:

Regra	Funcionamento
Janela de Operação	As solicitações de simulação e antecipação devem ser realizadas das 07h às 14h. Requisições fora desta janela serão rejeitadas.
Validade da Simulação	Todas as simulações geradas possuem validade diária limite e expiram impreterivelmente às 14h do mesmo dia.
Simulações Simultâneas	É permitida apenas uma simulação com status Ativa por vez para cada conta. A criação de uma nova simulação cancelará automaticamente a anterior.
Carência de Recebíveis	Somente são elegíveis recebíveis cujas datas de pagamento sejam superiores a 5 dias corridos a partir da data da solicitação.
Critério de Seleção	Caso o montante disponível ultrapasse o valor solicitado, o sistema selecionará a combinação de recebíveis mais próximos do vencimento (respeitando a carência de 5 dias) cujo valor total consolidado seja menor ou igual ao solicitado.

Simular Antecipação de Recebíveis

Para simular uma antecipação de recebível e conhecer as taxas a serem aplicadas é necessário realizar uma chamada na api Simular Antecipação de Recebíves utilizando o método POST, onde precisa ser preenchido algumas informações relacionadas as transações e bandeiras que serão antecipadas. Os dados necessários estão no quadro "Parâmetros do Body"

Modelo de requisição:

curl --request POST \
  --url https://api.celcoin.com.br/v1/antecipation/simulate \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {{token}}' \
  --header 'content-type: application/json' \
  --data '
{
  "value": 1000.00,
  "transactiongalaxypayId": "gpay_774910235"
}
'

Parâmetros do Body:

Campo	Descrição	Tipo	Obrigatório
value	Valor total que se deseja simular para a antecipação.	number (float)	Condicional
transactionGalaxPayIds	Transações desejadas para antecipar.	Array Int (32)	Condicional
brands	Bandeira do cartão. Informe apenas bandeiras e separe cada um por vírgula. Valores possíveis do campo: - discover mastercard elo hipercard amex visa*	Array de String	Não

Modelo de retorno:

Sucesso(200):

{
  "type": true,
  "antecipation": {
    "antecipationId": 34,
    "companyId": 16085,
    "transactionIds": "761,760,764",
    "totalValue": 1912.99,
    "totalMdr": 62.33,
    "averageDays": 16,
    "totalAntecipateTax": 30.95,
    "netValue": 1819.71,
    "cet": 93.28,
    "uuid": "d9c66552-03aa-41c5-a443-cfedd8212847",
    "done": "F",
    "createdAt": "2023-12-15T13:21:24Z",
    "updatedAt": "2023-12-15T13:21:24Z"
  },
  "releases": [
    {
      "releaseId": 68884668,
      "transactionId": 761,
      "createdAt": "2023-11-29T07:31:03Z",
      "installment": 1,
      "netValue": 402.2,
      "grossValue": 415.99,
      "expectedDate": "2023-12-31",
      "daysAntecipation": 16,
      "taxValueAntecipation": 6.41,
      "netValueAfterAntecipation": 395.79,
      "brand": "visa"
    }
  ],
  "operationSummary": {
    "grossTotal": 1912.99,
    "mdr": 1850.66,
    "mdrTax": 62.33,
    "averageDays": 16,
    "finalTax": 30.95,
    "cet": 93.28,
    "netValue": 1819.71
  },
  "brands": {
    "visa": 5,
    "mastercard": 2,
    "elo": 1
  }
}

Campos do response:

Campo	Descrição	Tipo
type	Retorna se simulação foi realizada com sucesso. Valores possíveis: True ou False	Bool
antecipation.galaxPayId	Identificador da Antecipação	Int (32)
antecipation.companyGalaxPayId	identificador da Empresa	Int (32)
antecipation.transactionsGalaxPayIds	Transações a serem antecipadas	String (255)
antecipation.totalValue	Valor total das transações	Int (32)
antecipation.totalMdr	Valor total das taxas	Int (32)
antecipation.averageDays	Média em dias das datas das transações que serão liquidadas.	Int (32)
antecipation.totalAntecipateTax	Valor total da taxa de antecipação.	Int (32)
antecipation.netValue	Valor líquido das transações.	Int (32)
antecipation.cet	Custo Efetivo Total. A soma de todas as taxas juntas.	Int (32)
antecipation.uuid	Identificador gerado aleatoriamente para realizar a antecipação.	String (255)
antecipation.done	Campo para verificar se esta antecipação já foi realizada.	String (255)
antecipation.createdAt	Data de criação da antecipação.	date
antecipation.updatedAt	Data de atualização da antecipação.	date
realeases.galaxPayId	Identificador do recebível	Int (32)
realeases.transactionGalaxPayId	Identificador da transação	int (32)
realeases.createdAt	Data de criação do recebível.	int (32)
realeases.installment	Número da parcela.	int (32)
realeases.netValue	Valor líquido do recebível.	int (32)
realeases.grossValue	Valor bruto do recebível.	int (32)
realeases.expectedDate	Data esperada de liquidação.	date
realeases.daysAntecipation	Dias até a liquidação.	int (32)
realeases.netValueAfterAntecipation	Valor líquido após a antecipação.	int (32)
realeases.taxValueAntecipation	Valor da taxa de antecipação.	int (32)
OperationSummary.grossTotal	Valor total das transações sem taxas.	int (32)
OperationSummary.mdr	Valor das transações - taxas	int (32)
OperationSummary.mdrTax	Valor das taxas.	int (32)
OperationSummary.averageDays	Média em dias das transações que serão antecipadas.	int (32)
OperationSummary.finalTax	Valor da taxa de antecipação.	int (32)
OperationSummary.cet	Custo Efetivo Total. A soma de todas as taxas juntas.	int (32)
OperationSummary.netValue	Valor das transações - Cet	int (32)

Erro 1: Fora da janela permitida (Após às 14h)

{
  "error": "Bad Request",
  "message": "A simulação está sendo feita fora da janela. Janela 07h ás 14h."
}

Erro 2: Recebíveis com menos de 5 dias corridos (Transação inteira inválida)

{
  "error": "Bad Request",
  "message": "Escolha transações com recebíveis com mais de 5 dias."
}

Erro 3: Uma ou mais transações inválidas no lote (Validação parcial)

{
  "error": "Bad Request",
  "message": "uma das transações informadas possui recebíveis com menos de 5 dias."
}

Efetivar a Antecipação dos Recebíveis

Após a simulação de antecipação de recebíveis, caso concorde com os termos apresentados, é possível concluir a antecipação. Para isso, é necessário realizar uma chamada na api Efetivar a Antecipação de Recebíveis utilizando o método POST, onde precisa ser enviado na requisição o identificador da simulação realizada na etapa anterior.

Modelo de request:

curl --request POST \
  --url https://api.celcoin.com.br/v1/antecipation \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {{token}}' \
  --header 'content-type: application/json' \
  --data '
{
  "simulationId": "sim_987654321"
}
'

Listar Simulações de Antecipação Realizadas

Caso necessite validar o status das simulações realizadas, você deve realizar uma chamada na API Listar Simulações de Antecipação utilizando o método GET

Modelo de requisição:

curl --location --request GET 'https://sandbox.openfinance.celcoin.dev/baas/v1/cash/antecipation/simulate/get-by-filters' \

Parâmetros do Body:

Campo	Descrição	Tipo
limit	Quantidade de dados retornados	int
startAt	A partir de que posição da query irá pegar os dados	int
done	Campo para verificar se esta antecipação já foi realizada.	string
page	página atual da paginação	int
createdAtFrom	Data de criação inicial	date
createdAtTo	Até que data foi criada a simulação	date

📘
Note que todos os dados podem ser filtrados

📘
Você pode filtrar todos os dados ou somente o campo que desejar.

Modelo de retorno:

{
    "totalQtdFoundInPage": 1,
    "Antecipation": [
        {
            "galaxPayId": 1,
            "companyGalaxPayId": 16966,
            "transactionsGalaxPayIds": "761,760,764",
            "totalValue": 1912,
            "totalMdr": 62,
            "averageDays": 16,
            "totalAntecipateTax": 30,
            "netValue": 1819,
            "cet": 93,
            "uuid": "d9c66552-03aa-41c5-a443-cfedd8212847",
            "done": "F",
            "createdAtTo": "2025-04-07",
            "createdAtFrom": "2025-04-07"
        }
    ]
}

Campos do response:

Campo	Descrição	Tipo
totalQtdFoundInPage	Quantidade total de registros do retorno da busca na página atual.	int (11)
antecipation.galaxPayId	Identificador da antecipação	int (11)
antecipation.companyGalaxPayId	Identificador da empresa	string
antecipation.transactionsGalaxPayIds	Transações a serem antecipadas.	int
antecipation.totalValue	Valor total das transações.	int
antecipation.totalMdr	Valor total das taxas.	int
antecipation.averageDays	Média em dias das transações que serão antecipadas.	int (32)
antecipation.totalAntecipateTax	Valor total da taxa de antecipação.	int
antecipation.netValue	Valor das transações - Cet	int
antecipation.cet	Custo Efetivo Total. A soma de todas as taxas juntas.	int
antecipation.uuid	Id gerado aleatoriamente para realizar a antecipação.	sting
antecipation.done	Campo para verificar se esta antecipação já foi realizada.	string (1)
antecipation.createdAtTo	Até que data foi criada a simulação	date
antecipation.createdAtFrom	Data de criação inicial	date

Updated about 1 hour ago