{
  "openapi": "3.1.0",
  "info": {
    "title": "API do Clube Bis",
    "version": "1",
    "description": "API do **Clube Bis**: o clube de assinatura oferecido na página de confirmação de compra das ticketeiras.\n\nPara integrar sua plataforma, comece pelo [guia de integração](/integracao/). Esta referência é gerada a partir dos contratos (zod) da API.\n\n## Convenções\n\n- **Base**: `https://api.clubebis.com` (produção) e `https://api-dev.clubebis.com` (testes). Todas as rotas ficam sob `/v1`.\n- **Dinheiro** sempre em **centavos** inteiros (`999` = R$ 9,99). Nunca float.\n- **Datas** em texto ISO-8601 UTC (`2026-11-16T12:00:00.000Z`).\n- **JSON** em toda requisição e resposta, exceto `GET /v1/me/export` (arquivo) e `POST /v1/widget/events` (`text/plain`).\n- **Erros**: `{ \"error\": \"mensagem\", \"details\"?: … }`, com o status HTTP adequado: `400` validação, `401` autenticação, `403` origem/domínio, `404` ausente, `409` conflito, `410` sessão/token expirado, `429` limite de taxa, `5xx` erro do Bis.\n\n## Autenticação\n\n| Quem chama | Esquema | Onde |\n|---|---|---|\n| Servidor da ticketeira | HMAC: `X-Bis-Partner` + `X-Bis-Signature` | `/v1/sessions`, `/v1/partner/*` |\n| Widget (banner, card, `/assinar`) | `Authorization: Bearer <sessionToken>` | `/v1/sessions/offer`, `/v1/handoffs`, `/v1/sessions/card`, `/v1/payments/*` |\n| Assinante | `Authorization: Bearer <token>` | `/v1/me/*` |\n\nAs chaves (`widgetSecret`) são criadas e revogadas no painel do parceiro em **Configuração → Chaves de API**. Qualquer chave ativa vale, então dá para rotacionar sem downtime.\n\n## Limites de taxa\n\n| Rota | Limite |\n|---|---|\n| `POST /v1/sessions/auto` | 10 por minuto por (parceiro, IP) |\n| `POST /v1/handoffs` | 10 por minuto por pedido |\n| `GET /v1/cashback/offers` | 60 por minuto por IP |\n\nAcima do limite a API responde `429`. Repita depois de alguns segundos.\n\nRotas internas (painel do parceiro, admin e o webhook do gateway de pagamento) não fazem parte desta referência.",
    "contact": {
      "name": "Clube Bis",
      "url": "https://clubebis.com"
    }
  },
  "servers": [
    {
      "url": "https://api-dev.clubebis.com",
      "description": "Desenvolvimento (testes)"
    },
    {
      "url": "https://api.clubebis.com",
      "description": "Produção"
    }
  ],
  "tags": [
    {
      "name": "Parceiro (servidor)",
      "description": "Chamadas do servidor da ticketeira, assinadas com HMAC."
    },
    {
      "name": "Sem código (bis-auto.js)",
      "description": "Integração por uma tag, sem servidor."
    },
    {
      "name": "Widget (sessionToken)",
      "description": "Usadas pelo loader, pelo banner/card e pela página `/assinar`. Você não precisa chamar estas rotas: o widget cuida."
    },
    {
      "name": "Cashback",
      "description": "Ofertas de lojas parceiras."
    },
    {
      "name": "Assinante",
      "description": "Login sem senha e área do assinante (`app.clubebis.com`)."
    },
    {
      "name": "Webhooks",
      "description": "Eventos que o Bis envia ao parceiro."
    },
    {
      "name": "Saúde"
    }
  ],
  "components": {
    "securitySchemes": {
      "PartnerId": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Bis-Partner",
        "description": "Id do parceiro (ex.: `prt_ticketandgo`). Sempre junto com `X-Bis-Signature`."
      },
      "PartnerSignature": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Bis-Signature",
        "description": "`HMAC-SHA256(widgetSecret, payload)` em hex (aceita o prefixo `sha256=`).\n\n- `POST`: payload = **corpo cru** da requisição (os mesmos bytes enviados).\n- `GET`: payload = `\"GET:<caminho+query>\"`, ex.: `GET:/v1/partner/reports/monthly?month=2026-11`.\n\nO `widgetSecret` fica **só no servidor** do parceiro. Qualquer chave ativa vale (rotação sem downtime)."
      },
      "SessionToken": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "sessionToken (opaco, AES-GCM, 30 min)",
        "description": "O `sessionToken` devolvido por `POST /v1/sessions` ou `POST /v1/sessions/auto`."
      },
      "MemberToken": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "token do assinante (7 dias)",
        "description": "O `token` devolvido por `POST /v1/auth/verify` ou `POST /v1/auth/magic`."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "Mensagem em pt-BR."
          },
          "details": {
            "description": "Detalhes da validação (zod `flatten()`), quando houver."
          }
        },
        "required": [
          "error"
        ],
        "description": "Formato de todo erro da API.",
        "example": {
          "error": "assinatura inválida"
        }
      },
      "CreateSessionRequest": {
        "type": "object",
        "properties": {
          "partnerId": {
            "type": "string",
            "minLength": 1
          },
          "orderRef": {
            "type": "string"
          },
          "amount": {
            "type": "integer"
          },
          "category": {
            "type": "string"
          },
          "city": {
            "type": "string"
          },
          "buyer": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "email": {
                "type": "string",
                "format": "email"
              },
              "phone": {
                "type": "string"
              },
              "cpf": {
                "type": "string",
                "pattern": "^\\d{11}$"
              }
            }
          }
        },
        "required": [
          "partnerId",
          "orderRef",
          "amount"
        ]
      },
      "CreateSessionResponse": {
        "type": "object",
        "properties": {
          "sessionToken": {
            "type": "string"
          },
          "show": {
            "type": "boolean"
          }
        },
        "required": [
          "sessionToken",
          "show"
        ]
      },
      "AutoSessionRequest": {
        "type": "object",
        "properties": {
          "partnerId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64
          },
          "orderRef": {
            "type": "string",
            "pattern": "^[A-Za-z0-9][A-Za-z0-9._\\/#-]{2,63}$"
          },
          "amount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100000000
          }
        },
        "required": [
          "partnerId",
          "orderRef"
        ]
      },
      "AutoSessionResponse": {
        "type": "object",
        "properties": {
          "sessionToken": {
            "type": "string"
          },
          "show": {
            "type": "boolean"
          },
          "verified": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        },
        "required": [
          "sessionToken",
          "show",
          "verified"
        ]
      },
      "OrderConfirmRequest": {
        "type": "object",
        "properties": {
          "partnerId": {
            "type": "string",
            "minLength": 1
          },
          "orders": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "orderRef": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 128
                },
                "buyerEmail": {
                  "type": "string",
                  "format": "email"
                }
              },
              "required": [
                "orderRef"
              ]
            },
            "minItems": 1,
            "maxItems": 500
          }
        },
        "required": [
          "partnerId",
          "orders"
        ]
      },
      "CardContent": {
        "type": "object",
        "properties": {
          "partnerName": {
            "type": "string"
          },
          "headline": {
            "type": "string"
          },
          "introPriceLabel": {
            "type": "string"
          },
          "monthlyPriceLabel": {
            "type": "string"
          },
          "prizeLabel": {
            "type": "string"
          },
          "variant": {
            "type": "string"
          },
          "verified": {
            "type": "boolean"
          },
          "creditCents": {
            "type": "integer"
          },
          "prefilled": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "email": {
                "type": "string",
                "format": "email"
              },
              "phone": {
                "type": "string"
              },
              "cpf": {
                "type": "string",
                "pattern": "^\\d{11}$"
              }
            }
          }
        },
        "required": [
          "partnerName",
          "headline",
          "introPriceLabel",
          "monthlyPriceLabel",
          "prizeLabel",
          "variant",
          "prefilled"
        ]
      },
      "OfferDisplay": {
        "type": "string",
        "enum": [
          "banner",
          "card"
        ]
      },
      "OfferSummary": {
        "type": "object",
        "properties": {
          "display": {
            "type": "string",
            "enum": [
              "banner",
              "card"
            ]
          },
          "partnerName": {
            "type": "string"
          },
          "creditCents": {
            "type": "integer"
          },
          "creditLabel": {
            "type": "string"
          },
          "variant": {
            "type": "string"
          },
          "orderRef": {
            "type": "string"
          },
          "verified": {
            "type": "boolean"
          }
        },
        "required": [
          "display",
          "partnerName",
          "creditCents",
          "creditLabel",
          "variant",
          "orderRef"
        ]
      },
      "HandoffResponse": {
        "type": "object",
        "properties": {
          "handoff": {
            "type": "string"
          },
          "expiresAt": {
            "type": "string"
          }
        },
        "required": [
          "handoff",
          "expiresAt"
        ]
      },
      "HandoffRedeemRequest": {
        "type": "object",
        "properties": {
          "handoff": {
            "type": "string",
            "minLength": 16,
            "maxLength": 128
          }
        },
        "required": [
          "handoff"
        ]
      },
      "HandoffRedeemResponse": {
        "type": "object",
        "properties": {
          "sessionToken": {
            "type": "string"
          },
          "card": {
            "type": "object",
            "properties": {
              "partnerName": {
                "type": "string"
              },
              "headline": {
                "type": "string"
              },
              "introPriceLabel": {
                "type": "string"
              },
              "monthlyPriceLabel": {
                "type": "string"
              },
              "prizeLabel": {
                "type": "string"
              },
              "variant": {
                "type": "string"
              },
              "verified": {
                "type": "boolean"
              },
              "creditCents": {
                "type": "integer"
              },
              "prefilled": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "phone": {
                    "type": "string"
                  },
                  "cpf": {
                    "type": "string",
                    "pattern": "^\\d{11}$"
                  }
                }
              }
            },
            "required": [
              "partnerName",
              "headline",
              "introPriceLabel",
              "monthlyPriceLabel",
              "prizeLabel",
              "variant",
              "prefilled"
            ]
          },
          "partnerId": {
            "type": "string"
          },
          "orderRef": {
            "type": "string"
          }
        },
        "required": [
          "sessionToken",
          "card"
        ]
      },
      "JoinRequest": {
        "type": "object",
        "properties": {
          "sessionToken": {
            "type": "string"
          },
          "paymentMethod": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "card",
                  "wallet",
                  "pix_automatico"
                ]
              },
              "gatewayToken": {
                "type": "string"
              }
            },
            "required": [
              "type",
              "gatewayToken"
            ]
          },
          "identity": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "email": {
                "type": "string",
                "format": "email"
              },
              "phone": {
                "type": "string"
              },
              "cpf": {
                "type": "string",
                "pattern": "^\\d{11}$"
              }
            },
            "required": [
              "name",
              "email",
              "phone",
              "cpf"
            ]
          },
          "consent": {
            "type": "object",
            "properties": {
              "terms": {
                "type": "boolean",
                "enum": [
                  true
                ]
              },
              "whatsappOptIn": {
                "type": "boolean"
              },
              "acceptedAt": {
                "type": "string",
                "format": "date-time"
              }
            },
            "required": [
              "terms",
              "whatsappOptIn",
              "acceptedAt"
            ]
          }
        },
        "required": [
          "sessionToken",
          "paymentMethod",
          "identity",
          "consent"
        ]
      },
      "JoinResponse": {
        "type": "object",
        "properties": {
          "memberId": {
            "type": "string",
            "minLength": 1
          },
          "subscriptionId": {
            "type": "string",
            "minLength": 1
          },
          "firstChargeAmount": {
            "type": "integer"
          },
          "nextFullChargeAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "memberId",
          "subscriptionId",
          "firstChargeAmount",
          "nextFullChargeAt"
        ]
      },
      "RequestCodeRequest": {
        "type": "object",
        "properties": {
          "identifier": {
            "type": "string"
          }
        },
        "required": [
          "identifier"
        ]
      },
      "VerifyCodeRequest": {
        "type": "object",
        "properties": {
          "identifier": {
            "type": "string"
          },
          "code": {
            "type": "string"
          }
        },
        "required": [
          "identifier",
          "code"
        ]
      },
      "MagicRequest": {
        "type": "object",
        "properties": {
          "token": {
            "type": "string"
          }
        },
        "required": [
          "token"
        ]
      },
      "MemberSession": {
        "type": "object",
        "properties": {
          "memberId": {
            "type": "string",
            "minLength": 1
          },
          "token": {
            "type": "string"
          }
        },
        "required": [
          "memberId",
          "token"
        ]
      },
      "MemberHome": {
        "type": "object",
        "properties": {
          "member": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "email": {
                "type": "string"
              }
            },
            "required": [
              "name",
              "email"
            ]
          },
          "subscription": {
            "type": "object",
            "properties": {
              "status": {
                "type": "string"
              },
              "nextChargeAt": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              },
              "nextChargeAmount": {
                "type": [
                  "integer",
                  "null"
                ]
              }
            },
            "required": [
              "status",
              "nextChargeAt",
              "nextChargeAmount"
            ]
          },
          "credit": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "amount": {
                "type": "integer"
              },
              "coupon": {
                "type": "string"
              },
              "expiresAt": {
                "type": "string",
                "format": "date-time"
              }
            },
            "required": [
              "amount",
              "coupon",
              "expiresAt"
            ]
          },
          "luckyNumber": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "month": {
                "type": "string"
              },
              "number": {
                "type": "string"
              }
            },
            "required": [
              "month",
              "number"
            ]
          },
          "purchaseVerification": {
            "type": "string",
            "enum": [
              "pending",
              "verified"
            ]
          }
        },
        "required": [
          "member",
          "subscription",
          "credit",
          "luckyNumber"
        ]
      },
      "MemberDraw": {
        "type": "object",
        "properties": {
          "month": {
            "type": "string"
          },
          "number": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "open",
              "drawn"
            ]
          },
          "result": {
            "type": "object",
            "properties": {
              "winningNumber": {
                "type": "string"
              },
              "won": {
                "type": "boolean"
              }
            },
            "required": [
              "winningNumber",
              "won"
            ]
          }
        },
        "required": [
          "month",
          "number",
          "status"
        ]
      },
      "PaymentInfo": {
        "type": "object",
        "properties": {
          "method": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "card",
                  "wallet",
                  "pix_automatico"
                ]
              },
              "label": {
                "type": "string"
              }
            },
            "required": [
              "type",
              "label"
            ]
          },
          "charges": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "date": {
                  "type": "string",
                  "format": "date-time"
                },
                "amount": {
                  "type": "integer"
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "paid",
                    "failed",
                    "refunded",
                    "pending"
                  ]
                },
                "invoiceUrl": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "date",
                "amount",
                "status"
              ]
            }
          }
        },
        "required": [
          "method",
          "charges"
        ]
      },
      "HostedSession": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string"
          }
        },
        "required": [
          "url"
        ]
      },
      "Profile": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "email": {
            "type": "string"
          },
          "phone": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "name",
          "email",
          "phone"
        ]
      },
      "Preferences": {
        "type": "object",
        "properties": {
          "whatsappOptIn": {
            "type": "boolean"
          },
          "emailReminders": {
            "type": "boolean"
          },
          "phone": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "whatsappOptIn",
          "emailReminders",
          "phone"
        ]
      },
      "CancelRequest": {
        "type": "object",
        "properties": {
          "channel": {
            "type": "string",
            "enum": [
              "app",
              "whatsapp",
              "email",
              "admin"
            ]
          },
          "reason": {
            "type": "string"
          }
        },
        "required": [
          "channel"
        ]
      },
      "CancelResponse": {
        "type": "object",
        "properties": {
          "canceledAt": {
            "type": "string",
            "format": "date-time"
          },
          "protocol": {
            "type": "string"
          }
        },
        "required": [
          "canceledAt",
          "protocol"
        ]
      },
      "PartnerMonthlyReport": {
        "type": "object",
        "properties": {
          "month": {
            "type": "string"
          },
          "ordersEligible": {
            "type": "integer"
          },
          "cardsShown": {
            "type": "integer"
          },
          "joins": {
            "type": "integer"
          },
          "activeMembers": {
            "type": "integer"
          },
          "payoutPreview": {
            "type": "integer"
          }
        },
        "required": [
          "month",
          "ordersEligible",
          "cardsShown",
          "joins",
          "activeMembers",
          "payoutPreview"
        ]
      },
      "PartnerPayout": {
        "type": "object",
        "properties": {
          "month": {
            "type": "string"
          },
          "commission": {
            "type": "integer"
          },
          "bonuses": {
            "type": "integer"
          },
          "creditsReimbursed": {
            "type": "integer"
          },
          "refunds": {
            "type": "integer"
          },
          "total": {
            "type": "integer"
          }
        },
        "required": [
          "month",
          "commission",
          "bonuses",
          "creditsReimbursed",
          "refunds",
          "total"
        ]
      },
      "CashbackOffersResponse": {
        "type": "object",
        "properties": {
          "offers": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "store": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "logoUrl": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  },
                  "required": [
                    "id",
                    "name",
                    "logoUrl"
                  ]
                },
                "title": {
                  "type": "string"
                },
                "category": {
                  "type": [
                    "object",
                    "null"
                  ],
                  "properties": {
                    "slug": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "slug",
                    "name"
                  ]
                },
                "benefit": {
                  "type": "object",
                  "properties": {
                    "kind": {
                      "type": "string",
                      "enum": [
                        "percent",
                        "amount",
                        "discount"
                      ]
                    },
                    "percent": {
                      "type": [
                        "number",
                        "null"
                      ]
                    },
                    "amountCents": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    },
                    "label": {
                      "type": "string"
                    },
                    "conditions": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  },
                  "required": [
                    "kind",
                    "percent",
                    "amountCents",
                    "label",
                    "conditions"
                  ]
                },
                "discountLabel": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "couponCode": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "image": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "validUntil": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "url": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "store",
                "title",
                "category",
                "benefit",
                "discountLabel",
                "couponCode",
                "image",
                "validUntil",
                "url"
              ]
            }
          },
          "page": {
            "type": "integer"
          },
          "total": {
            "type": "integer"
          },
          "hasMore": {
            "type": "boolean"
          },
          "publishedAt": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "offers",
          "page",
          "total",
          "hasMore",
          "publishedAt"
        ]
      },
      "AutoDetectRules": {
        "type": "object",
        "properties": {
          "host": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "urlPattern": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "textMarker": {
            "type": "string",
            "maxLength": 200
          },
          "selectorMarker": {
            "type": "string",
            "maxLength": 300
          },
          "dataLayerEvent": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_.:-]{1,64}$"
          },
          "orderRef": {
            "type": "object",
            "properties": {
              "selector": {
                "type": "string",
                "maxLength": 300
              },
              "label": {
                "type": "string",
                "maxLength": 100
              },
              "urlSegment": {
                "type": "integer",
                "minimum": -10,
                "maximum": 10
              },
              "pattern": {
                "type": "string",
                "minLength": 1,
                "maxLength": 200
              }
            },
            "required": [
              "pattern"
            ]
          },
          "amount": {
            "type": "object",
            "properties": {
              "selector": {
                "type": "string",
                "maxLength": 300
              },
              "label": {
                "type": "string",
                "maxLength": 100
              }
            }
          },
          "anchor": {
            "type": "object",
            "properties": {
              "selector": {
                "type": "string",
                "maxLength": 300
              },
              "text": {
                "type": "string",
                "maxLength": 200
              },
              "up": {
                "type": "integer",
                "minimum": 0,
                "maximum": 5
              },
              "position": {
                "type": "string",
                "enum": [
                  "after",
                  "before",
                  "append"
                ]
              }
            }
          }
        },
        "required": [
          "urlPattern",
          "orderRef",
          "anchor"
        ]
      },
      "BisEvent": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "member.joined"
                ]
              },
              "memberId": {
                "type": "string",
                "minLength": 1
              },
              "partnerId": {
                "type": "string",
                "minLength": 1
              },
              "at": {
                "type": "string"
              }
            },
            "required": [
              "type",
              "memberId",
              "partnerId",
              "at"
            ]
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "subscription.activated"
                ]
              },
              "subscriptionId": {
                "type": "string",
                "minLength": 1
              },
              "memberId": {
                "type": "string",
                "minLength": 1
              },
              "at": {
                "type": "string"
              }
            },
            "required": [
              "type",
              "subscriptionId",
              "memberId",
              "at"
            ]
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "subscription.canceled"
                ]
              },
              "subscriptionId": {
                "type": "string",
                "minLength": 1
              },
              "memberId": {
                "type": "string",
                "minLength": 1
              },
              "at": {
                "type": "string"
              }
            },
            "required": [
              "type",
              "subscriptionId",
              "memberId",
              "at"
            ]
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "credit.issued"
                ]
              },
              "creditId": {
                "type": "string",
                "minLength": 1
              },
              "memberId": {
                "type": "string",
                "minLength": 1
              },
              "partnerId": {
                "type": "string",
                "minLength": 1
              },
              "coupon": {
                "type": "string"
              },
              "amount": {
                "type": "integer"
              },
              "expiresAt": {
                "type": "string"
              }
            },
            "required": [
              "type",
              "creditId",
              "memberId",
              "partnerId",
              "coupon",
              "amount",
              "expiresAt"
            ]
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "credit.redeemed"
                ]
              },
              "creditId": {
                "type": "string",
                "minLength": 1
              },
              "orderRef": {
                "type": "string"
              },
              "at": {
                "type": "string"
              }
            },
            "required": [
              "type",
              "creditId",
              "orderRef",
              "at"
            ]
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "credit.expired"
                ]
              },
              "creditId": {
                "type": "string",
                "minLength": 1
              },
              "at": {
                "type": "string"
              }
            },
            "required": [
              "type",
              "creditId",
              "at"
            ]
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "payout.ready"
                ]
              },
              "partnerId": {
                "type": "string",
                "minLength": 1
              },
              "month": {
                "type": "string"
              },
              "total": {
                "type": "integer"
              }
            },
            "required": [
              "type",
              "partnerId",
              "month",
              "total"
            ]
          }
        ]
      },
      "AutoConfigPublic": {
        "type": "object",
        "properties": {
          "partnerId": {
            "type": "string"
          },
          "enabled": {
            "type": "boolean"
          },
          "rules": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/AutoDetectRules"
              },
              {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/AutoDetectRules"
                },
                "minItems": 1,
                "maxItems": 5
              },
              {
                "type": "null"
              }
            ]
          },
          "display": {
            "$ref": "#/components/schemas/OfferDisplay"
          }
        },
        "required": [
          "partnerId",
          "enabled",
          "rules"
        ]
      },
      "OrderConfirmResponse": {
        "type": "object",
        "properties": {
          "results": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "orderRef": {
                  "type": "string"
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "confirmed",
                    "already_confirmed",
                    "email_mismatch"
                  ]
                },
                "released": {
                  "type": "boolean",
                  "description": "true quando benefícios retidos foram liberados agora."
                }
              },
              "required": [
                "orderRef",
                "status"
              ]
            }
          }
        },
        "required": [
          "results"
        ]
      },
      "WidgetEvent": {
        "type": "object",
        "properties": {
          "sessionToken": {
            "type": "string"
          },
          "event": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "shown",
                  "viewed",
                  "clicked",
                  "joined",
                  "error",
                  "modal_shown",
                  "modal_dismissed"
                ]
              },
              "code": {
                "type": "string",
                "description": "Só em `error`: código curto, sem dado pessoal."
              }
            },
            "required": [
              "type"
            ]
          }
        },
        "required": [
          "sessionToken",
          "event"
        ]
      }
    },
    "parameters": {}
  },
  "paths": {
    "/health": {
      "get": {
        "tags": [
          "Saúde"
        ],
        "summary": "Saúde da API",
        "description": "Sem auth. Fora do prefixo `/v1`.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "env": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "ok",
                    "env"
                  ]
                },
                "example": {
                  "ok": true,
                  "env": "production"
                }
              }
            }
          }
        }
      }
    },
    "/v1/sessions": {
      "post": {
        "tags": [
          "Parceiro (servidor)"
        ],
        "summary": "Abrir a sessão do pedido",
        "description": "Chamado pelo **servidor** da ticketeira na confirmação do pedido. Idempotente por `orderRef`.\n\nAssine o **corpo cru** com o `widgetSecret` (ver *Autenticação*). `amount` em centavos.\nSem `buyer.name + email + phone + cpf` a página do Bis pede os dados ao comprador.\n\n`show=false`: o pedido caiu fora da amostra do piloto. Não embuta o widget.",
        "security": [
          {
            "PartnerId": [],
            "PartnerSignature": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateSessionRequest"
              },
              "example": {
                "partnerId": "prt_ticketandgo",
                "orderRef": "TNG-480231",
                "amount": 12000,
                "category": "show",
                "city": "São Paulo",
                "buyer": {
                  "name": "Tua Mãe Aquela Ursa",
                  "email": "ursa@tuamaeaquelaursa.com",
                  "phone": "+55 11 90000-0000",
                  "cpf": "52998224725"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Sessão aberta.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateSessionResponse"
                },
                "example": {
                  "sessionToken": "v1.Zk3x…(opaco)…q9A",
                  "show": true
                }
              }
            }
          },
          "400": {
            "description": "Validação falhou (corpo ou query fora do contrato).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "validação falhou"
                }
              }
            }
          },
          "401": {
            "description": "Assinatura ausente, inválida ou `partnerId` divergente do cabeçalho.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "partnerId divergente da assinatura"
                }
              }
            }
          }
        }
      }
    },
    "/v1/partner/orders/confirm": {
      "post": {
        "tags": [
          "Parceiro (servidor)"
        ],
        "summary": "Confirmar pedidos (destrava adesões sem código)",
        "description": "Confirma que os pedidos existem e foram pagos. Destrava crédito, número da sorte e bônus das adesões\nfeitas pelo modo sem código (`bis-auto.js`). Mesmo HMAC do `POST /v1/sessions` (corpo cru).\n\nAté **500** pedidos por chamada. Aceita pedidos que ainda não têm adesão (a adesão futura já nasce destravada).\n`buyerEmail` é opcional; se não bater com o e-mail do assinante, o status é `email_mismatch` e a adesão continua pendente.",
        "security": [
          {
            "PartnerId": [],
            "PartnerSignature": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OrderConfirmRequest"
              },
              "example": {
                "partnerId": "prt_ticketandgo",
                "orders": [
                  {
                    "orderRef": "TNG-8F3K2Q",
                    "buyerEmail": "ursa@tuamaeaquelaursa.com"
                  },
                  {
                    "orderRef": "TNG-9J4L1R"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resultado por pedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderConfirmResponse"
                },
                "example": {
                  "results": [
                    {
                      "orderRef": "TNG-8F3K2Q",
                      "status": "confirmed",
                      "released": true
                    },
                    {
                      "orderRef": "TNG-9J4L1R",
                      "status": "already_confirmed"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Validação falhou (corpo ou query fora do contrato).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "validação falhou"
                }
              }
            }
          },
          "401": {
            "description": "Assinatura ausente, inválida ou `partnerId` divergente.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "partnerId divergente da assinatura"
                }
              }
            }
          }
        }
      }
    },
    "/v1/partner/reports/monthly": {
      "get": {
        "tags": [
          "Parceiro (servidor)"
        ],
        "summary": "Relatório mensal do funil",
        "description": "Assine a string `GET:/v1/partner/reports/monthly?month=YYYY-MM`. Valores em centavos.",
        "security": [
          {
            "PartnerId": [],
            "PartnerSignature": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}$",
              "example": "2026-11"
            },
            "required": true,
            "name": "month",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Contadores + prévia do repasse.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerMonthlyReport"
                },
                "example": {
                  "month": "2026-11",
                  "ordersEligible": 42,
                  "cardsShown": 9,
                  "joins": 3,
                  "activeMembers": 3,
                  "payoutPreview": 450
                }
              }
            }
          },
          "401": {
            "description": "Assinatura ausente ou inválida.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "assinatura inválida"
                }
              }
            }
          }
        }
      }
    },
    "/v1/partner/payouts/{month}": {
      "get": {
        "tags": [
          "Parceiro (servidor)"
        ],
        "summary": "Extrato de repasse do mês",
        "description": "Assine `GET:/v1/partner/payouts/2026-11`. Valores em centavos.\n\n**Reembolsos.** Um estorno de mensalidade reverte a comissão (15%) proporcionalmente. O bônus de R$ 5 (dia 60)\né proporcional à parte não reembolsada da 1ª mensalidade cheia; estornos depois do dia 60 lançam um\n`bonus_clawback`. No extrato, o estorno aparece em `bonuses` (líquido) e em `refunds`.",
        "security": [
          {
            "PartnerId": [],
            "PartnerSignature": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}$",
              "example": "2026-11"
            },
            "required": true,
            "name": "month",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Extrato.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerPayout"
                },
                "example": {
                  "month": "2026-11",
                  "commission": 450,
                  "bonuses": 0,
                  "creditsReimbursed": 0,
                  "refunds": 0,
                  "total": 450
                }
              }
            }
          },
          "401": {
            "description": "Assinatura ausente ou inválida.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "assinatura inválida"
                }
              }
            }
          }
        }
      }
    },
    "/v1/partners/{id}/auto-config": {
      "get": {
        "tags": [
          "Sem código (bis-auto.js)"
        ],
        "summary": "Regras públicas de detecção",
        "description": "Lido pelo `bis-auto.js` na página do parceiro. Público, CORS aberto, `Cache-Control: public, max-age=300`.\nSem segredo nem dado pessoal. Desligado, sem regras ou parceiro inativo → `{ enabled: false, rules: null }`.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "example": "prt_palcoaberto"
            },
            "required": true,
            "name": "id",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Regras (ou desligado).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutoConfigPublic"
                },
                "example": {
                  "partnerId": "prt_palcoaberto",
                  "enabled": true,
                  "rules": {
                    "urlPattern": "/checkout/*|/paycheckout/*",
                    "textMarker": "pagamento aprovado",
                    "orderRef": {
                      "label": "Nº da transação",
                      "pattern": "([A-Za-z0-9][A-Za-z0-9._/#-]{2,63})"
                    },
                    "anchor": {
                      "text": "Ingressos adquiridos",
                      "position": "after"
                    }
                  },
                  "display": "banner"
                }
              }
            }
          }
        }
      }
    },
    "/v1/sessions/auto": {
      "post": {
        "tags": [
          "Sem código (bis-auto.js)"
        ],
        "summary": "Abrir sessão não assinada",
        "description": "Criada pelo loader/card quando detecta a confirmação. Sai `verified: false` e **sem dado do comprador**.\n\n- Só da página do parceiro: `Origin` num domínio permitido (ou `Origin` do iframe do widget + `X-Bis-Embed-Origin`).\n- Idempotente por (parceiro, `orderRef`): mantém a decisão de amostra da 1ª vez.\n- Limite: **10/min por (parceiro, IP)**.\n- `orderRef`: 3–64 caracteres de `[A-Za-z0-9._/#-]`. `amount` é informativo.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "description": "Origem da página do parceiro, quando a chamada sai do iframe do widget."
            },
            "required": false,
            "name": "X-Bis-Embed-Origin",
            "in": "header"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AutoSessionRequest"
              },
              "example": {
                "partnerId": "prt_palcoaberto",
                "orderRef": "PA-7Q2K9X",
                "amount": 12000
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Sessão aberta.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutoSessionResponse"
                },
                "example": {
                  "sessionToken": "v1.Zk3x…(opaco)…q9A",
                  "show": true,
                  "verified": false
                }
              }
            }
          },
          "400": {
            "description": "Validação falhou (corpo ou query fora do contrato).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "validação falhou"
                }
              }
            }
          },
          "403": {
            "description": "Origem fora dos domínios permitidos, ou modo sem código desligado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "modo sem código desligado para este parceiro"
                }
              }
            }
          },
          "404": {
            "description": "Parceiro inexistente ou inativo.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "parceiro não encontrado"
                }
              }
            }
          },
          "429": {
            "description": "Limite de taxa excedido (10/min por parceiro e IP). Tente de novo em instantes.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "muitas tentativas; tente de novo em instantes"
                }
              }
            }
          }
        }
      }
    },
    "/v1/sessions/offer": {
      "get": {
        "tags": [
          "Widget (sessionToken)"
        ],
        "summary": "O que o banner mostra",
        "description": "Chamado pelo loader na página do parceiro. CORS aberto; o domínio da página é conferido contra os domínios permitidos.\nSem dado do comprador. `display` vem da configuração do parceiro (`banner` padrão, ou `card`).",
        "security": [
          {
            "SessionToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Oferta.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OfferSummary"
                },
                "example": {
                  "display": "banner",
                  "partnerName": "Ticket and Go",
                  "creditCents": 2000,
                  "creditLabel": "R$ 20",
                  "variant": "A",
                  "orderRef": "TNG-8F3K2Q"
                }
              }
            }
          },
          "204": {
            "description": "Pedido fora da amostra: nada aparece."
          },
          "401": {
            "description": "Credencial ausente ou inválida.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "token ausente"
                }
              }
            }
          },
          "403": {
            "description": "Página fora dos domínios permitidos.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "domínio não autorizado para este parceiro"
                }
              }
            }
          },
          "410": {
            "description": "Sessão inválida ou expirada.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "sessão inválida ou expirada"
                }
              }
            }
          }
        }
      }
    },
    "/v1/handoffs": {
      "post": {
        "tags": [
          "Widget (sessionToken)"
        ],
        "summary": "Criar token de passagem para /assinar",
        "description": "O banner pede o token **depois** do clique e abre `https://widget.clubebis.com/assinar#h=<handoff>` numa aba nova.\nVale **5 min**, **uma vez**; o Bis guarda só o SHA-256. O token vai no fragmento (não chega a servidor, log nem `Referer`).",
        "security": [
          {
            "SessionToken": []
          }
        ],
        "responses": {
          "201": {
            "description": "Token criado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HandoffResponse"
                },
                "example": {
                  "handoff": "kQ2v9Zr1xT8mB4nL6pW0yC3sD5fG7hJ9aE1uI2oP4qR",
                  "expiresAt": "2026-11-16T12:05:00.000Z"
                }
              }
            }
          },
          "401": {
            "description": "Credencial ausente ou inválida.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "token ausente"
                }
              }
            }
          },
          "409": {
            "description": "Pedido fora da amostra.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "pedido fora da amostra"
                }
              }
            }
          },
          "410": {
            "description": "Sessão inválida ou expirada.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "sessão inválida ou expirada"
                }
              }
            }
          },
          "429": {
            "description": "Limite de taxa excedido (10/min por pedido). Tente de novo em instantes.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "muitas tentativas; tente de novo em instantes"
                }
              }
            }
          }
        }
      }
    },
    "/v1/handoffs/redeem": {
      "post": {
        "tags": [
          "Widget (sessionToken)"
        ],
        "summary": "Trocar o token de passagem pela sessão",
        "description": "Usado pela página do Bis (`/assinar`). Uma vez só: o segundo uso devolve `410`. Devolve uma sessão renovada (30 min) e o conteúdo do formulário.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/HandoffRedeemRequest"
              },
              "example": {
                "handoff": "kQ2v9Zr1xT8mB4nL6pW0yC3sD5fG7hJ9aE1uI2oP4qR"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Sessão e card.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HandoffRedeemResponse"
                },
                "example": {
                  "sessionToken": "v1.Zk3x…(opaco)…q9A",
                  "card": {
                    "partnerName": "Ticket and Go",
                    "headline": "R$ 20 de volta no seu próximo ingresso",
                    "introPriceLabel": "1º mês por R$ 1",
                    "monthlyPriceLabel": "depois R$ 9,99/mês",
                    "prizeLabel": "e concorra a R$ 10 mil todo mês",
                    "variant": "A",
                    "creditCents": 2000,
                    "prefilled": {
                      "name": "Tua Mãe Aquela Ursa",
                      "email": "ursa@tuamaeaquelaursa.com",
                      "phone": "+55 11 90000-0000",
                      "cpf": "52998224725"
                    }
                  },
                  "partnerId": "prt_ticketandgo",
                  "orderRef": "TNG-8F3K2Q"
                }
              }
            }
          },
          "400": {
            "description": "Validação falhou (corpo ou query fora do contrato).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "validação falhou"
                }
              }
            }
          },
          "404": {
            "description": "Parceiro inativo.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "parceiro não encontrado"
                }
              }
            }
          },
          "410": {
            "description": "Token inválido, expirado ou já usado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "link inválido, expirado ou já usado"
                }
              }
            }
          }
        }
      }
    },
    "/v1/sessions/card": {
      "get": {
        "tags": [
          "Widget (sessionToken)"
        ],
        "summary": "Conteúdo do card (modo card)",
        "description": "Usado pelo card em iframe (`display: \"card\"`). `GET /v1/card/{token}` é equivalente, com o token no caminho (e `404` fora da amostra).",
        "security": [
          {
            "SessionToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Card.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardContent"
                },
                "example": {
                  "partnerName": "Ticket and Go",
                  "headline": "R$ 20 de volta no seu próximo ingresso",
                  "introPriceLabel": "1º mês por R$ 1",
                  "monthlyPriceLabel": "depois R$ 9,99/mês",
                  "prizeLabel": "e concorra a R$ 10 mil todo mês",
                  "variant": "A",
                  "creditCents": 2000,
                  "prefilled": {
                    "name": "Tua Mãe Aquela Ursa",
                    "email": "ursa@tuamaeaquelaursa.com",
                    "phone": "+55 11 90000-0000",
                    "cpf": "52998224725"
                  }
                }
              }
            }
          },
          "204": {
            "description": "Pedido fora da amostra: o widget esconde."
          },
          "401": {
            "description": "Credencial ausente ou inválida.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "token ausente"
                }
              }
            }
          },
          "410": {
            "description": "Sessão inválida ou expirada.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "sessão inválida ou expirada"
                }
              }
            }
          }
        }
      }
    },
    "/v1/card/{token}": {
      "get": {
        "tags": [
          "Widget (sessionToken)"
        ],
        "summary": "Conteúdo do card (token no caminho)",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "required": true,
            "name": "token",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Card.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CardContent"
                },
                "example": {
                  "partnerName": "Ticket and Go",
                  "headline": "R$ 20 de volta no seu próximo ingresso",
                  "introPriceLabel": "1º mês por R$ 1",
                  "monthlyPriceLabel": "depois R$ 9,99/mês",
                  "prizeLabel": "e concorra a R$ 10 mil todo mês",
                  "variant": "A",
                  "creditCents": 2000,
                  "prefilled": {
                    "name": "Tua Mãe Aquela Ursa",
                    "email": "ursa@tuamaeaquelaursa.com",
                    "phone": "+55 11 90000-0000",
                    "cpf": "52998224725"
                  }
                }
              }
            }
          },
          "404": {
            "description": "Pedido fora da amostra.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "pedido fora da amostra"
                }
              }
            }
          },
          "410": {
            "description": "Sessão inválida ou expirada.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "sessão inválida ou expirada"
                }
              }
            }
          }
        }
      }
    },
    "/v1/payments/wallet-token": {
      "post": {
        "tags": [
          "Widget (sessionToken)"
        ],
        "summary": "Token de pagamento: carteira",
        "description": "O widget troca o resultado da carteira (Apple/Google Pay) ou a autorização do Pix por um token do gateway, que vai em `POST /v1/subscriptions`. Em dev o gateway é simulado (`mock_…`).",
        "security": [
          {
            "SessionToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Token do gateway.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "gatewayToken": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "gatewayToken"
                  ]
                },
                "example": {
                  "gatewayToken": "mock_wallet_3f9a0c1b2d4e5f60"
                }
              }
            }
          },
          "401": {
            "description": "Credencial ausente ou inválida.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "token ausente"
                }
              }
            }
          },
          "409": {
            "description": "Pedido fora da amostra.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "pedido fora da amostra"
                }
              }
            }
          },
          "501": {
            "description": "Gateway real ainda não integrado neste ambiente.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "tokenização no gateway real ainda não integrada"
                }
              }
            }
          }
        }
      }
    },
    "/v1/payments/pix-automatico-token": {
      "post": {
        "tags": [
          "Widget (sessionToken)"
        ],
        "summary": "Token de pagamento: Pix Automático",
        "description": "O widget troca o resultado da carteira (Apple/Google Pay) ou a autorização do Pix por um token do gateway, que vai em `POST /v1/subscriptions`. Em dev o gateway é simulado (`mock_…`).",
        "security": [
          {
            "SessionToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Token do gateway.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "gatewayToken": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "gatewayToken"
                  ]
                },
                "example": {
                  "gatewayToken": "mock_pix_3f9a0c1b2d4e5f60"
                }
              }
            }
          },
          "401": {
            "description": "Credencial ausente ou inválida.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "token ausente"
                }
              }
            }
          },
          "409": {
            "description": "Pedido fora da amostra.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "pedido fora da amostra"
                }
              }
            }
          },
          "501": {
            "description": "Gateway real ainda não integrado neste ambiente.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "tokenização no gateway real ainda não integrada"
                }
              }
            }
          }
        }
      }
    },
    "/v1/subscriptions": {
      "post": {
        "tags": [
          "Widget (sessionToken)"
        ],
        "summary": "Adesão em um toque",
        "description": "Cria membro e assinatura (R$ 1 no 1º mês, R$ 9,99/mês depois). Idempotente pelo cabeçalho `Idempotency-Key` (use o `sessionToken`).\nO Bis **nunca** vê PAN/CVV: só o token do gateway. `type`: `wallet` (Apple Pay / Google Pay), `card` (cartão de crédito digitado no campo hospedado do gateway, que devolve o token) ou `pix_automatico`.\n\nSessão sem código (`verified: false`): a assinatura nasce pendente e os benefícios ficam travados até a confirmação do pedido.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "description": "Use o próprio `sessionToken`."
            },
            "required": false,
            "name": "Idempotency-Key",
            "in": "header"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/JoinRequest"
              },
              "example": {
                "sessionToken": "v1.Zk3x…(opaco)…q9A",
                "paymentMethod": {
                  "type": "wallet",
                  "gatewayToken": "mock_wallet_3f9a0c1b2d4e5f60"
                },
                "identity": {
                  "name": "Tua Mãe Aquela Ursa",
                  "email": "ursa@tuamaeaquelaursa.com",
                  "phone": "+55 11 90000-0000",
                  "cpf": "52998224725"
                },
                "consent": {
                  "terms": true,
                  "whatsappOptIn": true,
                  "acceptedAt": "2026-11-16T12:00:00.000Z"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Adesão já existia (idempotência).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JoinResponse"
                },
                "example": {
                  "memberId": "mem_7Hk2Qp9x",
                  "subscriptionId": "sub_3Rt8Lm1v",
                  "firstChargeAmount": 100,
                  "nextFullChargeAt": "2026-12-16T12:00:00.000Z"
                }
              }
            }
          },
          "201": {
            "description": "Adesão criada.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JoinResponse"
                },
                "example": {
                  "memberId": "mem_7Hk2Qp9x",
                  "subscriptionId": "sub_3Rt8Lm1v",
                  "firstChargeAmount": 100,
                  "nextFullChargeAt": "2026-12-16T12:00:00.000Z"
                }
              }
            }
          },
          "400": {
            "description": "Validação falhou (corpo ou query fora do contrato).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "validação falhou"
                }
              }
            }
          },
          "403": {
            "description": "Pedido fora da amostra ou página fora dos domínios permitidos.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "pedido fora da amostra"
                }
              }
            }
          },
          "409": {
            "description": "O pedido já tem uma adesão de outro CPF.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "este pedido já tem uma adesão"
                }
              }
            }
          },
          "410": {
            "description": "Sessão inválida ou expirada.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "sessão inválida ou expirada"
                }
              }
            }
          }
        }
      }
    },
    "/v1/widget/events": {
      "post": {
        "tags": [
          "Widget (sessionToken)"
        ],
        "summary": "Telemetria do funil",
        "description": "Corpo JSON enviado como `text/plain` (`sendBeacon`). Sempre `204`, mesmo com token ou corpo inválido. Nunca bloqueia a adesão. Sem dado pessoal.",
        "requestBody": {
          "required": true,
          "content": {
            "text/plain": {
              "schema": {
                "$ref": "#/components/schemas/WidgetEvent"
              },
              "example": {
                "sessionToken": "v1.Zk3x…(opaco)…q9A",
                "event": {
                  "type": "clicked"
                }
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "Recebido (ou ignorado)."
          }
        }
      }
    },
    "/v1/cashback/offers": {
      "get": {
        "tags": [
          "Cashback"
        ],
        "summary": "Ofertas de cashback (PromoMais)",
        "description": "Público (`Cache-Control: public, max-age=300` + `ETag`; `If-None-Match` → `304`).\nCom o token do assinante (opcional), cada `url` ganha `&sub=<ref>` opaco e a resposta vira `private, no-store`.\nFonte fora do ar: serve a última cópia com `X-Bis-Stale: 1`. Limite: **60/min por IP**.",
        "security": [
          {},
          {
            "MemberToken": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "example": 1
            },
            "required": false,
            "name": "page",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "example": 24
            },
            "required": false,
            "name": "limit",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "example": "eletronicos"
            },
            "required": false,
            "name": "category",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "cashback",
                "discount"
              ]
            },
            "required": false,
            "name": "kind",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Página de ofertas.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CashbackOffersResponse"
                },
                "example": {
                  "offers": [
                    {
                      "id": "6f1c2a9e",
                      "store": {
                        "id": "adv-123",
                        "name": "Loja Exemplo",
                        "logoUrl": "https://cdn.exemplo.com/logo.png"
                      },
                      "title": "Até 8% de volta em eletrônicos",
                      "category": {
                        "slug": "eletronicos",
                        "name": "Eletrônicos"
                      },
                      "benefit": {
                        "kind": "percent",
                        "percent": 8,
                        "amountCents": null,
                        "label": "até 8%",
                        "conditions": null
                      },
                      "discountLabel": null,
                      "couponCode": null,
                      "image": null,
                      "validUntil": null,
                      "url": "https://promomais.app/r/loja-exemplo?utm_source=clubebis&utm_medium=cashback"
                    }
                  ],
                  "page": 1,
                  "total": 161,
                  "hasMore": true,
                  "publishedAt": "2026-11-16T08:01:44.000Z"
                }
              }
            }
          },
          "304": {
            "description": "Não mudou (`If-None-Match`)."
          },
          "400": {
            "description": "Validação falhou (corpo ou query fora do contrato).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "validação falhou"
                }
              }
            }
          },
          "429": {
            "description": "Limite de taxa excedido (60/min por IP). Tente de novo em instantes.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "muitas tentativas; tente de novo em instantes"
                }
              }
            }
          },
          "502": {
            "description": "Fonte indisponível e sem cópia em cache.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "cashback indisponível no momento"
                }
              }
            }
          },
          "503": {
            "description": "Cashback não configurado neste ambiente.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "cashback indisponível"
                }
              }
            }
          }
        }
      }
    },
    "/v1/auth/request-code": {
      "post": {
        "tags": [
          "Assinante"
        ],
        "summary": "Pedir código de acesso",
        "description": "Envia um código de 6 dígitos (10 min) por e-mail e, se o identificador for celular, por WhatsApp. Sempre `204`: não revela se o identificador existe.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RequestCodeRequest"
              },
              "example": {
                "identifier": "ursa@tuamaeaquelaursa.com"
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "Pedido aceito."
          },
          "400": {
            "description": "Validação falhou (corpo ou query fora do contrato).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "validação falhou"
                }
              }
            }
          }
        }
      }
    },
    "/v1/auth/verify": {
      "post": {
        "tags": [
          "Assinante"
        ],
        "summary": "Entrar com o código",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VerifyCodeRequest"
              },
              "example": {
                "identifier": "ursa@tuamaeaquelaursa.com",
                "code": "482913"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Token do assinante (7 dias).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MemberSession"
                },
                "example": {
                  "memberId": "mem_7Hk2Qp9x",
                  "token": "eyJtZW1iZXJJZCI6Im1lbV83SGsyUXA5eCJ9.…"
                }
              }
            }
          },
          "400": {
            "description": "Validação falhou (corpo ou query fora do contrato).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "validação falhou"
                }
              }
            }
          },
          "401": {
            "description": "Código inválido ou expirado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "código inválido ou expirado"
                }
              }
            }
          }
        }
      }
    },
    "/v1/auth/magic": {
      "post": {
        "tags": [
          "Assinante"
        ],
        "summary": "Entrar com link mágico",
        "description": "Troca o token de uso único do link (e-mail/WhatsApp) por uma sessão.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MagicRequest"
              },
              "example": {
                "token": "<token do link>"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Token do assinante.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MemberSession"
                },
                "example": {
                  "memberId": "mem_7Hk2Qp9x",
                  "token": "eyJtZW1iZXJJZCI6Im1lbV83SGsyUXA5eCJ9.…"
                }
              }
            }
          },
          "400": {
            "description": "Validação falhou (corpo ou query fora do contrato).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "validação falhou"
                }
              }
            }
          },
          "401": {
            "description": "Link inválido, expirado ou já usado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "link inválido ou expirado"
                }
              }
            }
          }
        }
      }
    },
    "/v1/me": {
      "get": {
        "tags": [
          "Assinante"
        ],
        "summary": "Início do assinante",
        "description": "Membro, assinatura, crédito e número da sorte. `GET /v1/me/home` é equivalente. No mês de R$ 1 (`intro`) `credit` é `null`: o crédito sai na 1ª mensalidade cheia.",
        "security": [
          {
            "MemberToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MemberHome"
                },
                "example": {
                  "member": {
                    "name": "Tua Mãe Aquela Ursa",
                    "email": "ursa@tuamaeaquelaursa.com"
                  },
                  "subscription": {
                    "status": "active",
                    "nextChargeAt": "2027-01-16T12:00:00.000Z",
                    "nextChargeAmount": 999
                  },
                  "credit": {
                    "amount": 2000,
                    "coupon": "BIS-7K2M-Q9XA",
                    "expiresAt": "2027-06-16T12:00:00.000Z"
                  },
                  "luckyNumber": {
                    "month": "2026-12",
                    "number": "04821"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Credencial ausente ou inválida.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "token ausente"
                }
              }
            }
          },
          "404": {
            "description": "Assinante não encontrado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "assinante não encontrado"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Assinante"
        ],
        "summary": "Excluir conta",
        "description": "Cancela a assinatura, registra o pedido do titular e **anonimiza** os dados pessoais.",
        "security": [
          {
            "MemberToken": []
          }
        ],
        "responses": {
          "204": {
            "description": "Excluída."
          },
          "401": {
            "description": "Credencial ausente ou inválida.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "token ausente"
                }
              }
            }
          },
          "404": {
            "description": "Assinante não encontrado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "assinante não encontrado"
                }
              }
            }
          }
        }
      }
    },
    "/v1/me/draws": {
      "get": {
        "tags": [
          "Assinante"
        ],
        "summary": "Números da sorte",
        "security": [
          {
            "MemberToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Um por mês.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/MemberDraw"
                  }
                },
                "example": [
                  {
                    "month": "2026-12",
                    "number": "04821",
                    "status": "open"
                  },
                  {
                    "month": "2026-11",
                    "number": "17733",
                    "status": "drawn",
                    "result": {
                      "winningNumber": "90412",
                      "won": false
                    }
                  }
                ]
              }
            }
          },
          "401": {
            "description": "Credencial ausente ou inválida.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "token ausente"
                }
              }
            }
          },
          "404": {
            "description": "Assinante não encontrado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "assinante não encontrado"
                }
              }
            }
          }
        }
      }
    },
    "/v1/me/payment": {
      "get": {
        "tags": [
          "Assinante"
        ],
        "summary": "Método e histórico de cobranças",
        "security": [
          {
            "MemberToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentInfo"
                },
                "example": {
                  "method": {
                    "type": "wallet",
                    "label": "Apple Pay"
                  },
                  "charges": [
                    {
                      "id": "chg_2Pq8",
                      "date": "2026-12-16T12:00:05.000Z",
                      "amount": 999,
                      "status": "paid"
                    },
                    {
                      "id": "chg_1Lm3",
                      "date": "2026-11-16T12:00:04.000Z",
                      "amount": 100,
                      "status": "paid"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Credencial ausente ou inválida.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "token ausente"
                }
              }
            }
          },
          "404": {
            "description": "Assinante não encontrado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "assinante não encontrado"
                }
              }
            }
          }
        }
      }
    },
    "/v1/me/payment/card-session": {
      "post": {
        "tags": [
          "Assinante"
        ],
        "summary": "Trocar cartão (campo hospedado)",
        "security": [
          {
            "MemberToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "URL do campo hospedado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HostedSession"
                },
                "example": {
                  "url": "https://app.clubebis.com/pagamento?metodo=card"
                }
              }
            }
          },
          "401": {
            "description": "Credencial ausente ou inválida.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "token ausente"
                }
              }
            }
          },
          "404": {
            "description": "Assinante não encontrado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "assinante não encontrado"
                }
              }
            }
          }
        }
      }
    },
    "/v1/me/payment/pix-automatico": {
      "post": {
        "tags": [
          "Assinante"
        ],
        "summary": "Autorizar Pix Automático",
        "security": [
          {
            "MemberToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "URL da autorização.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HostedSession"
                },
                "example": {
                  "url": "https://app.clubebis.com/pagamento?metodo=pix_automatico"
                }
              }
            }
          },
          "401": {
            "description": "Credencial ausente ou inválida.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "token ausente"
                }
              }
            }
          },
          "404": {
            "description": "Assinante não encontrado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "assinante não encontrado"
                }
              }
            }
          }
        }
      }
    },
    "/v1/me/profile": {
      "get": {
        "tags": [
          "Assinante"
        ],
        "summary": "Perfil",
        "security": [
          {
            "MemberToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Profile"
                },
                "example": {
                  "name": "Tua Mãe Aquela Ursa",
                  "email": "ursa@tuamaeaquelaursa.com",
                  "phone": "+55 11 90000-0000"
                }
              }
            }
          },
          "401": {
            "description": "Credencial ausente ou inválida.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "token ausente"
                }
              }
            }
          },
          "404": {
            "description": "Assinante não encontrado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "assinante não encontrado"
                }
              }
            }
          }
        }
      }
    },
    "/v1/me/preferences": {
      "get": {
        "tags": [
          "Assinante"
        ],
        "summary": "Preferências",
        "security": [
          {
            "MemberToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Preferences"
                },
                "example": {
                  "whatsappOptIn": true,
                  "emailReminders": true,
                  "phone": "+55 11 90000-0000"
                }
              }
            }
          },
          "401": {
            "description": "Credencial ausente ou inválida.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "token ausente"
                }
              }
            }
          },
          "404": {
            "description": "Assinante não encontrado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "assinante não encontrado"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "Assinante"
        ],
        "summary": "Salvar preferências",
        "security": [
          {
            "MemberToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Preferences"
              },
              "example": {
                "whatsappOptIn": true,
                "emailReminders": true,
                "phone": "+55 11 90000-0000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Salvo.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Preferences"
                },
                "example": {
                  "whatsappOptIn": true,
                  "emailReminders": true,
                  "phone": "+55 11 90000-0000"
                }
              }
            }
          },
          "400": {
            "description": "Validação falhou (corpo ou query fora do contrato).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "validação falhou"
                }
              }
            }
          },
          "401": {
            "description": "Credencial ausente ou inválida.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "token ausente"
                }
              }
            }
          },
          "404": {
            "description": "Assinante não encontrado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "assinante não encontrado"
                }
              }
            }
          }
        }
      }
    },
    "/v1/me/export": {
      "get": {
        "tags": [
          "Assinante"
        ],
        "summary": "Exportar meus dados (LGPD)",
        "description": "Arquivo JSON com todos os dados do titular (LGPD, art. 18). Vem com `Content-Disposition: attachment`.",
        "security": [
          {
            "MemberToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Arquivo JSON."
          },
          "401": {
            "description": "Credencial ausente ou inválida.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "token ausente"
                }
              }
            }
          },
          "404": {
            "description": "Assinante não encontrado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "assinante não encontrado"
                }
              }
            }
          }
        }
      }
    },
    "/v1/me/cancel": {
      "post": {
        "tags": [
          "Assinante"
        ],
        "summary": "Cancelar a assinatura",
        "description": "`POST /v1/me/subscription/cancel` é equivalente.",
        "security": [
          {
            "MemberToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CancelRequest"
              },
              "example": {
                "channel": "app",
                "reason": "não uso mais"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Cancelada.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CancelResponse"
                },
                "example": {
                  "canceledAt": "2026-11-20T14:03:11.000Z",
                  "protocol": "BIS-CAN-20261120-7K2M"
                }
              }
            }
          },
          "400": {
            "description": "Validação falhou (corpo ou query fora do contrato).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "validação falhou"
                }
              }
            }
          },
          "401": {
            "description": "Credencial ausente ou inválida.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "token ausente"
                }
              }
            }
          },
          "404": {
            "description": "Assinante não encontrado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "assinante não encontrado"
                }
              }
            }
          }
        }
      }
    }
  },
  "webhooks": {
    "bisEvent": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Evento do ciclo de vida",
        "description": "Enviado à URL cadastrada no painel do parceiro (**Configuração → Webhooks**), um envio por webhook inscrito no evento.\n\n- `X-Bis-Delivery`: id da entrega. Pode chegar mais de uma vez em retentativas: deduplique por ele.\n- `X-Bis-Signature`: `sha256=<hex>` = `HMAC-SHA256(segredo do webhook, corpo cru)`.\n\nResponda `2xx` rápido; fora de `2xx` a fila reentrega com backoff.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "example": "9c1f0e7b2a4d6c8e0f1a3b5c7d9e1f20"
            },
            "required": true,
            "name": "X-Bis-Delivery",
            "in": "header"
          },
          {
            "schema": {
              "type": "string",
              "example": "sha256=5d41402abc4b2a76b9719d911017c592…"
            },
            "required": true,
            "name": "X-Bis-Signature",
            "in": "header"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BisEvent"
              },
              "example": {
                "type": "credit.issued",
                "creditId": "crd_5Wn2Ks8d",
                "memberId": "mem_7Hk2Qp9x",
                "partnerId": "prt_ticketandgo",
                "coupon": "BIS-7K2M-Q9XA",
                "amount": 2000,
                "expiresAt": "2027-06-16T12:00:00.000Z"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Recebido. Qualquer `2xx` serve."
          }
        }
      }
    }
  }
}
