Âncoras - Integração Básica

Entenda o Fluxo de Subida

1 - Sacado faz a requisição com os títulos que irão subir para a plataforma.
2 - A API recebe a requisição e retorna o status code 202 Accepted e os títulos são enfileirados para serem processados.
3 - Os títulos enfileirados são processados e é aplicada a validação de duplicidade.
4 - Os títulos não duplicados são disponibilizados na plataforma.
5 - Os títulos duplicados são devolvidos via webhook para o Sacado.

Upload de Notas

O primeiro passo a ser feito é enviar suas notas para a plataforma da Monkey, para isso voce deverá realizar uma requisição para a API de Upload de Títulos.

Como a API funciona?

• A API recebe pacotes de 150 notas por vez, portanto na sua requisição você irá enviar um array com as notas e o nosso sistema irá fazer o processamento em background.
• O payload mínimo enviado deve conter:
  • invoiceNumber: Número da Fatura
  • paymentDate: Data de Pagamento
  • paymentValue: Valor de Pagamento
  • supplierGovernmentId: CPF/CNPJ do Fornecedor
• As validações realizadas são:
  • Notas com Valor de Pagamento menor do que R$ 5,00 não sobem.
  • A duplicidade é validada pela chave composta: invoiceNumber, paymentDate, supplierGovernmentId.
  • Caso o campo installment (Parcela) seja enviado, ele também será utilizado para validação de duplicidade.
• Em caso de duplicidade o Sacado será avisado via Webhook.

Webhook de Notas Duplicadas

As notas enviadas que não passaram pelo processo de validação de duplicidade são agrupadas e devolvidas para o Sacado via Webhook, no payload será enviada uma lista com as notas duplicadas de cada uma das requisições.

Como Funciona esse Webhook?

• O sistema da Monkey faz uma requisição HTTP para a URL configurada na plataforma.
• O Path dessa requisição é /payables, portanto esperamos que seu sistema tenha esse endpoint exposto.
• A requisição contém uma array de items como no exemplo abaixo:

{
   "sponsorId":8548754,
   "processId":"haq2gJdZpk",
   "items":[
      {
         "uuid":"BEiMDdBo64",
         "externalId":"vzAsW2cx2O",
         "paymentDate":1605887005033,
         "realPaymentDate":1605887005033,
         "paymentValue":5000,
         "supplierGovernmentId":"12212391010112",
         "supplierName":"SELLER LTDA",
         "invoiceNumber":"vzAsW2cx2O",
         "invoiceKey":null,
         "installment":1,
         "totalInstallment":1
      }
   ],
   "eventType":"PayableDuplicatedEvent",
   "_links":{
      "sponsor":{
         "href":"https://zuul.monkey.exchange/v2/sponsors/40566534",
         "type":"GET"
      }
   }
}

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

Webhook de Notas Negociadas

Quando uma negociação é realizada na plataforma o nosso sistema avisa o Sacado também via Webhook.
Para a plataforma da Monkey uma operação sempre irá conter um Sacado, um Fornecedor, um Investidor e uma ou mais notas. Portanto esteja preparado para receber uma lista de notas no webhook de notas negociadas.

Como Funciona esse Webhook?

• O sistema da Monkey faz uma requisição HTTP para a URL configurada na plataforma.
• O Path dessa requisição é /payables-response, portanto esperamos que seu sistema tenha esse endpoint exposto.
• A requisição contém uma array de items e também as informações do investidor que venceu o leilão para essa operaçao. Veja o exemplo abaixo:

{
  "purchaseId": "parniqQ70k",
  "sponsorId": 4026534,
  "sponsorName": "SACADO S.A",
  "sponsorGovernmentId": "13677912100135",
  "sellerId": 1614639279,
  "sellerName": "CEDENTE S.A",
  "sellerGovernmentId": "35060339000286",
  "buyerId": 540897447,
  "buyerName": "INVESTIDOR S.A.",
  "buyerGovernmentId": "01331122000222",
  "buyerReceivementBank": "341",
  "buyerReceivementAgency": "1234",
  "buyerReceivementAccount": "1234",
  "buyerReceivementAccountDigit": "1",
  "items": [
    {
      "payableUuid": "P7FQZxtGJD",
      "status": "SOLD", [*]
      "detail": "",
      "externalId": "GwQMrDKM0R",
      "invoiceNumber": "soroKFUWbs",
      "installment": 1, [**]
      "totalInstallment": 1, [**]
      "paymentDate": 1585450800000,
      "tax": 1.8,
      "sponsorTax": 0,
      "paymentValue": 99.93,
      "sellerPaymentValue": 98.87,
      "sponsorPaymentValue": 0,
      "_links": {
        "payable": {
          "href": "https://zuul.monkeyecx.com/v2/sponsors/4026534/payables/P7FQZxtGJD",
          "type": "GET"
        }
      }
    },
    {
      "payableUuid": "5xHO6IkIyz",
      "status": "REFUSED", [*]
      "detail": "",
      "externalId": "qTDXKkLZ7b",
      "invoiceNumber": "5Pfb1BEazX",
      "installment": 1, [**]
      "totalInstallment": 1, [**]
      "paymentDate": 1585450800000,
      "tax": 1.8,
      "sponsorTax": 0,
      "paymentValue": 99.93,
      "sellerPaymentValue": 98.87,
      "sponsorPaymentValue": 0,
      "_links": {
        "payable": {
          "href": "https://zuul.monkeyecx.com/v2/sponsors/4026534/payables/5xHO6IkIyz",
          "type": "GET"
        }
      }
    }
  ],
  "_links": {
    "sponsor": {
      "href": "https://zuul.monkeyecx.com/v1/sponsors/4026534",
      "type": "GET"
    },
    "payables": {
      "href": "https://zuul.monkeyecx.com/v2/sponsors/4026534/payables",
      "type": "GET"
    }
  }
}

No Payload acima temos as informações sobre qual investidor (buyer) realizou a antecipação (Razão Social, CNPJ, Dados Bancários).

Esse Payload também contém os IDs (externalId e InvoiceNumber) que são utilizados para que você identifique o título em seu sistema.