Stock API – Guia para Empresas Integradoras

A Stock API é um serviço de **controle de estoque e reposição automática** pensado para ser consumido por **empresas, ERPs, PDVs e outros sistemas corporativos**. Como cliente, você **não precisa nem deve acessar a infraestrutura interna** (código-fonte, banco de dados, servidores). Tudo o que você enxerga é uma **API segura**, por meio de: - Uma **URL base**, fornecida pelo provedor. - Suas **credenciais de acesso** (usuário/senha ou credenciais de integração). - Um conjunto de **endpoints** que permitem acessar apenas dados da **sua própria companhia**. Você **não terá acesso direto ao banco de dados** nem a tabelas internas. Toda interação acontece via endpoints documentados, e sempre limitada aos **produtos, usuários e movimentos de estoque da sua empresa**. --- ## 1. O que a sua empresa pode fazer Com a Stock API, sua empresa pode, via HTTP/HTTPS: - **Autenticar-se** com um usuário da sua companhia. - **Gerenciar produtos** (cadastrar, listar) da sua companhia. - **Registrar movimentos de estoque** (entradas e saídas) desses produtos. - Consumir os dados retornados pela API para alimentar **painéis, relatórios e automações** no seu próprio sistema. Importante: - Você **não vê nem manipula o banco de dados diretamente**. - Você **não enxerga dados de outras empresas**. - A API é multi-tenant: cada token de acesso está vinculado a uma única companhia. --- ## 2. Conceitos principais (lado do cliente) - **Company (Empresa)**: representa a sua organização dentro da Stock API. - **User (Usuário)**: usuário da sua empresa que faz login e obtém o token de acesso. - **Product (Produto)**: item cujo estoque você controla (ex.: "Arroz Tipo 1 5kg"). - **Stock Movement (Movimento de Estoque)**: registro de entrada (IN) ou saída (OUT) de um produto em determinado local (loja, depósito, etc.). Você interage apenas com esses conceitos via JSON nas respostas da API. Detalhes de armazenamento e tecnologias internas são responsabilidade do provedor e ficam encapsulados. --- ## 3. Acesso à API ### 3.1. URL base A URL base será informada pelo provedor. No ambiente padrão desta API: - **Produção (via RapidAPI – recomendada para clientes)**: `https://manager-stock2.p.rapidapi.com/api/v1` - **Produção (URL interna do provedor, não exposta aos clientes)** Sempre que este guia mencionar um caminho como `/auth/login` ou `/products`, ele deve ser combinado com a URL base acima. ### 3.2. Autenticação com token (visão do cliente) A Stock API utiliza **tokens de acesso (JWT)**. Do ponto de vista da sua aplicação, o fluxo é: 1. **Login** - Envie e-mail e senha do usuário da sua empresa para `/auth/login`. - A API retorna um `accessToken`. 2. **Uso do token** - Em cada chamada protegida, envie o cabeçalho `Authorization: Bearer <accessToken>`. 3. **Isolamento por companhia** - O token indica a qual companhia o usuário pertence. - A API só devolverá dados dessa companhia. Você nunca terá usuário de banco de dados, conexão direta de banco ou acesso à infraestrutura; apenas a API pública é exposta. ### 3.3. Uso via RapidAPI Esta API está publicada na **RapidAPI** em: - https://rapidapi.com/henrimi4710/api/manager-stock2 Ao consumir pela RapidAPI: - Utilize sempre a URL base: `https://manager-stock2.p.rapidapi.com/api/v1`. - Em **todas** as requisições, envie os cabeçalhos: - `X-RapidAPI-Key: <SUA_CHAVE_RAPIDAPI>` - `X-RapidAPI-Host: manager-stock2.p.rapidapi.com` O plano **Free** na RapidAPI permite até **1000 requisições**, ideal para testes e provas de conceito. Planos superiores oferecem limites maiores. --- ## 4. Fluxo básico de integração ### 4.1. Passo 1 – Obter credenciais e URL base O provedor da Stock API irá: - Criar sua **empresa** no ambiente da API. - Criar pelo menos um **usuário administrador**. - Entregar a você: - A **URL base** (sandbox e/ou produção). - E-mail do usuário da companhia. - Senha inicial ou mecanismo de geração de senha. Você **não precisa configurar servidores ou banco de dados**; isso é interno ao provedor. ### 4.2. Passo 2 – Fazer login e obter o token - **Método**: `POST` - **Caminho**: `/auth/login` Requisição: ```json { "email": "admin@suaempresa.com", "password": "SenhaForte123" } ``` Resposta: ```json { "accessToken": "<jwt>" } ``` Guarde esse token em local seguro (memória, cache, storage protegido). ### 4.3. Passo 3 – Enviar o token nas chamadas Para rotas protegidas (produtos, movimentos), inclua o cabeçalho: ```http Authorization: Bearer <accessToken> ``` Exemplo em HTTP bruto: ```http GET /api/v1/products HTTP/1.1 Host: manager-stock2.p.rapidapi.com X-RapidAPI-Key: SUA_CHAVE_RAPIDAPI X-RapidAPI-Host: manager-stock2.p.rapidapi.com Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... ``` Exemplo em código (JavaScript/TypeScript): ```ts const res = await fetch('https://manager-stock2.p.rapidapi.com/api/v1/products', { method: 'GET', headers: { 'X-RapidAPI-Key': 'SUA_CHAVE_RAPIDAPI', 'X-RapidAPI-Host': 'manager-stock2.p.rapidapi.com', Authorization: `Bearer ${accessToken}`, }, }); ``` --- ## 5. Endpoints principais (contrato público) ### 5.1. Autenticação #### 5.1.1. Login - **Método**: `POST` - **Caminho**: `/auth/login` - **Descrição**: autentica um usuário da sua companhia e retorna um token. Requisição: ```json { "email": "admin@suaempresa.com", "password": "SenhaForte123" } ``` Resposta (200): ```json { "accessToken": "<jwt>" } ``` Erros típicos: - 401 – credenciais inválidas. --- ### 5.2. Produtos (da sua companhia) #### 5.2.1. Listar produtos - **Método**: `GET` - **Caminho**: `/products` - **Autenticação**: `Authorization: Bearer <accessToken>`. Resposta (exemplo): ```json [ { "id": "product-uuid", "sku": "ARROZ-01", "name": "Arroz Tipo 1", "unit": "KG", "minStock": 10, "idealStock": 50, "safetyStock": 5, "avgDailyConsumption": 3.5, "leadTimeDays": 7, "createdAt": "2025-12-27T10:00:00.000Z" } ] ``` Somente produtos da **sua companhia** são retornados. #### 5.2.2. Criar produto - **Método**: `POST` - **Caminho**: `/products` - **Autenticação**: `Authorization: Bearer <accessToken>`. Requisição: ```json { "sku": "ARROZ-01", "name": "Arroz Tipo 1", "unit": "KG", "minStock": 10, "idealStock": 50, "safetyStock": 5, "avgDailyConsumption": 3.5, "leadTimeDays": 7 } ``` Resposta (exemplo): ```json { "id": "product-uuid", "sku": "ARROZ-01", "name": "Arroz Tipo 1", "unit": "KG", "minStock": 10, "idealStock": 50, "safetyStock": 5, "avgDailyConsumption": 3.5, "leadTimeDays": 7, "createdAt": "2025-12-27T10:00:00.000Z" } ``` --- ### 5.3. Movimentos de estoque #### 5.3.1. Registrar movimento - **Método**: `POST` - **Caminho**: `/stock-movements` - **Autenticação**: `Authorization: Bearer <accessToken>`. Requisição (exemplo – saída por venda): ```json { "productId": "product-uuid", "warehouseId": "warehouse-uuid", "type": "OUT", "quantity": 5, "reason": "Venda PDV 12345" } ``` Requisição (exemplo – entrada por compra): ```json { "productId": "product-uuid", "warehouseId": "warehouse-uuid", "type": "IN", "quantity": 10, "reason": "Compra fornecedor 789" } ``` Resposta (exemplo): ```json { "id": "movement-uuid", "productId": "product-uuid", "warehouseId": "warehouse-uuid", "type": "OUT", "quantity": 5, "reason": "Venda PDV 12345", "occurredAt": "2025-12-27T10:30:00.000Z" } ``` A forma como o saldo de estoque é calculado e como alertas/ordens sugeridas são gerados é tratada **internamente pela Stock API**, sem que seja necessário expor ou acessar o banco de dados. --- ## 6. Exemplos de integração ### 6.1. PDV 1. Backend do PDV faz login (`POST /auth/login`) e armazena o token. 2. A cada venda concluída, envia `POST /stock-movements` com `type: "OUT"`. 3. Painéis de gestão chamam `GET /products` para exibir informações de estoque. ### 6.2. ERP 1. Job de sincronização cadastra produtos via `POST /products`. 2. Compras geram `POST /stock-movements` com `type: "IN"`. 3. Vendas faturadas geram `POST /stock-movements` com `type: "OUT"`. Em ambos os casos, seu sistema **nunca acessa o banco de dados**: tudo passa pela API. --- ## 7. Segurança e isolamento - Cada token está vinculado a uma única companhia. - A API só retorna dados da companhia associada ao token. - Não há acesso direto a tabelas ou consultas SQL por parte do cliente. - Todo o tráfego deve ser feito sobre HTTPS. Em caso de incidente (credenciais comprometidas), o provedor pode revogar usuários e tokens, sem qualquer exposição de estrutura interna. --- ## 8. Suporte e evolução A Stock API pode evoluir internamente (tecnologias, estrutura de banco, infraestrutura) **sem mudar o contrato exposto neste guia**. Quaisquer novos endpoints ou campos serão documentados e comunicados aos clientes. Para dúvidas de integração, exemplos adicionais ou suporte, use o canal oficial disponibilizado. --- ## 9. Exemplos em linguagens comuns Os exemplos abaixo mostram o fluxo básico: 1. Fazer login em `/auth/login` para obter o `accessToken`. 2. Usar o token para chamar `/products`. Substitua `SEU_TOKEN_AQUI` pelo token real retornado no login. ### 9.1. cURL **Login** ```bash curl -X POST "https://manager-stock2.p.rapidapi.com/api/v1/auth/login" \ -H "Content-Type: application/json" \ -H "X-RapidAPI-Key: SUA_CHAVE_RAPIDAPI" \ -H "X-RapidAPI-Host: manager-stock2.p.rapidapi.com" \ -d '{ "email": "admin@suaempresa.com", "password": "SenhaForte123" }' ``` **Listar produtos** ```bash curl -X GET "https://manager-stock2.p.rapidapi.com/api/v1/products" \ -H "X-RapidAPI-Key: SUA_CHAVE_RAPIDAPI" \ -H "X-RapidAPI-Host: manager-stock2.p.rapidapi.com" \ -H "Authorization: Bearer SEU_TOKEN_AQUI" ``` ### 9.2. JavaScript (Node.js / browser com fetch) ```ts const BASE_URL = 'https://manager-stock2.p.rapidapi.com/api/v1'; const RAPIDAPI_KEY = 'SUA_CHAVE_RAPIDAPI'; const RAPIDAPI_HOST = 'manager-stock2.p.rapidapi.com'; async function login() { const res = await fetch(`${BASE_URL}/auth/login`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-RapidAPI-Key': RAPIDAPI_KEY, 'X-RapidAPI-Host': RAPIDAPI_HOST, }, body: JSON.stringify({ email: 'admin@suaempresa.com', password: 'SenhaForte123', }), }); if (!res.ok) throw new Error('Falha no login'); const data = await res.json(); return data.accessToken as string; } async function listarProdutos() { const token = await login(); const res = await fetch(`${BASE_URL}/products`, { headers: { Authorization: `Bearer ${token}`, 'X-RapidAPI-Key': RAPIDAPI_KEY, 'X-RapidAPI-Host': RAPIDAPI_HOST, }, }); if (!res.ok) throw new Error('Erro ao listar produtos'); const produtos = await res.json(); console.log(produtos); } listarProdutos().catch(console.error); ``` ### 9.3. Python (requests) ```python import requests BASE_URL = "https://manager-stock2.p.rapidapi.com/api/v1" RAPIDAPI_KEY = "SUA_CHAVE_RAPIDAPI" RAPIDAPI_HOST = "manager-stock2.p.rapidapi.com" def login() -> str: resp = requests.post( f"{BASE_URL}/auth/login", json={ "email": "admin@suaempresa.com", "password": "SenhaForte123", }, timeout=10, headers={ "X-RapidAPI-Key": RAPIDAPI_KEY, "X-RapidAPI-Host": RAPIDAPI_HOST, }, ) resp.raise_for_status() return resp.json()["accessToken"] def listar_produtos() -> None: token = login() resp = requests.get( f"{BASE_URL}/products", headers={ "Authorization": f"Bearer {token}", "X-RapidAPI-Key": RAPIDAPI_KEY, "X-RapidAPI-Host": RAPIDAPI_HOST, }, timeout=10, ) resp.raise_for_status() print(resp.json()) if __name__ == "__main__": listar_produtos() ``` ### 9.4. C# (.NET HttpClient) ```csharp using System; using System.Net.Http; using System.Net.Http.Headers; using System.Text; using System.Text.Json; using System.Threading.Tasks; public class StockApiClient { private static readonly string BaseUrl = "https://manager-stock2.p.rapidapi.com/api/v1"; private static readonly string RapidApiKey = "SUA_CHAVE_RAPIDAPI"; private static readonly string RapidApiHost = "manager-stock2.p.rapidapi.com"; private readonly HttpClient _http; public StockApiClient(HttpClient http) { _http = http; } public async Task<string> LoginAsync() { var body = new { email = "admin@suaempresa.com", password = "SenhaForte123" }; var content = new StringContent(JsonSerializer.Serialize(body), Encoding.UTF8, "application/json"); _http.DefaultRequestHeaders.Add("X-RapidAPI-Key", RapidApiKey); _http.DefaultRequestHeaders.Add("X-RapidAPI-Host", RapidApiHost); var response = await _http.PostAsync($"{BaseUrl}/auth/login", content); response.EnsureSuccessStatusCode(); using var stream = await response.Content.ReadAsStreamAsync(); using var json = await JsonDocument.ParseAsync(stream); return json.RootElement.GetProperty("accessToken").GetString(); } public async Task ListarProdutosAsync() { var token = await LoginAsync(); _http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token); var response = await _http.GetAsync($"{BaseUrl}/products"); response.EnsureSuccessStatusCode(); var json = await response.Content.ReadAsStringAsync(); Console.WriteLine(json); } } // Uso em uma aplicação console // var client = new StockApiClient(new HttpClient()); // await client.ListarProdutosAsync(); ```