Mepagg API v1

Resumo
- A API pública da Mepagg é transacional e orientada por conta.
- Autenticação por header `X-API-KEY`.
- Escopo atual: clientes, faturas, assinaturas, planos, carnês, links de pagamentos, consultas de transferências, extrato, dashboard, SMS, e-mails enviados, dados cadastrais da conta e webhooks.
- Cobranças públicas suportadas nesta versão: boleto e PIX.
- `boleto` e `pix` são formas de pagamento da cobrança. Eles não representam o tipo da fatura.

Base URLs
- Aplicação/API: `https://app.mepagg.com`
- Documentação humana: `https://documentacao.mepagg.com/`
- OpenAPI: `https://documentacao.mepagg.com/openapi.json`
- Referência técnica em Markdown: `https://documentacao.mepagg.com/api-reference.md`
- Postman Collection: `https://documentacao.mepagg.com/postman_collection.json`
- Changelog: `https://documentacao.mepagg.com/changelog.html`

Fluxo principal recomendado
1. Autenticar com `X-API-KEY`
2. Criar cliente em `/api/v1/customers/`
3. Criar fatura em `/api/v1/invoices/`
4. Aguardar pagamento por boleto e/ou PIX
5. Receber webhook
6. Consultar novamente a fatura
7. Conciliar no extrato e no resumo da conta

Recursos principais
- Clientes: `/api/v1/customers/`
- Faturas: `/api/v1/invoices/`
- Assinaturas: `/api/v1/subscriptions/`
- Planos: `/api/v1/subscription-plans/`
- Carnês: `/api/v1/carnes/`
- Links de pagamentos: `/api/v1/payment-links/`
- Transferências: consultas de leitura em `/api/v1/transfers/`
- Extrato: `/api/v1/statement/`
- Resumo financeiro: `/api/v1/statement/summary/`
- Dashboard: `/api/v1/dashboard/overview/`
  Rotas complementares: `/api/v1/dashboard/widgets/`, `/api/v1/dashboard/balances/`, `/api/v1/dashboard/income-preview/`, `/api/v1/dashboard/invoice-progress/`, `/api/v1/dashboard/latest-invoices/`, `/api/v1/dashboard/payment-method-chart/`, `/api/v1/dashboard/invoice-type-chart/`, `/api/v1/dashboard/received-calendar/`, `/api/v1/dashboard/monthly-received-chart/`, `/api/v1/dashboard/customers/`
- SMS: `/api/v1/sms/send/`, `/api/v1/sms/buy-credits/`, `/api/v1/sms/usages/`
- E-mails enviados: `/api/v1/emails/dispatches/`
- Conta autenticada: `/api/v1/settings/account/`
- Webhooks: `/api/v1/settings/webhooks/`, `/api/v1/settings/webhooks/deliveries/`

