Usar com IA

Você vai me ajudar a integrar meu sistema com a API pública da Assiny (plataforma de checkout e
pagamentos). Siga estas regras à risca e não invente rotas, campos ou valores que não estejam
aqui. Se faltar informação, pergunte.

## Conexão
- Endereço base: https://bff.assiny.com.br/v1/public
- Chamadas só pelo servidor (backend). A chave nunca vai para navegador, app ou repositório.
- Leia a chave da variável de ambiente ASSINY_API_KEY e o projeto de ASSINY_PROJECT_ID.
- Cabeçalhos em toda chamada:
  - Authorization: Bearer {ASSINY_API_KEY}
  - ProjectId: {ASSINY_PROJECT_ID}
  - Content-Type: application/json (quando houver corpo)
- A chave só acessa os projetos liberados para ela. Em POST /product e POST /multiple-products o
projeto vale pelo campo projectId do corpo; em GET /financial/bff/project/transaction, pelo
parâmetro projectId da URL; em GET /product/list/product/checkout/{projectId}, pelo caminho. Mande
o mesmo projeto também no cabeçalho ProjectId.

## Formato
- Valores em centavos, número inteiro (R$ 97,00 = 9700).
- Datas enviadas (só nos filtros da listagem de vendas): data e hora com fuso
(2026-11-01T00:00:00-03:00). Data sem hora é recusada com 400.
- Datas nas respostas vêm em UTC (2026-11-01T03:00:00Z).
- IDs são UUID.
- Filtros com vários valores vão separados por vírgula (status=paid,refunded).

## Rotas
Produtos
- GET  /product/list/product/checkout/{projectId} -> {"products":[{...produto, "offer":[...ofertas]}]}
- POST /product  corpo: projectId, name, nameDisplayed, class (DIGITAL|PHYSICAL),
productCategoryId, supportEmail, productorName (obrigatórios); description, productType
(PRODUCT|SERVICE|SPLIT), guarantee (7|15|30|60|90), productImage (URL), phoneNumber, language,
currency, isTermsEnabled, termsOfUse, width, height, length, weight (opcionais). Responde 201 com
o produto e o id.
- POST /multiple-products  corpo: lista de produtos no formato acima.
- POST /product/{productId}  corpo: produto completo (mesmos campos, sem projectId). Parta dos
dados da listagem.
- productCategoryId aceita só um destes IDs (escolha pelo assunto do produto; na dúvida,
pergunte):
  - 9e36e78f-f0e3-42e4-8551-e18e8cecc5cf = Desenvolvimento Pessoal
  - 67374e68-ca1a-40fa-85d4-590a7ba16d66 = Saúde e Bem-estar
  - 3611beb8-5c41-4b24-b857-97463d4bcc39 = Renda Extra
  - 780590e5-9341-461c-9c00-66325ae7c70e = Artes e Ofícios
  - 0b4ab084-3990-4c3f-b1ec-76122cf3c5ca = Ensino de idiomas
  - 581dd56a-43c9-4a91-aff3-cd9c4430ed89 = Viagens e Lazer
  - 8f5a247e-2589-4388-ac5f-44e372eb5652 = Culinária e Gastronomia
  - 3d484fcf-0f4e-430c-b7e5-8b4668b59d35 = Relacionamentos
  - a283c3fc-8a5b-4cff-9c21-f230c314a5d3 = Finanças
  - 08ecf47c-5468-499e-b2d7-cba13b1ba6ba = Midias Sociais
  - ede244ef-e49b-46cc-939a-3ae5a9262c4f = E-commerce
  - a8c6674b-1fbf-4e4a-84d3-7f4d59b564ed = Branding e Identidade
  - 9c844d4c-6fe6-4fb9-8c50-d6fca043bdc3 = Design de produto
  - 4687b15f-c4c6-4d96-8346-1c7e2e88ff5b = Marketing Digital
  - 2edfa341-407d-402b-b446-0a97811ec1b5 = Automação e Ferramentas
  - 6412fe3c-0901-4d4e-8de4-a0317620bc96 = Aquisição e Ads
  - 8cd1e715-8fa2-44ba-8cb8-a9670d8384b7 = Chatbots e IA
  - b7ca36bf-3fd1-4375-9112-f281c7b28d65 = Web design e Desenvolvimento
  - ee9cb75a-210b-4cfa-9105-698b544e17c2 = Gestão de projetos
  - a66021a5-9d8c-43e1-9aec-5b41d6c18324 = Desenvolvimento de jogos
- language e currency: copie de um produto que já existe no projeto; não invente.

