Sobre as APIs

Ambientes

Homologação

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

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

Produção

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

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

Tecnologias e Padrões

REST

É um estilo de arquitetura que define um conjunto de restrições e propriedades baseados em HTTP.

Web Services que obedecem ao estilo arquitetural REST, ou Web Services RESTful, fornecem interoperabilidade entre sistemas. Mais informações.

JSON

É um formato leve de troca de informações/dados entre sistemas, amplamente utilizado. Mais informações.

UTF-8

Define um padrão de caracteres de comunicação entre sistemas distribuídos. Mais informações.

ISO-8601

Padrão utilizado para envio e retorno de campos do tipo data/hora. Esse padrão utiliza a Time Zone.

"Padrão": "YYYY-MM-DDThh:mm:ss.sTZD"
"Exemplo": "2019-01-22T13:37:00.000-03:00" 

Mais informações.

Métodos HTTP

Nossas APIs seguem o padrão RESTful e utilizam o verbo HTTP referente a cada operação.

Códigos de Sucesso

Códigos de Erro no Cliente

Códigos de Erro no Servidor

Resposta Padrão de Erros

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

Paginação

No momento da listagem de um recurso deve-se utilizar os parâmetros de paginação page e size.

Veja um exemplo de requisição:

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

Caso não seja informado nenhum valor o padrão será 0 para o parâmetro page e 20 para o parâmetro size.

Ordenação

As APIs de listagem contam com ordenação e ela é feita através do parâmetro sort. Você pode utilizar mais de uma ordenação na mesma requisição.

Veja um exemplo de requisição:

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

Filtros

As APIs de listagem possuem um mecanismo de filtro e isso é feito através do parâmetro search e você pode combinar as buscas utilizando AND ou OR.

Veja um exemplo de requisição:

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)

Utilize os campos retornados no json para montar seu filtro. Veja as alternativas de busca:

: - Para busca por equalidade. Ex: supplierName:Fornecedor.

> - Para busca onde o atributo deve ser maior ou igual ao valor informado. Ex: paymentValue>200

< - Para busca onde o atributo deve ser menor ou igual ao valor informado. Ex: paymentValue<200

* - Para busca onde o atributo pode começar com (supplierName:Forne*), terminar com (supplierName:*cedor) ou conter (supplierName:*orne*).

Hypermedia (HATEOAS)

HATEOAS (Hypermedia as the Engine of Application State) possibilita que as aplicações que se integram com a API possam interagir através de links.

Dessa forma, ao acessar um recurso você irá, através de links, saber quais outros recursos se relacionam com ele e quais ações podem ser executadas.

A utilização de HATEOAS permite que a disponibilização de novas interações ocorra de forma dinâmica e que as aplicações consumidoras tomem conhecimento das novas opções de interação sem que sejam impactadas.

Veja um exemplo de 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"
   }
}

No exemplo acima, existem os links approve e unapprove esses links são condicionais e vão estar presente na resposta baseado no status do registro, um registro aprovado só terá o link unapprove e um registro reprovado só terá o link approve.

Sempre utilize os links para saber quais ações podem ser executadas em um registro.

Veja um exemplo de paginação:

"_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
}