Criação de intenção de ordem de compra e venda

Este endpoint permite que o parceiro Bankly ofereça a seus clientes a possibilidade de criar uma ordem de compra ou venda de criptomoedas. Ou seja, possibilita a garantia de uma cotação específica por um determinado período sem que ela seja modificada pela volatilidade do mercado de criptomoedas.

A criação da ordem não é a compra/venda em si. Para que o cliente de fato conclua a solicitação, o parceiro deverá executar a compra ou venda da criptomoeda escolhida pelo seu cliente em até um minuto. Caso contrário, o pedido de criação irá expirar e será necessário realizar uma nova solicitação.

🚧
Importante
Após a expiração do prazo de execução da compra ou venda, não é garantido que o preço final permanecerá igual ao da última consulta realizada.

Pré-requisitos

Para que seja possível utilizar este endpoint, é necessário que:

O cliente do parceiro possua uma conta ativa.

Requisição (Request)

Requisição HTTP

POST https://api-mtls.sandbox.bankly.com.br/v2/crypto/orders

--request POST \
--url 'https://api-mtls.sandbox.bankly.com.br/v2/crypto/orders' \
--header 'accept: application/json' \
--header 'bankly-idempotency-key: FLORESTA_ED' \
--header 'bankly-version: 2023-01-30' \
--header 'bankly-user-id: 47742663023' \
--header 'authorization: Bearer {Token}' \
--header 'content-type: application/json' \
--header 'bankly-correlation-id: 5a88c4ae-99cd-494e-96b7-39b8109c8a77' \
--data '{
         "data": {
            "type": "PURCHASE",
            "market": "BTC:BRL",
            "amount": {
               "value": 0,
               "currency": "BRL"
            },
            "fee": {
               "value": 0,
               "currency": "BRL"
            }
         },
         "metadata": {
            "exemplo1": "123",
            "exemplo2": 123,
            "exemplo3": {},
            "exemplo4": [],
         }
      }'

Autorização

Para garantir a segurança nas requisições, todos os endpoints do Bankly utilizam scopes como parte do seu fluxo de autorização.
Esta requisição requer o scope descrito a seguir:

Scope	Descrição
`crypto.order.create`	Concede acesso para criar a ordem de compra ou venda.

Cabeçalhos (Headers)

Nome	Descrição
`bankly-version`	Obrigatório. Data em que ocorreu a alteração no contrato. Neste caso, insira 2023-01-30.
`authorization`	Obrigatório. Token de autorização do tipo Bearer.
`bankly-correlation-id`	Obrigatório. Informe um GUID v4. A cada requisição, deve-se gerar um novo GUID.
`bankly-idempotency-key`	Obrigatório. Chave de idempotência para a requisição (UUID v4).
`bankly-user-id`	Obrigatório. Número do documento do usuário que irá fazer a requisição.

Parâmetros da rota (Path)

Não é necessário enviar parâmetros no path desta requisição.

Corpo da requisição (Body)

No body, envie os seguintes campos em formato JSON:

Nome	Tipo	Descrição
`type`	`object`	Obrigatório. Tipo de ordem (compra ou venda), o qual pode ser “PURCHASE” ou “SELL”.
`market`	`string`	Obrigatório. Mercado, o qual é constituído da sigla da criptomoeda com a sigla do real. Exemplo: BTC:BRL.
`amount`	`object`	Obrigatório. Objeto que contém informações sobre o valor da compra ou venda das criptomoedas, sem taxa.
`amount.value`	`string`	Obrigatório. Valor da compra ou venda, sem taxa.
`amount.currency`	`string`	Obrigatório. Código da moeda com base na ISO-4127.
`fee`	`object`	Obrigatório. Objeto que contém informações sobre as taxas aplicadas pelo parceiro no valor da compra ou venda.
`fee.value`	`number`	Obrigatório. Valor da taxa. Importante: a taxa aplicada não pode ser superior ao valor da criptomoeda.
`fee.currency`	`string`	Obrigatório. Código da moeda com base na ISO-4217.
`metadata`	`dictionary<string, object>`	Dicionário de metadados que pode conter informações adicionais da requisição, de acordo com o modelo de negócio do cliente.

{
  "data": {
    "type": "PURCHASE",
    "market": "BTC:BRL",
    "amount": {
      "value": 0,
      "currency": "BRL"
    },
    "fee": {
      "value": 0,
      "currency": "BRL"
    }
  },
  "metadata": {
		"exemplo1": "123",
		"exemplo2": 123,
		"exemplo3": {},
		"exemplo4": []
	}
}