Ofertas
- POST /checkout  corpo: productId, name, checkoutType (ENTRY|UPSELL|DOWNSELL|ORDERBUMP),
paymentType (TRANSACTION|SUBSCRIPTION), amount (centavos, mínimo 500) obrigatórios;
checkoutPaymentType (texto com PIX, BANK_SLIP, CREDIT separados por vírgula e espaço, ex. "PIX,
CREDIT"; BANK_SLIP só em TRANSACTION; null em ORDERBUMP), recurrence
(MONTHLY|QUARTERLY|SEMIANNUAL|YEARLY, só em SUBSCRIPTION), installments (1 a 12; em SUBSCRIPTION
no máximo MONTHLY 1, QUARTERLY 3, SEMIANNUAL 6, YEARLY 12), isInterestFree, amountAnchoring
(centavos), subscriptionMaxCycles (0 = sem limite), pixExpirationTimeHour (1 a 24),
bankSlipExpiration (1 a 5 dias), checkoutLayoutType (COMPACT|FULL), addressEnabled,
allowRepeatEmail, countdown, mainBanner, sideBanner, description. Responde 201 com a oferta e o id.
- POST /multiple-checkouts  corpo: lista de ofertas.
- POST /checkout/{offerId}  corpo: oferta completa. Parta dos dados da oferta na listagem de
produtos.
- 422 com assinyCode COUPON_BELOW_MIN_PRICE: o preço deixaria um cupom ativo abaixo de R$ 5,00;
nada foi salvo; mostre a message ao usuário.

Funis
- POST /funnel  corpo: name, checkoutId (id da oferta ENTRY), isActive. Responde 201 com id,
shortFunnelId e url (link do checkout).
- POST /multiple-funnels  corpo: lista de funis.

Vendas
- GET /financial/bff/project/transaction?projectId=...  filtros: limit, offset, startDate,
endDate, updatedAtStartDate, updatedAtEndDate, status (paid, pending, waiting_payment, refunded,
refused, chargedback, chargedback_refunded, pix_expired, request_refund, sent_to_refund,
refunded_by_client), paymentTypes (CREDIT, PIX, BANK_SLIP), offerTypes (ENTRY, UPSELL, DOWNSELL,
ORDERBUMP), products, offers, funnels, clientEmail, clientDocument, nameEmailClient, utmSource,
utmMedium, utmCampaign, utmTerm, utmContent, src. Resposta paginada.
- Para sincronizar, consulte por updatedAtStartDate/updatedAtEndDate a partir da última execução e
pagine com limit/offset até acabar.
- GET /financial/bff/sale/details/{transactionId} -> detalhe da venda (status, amount,
amountWithTax, paymentType, installments, dados do comprador, produto, oferta, funil, UTMs,
subscriptionId).

Assinaturas e parcelamentos
- GET   /subscription-admin/subscription/details/{subscriptionId} -> campos em snake_case
(recurrence_status, cycle, next_charge, last_charge_status, amount_with_tax...).
- PATCH /subscription-admin/cancel/subscription/{subscriptionId}  sem corpo; cancela a assinatura.
- POST  /subscription-admin/reactivate/charge/{subscriptionId}  sem corpo; reativa as cobranças e
pode cobrar o comprador. Responde {"status","messageResponse"}.
- POST  /smart-installment-admin/reactivate/charge/{installmentId}  sem corpo; o mesmo para
parcelamento.
- Ações que cancelam, reativam ou reembolsam exigem confirmação explícita do usuário antes de
rodar.

Pedidos de reembolso
- POST /request-refund/send-request  corpo: {"transaction_id": "...", "is_refund": true|false}.
Responde a um pedido que o comprador já abriu: true aprova, false recusa. Não abre pedido novo.

## Erros
- Corpo de erro: {"status","message","assinyCode","causes"}.
- 400 corpo inválido ou projeto ausente; 401 chave ausente, errada ou revogada; 403 projeto não
liberado para a chave; 404 ID não existe; 409 conflito; 422 regra de negócio; 5xx falha
temporária.
- Trate qualquer 2xx como sucesso. Em 5xx, tente de novo no máximo 3 vezes com espera crescente.
Nunca repita automaticamente PATCH/POST de cancelar, reativar ou reembolsar.
- Nunca registre a chave em log.

## Como trabalhar
- Antes de mapear campos de uma resposta para o meu banco, faça uma chamada real e use os nomes
que vierem nela.
- Gere código tipado, com uma função por rota e um cliente HTTP único que coloca os cabeçalhos.
- Confirme comigo a linguagem e o framework do meu projeto antes de começar.