> For the complete documentation index, see [llms.txt](https://developers.estoca.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.estoca.com.br/api-docs/concepts.md).

# Conceitos

A nossa API é baseada no modelo de arquitetura **`REST`**.

**`REST`** é um padrão de mercado e não é dependente da tecnologia utilizada no seu sistema, com isso é possível a integração com a nossa plataforma com as mais diversas linguagens de programação.

## Ambientes

A disponibilização dos nossos recursos é simples e baseia-se na utilização de dois ambientes principais:

1. Ambiente de testes
   * **`https://api-stg.estoca.com.br`**
2. Ambiente de produção
   * **`https://api.estoca.com.br`**

## Tipos de Requisições

|                               Método                               |                                                                   Descrição                                                                  |
| :----------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------: |
|   <mark style="color:blue;background-color:blue;">**GET**</mark>   | <p>Consulta ou retorna recursos já existentes para a operação desejada<br><br>Exemplo:</p><p>Utilizado na consulta de um pedido de venda</p> |
|  <mark style="color:green;background-color:green;">**POST**</mark> |             <p>Cria um novo recurso para a operação desejada<br><br>Exemplo:</p><p>Utilizado na criação de um pedido de venda</p>            |
| <mark style="color:orange;background-color:orange;">**PUT**</mark> |     <p>Atualiza um recurso já existente para a operação desejada<br><br>Exemplo:</p><p>Utilizado na atualização de um pedido de venda</p>    |
|   <mark style="color:red;background-color:red;">**DELETE**</mark>  |       <p>Deleta um recurso já existente para a operaçao desejada<br><br>Exemplo:</p><p>Utilizado na exclusão de um pedido de venda</p>       |

## Limites

A utilização dos recursos nossa API são limitadas a no máximo 100 requisições por minuto e esse limite é controlado por empresa.

Caso seja ultrapassado o limite a requisição, o recurso retornará o código de status **`429 Too Many Requests`** e a mensagem **`Requests limited. Retry after seconds in Headers`**.

Também será retornado no cabeçalho da requisição (**`Header`**) a informação **`Retry-After`** que é o tempo em segundos que o seu sistema deverá aguardar até enviar a próxima requisição **`HTTP`**.

## Passo a Passo

De forma resumida, para iniciar a utilização de um dos nossos recursos, é necessário seguir os seguintes passos abaixo:

* Gerar uma chave de API na plataforma
* Combinar a URL base (variável **`{url_base}`**) do ambiente com o caminho de rota (variável **`{url_path}`**) do recurso da operação desejada
* Preencher as informações necessárias no cabeçalho da requisição (**`Header`**)
* Enviar uma requisição **`HTTP`** utilizando o método (variável **`{http_method}`**) mais adequado ao recurso da operação desejada

{% hint style="info" %}
É **muito importante** ler todas as orientações na nossa página [**Autenticação**](/api-docs/authentication.md)
{% endhint %}

{% hint style="success" %} <mark style="color:green;">**Exemplo**</mark> para acessar o recurso de **consulta de status** no **ambiente de testes:**

* Considerando as seguintes variáveis:
  * **`{url_base} = https://api-stg.estoca.com.br`**
  * **`{url_path} = /health-check`**
  * **`{http_method} = GET`**
  * **`Header X-Api-Key = 00000000-0000-0000-0000-000000000000`**
  * **`Header X-Api-Version = v1`**
* Resultado final da combinação para a requisição no formato **`cURL`**:
  * **`curl --location`**\
    **`--request GET 'https://api-stg.estoca.com.br/health-check'`**\
    **`--header 'X-Api-Key: 00000000-0000-0000-0000-000000000000'`**\
    **`--header 'X-Api-Version: v1'`**

*<mark style="color:red;">**Atenção:**</mark> a chave de API utilizada neste exemplo não é válida!*
{% endhint %}

## Ferramentas

Indicamos que sempre seja utilizado ferramentas que tem como objetivo para testar os recursos disponibilizados através do envio de requisições **`HTTP`** para análise do seu envio e retorno, antes mesmo de iniciar o desenvolvimento ou ajuste no seu sistema.

Considerando isso, disponibilizamos abaixo o link de acesso aos exemplos das requisições (**`collections`**) através da ferramenta [Postman](https://www.postman.com/).

{% embed url="<https://estoca-public.s3.us-east-1.amazonaws.com/docs/Estoca+API+(v1).postman_collection.json>" %}
Collection Estoca REST API (v1)
{% endembed %}