Resposta (Response)

O status code 201 indicará que a ordem de compra ou venda foi criada com sucesso.

Sendo bem-sucedido, o retorno irá trazer um objeto contendo os seguintes campos em formato JSON:

Nome	Tipo	Descrição
`authenticationCode`	`string`	Identificador da transação que deve ser informado no path da requisição (campo `order_authentication_code`) do endpoint de execução de ordem de compra e venda.
`type`	`string`	Tipo de ordem (compra ou venda), o qual pode ser “PURCHASE” ou “SELL”.
`market`	`string`	O mercado, o qual é constituído da sigla da criptomoeda com a sigla do real. Exemplo: BTC:BRL.
`price`	`object`	Objeto que contém informações sobre o preço da criptomoeda.
`price.value`	`number`	Preço final da criptomoeda.
`price.currency`	`string`	Código da criptomoeda. Exemplo: “BTC”.
`amount`	`object`	Objeto que contém informações sobre o valor da compra ou venda das criptomoedas, sem taxa.
`amount.value`	`string`	Valor da criptomoeda, sem taxa.
`amount.currency`	`string`	Código da moeda com base na ISO-4217.
`fee`	`object`	Objeto que contém informações sobre as taxas aplicadas no o valor da compra ou venda.
`fee.value`	`object`	Valor da taxa.
`fee.currency`	`string`	Código da moeda com base na ISO-4217.
`quota`	`object`	Objeto que contém informações sobre o valor da operação, em criptomoeda.
`quota.value`	`number`	Valor da operação, em criptomoeda.
`quota.currency`	`string`	Código da criptomoeda. Exemplo: “BTC”.
`total`	`object`	Objeto que contém informações sobre o valor total (valor da criptomoeda + taxa) da compra ou venda.
`total.value`	`number`	Valor total da compra ou venda.
`total.currency`	`string`	Código da moeda com base na ISO-4217.
`status`	`string`	Situação da ordem de compra ou venda. Neste endpoint, o valor desse campo sempre retornará "CREATED".
`createdAt`	`object`	Data de criação da execução da ordem de compra ou venda, no formato ISO 8601 - UTC.
`expiresIn`	`string`	Data de expiração da execução da ordem, no formato ISO 8601 - UTC.
`metadata`	`dictionary<string, object>`	Dicionário de metadados que pode conter informações adicionais da requisição, de acordo com o modelo de negócio do cliente.
`links[]`	`array of objects`	Lista de objetos que contém os links de próximos estados válidos da entidade/recurso.
`links[].url`	`string`	Lista de objetos que contém os links de próximos estados válidos da entidade/recurso.
`links[].rel`	`string`	Descrição de como a URL se relaciona com o recurso atual.
`links[].method`	`string`	Tipo de verbo que deve ser utilizado para acessar a URL.

{
   "data": {
      "authenticationCode": "60c66bce-0127-4e07-a35d-d14d31e4126a",
      "type": "PURCHASE",
      "market": "BTC:BRL",
      "price": {
         "value": 0,
         "currency": "string"
      },
      "amount": {
         "value": 0,
         "currency": "string"
      },
      "fee": {
         "value": 0,
         "currency": "string"
      },
      "quota": {
         "value": 0,
         "currency": "string"
      },
      "total": {
         "value": 0,
         "currency": "string"
      },
      "status": "CREATED",
      "createdAt": "2023-01-03T17:23:22.829Z",
      "expiresIn": "2023-01-03T17:23:22.829Z"
   },
   "metadata": {
      "exemplo1": "123",
      "exemplo2": 123,
      "exemplo3": {},
      "exemplo4": []
   },
   "links": [
	   {
         "url": "/crypto/orders/60c66bce-0127-4e07-a35d-d14d31e4126a",
         "rel": "execute_order",
         "method": "POST"
      },
      {
         "url": "/crypto/orders/60c66bce-0127-4e07-a35d-d14d31e4126a",
         "rel": "get_order",
         "method": "GET"
      }
   ]
}

👍
Dica
Para simular uma requisição nesse endpoint, acesse o API Reference.

Erros

Este endpoint pode retornar alguns erros específicos, conforme a tabela a seguir:

Status Code	Código	Descrição
422	UNPROCESSABLE_ ENTITY	Requisição não pode ser processada, devido uma regra de negócio.

Recordamos que esta API também poderá retornar erros comuns entre todos os endpoints. Portanto, recomendamos a consulta da documentação de erros, onde é possível encontrar as mensagens comuns em inglês que acompanham os erros 400 (se houver).