Regras de integração
- Enviar JSON UTF-8 com `Content-Type: application/json` quando aplicável.
- Enviar a chave sempre no header `X-API-KEY`.
- Para interface, priorizar `status_label` e `type_label`.
- Para filtros, automações, regras e conciliação, usar `status_code` e `type_code`.
- Em `items`, a API aceita `qty` ou `quantity`; a resposta retorna `qty` como campo canônico.
- Faturas e assinaturas aceitam um ou vários itens, e o `total_amount` é a soma de `qty × price`.
- Carnês aceitam `items`, mas apenas com um único produto/serviço; a API usa esse item para calcular o total e distribuir o valor entre as parcelas.
- Na criação pública, assinaturas exigem `payment_methods`.
- Assinaturas aceitam `cycles` entre `0` e `120`; use `0` para recorrência sem limite fixo.
- Faturas e carnês com `boleto` e/ou `pix` não aceitam vencimento retroativo e bloqueiam criação com vencimento no mesmo dia a partir das `20h`.
- Carnês aceitam `schedule` opcional; quando enviado, ele precisa ter a mesma quantidade de parcelas de `installments`.
- Faturas retornam `public_url` e, quando aplicável, `public_boleto_url`.
- Carnês retornam `public_url` e a lista completa de parcelas em `invoices`.
- Cada parcela do carnê pode expor `public_url`, `public_boleto_url`, `boleto.*` e `pix.*`.
- Links de pagamentos usam `due_option` para a validade do link em si; quando `due_option=none`, o link deixa de expirar e a API exige `invoice_due_option` para definir o vencimento de cada fatura gerada.
- Em links sem vencimento, `invoice_due_option=today` deve ser apresentado em interface humana como `No mesmo dia`.
- Links de pagamento criados pelo painel usam origem `PANEL/panel/Painel`; `API/api/API` deve aparecer apenas quando o link tiver sido criado pela API pública com `X-API-KEY`.
- Confirmação econômica final deve considerar detalhe do recurso, extrato e resumo financeiro quando aplicável.
- `Idempotency-Key` está disponível em clientes (`POST/PUT/PATCH/DELETE`), faturas (`POST`, `cancel`, `refund`), links de pagamentos (`POST`), assinaturas (`POST/PUT/PATCH/DELETE/status`), planos (`POST/PUT/PATCH/DELETE`) e `POST /api/v1/sms/send/`.
- Compra de créditos SMS: enviar `sms_credit_package` e `sms_purchase_method=mepagg_balance`.
- Resposta típica da compra de créditos: `success`, `message` e `sms_credits` com o saldo atualizado.

Catálogo canônico
- Formas de pagamento da cobrança: `boleto`, `pix`.
- Tipos de desconto: `PERCENTAGE`, `FIXED_VALUE`.
- Para faturas, usar `status_label` e `type_label` em interface e `status_code` e `type_code` em regra de sistema.
- Tipos de fatura atualmente expostos: `2=subscription`, `3=oneoff`, `4=carne`, `5=payment_link`, `6=payment_button`.
- Origem de emissão de faturas: `PANEL/panel/Painel` e `API/api/API`.
- Links de pagamentos retornam `issued_via`, `issued_via_code` e `issued_via_label` para indicar se o link foi criado via painel ou API.
- `issued_via`, `issued_via_code` e `issued_via_label` são campos de saída e webhook, definidos internamente pela Mepagg; integrações não devem enviá-los no payload.
- Links de pagamentos também podem retornar `validity_display`, `invoice_due_option_label` e `invoice_due_summary` para leitura direta da regra de validade e vencimento.
- Quando um checkout público de link de pagamento gera uma fatura, ela sempre sai com `type_code=payment_link`; se o link tiver sido criado pela API pública, essa fatura também sai com `issued_via_code=api`.
- Para conciliação, persistir sempre `reference_id` e cruzar com `related_reference_id` do extrato quando disponível.

Limites operacionais
- Paginação: `limit` entre 1 e 200.
- SMS: `content` com no máximo 160 caracteres.
- Boleto agenda: `inter_boleto_num_dias_agenda` entre 1 e 60 quando aplicável.
- `Idempotency-Key`: até 255 caracteres.
- A criação de transferências, a consulta de motivo de recusa e o envio manual de recibo por e-mail são exclusivos do painel autenticado; a API pública mantém apenas consultas de leitura relacionadas.

Webhooks
- A Mepagg envia eventos para a URL cadastrada pela conta.
- `target_url` deve ser HTTPS público; HTTP só é aceito para `localhost` em ambiente controlado.
- `subscribed_events` aceita lista explícita de eventos ou `*` para todos os eventos públicos suportados.
- Preferir validar `X-Mepagg-Signature-V2` usando `X-Mepagg-Timestamp`.
- `X-Mepagg-Signature` permanece disponível por compatibilidade legada.
- Tratar `X-Mepagg-Event-Id` como chave de deduplicação.
- Responder HTTP `2xx` rapidamente e processar de forma assíncrona no sistema da conta.
- Após receber um webhook, consultar o recurso correspondente pela API para conciliação final.

