INGOO DOCS

API v1 Referência da API

Endpoints REST autenticados via JWT Bearer. Payloads em JSON. Webhooks com HMAC obrigatório.

Base URL

https://api.ingooapp.com.br

Todos os endpoints usam HTTPS (TLS 1.3). Content-Type: application/json.

Autenticação

Após login, o servidor retorna um JWT que deve ser enviado em todo request: 

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...

Tokens expirados (401) devem ser renovados via /auth/refresh.

Códigos de erro

Código Significado
200 / 201Sucesso
400Payload inválido
401Não autenticado
403Sem permissão
404Recurso não encontrado
429Rate limit
500Erro interno

Body de erro:

{ "error": "Mensagem legível", "code": "ERROR_CODE" }

Rate limit

300 req/min por IP global. Rotas críticas têm bypass.

Auth

POST /auth/register

Cadastra novo usuário e envia código de verificação por e-mail.

Request

{
  "name": "João Silva",
  "email": "joao@example.com",
  "password": "minhasenha123",
  "ref": "16193"  // optional, displayId of referrer
}

Response 201

{
  "user": { "id": "...", "displayId": 16213, "email": "joao@example.com" },
  "needsVerification": true
}
POST /auth/login

Autenticação por e-mail + senha. Retorna JWT.

Request

{ "email": "joao@example.com", "password": "minhasenha123" }

Response 200

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6...",
  "user": { "id": "...", "displayId": 16213, "name": "João" }
}
POST /auth/verify

Confirma código de 6 dígitos. Auto-login após sucesso.

Request

{ "email": "joao@example.com", "code": "123456" }
POST /auth/forgot-password

Envia link de reset por e-mail.

Request

{ "email": "joao@example.com" }
GET /auth/me

Perfil autenticado.

Response 200

{
  "id": "...",
  "displayId": 16213,
  "name": "João",
  "email": "joao@example.com",
  "walletBalance": 47.50,
  "freeMinutes": 60,
  "ingooPoints": 12,
  "referralCount": 2
}

Rentals

POST /rentals/start

Inicia aluguel após escanear QR Code.

Request

{ "qrCode": "INGOO-B00001929R-01", "machineId": "..." }

Response 201

{
  "rentalId": "...",
  "powerBankId": "PB-1234",
  "depositAmount": 5,
  "startedAt": "2026-05-06T13:42:11Z"
}
GET /rentals/active

Aluguel em andamento.

GET /rentals/history

Histórico paginado.

Payments

POST /payments/pix

Gera QR Code PIX + copia-cola.

Request

{ "amount": 50 }

Response 201

{
  "paymentId": "MP-...",
  "pixQrCode": "data:image/png;base64,...",
  "pixCopyPaste": "00020126580014BR.GOV.BCB.PIX...",
  "expiresAt": "2026-05-06T14:00:00Z",
  "amount": 50
}
POST /payments/card

Recarga via cartão.

POST /payments/withdraw

Saque PIX (refund FIFO).

Request

{ "amount": 30, "pixKey": "joao@example.com", "pixKeyType": "EMAIL" }

Machines

GET /machines/nearby?lat=−22.97&lng=−43.18&radius=50000

radius em metros (até 50000).

GET /machines/:id/status

Estado em tempo real.

Friends

POST /friends/request

Envia pedido de amizade.

Request

{ "displayId": 16193 }
GET /friends

Amigos + pedidos.

POST /transfer

Transferência entre amigos. Limite anti-fraude.

Request

{ "toUserId": "...", "amount": 10 }

Gamification

GET /gamification/ranking/monthly

Ranking anual nacional.

Response 200

{
  "year": 2026,
  "period": "yearly",
  "monthStart": "2026-01-01T00:00:00Z",
  "monthEnd": "2027-01-01T00:00:00Z",
  "top": [
    {
      "position": 1,
      "userId": "...", "displayId": 1,
      "name": "Diogo", "photoUrl": "...",
      "city": "Rio de Janeiro",
      "anonymous": false,
      "total": 320.50
    }
  ],
  "me": { "position": 47, "total": 12.00 }
}
PATCH /gamification/ranking/privacy

Toggle modo anônimo.

Request

{ "anonymous": true }

Webhooks

Webhooks com HMAC obrigatório:

Provedor URL
StripePOST /payments/stripe/webhook
Mercado PagoPOST /payments/mp/webhook

Idempotência garantida.