🗣️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
GET	Consulta ou retorna recursos já existentes para a operação desejada Exemplo: Utilizado na consulta de um pedido de venda
POST	Cria um novo recurso para a operação desejada Exemplo: Utilizado na criação de um pedido de venda
PUT	Atualiza um recurso já existente para a operação desejada Exemplo: Utilizado na atualização de um pedido de venda
DELETE	Deleta um recurso já existente para a operaçao desejada Exemplo: Utilizado na exclusão de um pedido de venda

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

É muito importante ler todas as orientações na nossa página Autenticação

Exemplo 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'

Atenção: a chave de API utilizada neste exemplo não é válida!

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://estoca-public.s3.us-east-1.amazonaws.com/docs/Estoca+API+(v1).postman_collection.jsonestoca-public.s3.us-east-1.amazonaws.com

Collection Estoca REST API (v1)