Headers de webhook
- `X-Mepagg-Event`: nome do evento
- `X-Mepagg-Event-Id`: identificador único do evento
- `X-Mepagg-Signature`: assinatura legada `sha256=...`
- `X-Mepagg-Delivery-Id`: identificador da tentativa de entrega
- `X-Mepagg-Timestamp`: unix timestamp da tentativa
- `X-Mepagg-Retry-Count`: contador da tentativa
- `X-Mepagg-Signature-V2`: assinatura `t=<timestamp>,sha256=<hash>`

Boas práticas de webhook
- Responder com HTTP `2xx` quando o evento for aceito.
- Validar a assinatura HMAC SHA-256.
- Processar o conteúdo com idempotência usando o `event_id`.

Eventos de webhook atualmente documentados
- `customer.created`
- `customer.updated`
- `customer.deleted`
- `invoice.created`
- `invoice.updated`
- `invoice.paid`
- `invoice.cancelled`
- `invoice.expired`
- `invoice.expired_final`
- `invoice.refunded`
- `subscription.created`
- `subscription.updated`
- `subscription.renewed`
- `plan.created`
- `plan.updated`
- `plan.deleted`
- `carne.cancelled`
- `payment_link.status_changed`
- `transfer.created`
- `transfer.completed`
- `sms.credits_purchased`
- `sms.sent`
- `email.sent`
- `payment_link.status_changed` cobre mudança de status do link de pagamento; usar `status_code` e `status_reason_code` para identificar expiração por vencimento, desativação manual e limite de usos.
- Para cobranças geradas pelo checkout do link, continuar observando também os eventos `invoice.*` e ler `type_code=payment_link`.

Erros comuns
- `INVALID_API_KEY`
- `INVALID_DOCUMENT`
- `INVALID_EMAIL`
- `CUSTOMER_NOT_FOUND`
- `INVOICE_NOT_FOUND`
- `TRANSFER_NOT_FOUND`
- `INSUFFICIENT_BALANCE`
- `INVALID_PIX_KEY`
- `VALIDATION_ERROR`
- `WEBHOOK_SIGNATURE_INVALID`
- `RATE_LIMIT_EXCEEDED`
- `INTERNAL_ERROR`

Segurança
- Nunca confiar apenas na resposta inicial de um `POST` financeiro.
- Toda transferência deve respeitar saldo disponível e janela operacional.
- Todo recurso deve ser tratado no contexto da conta autenticada.
- Nunca usar IDs ou referências de outra conta como válidos.
- Armazenar `signing_secret` em cofre de segredos do sistema da conta, nunca em frontend.
- Persistir `X-Mepagg-Event-Id` para impedir processamento duplicado de webhook.
- Guardar `paid_at`, `amount_paid`, `status_code` e `reference_id` no ERP ou sistema da conta.

Campos críticos
- Cliente: `document` deve conter apenas números.
- Cliente: `zipcode` deve conter apenas números.
- SMS: `content` deve respeitar limite máximo de `160` caracteres.
- Faturas: informar `payment_methods` com `boleto`, `pix` ou ambos.
- Em modelos próprios de boleto/carnê, incluir a identificação da intermediação: `Mepagg LTDA - CNPJ 05.098.228/0001-80`.
- Webhook `invoice.paid`: os campos principais são `id`, `type`, `occurred_at`, `account`, `data.invoice_reference_id`, `data.amount_paid`, `data.paid_at`, `data.paid_source` e `data.invoice`.
- No bloco `data.invoice` dos webhooks de fatura, usar `type`, `type_code`, `type_label`, `issued_via`, `issued_via_code` e `issued_via_label`.
- Na API de consulta da fatura, `type_display` pode aparecer como alias de `type_label`.

Arquivos recomendados para IA
- `openapi.json`: especificação principal e canônica.
- `api-reference.md`: apoio textual resumido.
- `llms.txt`: resumo curto para roteamento e consumo automatizado.
- Fonte única ativa da documentação pública: `backend/site/documentacao/openapi.json`.
- Toda alteração pedida na documentação pública deve aparecer visivelmente no ReDoc, não apenas em schema interno, enum técnico ou example isolado.