Investidores - Integração Básica

Descreve o fluxo básico para que um Investidor efetue a compra de uma operação na plataforma.

Suggest Edits

Entenda o Fluxo de Compra pelo Investidor

  1. Investidor realiza o Envio de Taxas para o(s) Sacado(s), via requisição para a API ou por upload de arquivo na plataforma.
  2. Quando um Cedente realiza uma operação (uma compra é realizada), a API envia um webhook com as informações do Sacado e Cedente, títulos negociados, valores e datas para o pagamento (para o Investidor que teve as melhores taxas para a operação).
  3. Investidor faz requisição para a API aprovando a compra. É possível também recusar a compra, total ou parcialmente, enviado um status de recusa para os títulos em questão.
  4. Cedente realiza a assinatura da operação de compra e a API envia um webhook informado o Investidor.
  5. Investidor faz requisição para a API realizando a assinatura da operação de compra.

Passo 1. Envio de Taxas

O primeiro passo a ser feito pelo Investidor é enviar suas taxas para a plataforma da Monkey, podendo ser feito por requisição para a API ou por upload de arquivo na plataforma.
O Investidor poderá definir o valor da taxa com base no prazo (em dias) e no grupo de risco dos cedentes, e também poderá definir um prazo de validade para cada taxa.

Envio de Taxas por Requisição na API

Ao realizar a requisição pela API o Investidor enviará as taxas para um Sacado específico.

Como a API funciona?

  • A API recebe até 1200 taxas, portanto na sua requisição você irá enviar um array com as taxas e o nosso sistema irá fazer o processamento em background.
  • O payload mínimo enviado deve conter:
    • days: Prazo (em dias) a que a taxa se refere
    • value: Valor da Taxa
    • validity: Prazo de Validade da Taxa

Veja os detalhes da API aqui.

Upload de Taxas por Arquivo na Plataforma

Ao enviar taxas via upload de arquivo na plataforma, o Investidor poderá enviar taxas para até 10 sacados.
Para enviar pela plataforma, o Investidor deve acessar seu perfil e clicar no menu Upload de Taxas:

1905

Basta agora realizar o upload de uma planilha com extensão xlsx. No modelo a seguir vemos uma planilha com taxas para 4 sacados diferentes:

1487

Faça o download da planilha de modelo clicando aqui.

Webhook de Arquivo de Taxas Processado

Após concluído o processamento das taxas, a plataforma da Monkey envia um retorno via Webhook para indicar a conclusão se foi bem sucedida ou caso tenha algum erro informar o motivo.

Como funciona esse Webhook?

  • O sistema da Monkey faz uma requisição HTTP para a URL configurada na plataforma.
  • O Path dessa requisição é /tax-file, portanto esperamos que seu sistema tenha esse endpoint exposto.
  • A requisição contém um campo success que indica o resultado do processamento.
  • A requisição contém um campo detail que será preenchido com o detalhamento do erro caso ocorram falhas no processamento. Veja o exemplo abaixo:
{
   "taxFileId":"hBslrLUoL1",
   "buyerId":123,
   "success":false,
   "detail":"Detalhe do erro de processamento",
   "_links":{
      "buyer":{
         "href":"https://zuul.monkeyecx.com/v2/buyers/123",
         "type":"GET"
      },
      "taxFile":{
         "href":"https://zuul.monkeyecx.com/v2/buyers/123/buyer-tax-file/hBslrLUoL1",
         "type":"GET"
      }
   }
}

Para mais informações sobre o Webhook clique aqui.

Passo 2. Webhook de Compra Realizada

Após uma operação ser realizada pelo Cedente, o Investidor (que teve as melhores taxa para a operação) receberá uma requisição via Webhook com as informações do Cedente e Sacado, títulos negociados, valores e datas para o pagamento.

