> ## Documentation Index
> Fetch the complete documentation index at: https://docs.assessiq.digital/llms.txt
> Use this file to discover all available pages before exploring further.

# Cobranças

> Endpoints para gerenciar cobranças de atribuições de teste (integração Asaas).

## GET /api/mobile/payments

Lista todas as cobranças da organização com estatísticas resumidas. **Requer role `ADMIN` ou `SUPER_ADMIN`.**

### Query Params

| Param      | Tipo   | Descrição                                                    |
| ---------- | ------ | ------------------------------------------------------------ |
| `page`     | number | Página (padrão: `1`)                                         |
| `pageSize` | number | Itens por página, máx. 50 (padrão: `20`)                     |
| `status`   | string | Filtrar por status: `pending`, `paid`, `exempt`, `cancelled` |

### Resposta

```json theme={null}
{
  "data": [
    {
      "id": "assign_id",
      "paymentStatus": "pending",
      "paymentMethod": "PIX",
      "paymentAmount": 50.00,
      "paymentId": "pay_asaas_id",
      "paymentLink": "https://sandbox.asaas.com/c/abc123",
      "paidAt": null,
      "createdAt": "2026-04-01T10:00:00.000Z",
      "form": { "id": "form_id", "title": "Avaliação Funcional" },
      "student": { "id": "student_id", "name": "Ana Lima" },
      "candidate": null,
      "teacher": { "id": "teacher_id", "name": "João Silva" }
    }
  ],
  "stats": {
    "pending": 12,
    "paid": 38,
    "totalCollected": 1900.00
  },
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "total": 50,
    "totalPages": 3
  }
}
```

***

## GET /api/mobile/assignments/:id/payment

Retorna o status de pagamento de uma atribuição específica.

### Resposta

```json theme={null}
{
  "paymentRequired": true,
  "paymentStatus": "pending",
  "paymentMethod": "PIX",
  "paymentAmount": 50.00,
  "paymentLink": "https://sandbox.asaas.com/c/abc123",
  "paymentQrCode": "data:image/png;base64,...",
  "paymentQrCodeText": "00020101021226870014br.gov.bcb...",
  "paymentId": "pay_asaas_id",
  "paidAt": null
}
```

***

## POST /api/mobile/assignments/:id/payment

Cria uma cobrança para a atribuição. Pode ser via **Asaas** (PIX, cartão de crédito, boleto) ou **método externo** (PIX externo, cartão externo). **Requer role `ADMIN` ou `SUPER_ADMIN`.**

### Body

```json theme={null}
{
  "method": "PIX",
  "amount": 50.00
}
```

| Campo    | Tipo   | Valores aceitos                                                                              |
| -------- | ------ | -------------------------------------------------------------------------------------------- |
| `method` | string | `PIX`, `CREDIT_CARD`, `BOLETO`, `PIX_EXTERNO`, `CARD_EXTERNO_CREDITO`, `CARD_EXTERNO_DEBITO` |
| `amount` | number | Valor em reais (ex.: `50.00`)                                                                |

### Resposta — Asaas PIX

```json theme={null}
{
  "ok": true,
  "paymentStatus": "pending",
  "paymentMethod": "PIX",
  "paymentAmount": 50.00,
  "paymentLink": "https://sandbox.asaas.com/c/abc123",
  "paymentQrCode": "data:image/png;base64,...",
  "paymentQrCodeText": "00020101021226870014br.gov.bcb..."
}
```

### Resposta — método externo

```json theme={null}
{
  "ok": true,
  "paymentStatus": "pending",
  "paymentMethod": "PIX_EXTERNO",
  "paymentAmount": 50.00
}
```

***

## POST /api/mobile/assignments/:id/payment/confirm

Confirma manualmente o pagamento de uma atribuição (registra como `paid` com método `cash`). **Requer role `ADMIN` ou `SUPER_ADMIN`.**

### Resposta

```json theme={null}
{ "ok": true }
```

***

## POST /api/mobile/assignments/:id/payment/exempt

Isenta o participante do pagamento (`paymentStatus: "exempt"`). O teste fica liberado sem cobrança. **Requer role `ADMIN` ou `SUPER_ADMIN`.**

### Resposta

```json theme={null}
{ "ok": true }
```

***

## POST /api/mobile/assignments/:id/payment/cancel

Cancela a cobrança. Se houver um `paymentId` Asaas vinculado, a cobrança é cancelada na plataforma. Os campos de pagamento são resetados. **Requer role `ADMIN` ou `SUPER_ADMIN`.**

> Não é possível cancelar pagamentos já confirmados (`paid`).

### Resposta

```json theme={null}
{ "ok": true }
```

***

## POST /api/mobile/assignments/:id/payment/sync

Sincroniza o status da cobrança com o Asaas. Útil quando o webhook não foi recebido ou o status está desatualizado. **Requer role `ADMIN` ou `SUPER_ADMIN`.**

> Requer que a atribuição tenha um `paymentId` vinculado.

### Resposta

```json theme={null}
{
  "ok": true,
  "status": "paid",
  "paidAt": "2026-04-01T14:30:00.000Z"
}
```

***

## Status de Pagamento

| Valor       | Descrição                             |
| ----------- | ------------------------------------- |
| `pending`   | Cobrança criada, aguardando pagamento |
| `paid`      | Pagamento confirmado                  |
| `exempt`    | Isento — teste liberado sem cobrança  |
| `cancelled` | Cobrança cancelada                    |

***

## Webhook Asaas

O endpoint `POST /api/webhooks/asaas` recebe notificações de pagamento do Asaas e atualiza automaticamente o `paymentStatus` da atribuição para `paid` quando o evento `PAYMENT_RECEIVED` ou `PAYMENT_CONFIRMED` é recebido.