Split de Pagamentos - Antecipação de Recebíveis

Redirecionando para https://docs.cielo.com.br/split/docs/antecipacao-de-recebiveis ...

As documentações do Split de Pagamentos estão em um novo portal

Acesse o novo portal de desenvolvedores E-commerce docs.cielo.com.br/split/docs/antecipacao-de-recebiveis.

Atenção: O conteúdo desta página está sendo descontinuado e não receberá atualizações a partir de 14/08/2024. Visite a nova documentação em docs.cielo.br.

Antecipação de recebíveis

A API de Antecipação de Recebíveis do Split de Pagamentos é mais um canal para que o master solicite a antecipação de valores, proporcionando uma conexão segura e direta.

Quem pode solicitar a antecipação de recebíveis via API?

Qualquer usuário com perfil master pode solicitar antecipação dos recebíveis para si ou para os seus sellers.

Quais são os requisitos para que a antecipação seja aprovada?

O master ou seller precisa ter saldo livre disponível em agenda na data do pedido de antecipação.

Qual é o prazo para receber o valor da antecipação?

O prazo de liquidação é de até dois dias úteis a partir da data da solicitação da antecipação (D+2). É importante considerar que o horário de operação da mesa de antecipação de recebíveis é de segunda à sexta, das 8h às 16h30.

Como começar

O cliente master deverá solicitar a habilitação de uso da API de Antecipação de Recebíveis ao time de atendimento Braspag.

Ambientes

Sandbox

API	URL	DESCRIÇÃO
`Braspag OAUTH2 Server`	https://authsandbox.braspag.com.br/	Autenticação
`split-anticipation-api`	https://splitsandbox.braspag.com.br/anticipation-api	Simular, criar e consultar antecipação.

Produção

API	URL	DESCRIÇÃO
`Braspag OAUTH2 Server`	https://auth.braspag.com.br/	Autenticação
`split-anticipation-api`	https://split.braspag.com.br/anticipation-api	Simular, criar e consultar antecipação.

Autenticação

O Split de Pagamentos utiliza como segurança o protocolo OAUTH2, no qual é necessário primeiro obter um token de acesso por meio das suas credenciais, e posteriormente enviar o token de acesso à API de de Antecipação de Recebíveis.

Para obter um token de acesso:

Concatene o MerchantId e ClientSecret: MerchantId:ClientSecret;
Codifique o resultado da concatenação em Base64;
Realize uma requisição ao servidor de autorização.

SplitAuth

Requisição

x-www-form-urlencoded
--header "Authorization: Basic {base64}"  
--header "Content-Type: application/x-www-form-urlencoded"  
grant_type=client_credentials

Resposta

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbG.....WE1igNAQRuHAs",
    "token_type": "bearer",
    "expires_in": 1199
}

O MerchantId é o mesmo utilizado na integração com a API Cielo E-Commerce ou com a API do Pagador. O ClientSecret deve ser obtido junto ao Split.

Use o token retornado (access_token) em toda requisição à API de Antecipação de Recebíveis como uma chave de autorização. O token de acesso possui uma validade de 20 minutos e é necessário gerar um novo token toda vez que a validade expirar.

Simular antecipação

Simula o cadastro de antecipações para o master.

Requisição

Parâmetros no cabeçalho (header)

KEY	VALUE
`Content-Type`	application/json
`Authorization`	Bearer {`access_token`}

Parâmetros na rota (path)

PROPRIEDADE	TIPO	TAMANHO	OBRIGATÓRIO	DESCRIÇÃO
`MerchantId`	GUID	-	Sim	Identificador do master merchant.

Parâmetros no corpo (body)

{
    "Amount": 10,
    "SettlementDate": "2024-05-27",
    "RecipientDocumentNumber": "61817215000194",
    "RequesterEmail": "requester@company.com"
}

PROPRIEDADE	TIPO	TAMANHO	OBRIGATÓRIO	DESCRIÇÃO
`Amount`	long	-	Sim	Valor a antecipar.
`SettlementDate`	DateTime	-	Sim	Data de liquidação.
`RecipientDocumentNumber`	String	-	Sim	Número de documento do recebedor. Pode ser o documento do próprio master ou o documento do seller para o qual a antecipação está sendo solicitada.
`RequesterEmail`	string	-	Sim	E-mail do master.

