Documentação — checkout-api

Índice completo da documentação do projeto. Toda documentação vive em .project/docs/, cujo primeiro nível é um conjunto fechado de pastas.

As regras de negócio têm um índice próprio em RULES.md.

O certainty de cada doc indica quanto do conteúdo veio do documento original (high), quanto foi parcialmente reconstruído a partir do código (medium), e quanto foi majoritariamente inferido (low).

specs/

Mudanças planejadas ou executadas, com contexto e objetivos.

Doc Descrição Status Certainty
20240318112519_checkout_custom_fields.md Campos personalizados por checkout, abertos ou com opções pré-definidas in_progress medium
20240430150453_gateway_transfers.md API assíncrona de transferência de saldo do gateway para conta externa ou chave PIX done medium
20240606182606_checkout_creation_api.md Criação de checkouts e links de pagamento pela API done medium
20240621125426_origin_campaigns.md Captura de parâmetros UTM no pagamento e visão de campanhas no admin done high
20240712163437_orders.md Entidade Order para pedidos com múltiplos checkouts proposed medium
20240815170531_organization_split_fee.md Cobrança de taxa por organização via split no gateway done medium
20240910123251_integration_webhooks_api.md API para organizações registrarem webhooks de eventos de cobrança done medium
20240925112122_apolo_integration_v2.md Integração Apolo cadastrada na organização, em vez de por checkout proposed medium
20250130105454_payment_refunds.md Armazenamento e rastreio dos estornos recebidos do Asaas done high
20250205110201_tracking_analytics.md Códigos de rastreio polimórficos em organização e produto done medium
20250211221228_payment_notifications.md Assumir do Asaas o envio de avisos de cobrança, via messenger-api proposed medium
20250630141914_checkout_order_bump.md Order bump, upsell e downsell ligando checkouts entre si done medium
20260407150300_organization_transfer.md Transferir organizações específicas entre dois cadastros de cliente done high
20260706173904_checkout_member_discount.md Desconto de membro por validação de email — versão percentual original superseded high
20260909143000_organization_product_slug.md Slug em organização e produto para identificar empresa e produto na sincronização de reparcelamento done high
20260914102226_repayment_sync_outbox_pattern.md Outbox genérico (tabela + job de varredura por cron) para disparo assíncrono de eventos a sistemas terceiros done high
20260914144321_customer_sync_new_checkout.md Unificação de cadastro e troca de e-mail sincronizadas com o checkout novo, pelo mesmo outbox done high
20260921114603_accounts_purchase_created_event.md Evento de compra criada (PURCHASE_CREATED) disparado para o accounts pelo outbox done high
20260922154500_accounts_installment_paid_event.md Evento de parcela paga (INSTALLMENT_PAID) disparado para o accounts pelo outbox in_progress high
20260924082916_installment_paid_as_object.md paid_installment do INSTALLMENT_PAID como objeto {number, provider_ref, paid_at}, com dedupe nos dois formatos in_progress high
20260928092233_accounts_organization_slug.md organization_slug no payload dos eventos do accounts, null quando a organização não tem slug in_progress high

plans/

Passo a passo de implementação de uma spec.

Doc Spec Descrição Certainty
20260318144411_onion_integration.md — Adicionar o Onion como plataforma de PlatformService high
20260407150300_organization_transfer.md 20260407150300_organization_transfer.md Service, job e ação de admin da transferência por organização high

architecture/

Decisões arquiteturais e suas consequências.

Doc Descrição Certainty
event_streaming.md Eventos com Wisper e GoodJob, sem broker externo; convenção de nomes e regras dos listeners high

guides/

How-to operacional.

Doc Descrição Certainty
setup.md Setup do ambiente local, scripts de run/ e alvos de make medium
operations.md Operações no console, cronjobs e provedores de PlatformService medium

learnings/

Aprendizados retrospectivos de bug ou decisão.

Doc Descrição Certainty
checkout_fixed_discount_must_be_applied_on_base.md Subtração não comuta com juros — desconto em reais precisa abater a base high

reference/

Como o sistema é: fluxos, APIs, contratos e modelos.

reference/payments/

Doc Descrição Certainty
payment_flow.md Ciclo de vida completo de um pagamento, da criação aos dois broadcasts high
payment_integration_flow.md Integração com plataformas LMS externas via PlatformService high
payment_webhooks.md Contrato público dos webhooks de pagamento para integradores high
onion_integration.md Contrato do webhook enviado ao Onion high
new_checkout_repayment_endpoint.md Contrato do webhook de reparcelamento enviado ao checkout novo high
new_checkout_customer_sync_endpoint.md Contrato de unificação de cadastro e troca de e-mail enviado ao checkout novo high
accounts_purchase_created_event.md Contrato do evento de compra criada enviado ao accounts high
accounts_installment_paid_event.md Contrato do evento de parcela paga enviado ao accounts high
asaas_payloads.md Exemplos de payload trocados com o gateway Asaas medium
assets/example_payment_webhook_payload.json Payload de webhook de exemplo, versionado high
accounts_purchase_created_event.md Contrato do evento PURCHASE_CREATED disparado ao accounts via outbox high
accounts_installment_overdue_event.md Contrato do evento INSTALLMENT_OVERDUE disparado ao accounts via outbox high

reference/checkout/

Doc Descrição Certainty
member_discount.md Desconto de membro por validação de email — comportamento atual high

reference/admin/

Doc Descrição Certainty
access_permissions.md Matriz de acesso por role e página inicial de cada uma high

rules/

Regras de negócio em Given/When/Then. Índice dedicado em RULES.md.

ID Doc Descrição Certainty
R-001 member_discount_requires_email_validation.md O desconto só é aplicado quando a validação confirma o email; qualquer falha resulta em preço cheio high
R-002 discount_amount_must_be_lower_than_total.md discount_amount aceita de 0 até menos que o total do checkout high
R-003 organization_product_slug.md Slug de organização e produto vem do name via parameterize, é estável no rename e único no escopo high
R-004 outbox_event_dispatch.md OutboxEvent vai para sent/failed (3 tentativas) sem distinguir tipo de erro; reenvio manual zera attempts high
R-005 accounts_installment_overdue_dispatch.md Atraso de compra padrão dispara INSTALLMENT_OVERDUE; idempotência por parcela, não por pagamento; carnê incompleto não bloqueia high

features/

Sem user stories nem critérios de aceite registrados até agora.