# API de Parceiros — Documentação Técnica

**Base URL:**
```
https://kealfidxmdzmskfwhuee.supabase.co/functions/v1
```

**Autenticação:**
Todas as requisições exigem o header:
```
Authorization: Bearer <PARTNER_API_KEY>
```

---

## Índice

1. [Listar Serviços](#1-listar-serviços)
2. [Listar Pacotes](#2-listar-pacotes)
3. [Buscar Cliente](#3-buscar-cliente)
4. [Criar Cliente](#4-criar-cliente)
5. [Criar Orçamento](#5-criar-orçamento)
6. [Gerar Cobrança](#6-gerar-cobrança)
7. [Códigos de Erro](#7-códigos-de-erro)

---

## 1. Listar Serviços

Retorna todos os tipos de serviço ativos.

**Endpoint:** `GET /partner-list-services`

**Resposta (200):**
```json
{
  "services": [
    {
      "id": "uuid",
      "name": "Maquiagem",
      "name_en": "Makeup",
      "name_es": "Maquillaje",
      "description": "Maquiagem profissional...",
      "description_en": "Professional makeup...",
      "description_es": "Maquillaje profesional..."
    }
  ]
}
```

---

## 2. Listar Pacotes

Retorna todos os pacotes ativos com preços e features.

**Endpoint:** `GET /partner-list-packages`

**Resposta (200):**
```json
{
  "packages": [
    {
      "id": "uuid",
      "name": "Pacote Noiva",
      "name_en": "Bride Package",
      "name_es": "Paquete Novia",
      "description": "Descrição do pacote...",
      "description_en": "Package description...",
      "description_es": "Descripción del paquete...",
      "price": 2500.00,
      "features": ["Item 1", "Item 2"],
      "features_en": ["Item 1", "Item 2"],
      "features_es": ["Item 1", "Item 2"],
      "image_url": "https://...",
      "extra_hairstyle_price": 200.00,
      "extra_makeup_price": 250.00
    }
  ]
}
```

---

## 3. Buscar Cliente

Busca um cliente pelo telefone ou pelo Instagram Scoped ID.

**Endpoint:** `GET /partner-lookup-client`

**Query Parameters (ao menos um obrigatório):**

| Parâmetro            | Tipo   | Obrigatório | Descrição                         |
|----------------------|--------|-------------|-----------------------------------|
| `phone`              | string | condicional | Telefone (ex: `+5511999999999`)   |
| `instagram_scoped_id`| string | condicional | IGSID do Instagram (15-20 dígitos)|

**Exemplo:**
```
GET /partner-lookup-client?phone=+5511999999999
GET /partner-lookup-client?instagram_scoped_id=6541234567890123
```

**Resposta — Cliente encontrado (200):**
```json
{
  "found": true,
  "client": {
    "id": "uuid",
    "name": "Maria Silva",
    "phone": "+5511999999999",
    "email": "maria@email.com",
    "instagram": "@maria",
    "instagram_scoped_id": "6541234567890123",
    "lead_status": "novo"
  }
}
```

**Resposta — Cliente não encontrado (200):**
```json
{
  "found": false
}
```

---

## 4. Criar Cliente

Registra um novo cliente no CRM.

**Endpoint:** `POST /partner-create-client`

**Body:**

| Campo                | Tipo   | Obrigatório | Descrição                          |
|----------------------|--------|-------------|------------------------------------|
| `name`               | string | ✅          | Nome completo                      |
| `phone`              | string | condicional | Telefone (obrigatório se não tiver IGSID) |
| `instagram_scoped_id`| string | condicional | IGSID (obrigatório se não tiver phone)    |
| `email`              | string | ❌          | E-mail                             |
| `instagram`          | string | ❌          | @ do Instagram                     |

**Exemplo:**
```json
{
  "name": "Maria Silva",
  "phone": "+5511999999999",
  "email": "maria@email.com",
  "instagram": "@mariasilva"
}
```

**Resposta (201):**
```json
{
  "id": "uuid",
  "name": "Maria Silva",
  "phone": "+5511999999999",
  "instagram_scoped_id": null
}
```

---

## 5. Criar Orçamento

Cria um orçamento vinculado a um cliente, opcionalmente criando um evento.

**Endpoint:** `POST /partner-create-budget`

**Body:**

| Campo                    | Tipo     | Obrigatório | Descrição                                      |
|--------------------------|----------|-------------|-------------------------------------------------|
| `client_id`              | uuid     | ✅          | ID do cliente (obtido via lookup ou create)      |
| `packages`               | array    | ✅          | Lista de pacotes (mínimo 1)                      |
| `packages[].package_id`  | uuid     | ✅          | ID do pacote                                     |
| `packages[].quantity`    | number   | ❌          | Quantidade (default: 1)                          |
| `packages[].custom_price`| number   | ❌          | Preço customizado (sobrescreve preço do pacote)  |
| `event_date`             | string   | ❌          | Data do evento (YYYY-MM-DD). Se informado, cria evento |
| `event_type_id`          | uuid     | ❌          | Tipo de evento                                   |
| `address`                | string   | ❌          | Endereço do evento                               |
| `extra_hairstyle_count`  | number   | ❌          | Qtd de penteados extras (default: 0)             |
| `extra_makeup_count`     | number   | ❌          | Qtd de maquiagens extras (default: 0)            |
| `extra_hairstyle_price`  | number   | ❌          | Preço unitário do penteado extra                 |
| `extra_makeup_price`     | number   | ❌          | Preço unitário da maquiagem extra                |
| `valid_until`            | string   | ❌          | Data de validade do orçamento (YYYY-MM-DD)       |
| `notes`                  | string   | ❌          | Observações internas                             |
| `service_description`    | string   | ❌          | Descrição dos serviços (texto livre)             |
| `language`               | string   | ❌          | Idioma: `pt-BR`, `en`, `es` (default: `pt-BR`)  |
| `currency`               | string   | ❌          | Moeda: `BRL`, `USD`, `EUR` (default: `BRL`)      |

**Exemplo:**
```json
{
  "client_id": "abc-123-uuid",
  "event_date": "2026-06-15",
  "event_type_id": "uuid-casamento",
  "packages": [
    { "package_id": "uuid-pacote-noiva", "quantity": 1 },
    { "package_id": "uuid-pacote-madrinha", "quantity": 3, "custom_price": 350.00 }
  ],
  "extra_makeup_count": 2,
  "extra_makeup_price": 250.00,
  "valid_until": "2026-03-30",
  "service_description": "Maquiagem e penteado para noiva + 3 madrinhas",
  "language": "pt-BR",
  "currency": "BRL"
}
```

**Resposta (201):**
```json
{
  "budget_id": "uuid",
  "unique_code": "A1B2C3D4",
  "public_url": "https://thaisalmeida.art/orcamento/A1B2C3D4",
  "event_id": "uuid-or-null"
}
```

---

## 6. Gerar Cobrança

Registra um pagamento no CRM e gera a cobrança automaticamente no gateway Asaas (PIX, Boleto ou Cartão de Crédito).

**Endpoint:** `POST /partner-create-charge`

**Body:**

| Campo                | Tipo   | Obrigatório | Descrição                                           |
|----------------------|--------|-------------|-----------------------------------------------------|
| `client_id`          | uuid   | ✅          | ID do cliente                                        |
| `amount`             | number | ✅          | Valor da cobrança (ex: 1500.00)                      |
| `payment_type`       | string | ✅          | Tipo: `sinal`, `parcela`, `pagamento_final`, `pagamento_unico`, `adicional` |
| `billing_type`       | string | ✅          | Forma de pagamento: `PIX`, `BOLETO`, `CREDIT_CARD`   |
| `description`        | string | ❌          | Descrição (auto-gerada para parcelas se omitida)     |
| `due_date`           | string | ❌          | Data de vencimento YYYY-MM-DD (default: hoje)        |
| `currency`           | string | ❌          | Moeda (default: `BRL`)                               |
| `contract_id`        | uuid   | ❌          | ID do contrato vinculado                             |
| `installment_number` | number | condicional | Número da parcela (obrigatório se `payment_type = parcela`) |
| `total_installments` | number | condicional | Total de parcelas (obrigatório se `payment_type = parcela`) |
| `notes`              | string | ❌          | Observações internas                                 |

### Tipos de Pagamento

| Valor              | Descrição                        |
|--------------------|----------------------------------|
| `sinal`            | Sinal / Entrada                  |
| `parcela`          | Parcela (requer número e total)  |
| `pagamento_final`  | Pagamento final / Saldo restante |
| `pagamento_unico`  | Pagamento único / À vista        |
| `adicional`        | Serviço adicional                |

### Formas de Pagamento

| Valor         | Descrição         | Retorno extra        |
|---------------|-------------------|----------------------|
| `PIX`         | PIX instantâneo   | QR Code + código Pix |
| `BOLETO`      | Boleto bancário   | URL do boleto        |
| `CREDIT_CARD` | Cartão de crédito | URL de pagamento     |

**Exemplo — Pagamento PIX único:**
```json
{
  "client_id": "abc-123-uuid",
  "amount": 2500.00,
  "payment_type": "pagamento_unico",
  "billing_type": "PIX",
  "description": "Pacote Noiva Completo",
  "due_date": "2026-03-15"
}
```

**Exemplo — Parcela com Boleto:**
```json
{
  "client_id": "abc-123-uuid",
  "amount": 833.33,
  "payment_type": "parcela",
  "billing_type": "BOLETO",
  "installment_number": 1,
  "total_installments": 3,
  "due_date": "2026-03-01",
  "contract_id": "uuid-contrato"
}
```

**Exemplo — Sinal com Cartão:**
```json
{
  "client_id": "abc-123-uuid",
  "amount": 500.00,
  "payment_type": "sinal",
  "billing_type": "CREDIT_CARD",
  "description": "Sinal - Pacote Madrinhas"
}
```

**Resposta (200):**
```json
{
  "payment_id": "uuid",
  "asaas_payment_id": "pay_abc123def456",
  "status": "PENDING",
  "invoice_url": "https://www.asaas.com/i/abc123",
  "pix_qrcode": "data:image/png;base64,...",
  "pix_code": "00020126580014br.gov.bcb.pix...",
  "billing_type": "PIX",
  "amount": 2500.00
}
```

> **Nota:** `pix_qrcode` e `pix_code` só são retornados quando `billing_type = "PIX"`. Para `BOLETO` e `CREDIT_CARD`, use o `invoice_url` para redirecionar o cliente ao pagamento.

---

## 7. Códigos de Erro

Todos os endpoints retornam erros no formato:
```json
{
  "error": "Mensagem descritiva do erro"
}
```

| HTTP Status | Significado                                           |
|-------------|-------------------------------------------------------|
| `400`       | Parâmetros inválidos ou ausentes                      |
| `401`       | API key inválida ou ausente                           |
| `404`       | Recurso não encontrado (cliente, pacote, etc.)        |
| `405`       | Método HTTP não permitido                             |
| `500`       | Erro interno do servidor                              |

---

## Fluxo Completo Recomendado

```
1. GET  /partner-list-packages        → Obter pacotes disponíveis
2. GET  /partner-list-services         → Obter serviços disponíveis
3. GET  /partner-lookup-client?phone=  → Verificar se cliente já existe
4. POST /partner-create-client         → Criar cliente (se não existir)
5. POST /partner-create-budget         → Criar orçamento com pacotes
6. POST /partner-create-charge         → Gerar cobrança (PIX/Boleto/Cartão)
```

---

## Notas Técnicas

- **IGSID (Instagram Scoped ID):** Identificador único de 15-20 dígitos fornecido pela Meta para cada usuário que interage via Instagram DM. Útil para bots de automação.
- **Sandbox vs Produção:** O sistema detecta automaticamente se está em sandbox ou produção pela API key do Asaas (prefixo `$aact_` = produção).
- **Webhooks Asaas:** Pagamentos confirmados são atualizados automaticamente via webhook no CRM. O parceiro não precisa implementar polling.
- **Moedas:** O sistema suporta `BRL`, `USD` e `EUR`, porém cobranças via Asaas são apenas em `BRL`.
- **Idiomas:** Orçamentos suportam `pt-BR`, `en` e `es` para a página pública.