Como funciona esse Webhook?

  • O sistema da Monkey faz uma requisição HTTP para a URL configurada na plataforma.
  • O Path dessa requisição /purchase, portanto esperamos que seu sistema tenha esse endpoint exposto.
  • A requisição contém uma array de items como no exemplo abaixo:
{
   "id":"VLbxGglIct",
   "status":"WAITING_CUSTODY",
   "tax":2.02,
   "days":288,
   "paymentDate":1550023200000,
   "grossPaymentValue":232199.89,
   "netPaymentValue":190804.21,
   "buyerId":78676,
   "buyerName":"INVESTIDOR",
   "buyerGovernmentId":"02638882000895",
   "sponsorId":4026534,
   "sponsorName":"SACADO",
   "sponsorPersonType":"LEGAL_PERSON",
   "sponsorGovernmentId":"02135252000189",
   "sponsorExternalCode":"100",
   "sponsorAddress":"ROD. SP 080 KM 75,1",
   "sponsorAddressNumber":"S/N",
   "sponsorAddressComplement":"",
   "sponsorNeighborhood":"CENTRO",
   "sponsorCity":"São Paulo",
   "sponsorState":"SP",
   "sponsorCountry":"Brasil",
   "sponsorZipCode":"26380000",
   "sponsorBank": "New Bank",
   "sponsorAgency":"1234",
   "sponsorAccount":"98765",
   "sponsorAccountDigit":"9",
   "sellerId":1614639272,
   "sellerName":"CEDENTE",
   "sellerPersonType":"LEGAL_PERSON",
   "sellerGovernmentId":"02890352000103",
   "sellerAddress":"Rua Monte Aprazável",
   "sellerAddressNumber":"109",
   "sellerAddressComplement":"",
   "sellerNeighborhood":"Centro",
   "sellerCity":"São Paulo",
   "sellerState":"SP",
   "sellerCountry":"Brasil",
   "sellerZipCode":"04512030",
   "sellerBank":"341",
   "sellerAgency":"9122",
   "sellerAgencyDigit":"0",
   "sellerAccount":"02603",
   "sellerAccountDigit":"1",
   "coobrigation":false,
   "createdAt":1553609535336,
   "items":[
      {
         "id":"SFgA83Edw4",
         "receivableUuid":"S8jTcn7GeW",
         "externalId":"CFIiMIxfFZ",
         "assetType":"DUPLICATA_MERCANTIL",
         "performed":true,
         "operationType":"PRE",
         "invoiceType":"NOTA_FISCAL_ELETRONICA",
         "invoiceDate":1574906400000,
         "invoiceNumber":"rn0iSyHbCf",
         "installment":1,
         "totalInstallment":1,
         "paymentValue":232199.89,
         "paymentDate":1574906400000,
         "status":"WAITING_CUSTODY",
         "tax":1.7999999523162842,
         "sellerPaymentValue":190804.21,
         "sponsorTax":0.2199999988079071,
         "sponsorPaymentValue":4847.36,
         "penaltyBill":0.0,
         "interestLatePayment":0.0
      }
   ],
   "_links":{
      "seller":{
         "href":"https://zuul.monkey.exchange/v2/buyers/78676/sellers/1614639272",
         "type":"GET"
      },
      "sponsor":{
         "href":"https://zuul.monkey.exchange/v2/buyers/78676/sponsors/4026534",
         "type":"GET"
      },
      "purchase":{
         "href":"https://zuul.monkey.exchange/v2/buyers/78676/purchases/VLbxGglIct",
         "type":"GET"
      },
      "purchases":{
         "href":"https://zuul.monkey.exchange/v2/buyers/78676/purchases",
         "type":"GET"
      },
      "signature":{
         "href":"https://zuul.monkey.exchange/v2/buyers/78676/signatures/VLbxGglIct",
         "type":"GET"
      }
   }
}

Para mais detalhes consulte a documentação de webhooks.

Passo 3. Aprovar Operação de Compra

O Investidor faz requisição para a API de Aprovação de Compra. É possível também recusar a compra, total ou parcialmente, enviado um status de recusa para os títulos em questão.

Como a API funciona?

  • A sua requisição deverá enviar um array com todos os itens (notas) referentes à compra e você enviará no atributo status quais você deseja aprovar ou recusar.
  • O payload mínimo deve conter:
    • id: Identificador do Item de Compra
    • installment: Parcela Referente ao Título
    • status: Aprovação ou Recusa

Passo 4. Webhook de Assinatura da Operação pelo Cedente

Após a aprovação da operação de compra pelo Cedente (Passo 3) é gerado um Termo de Cessão para que o Cedente assine.
Quando um Cedente assina ou reprova uma compra, o Investidor receberá uma requisição via Webhook com as informações de quem são os participantes da compra e o status para identificar se a assinatura foi realizada ou a compra foi reprovada.

Como funciona esse Webhook?

  • O sistema da Monkey faz uma requisição HTTP para a URL configurada na plataforma.
  • O Path dessa requisição /seller-signature, portanto esperamos que seu sistema tenha esse endpoint exposto.
  • A requisição contém uma array de signatures para os casos de múltiplas assinaturas, como no exemplo abaixo:
{
   "sponsorId":111111,
   "buyerId":78676,
   "sellerId":1611954924,
   "purchaseId":"GUXbVzi0Tn",
   "status":"APPROVED",
   "signatures":[  
      {  
         "name":"José Carlos",
         "email":"[email protected]",
         "governmentId":"05319135679",
         "status":"APPROVED"
      },
      {  
         "name":"João Pedro",
         "email":"[email protected]",
         "governmentId":"99813646063",
         "status":"APPROVED"
      }
   ],	
   "_links": {
      "documents":{
         "href":"https://zuul.monkey.exchange/v2/buyers/78676/signatures/GUXbVzi0Tn/documents{?type}",
         "type":"GET",
         "templated":true
      },	 
      "purchase":{
         "href":"https://zuul.monkey.exchange/v2/buyers/78676/purchases/GUXbVzi0Tn",
         "type":"GET"
      },
      "signature":{
         "href":"https://zuul.monkey.exchange/v2/buyers/78676/signatures/GUXbVzi0Tn",
         "type":"GET"
      }
   }
}

Passo 5. Assinar Operação de Compra

O Investidor faz requisição para a API de Assinar Compra. A assinatura de compra representa a aprovação da mesma por parte do Investidor.

Como a API funciona?

  • A sua requisição não necessita de envio de informações no payload, será apenas um POST para realizar a aprovação.

Veja os detalhes da API aqui.

Updated over 2 years ago