Documentação

Investors - Basic Integration

Describes the basic process for an investor to transact on the platform.

Suggest Edits

Understanding the Purchase Flow for Investors

  1. Rate Submission: Investors send their rates to the Anchor(s) via API request or file upload on the platform.
  2. Webhook Notification: When a supplier makes a sale, the API sends a webhook with details of the Anchor and Supplier, invoices transacted, amounts and due dates to the investor with the best rates.
  3. Purchase Approval: Investors approve or reject the purchase via API. It is possible to reject the purchase, partially or in full, , by sending a rejection status for the respective invoices.
  4. Seller’s Signatures: The seller signs off on the transaction, and the API notifies the investor via webhook.
  5. Investor’s Signatures: The investor then signs off on the transaction via API.

Step 1: Rate Submission

The first step for the investor is to send their rates to the Monkey platform, which can be done via an API request or file upload on the platform.
The investor can set the rate value based on the term (in days) and the risk group of the sellers. A validity period can also be defined for each rate.

Rate Submission via API Request

When making an API request, the investor sends rates to a specific debtor.

How does the API work?

  • The API accepts up to 1200 rates per request. Therefore, you will send an array of rates, and our system will process them in the background.
  • Minimum payload:
    • days: Term (in days) of the reference rate
    • value: Rate value
    • validity: Rate validity period

View API details here.

Rate Upload via File on the Platform

When uploading rates via file on the platform, the investor can send rates for up to 10 anchors.
To upload on the platform, the investor should access their profile and click on the Upload Rates menu.

Now, simply upload a spreadsheet with the .xlsx extension. In the following example, we see a spreadsheet with rates for 4 different anchors:

Download the template spreadsheet by clicking here.

Processed Rate File Webhook

After processing the rates, the Monkey platform sends a return via webhook to indicate completion, whether it was successful or if there were any errors, along with the reason for any errors.

How does this Webhook work?

  • The Monkey system makes an HTTP request to the URL configured on the platform.
  • The path of this request is /tax-file, so we expect your system to have this endpoint exposed.
  • The request contains a success field indicating the result of the processing.
  • It also includes a detail field that provides error details if any processing failures occur. See the example below:
{
   "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"
      }
   }
}

For more information about the Webhook click here.

Step 2: Completed Purchase Webhook

After a transaction is completed by the supplier, the investor (who offered the best rates for the transaction) will receive a webhook request with details of the seller and anchor, transacted invoices, amounts, and payment dates.

How does this Webhook work?

  • The Monkey system makes an HTTP request to the URL configured on the platform.
  • The path for this request is /purchase, so we expect your system to have this endpoint exposed.
  • The request contains an array of items, as shown in the example below::
{
   "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"
      }
   }
}

For more details, consult the webhook documentation webhooks.

Step 3: Purchase Approval

The investor makes a request to the Purchase Approval API. It is also possible to reject the purchase, either partially or in full, by sending a rejection status for the respective invoices.

How does the API work?

  • Your request should send an array of all items (invoices) related to the purchase, and in the status attribute, specify which ones you want to approve or reject.
  • Minimum payload must include:
    • id: Identifier of the Purchase Item
    • installment: Installment related to the Invoice
    • status: Approval or Rejection

Step 4: Seller's Signatures

After the transaction is approved by the supplier (Step 3), a Credit Assignment Agreement is generated for the supplier to sign.
When a supplier signs or rejects a purchase, the investor will receive a Webhook request with details of the participants in the transaction and the status indicating whether the signature was completed or the transaction was rejected.

How does this Webhook work?

  • The Monkey system makes an HTTP request to the URL configured on the platform.
  • The path for this request is /seller-signature, so we expect your system to have this endpoint exposed.
  • The request contains an array of signatures for cases with multiple signatures, as shown in the example below:
{
   "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"
      }
   }
}

Step 5: Investor’s Signatures

The investor makes a request to the Sign Purchase API. Signing off on the purchase represents the investor's approval.

How does the API work?

  • Your request does not need to include any information in the payload; it will simply be a POST request to complete the approval.

For more details on the API, please visit the documentation here.

Updated 7 months ago