LCEssentials/API_Mobile_App.md

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:

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:

{
  "name": "Daniel Loverde",
  "email": "daniel@example.com",
  "phoneNumber": "+5511999999999",
  "birthDate": "1990-01-01T00:00:00Z" // Opcional
}

Response:

{
  "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:

{
  "email": "daniel@example.com",
  "otp": "123456" // Em dev/demo, apenas email pode bastar se configurado assim
}

Response:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "error": false,
  "code": "ORDER_CREATED",
  "result": {
    "id": "ord_987...",
    "status": "created",
    "paymentPayload": "https://www.asaas.com/i/..." // Link para pagamento (Pix/Boleto)
  }
}