Resposta

{
    "Id": "2106498e-5569-4c39-a778-8e3aafd740b3",
    "Amount": 10,
    "AmountToAnticipate": 35619733,
    "AnticipationNetAmount": "271928",
    "PrecificationDate": "2024-05-28",
    "SettlementDate": "2024-05-31",
    "Status": "EmProcessamento",
    "Details": {
       "SubAcquirerAnticipationRate": "23145",
       "MasterAnticipationRate": "12312",
     },
    "LegalEntity": {
        "RecipientDocumentNumber": "93719314000120",
        "RecipientCorporateName": "alexsander alterado",
        "RecipientFancyName": "alexsander alterado"
    },
    "BankAccount": {
        "AccountNumber": "1234",
        "AccountDigit": "1",
        "AgencyNumber": "1234",
        "AgencyDigit": "1",
        "DocumentNumber": "93719314000120",
        "DocumentType": "Cnpj",
        "BankAccountType": "CheckingAccount",
        "CompeCode": "002"
    },
    "Links": [
        {
            "Href": "https://splitblobstr.blob.core.windows.net/anticipation-precification-sandbox/20240531/alexsander%20alterado%20(93719314000120)%20-%2020240531%20-%20v7.xlsx?sv=2018-03-28&sr=b&sig=fRVy6pA2vpK9Ln4Y2TVkrs2SGRXi7SytbPSAC6cHjJ0%3D&st=2024-05-28T18%3A34%3A46Z&se=2024-05-28T23%3A59%3A59Z&sp=r"
        }
    ],
}

PROPRIEDADE	TIPO	DESCRIÇÃO
`Id`	GUID	Identificador da antecipação.
`Amount`	long	Valor de antecipação solicitado.
`AmountToAnticipate`	long	Valor bruto alcançado para antecipação.
`AnticipateNetAmount`	long	Valor líquido a receber.
`PrecificationDate`	string	Data de precificação.
`SettlementDate`	string	Data de liquidação.
`AverageTerm`	long	Prazo médio em dias.
`SubAcquirerAnticipationRate`	long	Taxa do subadquirente.
`MasterAnticipationRate`	long	Taxa de comissão do master.
`Status`	string	Situação da antecipação.
`RecipientDocumentNumber`	string	Número de documento da pessoa física/jurídica recebedora. Pode ser o documento do próprio master ou o documento do seller para o qual a antecipação está sendo solicitada.
`RecipientCoporateName`	string	Nome da corporação da pessoa física/jurídica.
`RecipientFancyName`	string	Nome comum da pessoa física/jurídica.
`AccountNumber`	string	Número da conta.
`AccountDigit`	char	Dígito da conta.
`AgencyNumber`	string	Número da agência.
`AgencyDigit`	char	Dígito da agência.
`DocumentNumber`	string	Número de documento da conta.
`DocumentType`	string	Tipo de documento.
`BankAccountType`	string	Tipo de conta bancária.
`CompeCode`	string	Código de compensação do banco. Lista de código de compensação
`Href`	string	link de download de planilha dos recebíveis antecipados.

Criar antecipação de recebíveis

Solicita a antecipação de recebíveis para o master.

Requisição

Parâmetros no cabeçalho (header)

KEY	VALUE
`Content-Type`	application/json
`Authorization`	Bearer {`access_token`}

Parâmetros na rota (path)

PROPRIEDADE	TIPO	TAMANHO	OBRIGATÓRIO	DESCRIÇÃO
`MerchantId`	GUID	-	Sim	Identificador do master merchant.

Parâmetros no corpo (body)

{
    "Amount": 10,
    "SettlementDate": "2024-05-27",
    "RecipientDocumentNumber": "61817215000194",
    "RequesterEmail": "requester@company.com"
}

PROPRIEDADE	TIPO	TAMANHO	OBRIGATÓRIO	DESCRIÇÃO
`Amount`	long	-	Sim	Valor a antecipar.
`SettlementDate`	DateTime	-	Sim	Data de liquidação.
`RecipientDocumentNumber`	String	-	Sim	Número de documento do recebedor. Pode ser o documento do próprio master ou o documento do seller para o qual a antecipação está sendo solicitada.
`RequesterEmail`	String	-	Sim	E-mail do master.

