Sobre as APIs

Nossas APIs possuem diversos recursos, descreveremos cada um deles antes de você analisar a documentação dos nossos Endpoints.

Ambientes

Homologação

https://gateway.hmg.spike.cash

Produção

https://gateway.spike.cash

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.

AçãoMétodoDescrição
CreatePOSTCria um novo recurso.
ReadGETConsulta um recurso ou uma lista.
UpdatePUTAtualiza um recurso existente.
DeleteDELETERemove um recurso existente. Essa operação não pode ser desfeita.

Códigos de Sucesso

Código HTTPDescriçãoMétodos HTTP
200Indica que o processamento foi realizado com sucesso.GET
201Indica que o recurso foi criado com sucesso.POST
202Indica que o processamento será assíncrono, portanto, irá retornar um link "process" onde será possível verificar o status.POST
204Indica que o recurso foi atualizado com sucesso.PUT

Códigos de Erro no Cliente

Código HTTPDescrição
400Erro na requisição, Json mal formatado ou campos inválidos.
401Erro na autenticação do usuário.
403Usuário sem acesso ao recurso.
404Recurso não encontrado.
405Método não permitido.
409Recurso já existente.
412Exceções de negócio.

Códigos de Erro no Servidor

Código HTTPDescrição
5xxErro interno inesperado do 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://gateway.spike.cash/v1/buyers/32779742000153/contracts?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://gateway.spike.cash/v1/buyers/32779742000153/contracts?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://gateway.spike.cash/v1/buyers/32779742000153/contracts?search=sellerGovernmentId:24212752000184 AND sellerName:*Fornecedor* AND paymentDate>2020-04-23 AND (id:123 OR numberOfReceivables:2)

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

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

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

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

* - Para busca onde o atributo pode começar com (sellerName:Forne*), terminar com (sellerName:*cedor) ou conter (sellerName:*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://gateway.spike.cash/v1/buyers/32779742000153/signatures/0zkvnbfZsE",
      "type":"GET"
   },
   "documents":{
      "href":"https://gateway.spike.cash/v1/buyers/32779742000153/signatures/0zkvnbfZsE/documents{?type}",
      "type":"GET",
      "templated":true
   },
   "approve":{
      "href":"https://gateway.spike.cash/v1/buyers/32779742000153/signatures/0zkvnbfZsE/approve",
      "type":"POST"
   },
   "unapprove":{
      "href":"https://gateway.spike.cash/v1/buyers/32779742000153/signatures/0zkvnbfZsE/unapprove",
      "type":"POST"
   },
   "buyer":{
      "href":"https://gateway.spike.cash/v1/buyers/32779742000153",
      "type":"GET"
   },
   "contract":{
      "href":"https://gateway.spike.cash/v1/buyers/32779742000153/contracts/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":"https://gateway.spike.cash/v1/buyers/32779742000153/contracts?status=UNAPPROVED&page=0&size=20"
   },
   "self":{
      "href":"https://gateway.spike.cash/v1/buyers/32779742000153/contracts?status=UNAPPROVED&page=0&size=20"
   },
   "next":{
      "href":"https://gateway.spike.cash/v1/buyers/32779742000153/contracts?status=UNAPPROVED&page=1&size=20"
   },
   "last":{
      "href":"https://gateway.spike.cash/v1/buyers/32779742000153/contracts?status=UNAPPROVED&page=12&size=20"
   }
},
"page":{
   "size":20,
   "totalElements":249,
   "totalPages":13,
   "number":0
}