About the APIs

Environments

Below are the API URLs by environment.

Technologies and Standards

REST

REST is an architectural style that defines a set of HTTP-based constraints and properties.

Web services that follow the REST architectural style, or RESTful web services, provide interoperability between systems. Learn more.

JSON

JSON is a lightweight format for exchanging information and data between systems. Learn more.

UTF-8

UTF-8 defines a character encoding standard for communication between distributed systems. Learn more.

ISO-8601

ISO-8601 is the standard used to send and return date/time fields. This standard uses a time zone.

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

Learn more.

HTTP Methods

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

Success Codes

Client Error Codes

Server Error Codes

Standard Error Response

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

Pagination

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

See an example request:

GET https://gateway.hmg.sales.finance/v2/sponsors/123/payables?page=0&size=20

If no value is provided, the default is 0 for the page parameter and 20 for the size parameter.

Sorting

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

See an example request:

GET https://gateway.hmg.sales.finance/v2/sponsors/123/payables?page=0&size=20&sort=updatedAt,desc&sort=status,asc

Filters

List APIs include a filtering mechanism through the search parameter. You can combine searches using AND or OR.

See an example request:

GET https://gateway.hmg.sales.finance/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 the JSON response to build your filter. See the available search options:

: - Searches for equality. Example: supplierName:Fornecedor.

> - Searches where the attribute must be greater than or equal to the provided value. Example: paymentValue>200

< - Searches where the attribute must be less than or equal to the provided value. Example: paymentValue<200

* - Searches where the attribute can start with (supplierName:Forne*), end with (supplierName:*cedor), or contain (supplierName:*orne*) the value.

Hypermedia (HATEOAS)

HATEOAS (Hypermedia as the Engine of Application State) enables applications that integrate with the API to interact through links.

When you access a resource, links tell you which other resources are related to it and which actions can be performed.

Using HATEOAS allows new interactions to be made available dynamically, and consumer applications can discover new interaction options without being impacted.

See an example of links:

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

In the example above, the approve and unapprove links are conditional and appear in the response based on the record status. An approved record only has the unapprove link, and a rejected record only has the approve link.

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

See 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
}