Skip and docs
This commit is contained in:
Daniel Arantes Loverde
358
API_Mobile_App.md
Normal file
358
API_Mobile_App.md
Normal file
@@ -0,0 +1,358 @@
|
||||
# Atomenta Mobile App API Documentation
|
||||
|
||||
## 🔐 Authentication & Headers
|
||||
|
||||
The mobile app accesses distinct sets of APIs:
|
||||
1. **App APIs (`/api/app/*`)**: For general app features like Home Screen and Orders listing.
|
||||
2. **Customer APIs (`/api/customer/*`)**: For User Registration, Login, and Profile Management.
|
||||
3. **Store External APIs (`/api/store/*`)**: For store-specific operations like Catalog and Checkout.
|
||||
|
||||
### Common Headers
|
||||
All requests should ideally include:
|
||||
|
||||
```http
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
### Authentication Strategies
|
||||
|
||||
#### 1. Customer Auth (for App & Customer APIs)
|
||||
Used for everything related to the logged-in user (Profile, Orders, etc).
|
||||
- **Header:** `Authorization: Bearer <Users_JWT_Token>`
|
||||
- **Note:** Obtained via `/api/customer/login`.
|
||||
|
||||
#### 3. Hybrid Store Auth (for Store External APIs)
|
||||
Used when interacting with a specific store (Catalog, Checkout).
|
||||
- **Header 1:** `Atomenta-Token: 550e8400-e29b-41d4-a716-446655440008` (Store Module ID)
|
||||
- **Header 2:** `Authorization: Bearer <Users_JWT_Token>` (Required for Checkout/Orders)
|
||||
|
||||
---
|
||||
|
||||
## 👤 Customer Management
|
||||
|
||||
### 1. Register Customer
|
||||
**POST** `/api/customer`
|
||||
|
||||
**Headers:**
|
||||
- `Atomenta-Token: 550e8400-e29b-41d4-a716-44665544000a` (Customer Module ID)
|
||||
|
||||
**Body:**
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Daniel Loverde",
|
||||
"email": "daniel@example.com",
|
||||
"phoneNumber": "+5511999999999",
|
||||
"birthDate": "1990-01-01T00:00:00Z" // Opcional
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"error": false,
|
||||
"code": "CUSTOMER_CREATED",
|
||||
"result": {
|
||||
"id": "cust_uuid...",
|
||||
"name": "Daniel Loverde",
|
||||
"email": "daniel@example.com"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Login (Get Token)
|
||||
**POST** `/api/customer/login`
|
||||
|
||||
**Body:**
|
||||
|
||||
```json
|
||||
{
|
||||
"email": "daniel@example.com",
|
||||
"otp": "123456" // Em dev/demo, apenas email pode bastar se configurado assim
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"error": false,
|
||||
"code": "LOGIN_SUCCESS",
|
||||
"result": {
|
||||
"token": "eyJhbGciOi...", // <--- Use as Bearer Token for other requests
|
||||
"customer": {
|
||||
"id": "cust_uuid...",
|
||||
"name": "Daniel Loverde",
|
||||
"email": "daniel@example.com"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Get Profile
|
||||
**GET** `/api/customer/profile`
|
||||
|
||||
**Headers:**
|
||||
|
||||
- `Authorization: Bearer <JWT_Token>`
|
||||
- `Atomenta-Token: 550e8400-e29b-41d4-a716-44665544000a`
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"error": false,
|
||||
"code": "CUSTOMER_PROFILE_RETRIEVED",
|
||||
"result": {
|
||||
"id": "cust_uuid...",
|
||||
"name": "Daniel Loverde",
|
||||
"email": "daniel@example.com",
|
||||
"phoneNumber": "+5511999999999",
|
||||
"favorites": ["store_abc...", "store_xyz..."],
|
||||
"address_book": [],
|
||||
"behavioral_stats": {
|
||||
"total_orders": 5,
|
||||
"avg_ticket_size": 45.00
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Update Profile
|
||||
**POST** `/api/customer/:id`
|
||||
|
||||
**Headers:**
|
||||
|
||||
- `Authorization: Bearer <JWT_Token>`
|
||||
- `Atomenta-Token: 550e8400-e29b-41d4-a716-44665544000a`
|
||||
|
||||
**Body:**
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Daniel A. Loverde", // Fields to update
|
||||
"phoneNumber": "+5511988888888",
|
||||
"biometricsEnabled": true
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🏠 App Home Screen
|
||||
|
||||
### List Stores (Smart Listing)
|
||||
**GET** `/api/app/stores`
|
||||
|
||||
**Headers:**
|
||||
- `Authorization: Bearer <Users_JWT_Token>` (Customer obrigatório)
|
||||
|
||||
Lists stores based on user location, filtered by distance.
|
||||
|
||||
**Query Parameters:**
|
||||
|
||||
- `lat` (Required): User Latitude (e.g., `-23.550520`)
|
||||
- `lng` (Required): User Longitude (e.g., `-46.633308`)
|
||||
- `category` (Optional): Filter by category name (e.g., `Lanches`)
|
||||
- `search` (Optional): Search by store name
|
||||
|
||||
**Notes:**
|
||||
|
||||
- Sem login do customer, a listagem é bloqueada.
|
||||
- Se `lat/lng` não forem enviados, a API tenta usar o endereço salvo no perfil do customer (`address_book.lat_long`).
|
||||
- Lojas fora do raio/bairro de entrega não são exibidas.
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"error": false,
|
||||
"result": [
|
||||
{
|
||||
"id": "store_123...",
|
||||
"name": "Burger King",
|
||||
"logo": "https://...",
|
||||
"cover": "https://...",
|
||||
"category": "Lanches",
|
||||
"rating": 4.8,
|
||||
"deliveryTime": "30-45 min",
|
||||
"deliveryFee": 5.99,
|
||||
"distance": 1.2, // km
|
||||
"isOpen": true,
|
||||
"statusLabel": "Aberto"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### List User Orders
|
||||
**GET** `/api/app/orders`
|
||||
|
||||
**Headers:**
|
||||
|
||||
- `Authorization: Bearer <JWT>`
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"error": false,
|
||||
"result": [
|
||||
{
|
||||
"id": "ord_123...",
|
||||
"total": 54.90,
|
||||
"status": "completed",
|
||||
"createdAt": "2024-03-20T10:00:00Z",
|
||||
"items": [...]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🏪 Store Integration (External API)
|
||||
|
||||
**Base URL:** `/api/store/:storeId`
|
||||
|
||||
### 1. Store Identity & Status
|
||||
**GET** `/api/store/:storeId/identity`
|
||||
|
||||
**Headers/Query:**
|
||||
|
||||
- `x-user-lat` / `lat`: User Latitude
|
||||
- `x-user-lng` / `lng`: User Longitude
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"error": false,
|
||||
"result": {
|
||||
"fantasyName": "Mc Donalds",
|
||||
"distance": 2.5,
|
||||
"deliveryTime": "30-45 min",
|
||||
"minOrder": 15.00
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Full Store Info
|
||||
**GET** `/api/store/:storeId/info`
|
||||
|
||||
Returns detailed info including operating hours and accepted payment methods.
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"error": false,
|
||||
"code": "STORE_INFO_RETRIEVED",
|
||||
"result": {
|
||||
"isOpen": true,
|
||||
"paymentMethods": {
|
||||
"paymentOnDelivery": true,
|
||||
"paymentOnPickup": true,
|
||||
"acceptCash": true,
|
||||
"acceptPix": true,
|
||||
"acceptCreditCard": true, // Resumo Geral
|
||||
"acceptDebitCard": true, // Resumo Geral
|
||||
"brands": {
|
||||
"credit": {
|
||||
"visa": true,
|
||||
"master": true,
|
||||
"elo": true,
|
||||
"amex": false,
|
||||
"hipercard": false
|
||||
},
|
||||
"debit": {
|
||||
"visa": true,
|
||||
"master": true,
|
||||
"elo": true
|
||||
}
|
||||
}
|
||||
},
|
||||
"openingHours": { ... },
|
||||
"address": { ... }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Product Catalog
|
||||
**GET** `/api/store/:storeId/catalog`
|
||||
|
||||
Returns categories with their respective products.
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"error": false,
|
||||
"result": [
|
||||
{
|
||||
"id": "cat_1...",
|
||||
"name": "Burgers",
|
||||
"products": [
|
||||
{
|
||||
"id": "prod_1...",
|
||||
"name": "Big Mac",
|
||||
"price": 25.90,
|
||||
"image": "https://...",
|
||||
"addonGroups": [...]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Create Order (Checkout)
|
||||
**POST** `/api/store/:storeId/orders`
|
||||
|
||||
**Body:**
|
||||
|
||||
```json
|
||||
{
|
||||
"customer": {
|
||||
"name": "Daniel Loverde",
|
||||
"phone": "11999999999",
|
||||
"email": "daniel@example.com",
|
||||
"asaasId": "cus_000005165985" // Opcional.
|
||||
},
|
||||
// Nota: O usuário DEVE estar autenticado via Bearer Token.
|
||||
// Os dados de 'customer' enviados aqui são usados preferencialmente para
|
||||
// registrar os dados de entrega/cobrança deste pedido específico no Asaas,
|
||||
// mas o 'userId' e o histórico são vinculados ao token do usuário logado.
|
||||
"items": [
|
||||
{
|
||||
"productId": "prod_123",
|
||||
"qty": 2,
|
||||
"price": 25.00,
|
||||
"addons": []
|
||||
}
|
||||
],
|
||||
"total": 50.00,
|
||||
"paymentMethod": "PIX", // "PIX" | "CREDIT_CARD" | "DEBIT_CARD" | "MONEY"
|
||||
"deliveryType": "DELIVERY", // "DELIVERY" | "PICKUP"
|
||||
"address": {
|
||||
"street": "Rua Exemplo",
|
||||
"number": "123",
|
||||
"neighborhood": "Centro"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"error": false,
|
||||
"code": "ORDER_CREATED",
|
||||
"result": {
|
||||
"id": "ord_987...",
|
||||
"status": "created",
|
||||
"paymentPayload": "https://www.asaas.com/i/..." // Link para pagamento (Pix/Boleto)
|
||||
}
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user