Resposta

{
    "Id": "2106498e-5569-4c39-a778-8e3aafd740b3",
    "Amount": 10,
    "AmountToAnticipate": 35619733,
    "AnticipationNetAmount": "271928",
    "PrecificationDate": "2024-05-28",
    "SettlementDate": "2024-05-31",
    "Status": "EmProcessamento",
    "Details": {
       "SubAcquirerAnticipationRate": "23145",
       "MasterAnticipationRate": "12312",
     },
    "LegalEntity": {
        "RecipientDocumentNumber": "93719314000120",
        "RecipientCorporateName": "alexsander alterado",
        "RecipientFancyName": "alexsander alterado"
    },
    "BankAccount": {
        "AccountNumber": "1234",
        "AccountDigit": "1",
        "AgencyNumber": "1234",
        "AgencyDigit": "1",
        "DocumentNumber": "93719314000120",
        "DocumentType": "Cnpj",
        "BankAccountType": "CheckingAccount",
        "CompeCode": "002"
    },
    "Links": [
        {
            "Href": "https://splitblobstr.blob.core.windows.net/anticipation-precification-sandbox/20240531/alexsander%20alterado%20(93719314000120)%20-%2020240531%20-%20v7.xlsx?sv=2018-03-28&sr=b&sig=fRVy6pA2vpK9Ln4Y2TVkrs2SGRXi7SytbPSAC6cHjJ0%3D&st=2024-05-28T18%3A34%3A46Z&se=2024-05-28T23%3A59%3A59Z&sp=r"
        }
    ],
}

PROPRIEDADE	TIPO	DESCRIÇÃO
`Id`	GUID	Identificador da antecipação.
`Amount`	long	Valor de antecipação solicitado.
`AmountToAnticipate`	long	Valor bruto alcançado para antecipação.
`AnticipateNetAmount`	long	Valor líquido a receber.
`PrecificationDate`	string	Data de precificação.
`SettlementDate`	string	Data de liquidação.
`AverageTerm`	long	Prazo médio em dias.
`SubAcquirerAnticipationRate`	long	Taxa do subadquirente.
`MasterAnticipationRate`	long	Taxa de comissão do master.
`Status`	string	Situação da antecipação.
`RecipientDocumentNumber`	string	Número de documento da pessoa física/jurídica recebedora. Pode ser o documento do próprio master ou o documento do seller para o qual a antecipação está sendo solicitada.
`RecipientCorporateName`	string	Nome da corporação da pessoa física/jurídica.
`RecipientFancyName`	string	Nome comum da pessoa física/jurídica.
`AccountNumber`	string	Número da conta.
`AccountDigit`	char	Dígito da conta.
`AgencyNumber`	string	Número da agência.
`AgencyDigit`	char	Dígito da agência.
`DocumentNumber`	string	Número de documento da conta.
`DocumentType`	string	Tipo de documento.
`BankAccountType`	string	Tipo de conta bancária.
`CompeCode`	string	Código de compensação do banco. Lista de código de compensação
`Href`	string	Link de download de planilha dos recebíveis antecipados.

Consultar antecipação

Consulta uma antecipação pelo identificador da antecipação e do merchant.

Requisição

Parâmetros no cabeçalho (header)

KEY	VALUE
`Content-Type`	application/json
`Authorization`	Bearer {`access_token`}

Parâmetros na rota (path)

PROPRIEDADE	TIPO	TAMANHO	OBRIGATÓRIO	DESCRIÇÃO
`MerchantId`	GUID	-	Sim	Código do master merchant
`AnticipationId`	GUID	-	Sim	Identificador da antecipação.

Resposta

