174 lines
4.0 KiB
Markdown
174 lines
4.0 KiB
Markdown
# Portal Jurunense API - SDK
|
|
|
|
Este projeto agora inclui um **SDK oficial** para consumir a API Portal Jurunense de forma simples e tipada em TypeScript/JavaScript.
|
|
|
|
## Localização
|
|
|
|
O SDK está localizado no diretório `/sdk` na raiz do projeto.
|
|
|
|
## Estrutura do SDK
|
|
|
|
```
|
|
sdk/
|
|
├── src/ # Código fonte TypeScript
|
|
│ ├── types/ # Definições de tipos
|
|
│ ├── client/ # Clientes HTTP
|
|
│ └── index.ts # Ponto de entrada
|
|
├── dist/ # Código compilado (gerado)
|
|
├── examples/ # Exemplos de uso
|
|
├── package.json
|
|
├── tsconfig.json
|
|
├── README.md # Documentação completa
|
|
├── QUICK_START.md # Guia de início rápido
|
|
├── CONTRIBUTING.md # Guia de contribuição
|
|
└── PUBLISH.md # Guia de publicação
|
|
```
|
|
|
|
## Scripts Disponíveis
|
|
|
|
No diretório raiz do projeto, você pode usar os seguintes scripts para trabalhar com o SDK:
|
|
|
|
```bash
|
|
npm run sdk:install # Instala dependências do SDK
|
|
npm run sdk:build # Compila o SDK
|
|
npm run sdk:watch # Compila e observa mudanças
|
|
npm run sdk:publish # Publica o SDK no NPM
|
|
```
|
|
|
|
## Uso do SDK
|
|
|
|
### Instalação (quando publicado)
|
|
|
|
```bash
|
|
npm install @portaljuru/api-client
|
|
```
|
|
|
|
### Exemplo Básico
|
|
|
|
```typescript
|
|
import { PortalJuruClient } from '@portaljuru/api-client';
|
|
|
|
const client = new PortalJuruClient({
|
|
baseURL: 'https://api.portaljuru.com.br'
|
|
});
|
|
|
|
// Fazer login
|
|
const { data } = await client.auth.login({
|
|
username: 'usuario',
|
|
password: 'senha'
|
|
});
|
|
|
|
// Buscar pedidos
|
|
const orders = await client.orders.findOrders({
|
|
status: 'processando'
|
|
});
|
|
|
|
// Listar produtos
|
|
const products = await client.products.listProducts();
|
|
```
|
|
|
|
## Módulos Disponíveis
|
|
|
|
O SDK expõe os seguintes módulos:
|
|
|
|
- **auth** - Autenticação (login, refresh token, logout)
|
|
- **logistic** - Logística (expedição, funcionários, entregas, veículos)
|
|
- **orders** - Pedidos (busca, criação, transferências, notas fiscais)
|
|
- **products** - Produtos (listagem, busca, validação)
|
|
- **partners** - Parceiros (CRUD completo)
|
|
- **dataConsult** - Consulta de dados (clientes, transportadoras, vendedores, lojas)
|
|
- **ordersPayment** - Pagamentos de pedidos
|
|
- **crm** - CRM (negociações, ocorrências, tabela de motivos)
|
|
|
|
## Tipos TypeScript
|
|
|
|
O SDK inclui tipos completos para TypeScript, facilitando o desenvolvimento com autocompletar e validação de tipos.
|
|
|
|
```typescript
|
|
import type {
|
|
Order,
|
|
Product,
|
|
Customer,
|
|
LoginResponse,
|
|
ApiResponse
|
|
} from '@portaljuru/api-client';
|
|
```
|
|
|
|
## Desenvolvimento
|
|
|
|
Para desenvolver o SDK localmente:
|
|
|
|
1. Entre no diretório do SDK:
|
|
```bash
|
|
cd sdk
|
|
```
|
|
|
|
2. Instale as dependências:
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
3. Compile o código:
|
|
```bash
|
|
npm run build
|
|
```
|
|
|
|
4. Para desenvolvimento contínuo:
|
|
```bash
|
|
npm run watch
|
|
```
|
|
|
|
## Documentação
|
|
|
|
- [README completo do SDK](./sdk/README.md) - Documentação detalhada de todas as funcionalidades
|
|
- [Guia de Início Rápido](./sdk/QUICK_START.md) - Comece a usar em minutos
|
|
- [Guia de Contribuição](./sdk/CONTRIBUTING.md) - Como contribuir com o SDK
|
|
- [Guia de Publicação](./sdk/PUBLISH.md) - Como publicar no NPM
|
|
|
|
## Exemplos
|
|
|
|
Veja os exemplos práticos em [sdk/examples/](./sdk/examples/):
|
|
|
|
- `basic-usage.ts` - Exemplo básico de uso
|
|
- `logistic-example.ts` - Exemplo de operações logísticas
|
|
|
|
## Publicação
|
|
|
|
Para publicar uma nova versão do SDK no NPM:
|
|
|
|
1. Atualize a versão:
|
|
```bash
|
|
cd sdk
|
|
npm version patch # ou minor/major
|
|
```
|
|
|
|
2. Compile:
|
|
```bash
|
|
npm run build
|
|
```
|
|
|
|
3. Publique:
|
|
```bash
|
|
npm publish --access public
|
|
```
|
|
|
|
Ou use o script do projeto raiz:
|
|
```bash
|
|
npm run sdk:publish
|
|
```
|
|
|
|
## Benefícios do SDK
|
|
|
|
- Tipagem completa em TypeScript
|
|
- Autocompletar em IDEs
|
|
- Tratamento de erros consistente
|
|
- Gerenciamento automático de tokens
|
|
- Interface intuitiva e orientada a objetos
|
|
- Documentação completa com exemplos
|
|
- Suporte a todas as funcionalidades da API
|
|
|
|
## Licença
|
|
|
|
MIT - Veja o arquivo [LICENSE](./sdk/LICENSE) para mais detalhes.
|
|
|