About the APIs

Environments

Testing

• Brazil: https://hmg-zuul.monkeyecx.com

• Chile: https://zuul.hmg.monkeyexchange.cl

Production

• Brazil: https://zuul.monkey.exchange

• Chile: https://zuul.monkeyexchange.cl

Technologies and Standards

REST

An architectural style based on HTTP constraints and properties, facilitating interoperability between systems.

Web Services que obedecem ao estilo arquitetural REST, ou Web Services RESTful, fornecem interoperabilidade entre sistemas. More information.

JSON

A lightweight data exchange format widely used. More information.

UTF-8

A communication character standard for distributed systems.More information.

ISO-8601

A standard for sending and receiving date/time fields, using
the Time Zone.

"Standard": "YYYY-MM-DDThh:mm:ss.sTZD"
"Example": "2019-01-22T13:37:00.000-03:00" 

More information.

HTTP Methods

Our APIs follow the RESTful standard and use the HTTP verb corresponding
to each operation.

Success Codes

Client Error Codes

Server Error Codes

Standard Error Response

{ 
  "type":"Business_Logic_Error", "description":"Business logic error.",
  "notifications":[ "Erro 1'", "Erro x'" ]           
}

Pagination

When listing a resource, you should use the pagination parameters page and size.

Here is an example of a request:

GET https://zuul.monkey.exchange/v2/sponsors/123/payables?page=0&size=20

If no values are provided, the default will be 0 for the page parameter and 20 for the size parameter.

Sorting

Listing APIs support sorting through the sort parameter. You can use more than one sorting criterion in the same request.

Here is an example of a request:

GET https://zuul.monkey.exchange/v2/sponsors/123/payables?page=0&size=20&sort=updatedAt,desc&sort=status,asc

Filters

The listing APIs have a filtering mechanism done through the search parameter, allowing combinations using AND or OR.

Example request:

GET https://zuul.monkey.exchange/v2/sponsors/123/payables?search=supplierGovernmentId:24212752000184 AND supplierName:*Fornecedor* AND paymentDate>2020-04-23 AND (externalId:123 OR invoiceNumber:123)

Use the fields returned in JSON to build your filter. Search options:

: - Equality search. E.g., supplierName:Fornecedor.

> - Greater than or equal. E.g., paymentValue>200

< - Less than or equal. E.g., paymentValue<200

* -Contains, e.g. (supplierName:Forne*), starts with, e.g., (supplierName:*cedor) or ends with, e.g.,(supplierName:*orne*).

Hypermedia (HATEOAS)

HATEOAS (Hypermedia as the Engine of Application State) allows applications integrating with the API to interact through links.

By accessing a resource, you can use links to discover related resources and available actions.

Using HATEOAS enables dynamic availability of new interactions, allowing consuming applications to become aware of new interaction options without being impacted.

Here is an example of links::

"_links":{
   "self":{
      "href":"https://zuul.monkey.exchange/v2/buyers/123/signatures/0zkvnbfZsE",
      "type":"GET"
   },
   "documents":{
      "href":"https://zuul.monkey.exchange/v2/buyers/123/signatures/0zkvnbfZsE/documents{?type}",
      "type":"GET",
      "templated":true
   },
   "approve":{
      "href":"https://zuul.monkey.exchange/v2/buyers/123/signatures/0zkvnbfZsE/approve",
      "type":"POST"
   },
   "unapprove":{
      "href":"https://zuul.monkey.exchange/v2/buyers/123/signatures/0zkvnbfZsE/unapprove",
      "type":"POST"
   },
   "buyer":{
      "href":"https://zuul.monkey.exchange/v2/buyers/123",
      "type":"GET"
   },
   "purchase":{
      "href":"https://zuul.monkey.exchange/v2/buyers/123/purchases/0zkvnbfZsE",
      "type":"GET"
   }
}

In the example above, there are the links approve and unapprove. These links are conditional and will be present in the response based on the status of the record. An approved record will only have theunapprove link, and a disapproved record will only have the approve link.

Always use the links to determine which actions can be performed on a record.

Here is an example of pagination:

"_links":{
   "first":{
      "href":"http://zuul.monkey.exchange/v2/buyers/123/signatures?status=UNAPPROVED&page=0&size=20"
   },
   "self":{
      "href":"http://zuul.monkey.exchange/v2/buyers/123/signatures?status=UNAPPROVED&page=0&size=20"
   },
   "next":{
      "href":"http://zuul.monkey.exchange/v2/buyers/123/signatures?status=UNAPPROVED&page=1&size=20"
   },
   "last":{
      "href":"http://zuul.monkey.exchange/v2/buyers/123/signatures?status=UNAPPROVED&page=12&size=20"
   }
},
"page":{
   "size":20,
   "totalElements":249,
   "totalPages":13,
   "number":0
}