{
    "Id": "4d1f9698-a9bb-44f6-be03-6e0d258df2b8",
    "Amount": 10,
    "AmountToAnticipate": 35288571,
    "AnticipationNetAmount": 271928,
    "PrecificationDate": "2024-05-28",
    "TargetDate": "2024-06-03",
    "LastReceivableDate": "2025-05-15",
    "CreatedAt": "2024-06-03T14:56:19.85",
    "AverageTerm": 67,
    "Status": "Canceled",
    "Recipient":{
        "DocumentNumber": "12345678912345",
        "FancyName": "Fancy Name",
        "CorporateName": "CorporateName"
    },
    "RateDetails": { 
        "SubAcquirerAnticipationRate": 0.35,
        "MasterAnticipationRate": 0.00
    },
    "BankAccount": {
        "BankId": 2,
        "BankName": "Banco Simulado",
        "AccountNumber": "1234",
        "AccountDigit": "1",
        "AgencyNumber": "1234",
        "AgencyDigit": "1",
        "DocumentNumber": "12345678912345",
        "DocumentType": "Cnpj",
        "BankAccountType": "CheckingAccount"
    }
}

PROPRIEDADE	TIPO	TAMANHO	DESCRIÇÃO
`Id`	GUID	-	Identificador da Antecipação
`Amount`	Long	-	Valor requerido da antecipação
`AmountToAnticipate`	Long	-	Valor que será antecipado
`PrecificationDate`	Date	-	Data de quando foi feito a precificação da antecipação, não necessariamente a data que será antecipado.
`TargetDate`	Date	-	Data da antecipação
`LastReceivableDate`	Date	-	Data do ultimo recebível
`CreatedAt`	Date	-	Data da criação da antecipação
`AverageTerm`	Int	-	Valor médio em dias do pagamento da antecipação
`Status`	String	-	Status indicado da antecipação (“Undefined”, “Processing”, “Processed”, “Canceled”, “Settled”)
`Recipient`	Object	-	Objeto com os detalhes do recebedor
`Recipient.DocumentNumber`	String	-	Número de documento do recebedor. Pode ser o documento do próprio master ou o documento do seller para o qual a antecipação está sendo solicitada.
`Recipient.FancyName`	String	-	Nome comum da pessoa física/jurídica.
`Recipient.CorporateName`	String	-	Nome da corporação da pessoa física/jurídica.
`RateDetails`	Object	-	Objeto com os valores das porcentagens da antecipação
`SubAcquirerAnticipationRate`	Long	-	Taxa do Sub adquirente
`MasterAnticipationRate`	Long	-	Taxa do master
`BankAccount`	Object	-	Objeto com as informações da conta bancária
`BankId`	Long	-	Identificador do Banco
`BankName`	String	-	Valor da taxa de exceção atual
`AccountNumber`	String	-	Número da conta
`AccountDigit`	Char	-	Dígito da conta
`AgencyNumber`	String	-	Número da agência
`DocumentNumber`	String	-	Número de documento da conta
`DocumentType`	Decimal	-	Tipo de documento
`BankAccountType`	string	-	Tipo de conta bancária

Validações e retornos possíveis

Caso o MerchantId informado na rota não seja do cliente logado e o usuário seja do tipo master, o retorno será:

Status Code = 400

Mensagem: Not possible to consult an anticipation for {merchantId} master merchant id.
Caso a antecipação informada não faça parte do merchant informado, o retorno será:

Status Code = 400

Mensagem: User hasn’t permission for this anticipation or anticipation doesn’t exist
Caso a antecipação informada não seja encontrada, o retorno será:

Status Code = 404

Notificação da antecipação

A configuração da URL de notificação é opcional.

Para receber a notificação o tipo POST é necessário configurar a URL de Notificação durante o cadastro do master na Braspag. O endereço deve ser HTTPS e não se deve utilizar uma porta fora do padrão HTTPS (443).

Quando houver alteração no status da antecipação, o Split enviará uma notificação com os parâmetros do identificador da antecipação (AnticipationId) e o novo Status.

Exemplo de notificação de mudança de Status:

{
    "AnticipationId" : "96ffb8be-6693-4f9b-bf8e-925b555b3207",
    "Status" : 2
}

PROPRIEDADE	TIPO	TAMANHO	DESCRIÇÃO
`AnticipationId`	GUID	-	Identificador da antecipação.
`Status`	int ou string	Descrição Enum Status ou Id do Enum de Status	Identificador do Status. Valores possíveis: Undefined = 0 Processing = 1 Processed = 2 Canceled = 3 Settled = 4