{
  "openapi": "3.0.3",
  "info": {
    "title": "Mepagg API",
    "version": "1.1.6",
    "description": "# Mepagg API\n\nDocumentação pública da API Mepagg para integrações transacionais com clientes, cobranças, recorrência, planos, carnês, consultas de transferências, extrato, dashboard, SMS, e-mails enviados, dados cadastrais da conta e webhooks.\n\nA API pública da Mepagg é orientada por conta. Toda chave pertence a uma única conta Mepagg e só consegue consultar ou operar recursos daquela conta.\n\nEsta página é a leitura humana principal da API. O arquivo `openapi.json` continua sendo a especificação canônica e deve permanecer sincronizado com esta documentação.\n\nToda alteração pedida para a documentação pública precisa aparecer de forma visível no ReDoc. Não basta atualizar apenas schema interno, enum técnico ou example isolado se a mudança não ficar claramente renderizada para leitura humana.\n\n### Procedimento rápido para ajustar documentação\n\n1. Atualizar primeiro o `openapi.json`.\n2. Garantir que a mudança fique visível no ReDoc com descrição, tabela, seção conceitual ou payload exemplo quando fizer sentido.\n3. Sincronizar `api-reference.md`, `llms.txt`, `postman_collection.json` quando aplicável e `changelog.html`.\n4. Se a mudança for pública, revisar o cache-buster do ReDoc.\n5. Validar os arquivos alterados antes de concluir.\n\n### Arquivos rápidos\n\n- [OpenAPI JSON](./openapi.json)\n- [API Reference](./api-reference.md)\n- [llms.txt](./llms.txt)\n- [Postman Collection](./postman_collection.json)\n- [Changelog](./changelog.html)",
    "contact": {
      "name": "Mepagg",
      "url": "https://documentacao.mepagg.com/",
      "email": "suporte@mepagg.com"
    }
  },
  "servers": [
    {
      "url": "https://app.mepagg.com",
      "description": "Produção"
    }
  ],
  "tags": [
    {
      "name": "Autenticação",
      "x-displayName": "Autenticação",
      "x-section-id": "autenticacao",
      "description": "Envie a chave da conta no header `X-API-KEY`. O formato principal da API é `application/json`.\n\n```\nX-API-KEY: SUA_CHAVE_DE_API\n```\n\n```bash\ncurl \"https://app.mepagg.com/api/v1/customers/\" \\\n  -H \"X-API-KEY: SUA_CHAVE_DE_API\"\n```"
    },
    {
      "name": "Regras principais",
      "x-displayName": "Regras principais",
      "x-section-id": "regras-principais",
      "description": "- `boleto` e `pix` são formas de pagamento da cobrança.\n- Para interface, priorize `status_label` e `type_label`.\n- Para filtros, automações e regra de sistema, use `status_code` e `type_code`.\n- Para clientes, envie `document` com apenas números.\n- Para SMS, o campo `content` aceita no máximo `160` caracteres.\n- Confirmação econômica final deve considerar o recurso consultado e, quando aplicável, o extrato e o resumo financeiro."
    },
    {
      "name": "Comece em 5 minutos",
      "x-displayName": "Comece em 5 minutos",
      "x-section-id": "comece-5-minutos",
      "description": "1. Autenticar com `X-API-KEY`.\n2. Criar ou localizar o cliente.\n3. Criar a fatura com `boleto`, `pix` ou ambos.\n4. Aguardar o pagamento do pagador.\n5. Receber o webhook.\n6. Consultar novamente a fatura.\n7. Conciliar no extrato.\n\n### 1. Listar clientes\n\n```bash\ncurl --request GET \\\n  --url 'https://app.mepagg.com/api/v1/customers/?limit=20&offset=0' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API'\n```\n\n### 2. Criar cliente\n\n```bash\ncurl --request POST \\\n  --url 'https://app.mepagg.com/api/v1/customers/' \\\n  --header 'Content-Type: application/json' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API' \\\n  --data '{\n    \"name\": \"Cliente Exemplo LTDA\",\n    \"document\": \"12345678000195\",\n    \"email_primary\": \"financeiro@clienteexemplo.com.br\",\n    \"phone_number\": \"11987654321\",\n    \"street\": \"Avenida Exemplo\",\n    \"neighborhood\": \"Jardim Modelo\",\n    \"number\": \"100\",\n    \"zipcode\": \"01311000\",\n    \"city\": \"Sao Paulo\",\n    \"state\": \"SP\"\n  }'\n```\n\n### 3. Criar fatura\n\n```bash\ncurl --request POST \\\n  --url 'https://app.mepagg.com/api/v1/invoices/' \\\n  --header 'Content-Type: application/json' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API' \\\n  --header 'Idempotency-Key: 8f5b5820-2d19-4be3-8f57-64c3d5d9e2f7' \\\n  --data '{\n    \"customer_reference_id\": \"CUST_EXAMPLE_001\",\n    \"due_date\": \"2026-06-30\",\n    \"payment_methods\": [\"boleto\", \"pix\"],\n    \"items\": [\n      {\n        \"description\": \"Mensalidade da plataforma\",\n        \"quantity\": 1,\n        \"price\": \"120.00\"\n      }\n    ]\n  }'\n```\n\n### 4. Consultar a fatura após o webhook\n\n```bash\ncurl --request GET \\\n  --url 'https://app.mepagg.com/api/v1/invoices/GLZOX8K19Q40NVLJ6WJ2PRYD7EV653/' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API'\n```\n\n### 5. Conciliar no extrato\n\n```bash\ncurl --request GET \\\n  --url 'https://app.mepagg.com/api/v1/statement/?start_date=2026-06-01&end_date=2026-06-30&limit=20&offset=0' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API'\n```"
    },
    {
      "name": "Fluxo financeiro",
      "x-displayName": "Fluxo financeiro",
      "x-section-id": "fluxo-financeiro",
      "description": "- Valor bruto da cobrança: total cobrado do pagador.\n- Taxas: tarifas e custos operacionais associados.\n- Valor líquido: valor efetivamente disponível após tarifas aplicáveis.\n- Status da fatura: fonte principal do estado da cobrança.\n- Saldo disponível: valor liberado para movimentação da conta.\n- Transferência PIX: depende de saldo disponível e janela operacional.\n- Conciliação final: deve ser confirmada no extrato e no resumo financeiro.\n\n> Use a fatura para entender o ciclo da cobrança, use o webhook para reduzir latência operacional e use extrato e resumo financeiro para validar impacto econômico real."
    },
    {
      "name": "Idempotency-Key",
      "x-displayName": "Idempotency-Key",
      "x-section-id": "idempotency-key",
      "description": "Header suportado:\n\n```\nIdempotency-Key: uuid-ou-chave-unica\n```\n\nEndpoints com suporte atual:\n\n- `POST /api/v1/invoices/`\n- `POST /api/v1/invoices/{reference_id}/cancel/`\n- `POST /api/v1/invoices/{reference_id}/refund/`\n- `POST /api/v1/sms/send/`\n\n> Mesma chave com mesmo payload devolve a resposta original. Mesma chave com payload diferente retorna conflito."
    },
    {
      "name": "Modelos por linguagem",
      "x-displayName": "Modelos por linguagem",
      "x-section-id": "modelos-por-linguagem",
      "description": "Exemplos prontos para os fluxos mais comuns de integração.\n\n### Criar fatura em cURL\n\n```bash\ncurl --request POST \\\n  --url 'https://app.mepagg.com/api/v1/invoices/' \\\n  --header 'Content-Type: application/json' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API' \\\n  --header 'Idempotency-Key: 8f5b5820-2d19-4be3-8f57-64c3d5d9e2f7' \\\n  --data '{\n    \"customer_reference_id\": \"CUST_EXAMPLE_001\",\n    \"due_date\": \"2026-06-30\",\n    \"payment_methods\": [\"boleto\", \"pix\"],\n    \"discount_type\": \"FIXED_VALUE\",\n    \"discount\": \"10.00\",\n    \"items\": [\n      {\n        \"description\": \"Mensalidade da plataforma\",\n        \"quantity\": 1,\n        \"price\": \"120.00\"\n      }\n    ]\n  }'\n```\n\n### Criar fatura em PHP\n\n```php\n$payload = [\n    'customer_reference_id' => 'CUST_EXAMPLE_001',\n    'due_date' => '2026-06-30',\n    'payment_methods' => ['boleto', 'pix'],\n    'discount_type' => 'FIXED_VALUE',\n    'discount' => '10.00',\n    'items' => [\n        [\n            'description' => 'Mensalidade da plataforma',\n            'quantity' => 1,\n            'price' => '120.00',\n        ],\n    ],\n];\n\n$ch = curl_init('https://app.mepagg.com/api/v1/invoices/');\ncurl_setopt_array($ch, [\n    CURLOPT_POST => true,\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_HTTPHEADER => [\n        'Content-Type: application/json',\n        'X-API-KEY: SUA_CHAVE_DE_API',\n        'Idempotency-Key: 8f5b5820-2d19-4be3-8f57-64c3d5d9e2f7',\n    ],\n    CURLOPT_POSTFIELDS => json_encode($payload),\n]);\n\n$response = curl_exec($ch);\n$statusCode = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);\ncurl_close($ch);\n```\n\n### Criar fatura em Node.js\n\n```js\nconst response = await fetch('https://app.mepagg.com/api/v1/invoices/', {\n  method: 'POST',\n  headers: {\n    'Content-Type': 'application/json',\n    'X-API-KEY': 'SUA_CHAVE_DE_API',\n    'Idempotency-Key': '8f5b5820-2d19-4be3-8f57-64c3d5d9e2f7'\n  },\n  body: JSON.stringify({\n    customer_reference_id: 'CUST_EXAMPLE_001',\n    due_date: '2026-06-30',\n    payment_methods: ['boleto', 'pix'],\n    discount_type: 'FIXED_VALUE',\n    discount: '10.00',\n    items: [\n      {\n        description: 'Mensalidade da plataforma',\n        quantity: 1,\n        price: '120.00'\n      }\n    ]\n  })\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);\n```\n\n### Criar fatura em Python\n\n```python\nimport requests\n\nurl = 'https://app.mepagg.com/api/v1/invoices/'\nheaders = {\n    'X-API-KEY': 'SUA_CHAVE_DE_API',\n    'Content-Type': 'application/json',\n    'Idempotency-Key': '8f5b5820-2d19-4be3-8f57-64c3d5d9e2f7',\n}\npayload = {\n    'customer_reference_id': 'CUST_EXAMPLE_001',\n    'due_date': '2026-06-30',\n    'payment_methods': ['boleto', 'pix'],\n    'discount_type': 'FIXED_VALUE',\n    'discount': '10.00',\n    'items': [\n        {\n            'description': 'Mensalidade da plataforma',\n            'quantity': 1,\n            'price': '120.00',\n        }\n    ],\n}\n\nresponse = requests.post(url, json=payload, headers=headers, timeout=30)\nprint(response.status_code)\nprint(response.json())\n```\n\n### Configurar webhook em cURL\n\n```bash\ncurl --request POST \\\n  --url 'https://app.mepagg.com/api/v1/settings/webhooks/' \\\n  --header 'Content-Type: application/json' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API' \\\n  --data '{\n    \"target_url\": \"https://erp.exemplo.com/webhooks/mepagg\",\n    \"subscribed_events\": [\"invoice.paid\", \"invoice.cancelled\", \"payment_link.status_changed\", \"transfer.completed\"],\n    \"is_enabled\": true\n  }'\n```"
    },
    {
      "name": "Clientes",
      "x-displayName": "Clientes",
      "x-section-id": "clientes",
      "description": "Cadastro, consulta, atualização e importação/exportação de clientes.\n\n> Rotas: `GET /api/v1/customers/`, `POST /api/v1/customers/`, `GET /api/v1/customers/{reference_id}/`, `PUT`, `PATCH`, `DELETE`, exportação e importação CSV.\n\n### Operações disponíveis\n\n| Método | Rota | Uso |\n| --- | --- | --- |\n| `GET` | `/api/v1/customers/` | Lista os clientes da conta autenticada com filtros por busca textual, localização e inadimplência. |\n| `POST` | `/api/v1/customers/` | Cria um cliente para cobranças avulsas, recorrências e carnês. |\n| `GET` | `/api/v1/customers/{reference_id}/` | Retorna o cadastro completo de um cliente. |\n| `PUT` | `/api/v1/customers/{reference_id}/` | Substitui integralmente os dados do cliente informado. |\n| `PATCH` | `/api/v1/customers/{reference_id}/` | Atualiza apenas os campos enviados no payload. |\n| `DELETE` | `/api/v1/customers/{reference_id}/` | Exclui o cliente informado da conta autenticada. |\n\n### Filtros da listagem\n\n| Parâmetro | Tipo | Obrigatório | Uso |\n| --- | --- | --- | --- |\n| `q` | string | Não | Busca textual por nome, documento, e-mail ou referência. |\n| `state` | string | Não | Filtra pela UF do cliente. |\n| `city` | string | Não | Filtra pela cidade do cliente. |\n| `is_defaulter` | boolean | Não | Filtra clientes adimplentes ou inadimplentes. |\n| `limit` | integer | Não | Paginação. Padrão `20`. |\n| `offset` | integer | Não | Paginação. Padrão `0`. |\n\n### Campos principais de criação\n\n| Campo | Tipo | Obrigatório | Formato / regra |\n| --- | --- | --- | --- |\n| `name` | string | Sim | Nome ou razão social |\n| `document` | string | Sim | CPF ou CNPJ com apenas números |\n| `email_primary` | string | Não | E-mail principal |\n| `email_secondary` | string | Não | E-mail alternativo |\n| `phone_number` | string | Não | Celular ou telefone com DDD |\n| `street` | string | Sim | Logradouro |\n| `neighborhood` | string | Sim | Bairro |\n| `city` | string | Sim | Cidade |\n| `state` | string | Sim | UF com 2 letras |\n| `zipcode` | string | Sim | CEP com apenas números |\n| `number` | string | Condicional | Obrigatório quando `no_number=false` |\n| `no_number` | boolean | Não | Dispensa `number` quando `true` |\n| `complement` | string | Não | Complemento |\n| `observation` | string | Não | Observação interna |\n\n### Campos principais de resposta\n\n| Campo | Tipo | Uso | Exemplo |\n| --- | --- | --- | --- |\n| `reference_id` | string | Identificador público estável do cliente na Mepagg. | `CUST_EXAMPLE_001` |\n| `name` | string | Nome completo ou razão social do cliente. | `Cliente Exemplo LTDA` |\n| `document` | string | CPF ou CNPJ retornado sem máscara. | `12345678000195` |\n| `email_primary` | string | E-mail principal usado nas comunicações. | `financeiro@clienteexemplo.com.br` |\n| `email_secondary` | string | E-mail secundário opcional para cópia. | `cobranca@clienteexemplo.com.br` |\n| `phone_number` | string | Telefone preferencialmente com DDD e apenas números. | `11987654321` |\n| `street` | string | Logradouro do endereço. | `Avenida Exemplo` |\n| `neighborhood` | string | Bairro do endereço. | `Jardim Modelo` |\n| `city` | string | Cidade do endereço. | `Sao Paulo` |\n| `state` | string | UF do endereço. | `SP` |\n| `zipcode` | string | CEP retornado com apenas números quando aplicável. | `01311000` |\n| `number` | string | Número do endereço. | `100` |\n| `no_number` | boolean | Indica endereço sem número definido. | `false` |\n| `complement` | string | Complemento do endereço. | `Sala 2` |\n| `observation` | string | Observação interna do cadastro. | `Cliente com comunicação por e-mail.` |\n| `is_defaulter` | boolean | Indica se o cliente está internamente marcado como inadimplente. | `false` |\n| `created_at` | datetime | Data e hora de criação do cliente. | `2026-06-17T09:10:00-03:00` |\n| `updated_at` | datetime | Data e hora da última atualização do cliente. | `2026-06-17T09:15:00-03:00` |\n\n### Exemplo de criação\n\n```json\n{\n  \"name\": \"Cliente Exemplo LTDA\",\n  \"document\": \"12345678000195\",\n  \"email_primary\": \"financeiro@clienteexemplo.com.br\",\n  \"phone_number\": \"11987654321\",\n  \"street\": \"Avenida Exemplo\",\n  \"neighborhood\": \"Jardim Modelo\",\n  \"number\": \"100\",\n  \"zipcode\": \"01311000\",\n  \"city\": \"Sao Paulo\",\n  \"state\": \"SP\"\n}\n```\n\n### Exemplo de listagem\n\n```json\n{\n  \"count\": 1,\n  \"results\": [\n    {\n      \"reference_id\": \"CUST_EXAMPLE_001\",\n      \"name\": \"Cliente Exemplo LTDA\",\n      \"document\": \"12345678000195\",\n      \"email_primary\": \"financeiro@clienteexemplo.com.br\",\n      \"phone_number\": \"11987654321\",\n      \"city\": \"Sao Paulo\",\n      \"state\": \"SP\",\n      \"is_defaulter\": false\n    }\n  ]\n}\n```\n\n### Exemplo de atualização parcial\n\n```json\n{\n  \"email_primary\": \"atualizado@clienteexemplo.com.br\",\n  \"phone_number\": \"11999990000\",\n  \"observation\": \"Cadastro atualizado pelo ERP.\"\n}\n```\n\n### Respostas HTTP\n\n| Status | Quando esperar |\n| --- | --- |\n| `200` | Listagem, consulta, criação, atualização ou exclusão processada com sucesso. |\n| `400` | Payload inválido, endereço inconsistente ou regra de cadastro não atendida. |\n| `401` | Chave ausente ou inválida. |\n| `404` | Cliente não localizado na conta autenticada. |\n| `422` | Documento, e-mail ou telefone aceitos no formato HTTP, mas rejeitados pela regra de negócio. |\n| `429` | Limite operacional excedido. |\n| `500` | Falha inesperada no backend. |"
    },
    {
      "name": "Faturas",
      "x-displayName": "Faturas",
      "x-section-id": "faturas",
      "description": "Cobranças avulsas com boleto, PIX ou ambos como formas de pagamento.\n\n> Rotas: `GET /api/v1/invoices/`, `POST /api/v1/invoices/`, `GET /api/v1/invoices/{reference_id}/`, cancelamento, estorno, segunda via, reenvio de e-mail e SMS.\n\n### Convenções financeiras\n\n| Campo | Como enviar | Exemplo | Observação |\n| --- | --- | --- | --- |\n| `price` | Valor unitário em reais | `\"120.00\"` | Use ponto como separador decimal. |\n| `quantity` | Quantidade positiva | `1` | A API aceita número ou string numérica. |\n| `fees` | Juros em valor monetário | `\"1.00\"` | Valor em reais, não percentual. |\n| `fines` | Multa em valor monetário | `\"2.00\"` | Valor em reais, não percentual. |\n| `discount_type` | `PERCENTAGE` ou `FIXED_VALUE` | `\"PERCENTAGE\"` | Define a interpretação do campo `discount`. |\n| `discount` | Percentual ou valor fixo | `\"10.00\"` | Se `PERCENTAGE`, representa percentual; se `FIXED_VALUE`, representa reais. |\n| `inter_boleto_num_dias_agenda` | Prazo de agenda do boleto | `3` | Valor entre `1` e `60` quando aplicável. |\n\n### Operações disponíveis\n\n| Método | Rota | Uso |\n| --- | --- | --- |\n| `GET` | `/api/v1/invoices/` | Lista faturas. Para interface, priorize `status_label` e `type_label`. Para regras, use `status_code` e `type_code`. |\n| `POST` | `/api/v1/invoices/` | Cria fatura com boleto, PIX ou ambos como formas de pagamento. |\n| `GET` | `/api/v1/invoices/{reference_id}/` | Consulta o estado atual da fatura. |\n| `POST` | `/api/v1/invoices/{reference_id}/cancel/` | Cancela uma fatura ainda elegível para cancelamento. |\n| `POST` | `/api/v1/invoices/{reference_id}/refund/` | Solicita estorno de uma fatura paga quando a regra operacional permitir. |\n| `GET` | `/api/v1/invoices/{reference_id}/second-copy/` | Retorna dados atualizados para segunda via da cobrança. |\n| `POST` | `/api/v1/invoices/{reference_id}/resend-email/` | Reenvia a comunicação de cobrança por e-mail. |\n| `POST` | `/api/v1/invoices/{reference_id}/resend-sms/` | Reenvia a comunicação de cobrança por SMS. |\n\n### Filtros da listagem\n\n| Parâmetro | Tipo | Obrigatório | Uso |\n| --- | --- | --- | --- |\n| `q` | string | Não | Busca textual por referência, nome ou documento relacionado. |\n| `customer_reference_id` | string | Não | Filtra faturas de um cliente específico. |\n| `status` | string | Não | Filtra pelo código estável do status. |\n| `type` | string | Não | Filtra pelo código estável do tipo. |\n| `start_due_date` | date | Não | Vencimento inicial no formato `YYYY-MM-DD`. |\n| `end_due_date` | date | Não | Vencimento final no formato `YYYY-MM-DD`. |\n| `limit` | integer | Não | Paginação. Padrão `20`. |\n| `offset` | integer | Não | Paginação. Padrão `0`. |\n\n### Headers importantes\n\n| Header | Obrigatório | Uso |\n| --- | --- | --- |\n| `X-API-KEY` | Sim | Autentica a conta emissora da cobrança. |\n| `Idempotency-Key` | Recomendado no `POST` | Previne duplicidade acidental em retries de criação, cancelamento e estorno. |\n\n### Campos principais\n\n| Campo | Tipo | Obrigatório | Formato / regra |\n| --- | --- | --- | --- |\n| `customer_reference_id` | string | Sim* | Cliente da mesma conta |\n| `customer_id` | integer | Sim* | Alternativa a `customer_reference_id` |\n| `due_date` | string | Sim | Formato `YYYY-MM-DD`. Não pode ser retroativa. |\n| `payment_methods` | array[string] | Sim* | `[\"boleto\"]`, `[\"pix\"]` ou `[\"boleto\",\"pix\"]` |\n| `items` | array | Sim | Itens da cobrança. A fatura aceita um ou vários produtos/serviços e o total é calculado pela soma dos itens. |\n| `fees` | number|string | Não | Juros em valor monetário. Exemplo: `\"1.00\"` |\n| `fines` | number|string | Não | Multa em valor monetário. Exemplo: `\"2.00\"` |\n| `discount_type` | string | Não | `PERCENTAGE` ou `FIXED_VALUE` |\n| `discount` | number|string | Não | Percentual ou valor fixo conforme `discount_type` |\n| `inter_boleto_num_dias_agenda` | integer | Não | Entre `1` e `60` quando aplicável |\n\n### Estrutura dos itens\n\n| Campo | Tipo | Obrigatório | Formato / regra |\n| --- | --- | --- | --- |\n| `description` | string | Sim | Descrição do item |\n| `qty` ou `quantity` | number|string | Sim | Quantidade positiva. `qty` é o nome canônico retornado na resposta. |\n| `price` | number|string | Sim | Valor unitário não negativo |\n\n> A fatura aceita um ou vários itens com descrições diferentes. O `total_amount` da fatura é a soma de `qty × price` de todos os itens, antes dos ajustes de juros, multa e desconto.\n\n### Valor mínimo de criação\n\n> O valor total mínimo para criar uma fatura é  R$ 5,00 . Essa validação considera a soma de todos os itens enviados antes da emissão da cobrança.\n\n### Regras operacionais de vencimento\n\n> Para cobranças com `boleto` e/ou `pix`, a API não aceita vencimento retroativo e também bloqueia criação com vencimento no mesmo dia a partir das  20h  (horário local da operação).\n\n### Leitura do valor final\n\n| Etapa | Como interpretar |\n| --- | --- |\n| Soma dos itens | Base principal da cobrança. Some `qty × price` de todos os itens enviados. |\n| Juros | Campo `fees`, sempre em valor monetário em reais. |\n| Multa | Campo `fines`, sempre em valor monetário em reais. |\n| Desconto | Campo `discount`, interpretado por `discount_type` como percentual ou valor fixo. |\n| Total da fatura | Leia pelo campo retornado pela API, como `total_amount` ou `total`, e não recalcule no frontend após criação. |\n| Valor pago | Use `amount_paid` e `paid_at` quando houver confirmação de pagamento. |\n\n### Campos recomendados de leitura\n\n- `reference_id`: identificador externo da fatura.\n- `status_label`: exibir em interface.\n- `status_code`: regras, filtros e automações.\n- `type_label`: exibir em interface.\n- `type_code`: regras e integrações.\n- `paid_at`: data e hora de pagamento quando houver.\n- `amount_paid`: valor efetivamente pago quando houver.\n- `public_url`: abre a cobrança pública da Mepagg.\n- `public_boleto_url`: abre a impressão pública do boleto quando houver.\n- `boleto.linha_digitavel`, `boleto.codigo_barras` e `boleto.nosso_numero`: base para montar boleto próprio.\n- `pix.copia_e_cola`: base para exibir pagamento Pix quando disponível.\n\n### Campos principais da resposta detalhada\n\n| Campo | Tipo | Uso | Exemplo |\n| --- | --- | --- | --- |\n| `reference_id` | string | Identificador público estável da cobrança. | `GLZOX8K19Q40NVLJ6WJ2PRYD7EV653` |\n| `status` | integer | Código numérico retornado para compatibilidade. | `2` |\n| `status_code` | string | Código estável para automação. | `paid` |\n| `status_label` | string | Texto amigável para interface. | `Paga` |\n| `type` | integer | Código numérico do tipo. | `3` |\n| `type_code` | string | Código estável do tipo para integração. | `oneoff` |\n| `type_label` | string | Texto amigável do tipo. | `Avulsa` |\n| `payment_methods` | array[string] | Formas de pagamento habilitadas na cobrança. | `[\"boleto\",\"pix\"]` |\n| `payment_methods_display` | string | Texto pronto para interface. | `Boleto, Pix` |\n| `due_date` | date | Vencimento da cobrança. | `2026-06-15` |\n| `total_amount` / `total` | string | Valor total da cobrança em reais. | `5200.00` |\n| `amount_paid` | string | Valor efetivamente pago. | `5200.00` |\n| `paid_at` | datetime|null | Data e hora de confirmação do pagamento. | `2026-06-15T10:18:00-03:00` |\n| `cancelled_reason` | string | Motivo do cancelamento quando a cobrança é cancelada. | `Cobrança substituída por nova emissão.` |\n| `public_url` | string | Link público da fatura no modelo Mepagg. | `https://app.mepagg.com/fatura/GLZOX8...` |\n| `public_boleto_url` | string|null | Link público do boleto pronto para impressão. | `https://app.mepagg.com/fatura/.../boleto/` |\n| `items` | array | Itens cobrados com quantidade, valor unitário e total por item. | `[...]` |\n| `customer` | object | Resumo do cliente vinculado. | `{...}` |\n| `boleto` | object | Dados estruturados do boleto quando houver. | `{...}` |\n| `pix` | object | Dados estruturados do Pix quando houver. | `{...}` |\n\n### Operações auxiliares da fatura\n\n| Rota | Payload | Uso |\n| --- | --- | --- |\n| `POST /api/v1/invoices/{reference_id}/cancel/` | `{\"cancelled_reason\":\"...\"}` | Cancela uma cobrança elegível e registra o motivo do cancelamento. |\n| `POST /api/v1/invoices/{reference_id}/refund/` | `{\"refund_reason\":\"...\"}` | Solicita estorno operacional quando a fatura já foi paga e a regra permitir. |\n| `GET /api/v1/invoices/{reference_id}/second-copy/` | Sem body | Gera e consulta uma segunda via atualizada da cobrança. |\n| `POST /api/v1/invoices/{reference_id}/resend-email/` | Sem body | Dispara novamente a comunicação por e-mail ao cliente. |\n| `POST /api/v1/invoices/{reference_id}/resend-sms/` | Sem body | Dispara novamente a comunicação por SMS ao cliente. |\n\n### Acesso público e impressão\n\nA API retorna links públicos para a própria cobrança e, quando existir boleto emitido, também para a tela pública de boleto. Isso permite duas estratégias de integração.\n\n| Estratégia | Como usar | Quando faz sentido |\n| --- | --- | --- |\n| Usar o modelo Mepagg | Abrir `public_url` da fatura ou `public_boleto_url` do boleto. | Quando a conta quer implantação rápida e impressão pronta. |\n| Montar modelo próprio | Usar os campos estruturados do objeto `invoice`, `boleto` e `pix`. | Quando a conta quer personalizar layout, UX e marca. |\n\n### Campos sugeridos para boleto próprio\n\n| Bloco | Campos sugeridos |\n| --- | --- |\n| Identificação da cobrança | `reference_id`, `due_date`, `total_amount`, `status_label` |\n| Pagador | `customer.name`, `customer.reference_id`, documento e endereço quando o sistema da conta já tiver esses dados do cliente |\n| Boleto | `boleto.linha_digitavel`, `boleto.codigo_barras`, `boleto.nosso_numero`, `boleto.pdf_url`, `public_boleto_url` |\n| Pix complementar | `pix.copia_e_cola`, `pix.txid`, `public_url` |\n| Intermediação obrigatória | Exibir `Mepagg LTDA - CNPJ 05.098.228/0001-80` como intermediação operacional da cobrança. |\n\n### Exemplos práticos de cobrança\n\n\n### Sem juros, multa ou desconto\n\n```json\n{\n  \"customer_reference_id\": \"CUST_EXAMPLE_001\",\n  \"due_date\": \"2026-06-30\",\n  \"payment_methods\": [\"boleto\", \"pix\"],\n  \"items\": [\n    {\n      \"description\": \"Mensalidade da plataforma\",\n      \"quantity\": 1,\n      \"price\": \"120.00\"\n    }\n  ]\n}\n```\n\n\n\n### Com juros e multa em reais\n\n```json\n{\n  \"customer_reference_id\": \"CUST_EXAMPLE_001\",\n  \"due_date\": \"2026-06-30\",\n  \"payment_methods\": [\"boleto\"],\n  \"fees\": \"1.50\",\n  \"fines\": \"2.00\",\n  \"items\": [\n    {\n      \"description\": \"Mensalidade da plataforma\",\n      \"quantity\": 1,\n      \"price\": \"120.00\"\n    }\n  ]\n}\n```\n\n\n### Com desconto percentual\n\n```json\n{\n  \"customer_reference_id\": \"CUST_EXAMPLE_001\",\n  \"due_date\": \"2026-06-30\",\n  \"payment_methods\": [\"pix\"],\n  \"discount_type\": \"PERCENTAGE\",\n  \"discount\": \"10.00\",\n  \"items\": [\n    {\n      \"description\": \"Plano anual - parcela 1\",\n      \"quantity\": 1,\n      \"price\": \"200.00\"\n    }\n  ]\n}\n```\n\n\n\n### Com desconto fixo em reais\n\n```json\n{\n  \"customer_reference_id\": \"CUST_EXAMPLE_001\",\n  \"due_date\": \"2026-06-30\",\n  \"payment_methods\": [\"boleto\", \"pix\"],\n  \"discount_type\": \"FIXED_VALUE\",\n  \"discount\": \"15.00\",\n  \"inter_boleto_num_dias_agenda\": 3,\n  \"items\": [\n    {\n      \"description\": \"Mensalidade da plataforma\",\n      \"quantity\": 1,\n      \"price\": \"120.00\"\n    }\n  ]\n}\n```\n\n\n### Com mais de um produto ou serviço\n\n```json\n{\n  \"customer_reference_id\": \"CUST_EXAMPLE_001\",\n  \"due_date\": \"2026-06-30\",\n  \"payment_methods\": [\"boleto\", \"pix\"],\n  \"items\": [\n    {\n      \"description\": \"Mensalidade da plataforma\",\n      \"qty\": 1,\n      \"price\": \"120.00\"\n    },\n    {\n      \"description\": \"Implantação inicial\",\n      \"quantity\": 2,\n      \"price\": \"35.00\"\n    }\n  ]\n}\n```\n\nTotal dos itens: `120.00 + (2 × 35.00) = 190.00`.\n\n\n### Exemplo de criação\n\n```json\n{\n  \"customer_reference_id\": \"CUST_EXAMPLE_001\",\n  \"due_date\": \"2026-06-30\",\n  \"payment_methods\": [\"boleto\", \"pix\"],\n  \"discount_type\": \"FIXED_VALUE\",\n  \"discount\": \"10.00\",\n  \"items\": [\n    {\n      \"description\": \"Mensalidade da plataforma\",\n      \"quantity\": 1,\n      \"price\": \"120.00\"\n    }\n  ]\n}\n```\n\n\n\n### Exemplo de resposta\n\n```json\n{\n  \"success\": true,\n  \"invoice\": {\n    \"reference_id\": \"GLZOX8K19Q40NVLJ6WJ2PRYD7EV653\",\n    \"status\": 2,\n    \"status_code\": \"paid\",\n    \"status_label\": \"Paga\",\n    \"type\": 3,\n    \"type_code\": \"oneoff\",\n    \"type_label\": \"Avulsa\",\n    \"payment_methods\": [\"boleto\", \"pix\"],\n    \"fees\": \"1.00\",\n    \"fines\": \"2.00\",\n    \"due_date\": \"2026-06-15\",\n    \"total\": \"5200.00\",\n    \"amount_paid\": \"5200.00\",\n    \"paid_at\": \"2026-06-15T10:18:00-03:00\",\n    \"public_url\": \"https://app.mepagg.com/fatura/GLZOX8K19Q40NVLJ6WJ2PRYD7EV653/\",\n    \"public_boleto_url\": \"https://app.mepagg.com/fatura/conta_publica_exemplo/GLZOX8K19Q40NVLJ6WJ2PRYD7EV653/boleto/\",\n    \"boleto\": {\n      \"public_url\": \"https://app.mepagg.com/fatura/conta_publica_exemplo/GLZOX8K19Q40NVLJ6WJ2PRYD7EV653/boleto/\",\n      \"pdf_url\": \"https://boleto.exemplo.test/arquivo.pdf\",\n      \"linha_digitavel\": \"07791000000000000000123456789012345678901234\",\n      \"codigo_barras\": \"07791234567890123456789012345678901234567890\",\n      \"nosso_numero\": \"1234567890\"\n    },\n    \"pix\": {\n      \"public_url\": \"https://app.mepagg.com/fatura/GLZOX8K19Q40NVLJ6WJ2PRYD7EV653/\",\n      \"txid\": \"pix_txid_exemplo_001\",\n      \"copia_e_cola\": \"00020101021226850014br.gov.bcb.pix...\"\n    }\n  }\n}\n```\n\n### Exemplo de listagem\n\n```json\n{\n  \"count\": 2,\n  \"results\": [\n    {\n      \"reference_id\": \"GLZOX8K19Q40NVLJ6WJ2PRYD7EV653\",\n      \"status_code\": \"paid\",\n      \"status_label\": \"Paga\",\n      \"type_code\": \"oneoff\",\n      \"type_label\": \"Avulsa\",\n      \"due_date\": \"2026-06-15\",\n      \"total\": \"5200.00\"\n    },\n    {\n      \"reference_id\": \"KQ38REJLG9O2W2Q86NY7VIP564ZDX0\",\n      \"status_code\": \"paid\",\n      \"status_label\": \"Paga\",\n      \"type_code\": \"oneoff\",\n      \"type_label\": \"Avulsa\",\n      \"due_date\": \"2026-06-15\",\n      \"total\": \"1020.00\"\n    }\n  ]\n}\n```\n\n### Exemplo de cancelamento\n\n```json\n{\n  \"cancelled_reason\": \"Cobrança substituída por nova emissão.\"\n}\n```\n\n### Exemplo de estorno\n\n```json\n{\n  \"refund_reason\": \"Pagamento recebido em duplicidade.\"\n}\n```\n\n### Exemplo de segunda via\n\n```json\n{\n  \"success\": true,\n  \"invoice\": {\n    \"reference_id\": \"GLZOX8K19Q40NVLJ6WJ2PRYD7EV653\",\n    \"status_code\": \"to_expire\",\n    \"status_label\": \"A vencer\",\n    \"public_url\": \"https://app.mepagg.com/fatura/GLZOX8K19Q40NVLJ6WJ2PRYD7EV653/\",\n    \"public_boleto_url\": \"https://app.mepagg.com/fatura/conta_publica_exemplo/GLZOX8K19Q40NVLJ6WJ2PRYD7EV653/boleto/\"\n  }\n}\n```\n\n### Fluxo recomendado da fatura em produção\n\n1. Criar o cliente e persistir o `customer_reference_id`.\n2. Criar a fatura com `Idempotency-Key` e persistir o `reference_id`.\n3. Exibir `public_url`, `public_boleto_url`, `boleto` e `pix` conforme a experiência desejada.\n4. Receber o webhook de mudança relevante, como `invoice.paid`, `invoice.cancelled` ou `invoice.refunded`.\n5. Reconsultar `GET /api/v1/invoices/{reference_id}/` e confirmar `status_code`, `amount_paid` e `paid_at`.\n6. Conciliar financeiramente no extrato usando o `related_reference_id` quando aplicável.\n\n### Respostas HTTP\n\n| Status | Quando esperar |\n| --- | --- |\n| `200` | Listagem, consulta, criação, cancelamento, estorno ou reenvio processado com sucesso. |\n| `400` | Payload inválido, total inconsistente, item incompleto ou regra operacional não atendida. |\n| `401` | Chave ausente ou inválida. |\n| `404` | Fatura não localizada na conta autenticada. |\n| `409` | Conflito de idempotência ou estado atual incompatível com a operação solicitada. |\n| `422` | Cliente, forma de pagamento, desconto, juros ou multa rejeitados pela regra de negócio. |\n| `429` | Limite operacional excedido. |\n| `500` | Falha inesperada no backend. |"
    },
    {
      "name": "Assinaturas",
      "x-displayName": "Assinaturas",
      "x-section-id": "assinaturas",
      "description": "Recorrências da conta autenticada.\n\n- `GET /api/v1/subscriptions/`\n- `POST /api/v1/subscriptions/`\n- `GET /api/v1/subscriptions/{reference_id}/`\n- `POST /api/v1/subscriptions/{reference_id}/status/`\n\n### Operações disponíveis\n\n| Método | Rota | Uso |\n| --- | --- | --- |\n| `GET` | `/api/v1/subscriptions/` | Lista as assinaturas da conta autenticada. |\n| `POST` | `/api/v1/subscriptions/` | Cria assinatura para recorrência previsível. |\n| `GET` | `/api/v1/subscriptions/{reference_id}/` | Retorna os dados principais da assinatura informada. |\n| `POST` | `/api/v1/subscriptions/{reference_id}/status/` | Altera o status operacional da assinatura. |\n\n### Campos principais de criação\n\n| Campo | Tipo | Obrigatório | Formato / regra |\n| --- | --- | --- | --- |\n| `customer_reference_id` | string | Sim* | Cliente da mesma conta. |\n| `customer_id` | integer | Sim* | Alternativa a `customer_reference_id`. |\n| `interval` | string | Sim | Periodicidade da recorrência. Veja a lista completa em **Tipos de recorrência aceitos**. |\n| `cycles` | integer | Não | Entre `0` e `120`. Use `0` para recorrência sem limite fixo. |\n| `last_due_date` | date | Sim | Último vencimento previsto no formato `YYYY-MM-DD`. Não pode ser menor que a data de hoje. |\n| `status` | string | Não | `ACTIVE` ou `SUSPENDED`. Na criação, normalmente use `ACTIVE`. |\n| `payment_methods` | array[string] | Sim* | `[\"boleto\"]`, `[\"pix\"]` ou ambos, conforme a conta permitir. |\n| `items` | array | Sim | Itens recorrentes da assinatura. A assinatura aceita um ou vários produtos/serviços e o total é a soma deles. |\n| `fees` | number|string | Não | Juros em valor monetário. |\n| `fines` | number|string | Não | Multa em valor monetário. |\n| `discount_type` | string | Não | `PERCENTAGE` ou `FIXED_VALUE`. |\n| `discount` | number|string | Não | Valor conforme `discount_type`. |\n\n### Tipos de recorrência aceitos\n\n| `interval` | `interval_label` | Quando usar |\n| --- | --- | --- |\n| `WEEKLY` | `Semanal` | Cobranças com repetição a cada 7 dias. |\n| `BIWEEKLY` | `Quinzenal` | Cobranças com repetição a cada 15 dias. |\n| `MONTHLY` | `Mensal` | Cobranças com repetição mensal. |\n| `BIMONTHLY` | `Bimestral` | Cobranças com repetição a cada 2 meses. |\n| `QUARTERLY` | `Trimestral` | Cobranças com repetição a cada 3 meses. |\n| `FOUR_MONTHS` | `Quadrimestral` | Cobranças com repetição a cada 4 meses. |\n| `SEMIANNUAL` | `Semestral` | Cobranças com repetição a cada 6 meses. |\n| `YEARLY` | `Anual` | Cobranças com repetição anual. |\n\n### Valor mínimo de criação\n\n> O valor total mínimo para criar uma assinatura é  R$ 5,00 . Essa validação considera a soma de todos os itens recorrentes enviados.\n\n### Regras operacionais adicionais\n\n> `payment_methods` é obrigatório na criação pública da assinatura. O campo `cycles` aceita de  0  a  120 , e `last_due_date` não pode ser anterior à data atual.\n\n### Convenções da recorrência\n\n| Campo | Como interpretar | Exemplo | Observação |\n| --- | --- | --- | --- |\n| `interval` | Código da periodicidade | `MONTHLY` | Aceita `WEEKLY`, `BIWEEKLY`, `MONTHLY`, `BIMONTHLY`, `QUARTERLY`, `FOUR_MONTHS`, `SEMIANNUAL` e `YEARLY`. |\n| `interval_label` | Texto amigável da periodicidade | `Mensal` | Campo próprio para exibição. |\n| `next_due_date` | Próximo vencimento previsto | `2026-07-10` | Formato `YYYY-MM-DD`. |\n| `last_due_date` | Último vencimento previsto | `2027-06-10` | Pode vir vazio em recorrências sem data final definida. |\n| `date_billing_next` | Próxima data prevista de faturamento | `2026-07-07` | Pode diferir do vencimento conforme a regra operacional. |\n| `due_day_anchor` | Dia âncora do vencimento | `10` | Usado para repetição da cobrança nos próximos ciclos. |\n| `cycles` | Quantidade de ciclos configurados | `12` | `0` normalmente representa recorrência sem limite fixo. |\n| `fees` | Juros em valor monetário | `\"1.00\"` | Valor em reais, não percentual. |\n| `fines` | Multa em valor monetário | `\"2.00\"` | Valor em reais, não percentual. |\n| `discount_type` | `PERCENTAGE` ou `FIXED_VALUE` | `FIXED_VALUE` | Define a interpretação do campo `discount`. |\n| `discount` | Percentual ou valor fixo | `\"10.00\"` | Se `PERCENTAGE`, representa percentual; se `FIXED_VALUE`, representa reais. |\n\n### Campos principais de resposta\n\n| Campo | Tipo | Formato / regra | Exemplo |\n| --- | --- | --- | --- |\n| `id` | integer | Identificador interno | `91` |\n| `reference_id` | string | Identificador público da assinatura | `SUB_A1B2C3` |\n| `status` | string | Código interno | `ACTIVE` |\n| `status_code` | string | Código estável para regras | `active` |\n| `status_label` | string | Texto amigável para interface | `Ativa` |\n| `interval` | string | Periodicidade configurada | `MONTHLY` |\n| `interval_label` | string | Texto amigável da periodicidade | `Mensal` |\n| `next_due_date` | date | Formato `YYYY-MM-DD` | `2026-07-10` |\n| `due_day_anchor` | integer | Dia âncora do vencimento | `10` |\n| `cycles` | integer | `0` normalmente representa recorrência sem limite fixo | `12` |\n| `fees` | string | Juros em reais | `1.00` |\n| `fines` | string | Multa em reais | `2.00` |\n| `discount_type` | string | `PERCENTAGE` ou `FIXED_VALUE` | `FIXED_VALUE` |\n| `discount` | string | Valor do desconto conforme `discount_type` | `10.00` |\n| `has_overdue_invoices` | boolean | Indica se existem faturas vencidas em aberto | `false` |\n| `payment_methods` | array | Formas de pagamento vinculadas | `[...]` |\n| `customer` | object | Cliente vinculado | `{...}` |\n| `items` | array | Itens recorrentes. O `total_amount` da assinatura é a soma deles. | `[...]` |\n| `total_amount` | string | Valor total calculado | `120.00` |\n\n### Estrutura dos itens da assinatura\n\n| Campo | Tipo | Obrigatório | Formato / regra |\n| --- | --- | --- | --- |\n| `description` | string | Sim | Descrição do produto ou serviço recorrente. |\n| `qty` ou `quantity` | number|string | Sim | Quantidade positiva. A resposta retorna `qty`. |\n| `price` | number|string | Sim | Valor unitário em reais. |\n\n> A assinatura pode ter um ou vários itens com valores diferentes. O `total_amount` retornado pela API corresponde à soma de `qty × price` de todos os itens recorrentes.\n\n### Alteração de status da assinatura\n\n| Rota | Payload | Uso |\n| --- | --- | --- |\n| `POST /api/v1/subscriptions/{reference_id}/status/` | `{\"status\":\"SUSPENDED\"}` ou `{\"status\":\"ACTIVE\"}` | Suspende ou reativa a recorrência sem trocar o identificador público da assinatura. |\n\n### Exemplo de resposta\n\n```json\n{\n  \"success\": true,\n  \"subscription\": {\n    \"id\": 91,\n    \"reference_id\": \"SUB_A1B2C3\",\n    \"status\": \"ACTIVE\",\n    \"status_code\": \"active\",\n    \"status_label\": \"Ativa\",\n    \"interval\": \"MONTHLY\",\n    \"interval_label\": \"Mensal\",\n    \"next_due_date\": \"2026-07-10\",\n    \"due_day_anchor\": 10,\n    \"cycles\": 12,\n    \"fees\": \"1.00\",\n    \"fines\": \"2.00\",\n    \"discount_type\": \"FIXED_VALUE\",\n    \"discount\": \"10.00\",\n    \"has_overdue_invoices\": false,\n    \"payment_methods\": [\n      {\n        \"id\": 1,\n        \"label\": \"Boleto\",\n        \"code\": \"boleto\"\n      }\n    ],\n    \"customer\": {\n      \"id\": 814,\n      \"reference_id\": \"CUST_EXAMPLE_001\",\n      \"name\": \"Cliente Exemplo LTDA\",\n      \"email_primary\": \"financeiro@clienteexemplo.com.br\"\n    },\n    \"items\": [\n      {\n        \"description\": \"Mensalidade da plataforma\",\n        \"qty\": 1,\n        \"price\": \"120.00\"\n      }\n    ],\n    \"total_amount\": \"120.00\"\n  }\n}\n```\n\n### Exemplo de criação\n\n```json\n{\n  \"customer_reference_id\": \"CUST_EXAMPLE_001\",\n  \"interval\": \"MONTHLY\",\n  \"due_day_anchor\": 10,\n  \"cycles\": 12,\n  \"payment_methods\": [\"boleto\", \"pix\"],\n  \"fees\": \"1.00\",\n  \"fines\": \"2.00\",\n  \"discount_type\": \"FIXED_VALUE\",\n  \"discount\": \"10.00\",\n  \"items\": [\n    {\n      \"description\": \"Mensalidade da plataforma\",\n      \"qty\": 1,\n      \"price\": \"120.00\"\n    }\n  ]\n}\n```\n\n### Exemplo com mais de um item recorrente\n\n```json\n{\n  \"customer_reference_id\": \"CUST_EXAMPLE_001\",\n  \"interval\": \"MONTHLY\",\n  \"cycles\": 12,\n  \"payment_methods\": [\"boleto\", \"pix\"],\n  \"items\": [\n    {\n      \"description\": \"Licença principal\",\n      \"qty\": 1,\n      \"price\": \"49.90\"\n    },\n    {\n      \"description\": \"Usuário adicional\",\n      \"quantity\": 2,\n      \"price\": \"15.00\"\n    }\n  ]\n}\n```\n\nTotal recorrente: `49.90 + (2 × 15.00) = 79.90`.\n\n### Exemplo de alteração de status\n\n```json\n{\n  \"status\": \"SUSPENDED\"\n}\n```\n\n### Como ler a assinatura na prática\n\n- `status_code` e `status_label` representam a situação atual da recorrência.\n- `interval`, `interval_label`, `next_due_date` e `last_due_date` orientam o calendário previsto da cobrança.\n- `items` representa exatamente o que será faturado nos próximos ciclos.\n- `has_overdue_invoices` ajuda o sistema da conta a sinalizar recorrências com pendências financeiras abertas.\n- `payment_methods` informa quais formas de pagamento devem ser usadas nas faturas futuras geradas pela assinatura.\n\n### Respostas HTTP\n\n| Status | Quando esperar |\n| --- | --- |\n| `200` | Listagem, consulta ou criação processada com sucesso. |\n| `400` | Payload inválido, cliente incompatível ou regra operacional não atendida. |\n| `401` | Chave ausente ou inválida. |\n| `429` | Limite operacional excedido. |\n| `500` | Falha inesperada no backend. |"
    },
    {
      "name": "Planos",
      "x-displayName": "Planos",
      "x-section-id": "planos",
      "description": "Planos de assinatura reutilizáveis da conta autenticada. Use estes recursos para criar, listar, consultar, editar e remover os planos que podem ser vinculados às assinaturas.\n\n- `GET /api/v1/subscription-plans/`\n- `POST /api/v1/subscription-plans/`\n- `GET /api/v1/subscription-plans/{reference_id}/`\n- `PUT /api/v1/subscription-plans/{reference_id}/`\n- `PATCH /api/v1/subscription-plans/{reference_id}/`\n- `DELETE /api/v1/subscription-plans/{reference_id}/`\n\n### Operações disponíveis\n\n| Método | Rota | Uso |\n| --- | --- | --- |\n| `GET` | `/api/v1/subscription-plans/` | Lista os planos cadastrados na conta autenticada. |\n| `POST` | `/api/v1/subscription-plans/` | Cria um novo plano reutilizável para assinaturas. |\n| `GET` | `/api/v1/subscription-plans/{reference_id}/` | Retorna os dados completos de um plano específico. |\n| `PUT` | `/api/v1/subscription-plans/{reference_id}/` | Atualiza completamente o plano informado. |\n| `PATCH` | `/api/v1/subscription-plans/{reference_id}/` | Atualiza apenas os campos enviados. |\n| `DELETE` | `/api/v1/subscription-plans/{reference_id}/` | Remove logicamente o plano quando ele não estiver vinculado a assinaturas. |\n\n### Filtros da listagem\n\n| Parâmetro | Tipo | Obrigatório | Uso |\n| --- | --- | --- | --- |\n| `q` | string | Não | Busca por nome do plano ou `reference_id`. |\n| `interval` | string | Não | Filtra pela recorrência do plano. Use os mesmos códigos da assinatura, como `MONTHLY` ou `YEARLY`. |\n| `limit` | integer | Não | Paginação. Entre `1` e `200`. |\n| `offset` | integer | Não | Paginação. Padrão `0`. |\n\n### Campos principais de criação e edição\n\n| Campo | Tipo | Obrigatório | Formato / regra |\n| --- | --- | --- | --- |\n| `name` | string | Sim | Nome comercial do plano. |\n| `amount` | number|string | Sim | Valor principal do plano em reais. |\n| `interval` | string | Sim | Recorrência do plano. Veja a tabela em **Tipos de recorrência aceitos** na seção de assinaturas. |\n| `payment_method_ids` | array[integer] | Sim | IDs internos das formas de pagamento aceitas no plano. |\n| `fees` | number|string | Não | Juros em valor monetário. |\n| `fines` | number|string | Não | Multa em valor monetário. |\n| `discount_type` | string | Não | `PERCENTAGE` ou `FIXED_VALUE`. |\n| `discount` | number|string | Não | Valor conforme `discount_type`. |\n| `inter_boleto_num_dias_agenda` | integer | Não | Entre `1` e `60` quando aplicável ao boleto. |\n| `is_active` | boolean | Não | Estado operacional do plano. |\n\n### Campos principais de resposta\n\n| Campo | Tipo | Uso | Exemplo |\n| --- | --- | --- | --- |\n| `id` | integer | Identificador interno do plano. | `18` |\n| `reference_id` | string | Identificador público do plano. | `PLAN_01JABCXYZ` |\n| `name` | string | Nome comercial do plano. | `Mensalidade hospedagem` |\n| `amount` | string | Valor base do plano em reais. | `85.00` |\n| `interval` | string | Código da recorrência. | `MONTHLY` |\n| `interval_label` | string | Texto amigável da recorrência. | `Mensal` |\n| `subscriptions_count` | integer | Quantidade de assinaturas vinculadas a esse plano. | `3` |\n| `payment_methods` | array | Formas de pagamento ligadas ao plano. | `[{...}]` |\n| `is_active` | boolean | Indica se o plano está ativo. | `true` |\n| `created_at` | datetime | Data de criação. | `2026-07-11T10:30:00-03:00` |\n| `updated_at` | datetime | Última atualização. | `2026-07-11T10:35:00-03:00` |\n\n### Regras importantes\n\n- `POST`, `PUT`, `PATCH` e `DELETE` aceitam `Idempotency-Key`.\n- Um plano não pode ser removido enquanto existir assinatura vinculada a ele.\n- Ao editar um plano, a Mepagg sincroniza os campos gerenciados do plano com as assinaturas vinculadas por esse modelo.\n- A remoção é lógica: o plano deixa de aparecer na listagem pública, mas pode permanecer referenciado em histórico operacional.\n\n### Exemplo de criação\n\n```json\n{\n  \"name\": \"Mensalidade hospedagem\",\n  \"amount\": \"85.00\",\n  \"interval\": \"MONTHLY\",\n  \"fees\": \"1.00\",\n  \"fines\": \"2.00\",\n  \"discount_type\": \"FIXED_VALUE\",\n  \"discount\": \"5.00\",\n  \"inter_boleto_num_dias_agenda\": 3,\n  \"payment_method_ids\": [1, 2],\n  \"is_active\": true\n}\n```\n\n### Exemplo de resposta\n\n```json\n{\n  \"success\": true,\n  \"plan\": {\n    \"id\": 18,\n    \"reference_id\": \"PLAN_01JABCXYZ\",\n    \"name\": \"Mensalidade hospedagem\",\n    \"amount\": \"85.00\",\n    \"interval\": \"MONTHLY\",\n    \"interval_label\": \"Mensal\",\n    \"subscriptions_count\": 3,\n    \"fees\": \"1.00\",\n    \"fines\": \"2.00\",\n    \"discount_type\": \"FIXED_VALUE\",\n    \"discount\": \"5.00\",\n    \"inter_boleto_num_dias_agenda\": 3,\n    \"payment_methods\": [\n      {\n        \"id\": 1,\n        \"name\": \"Boleto\",\n        \"slug\": \"boleto\"\n      },\n      {\n        \"id\": 2,\n        \"name\": \"Pix\",\n        \"slug\": \"pix\"\n      }\n    ],\n    \"is_active\": true,\n    \"created_at\": \"2026-07-11T10:30:00-03:00\",\n    \"updated_at\": \"2026-07-11T10:35:00-03:00\"\n  }\n}\n```\n\n### Respostas HTTP\n\n| Status | Quando esperar |\n| --- | --- |\n| `200` | Listagem, consulta, atualização parcial/completa ou remoção processada com sucesso. |\n| `201` | Plano criado com sucesso. |\n| `400` | Payload inválido, filtro inválido ou tentativa de remover plano vinculado a assinaturas. |\n| `401` | Chave ausente ou inválida. |\n| `404` | Plano não encontrado na conta autenticada. |\n| `429` | Limite operacional excedido. |\n| `500` | Falha inesperada no backend. |"
    },
    {
      "name": "Carnês",
      "x-displayName": "Carnês",
      "x-section-id": "carnes",
      "description": "Conjunto de parcelas emitidas sob a mesma estrutura operacional.\n\n- `GET /api/v1/carnes/`\n- `POST /api/v1/carnes/`\n- `GET /api/v1/carnes/{reference_id}/`\n- `POST /api/v1/carnes/{reference_id}/cancel/`\n- `POST /api/v1/carnes/{reference_id}/send-email/`\n\n### Operações disponíveis\n\n| Método | Rota | Uso |\n| --- | --- | --- |\n| `GET` | `/api/v1/carnes/` | Lista os carnês vinculados à conta autenticada. |\n| `POST` | `/api/v1/carnes/` | Cria um carnê com múltiplas parcelas para o cliente informado. |\n| `GET` | `/api/v1/carnes/{reference_id}/` | Retorna a visualização completa do carnê, com resumo consolidado e todas as parcelas em `invoices`. |\n| `POST` | `/api/v1/carnes/{reference_id}/cancel/` | Cancela o carnê quando a regra operacional permitir. |\n| `POST` | `/api/v1/carnes/{reference_id}/send-email/` | Envia o carnê para o e-mail cadastrado do cliente. |\n\n### Campos principais de criação\n\n| Campo | Tipo | Obrigatório | Formato / regra |\n| --- | --- | --- | --- |\n| `customer_reference_id` | string | Sim* | Cliente da mesma conta |\n| `customer_id` | integer | Sim* | Alternativa a `customer_reference_id` |\n| `description` | string | Condicional | Descrição geral do carnê. Se `items` for enviado, pode ser derivada automaticamente. |\n| `items` | array | Não | Opcional. Quando enviado, o carnê aceita apenas **1** produto/serviço em `items`. |\n| `total_amount` | number|string | Condicional | Obrigatório quando `items` não for enviado. Se `items` for enviado, deve bater com a soma ou pode ser omitido. |\n| `installments` | integer | Sim | Quantidade de parcelas entre `2` e `60`. |\n| `due_date` | string | Sim | Primeiro vencimento no formato `YYYY-MM-DD`. Não pode ser retroativo. |\n| `payment_methods` | array[string] | Sim | `[\"boleto\"]`, `[\"pix\"]` ou ambos. |\n| `schedule` | array | Não | Grade opcional com uma entrada por parcela. Quando enviado, precisa ter a mesma quantidade de `installments`. |\n| `fees` | number|string | Não | Juros em valor monetário aplicados às parcelas. |\n| `fines` | number|string | Não | Multa em valor monetário aplicada às parcelas. |\n| `discount_type` | string | Não | `PERCENTAGE` ou `FIXED_VALUE`. |\n| `discount` | number|string | Não | Desconto aplicado conforme o tipo informado. |\n\n### Estrutura dos itens do carnê\n\n| Campo | Tipo | Obrigatório | Formato / regra |\n| --- | --- | --- | --- |\n| `description` | string | Sim | Descrição do produto ou serviço. |\n| `qty` ou `quantity` | number|string | Sim | Quantidade positiva. |\n| `price` | number|string | Sim | Valor unitário em reais. |\n\n> Quando você envia `items` no carnê, a Mepagg aceita apenas um item, calcula o `total_amount` a partir dele e distribui esse valor entre as parcelas. Cada parcela continua sendo retornada em `invoices` com seu próprio item e total.\n\n### Valor mínimo de criação\n\n> O valor total mínimo para criar um carnê é  R$ 5,00 , seja informando `total_amount` diretamente ou enviando um item em `items`.\n\n### Regras operacionais adicionais\n\n> Para carnês com `boleto` e/ou `pix`, a API não aceita vencimento retroativo e também bloqueia criação com vencimento no mesmo dia a partir das  20h . Se você enviar `schedule`, a lista precisa ter exatamente a mesma quantidade de parcelas de `installments`.\n\n### Estrutura opcional de schedule\n\n| Campo | Tipo | Obrigatório | Formato / regra |\n| --- | --- | --- | --- |\n| `due_date` | string | Sim | Formato `YYYY-MM-DD` para a parcela correspondente. |\n| `amount` | number|string | Sim | Valor da parcela em reais. A soma de todas as parcelas deve bater com o total do carnê. |\n\n### Como o valor do carnê é distribuído\n\n| Etapa | Como funciona |\n| --- | --- |\n| Soma dos itens | Quando `items` é enviado, a API calcula o valor total do carnê a partir do único item permitido. |\n| Validação opcional de `total_amount` | Se você também enviar `total_amount`, ele deve ser igual à soma dos itens. |\n| Distribuição entre parcelas | A Mepagg reparte o valor total entre as parcelas do carnê e preserva consistência em centavos. |\n| Itens por parcela | Cada parcela em `carne.invoices` já volta com seu próprio item, valor total e meios de pagamento. |\n\n### Leitura do resumo do carnê\n\n| Campo | Uso | Exemplo |\n| --- | --- | --- |\n| `summary.status_code` | Código consolidado para regra de sistema. | `open` |\n| `summary.status_label` | Texto amigável para interface. | `Em aberto` |\n| `summary.total_installments` | Total de parcelas no conjunto. | `6` |\n| `summary.paid_installments` | Quantidade de parcelas pagas. | `2` |\n| `summary.cancelled_installments` | Quantidade de parcelas canceladas. | `1` |\n| `summary.overdue_installments` | Quantidade de parcelas vencidas. | `1` |\n| `summary.processing_installments` | Quantidade de parcelas em processamento. | `1` |\n| `summary.to_expire_installments` | Quantidade de parcelas a vencer. | `2` |\n| `summary.open_installments` | Quantidade de parcelas ainda abertas no conjunto. | `3` |\n\n### Campos principais de resposta\n\n| Campo | Tipo | Formato / regra | Exemplo |\n| --- | --- | --- | --- |\n| `id` | integer | Identificador interno | `17` |\n| `reference_id` | string | Identificador público do carnê | `CAR_01JABCXYZ` |\n| `description` | string | Descrição principal do carnê | `Parcelamento da adesão anual` |\n| `installments_count` | integer | Quantidade total de parcelas | `6` |\n| `total_amount` | string | Valor total em reais | `600.00` |\n| `first_due_date` | date | Primeiro vencimento previsto | `2026-07-10` |\n| `customer` | object | Cliente vinculado | `{...}` |\n| `summary.status_code` | string | Situação consolidada para regra | `open` |\n| `summary.status_label` | string | Situação consolidada para interface | `Em aberto` |\n| `summary.total_installments` | integer | Total de parcelas | `6` |\n| `summary.paid_installments` | integer | Parcelas pagas | `2` |\n| `summary.cancelled_installments` | integer | Parcelas canceladas | `1` |\n| `summary.overdue_installments` | integer | Parcelas vencidas | `1` |\n| `summary.processing_installments` | integer | Parcelas em processamento | `1` |\n| `summary.to_expire_installments` | integer | Parcelas a vencer | `2` |\n| `summary.open_installments` | integer | Parcelas ainda abertas | `3` |\n| `invoices` | array | Parcelas representadas como faturas | `[...]` |\n\n> Ao consultar `GET /api/v1/carnes/{reference_id}/`, a API retorna a visualização do carnê já expandida. O array `invoices` traz todas as parcelas na mesma ordem exibida na interface, com status, vencimento, itens, formas de pagamento e demais dados da fatura. Na prática, `summary` serve para leitura consolidada e `invoices` serve para montar a grade completa de parcelas.\n\n### Acesso público, parcelas e impressão\n\nO carnê detalhado também retorna um link público para a visualização completa da Mepagg com todas as parcelas. Além disso, cada parcela segue a mesma estrutura da API de faturas, inclusive com links públicos e dados de boleto e Pix quando disponíveis.\n\n| Uso | Campo principal | Observação |\n| --- | --- | --- |\n| Abrir o carnê completo da Mepagg | `carne.public_url` | Exibe todas as parcelas em um único documento público pronto para impressão. |\n| Abrir a cobrança pública de uma parcela | `carne.invoices[].public_url` | Útil para fluxo de detalhe por parcela. |\n| Abrir o boleto público de uma parcela | `carne.invoices[].public_boleto_url` | Útil para impressão direta do boleto daquela parcela. |\n| Montar layout próprio | `carne` + `carne.invoices[]` + `boleto` + `pix` | Permite criar carnê e boleto com identidade visual própria. |\n\n### Campos sugeridos para modelo próprio de carnê\n\n| Bloco | Campos sugeridos |\n| --- | --- |\n| Cabeçalho do carnê | `reference_id`, `description`, `installments_count`, `total_amount`, `first_due_date`, `customer.name` |\n| Resumo | `summary.status_label`, `summary.total_installments`, `summary.paid_installments`, `summary.open_installments` |\n| Grade de parcelas | `invoices[].reference_id`, `invoices[].carne_installment_number`, `invoices[].due_date`, `invoices[].total_amount`, `invoices[].status_label`, `invoices[].payment_methods_display` |\n| Dados bancários da parcela | `invoices[].boleto.linha_digitavel`, `invoices[].boleto.codigo_barras`, `invoices[].boleto.nosso_numero`, `invoices[].boleto.pdf_url` |\n| Dados Pix da parcela | `invoices[].pix.copia_e_cola`, `invoices[].pix.txid`, `invoices[].public_url` |\n| Intermediação obrigatória | Exibir `Mepagg LTDA - CNPJ 05.098.228/0001-80` no carnê e nos boletos emitidos pelo seu layout. |\n\n### Exemplo de resposta\n\n```json\n{\n  \"success\": true,\n  \"carne\": {\n    \"id\": 17,\n    \"reference_id\": \"CAR_01JABCXYZ\",\n    \"description\": \"Parcelamento da adesão anual\",\n    \"installments_count\": 6,\n    \"total_amount\": \"600.00\",\n    \"first_due_date\": \"2026-07-10\",\n    \"public_url\": \"https://app.mepagg.com/carne/CAR_01JABCXYZ/\",\n    \"customer\": {\n      \"id\": 814,\n      \"reference_id\": \"CUST_EXAMPLE_001\",\n      \"name\": \"Cliente Exemplo LTDA\",\n      \"email_primary\": \"financeiro@clienteexemplo.com.br\"\n    },\n    \"summary\": {\n      \"status_code\": \"open\",\n      \"status_label\": \"Em aberto\",\n      \"total_installments\": 6,\n      \"paid_installments\": 2,\n      \"cancelled_installments\": 1,\n      \"overdue_installments\": 1,\n      \"processing_installments\": 1,\n      \"to_expire_installments\": 2,\n      \"open_installments\": 3\n    },\n    \"invoices\": [\n      {\n        \"reference_id\": \"GLZOX8K19Q40NVLJ6WJ2PRYD7EV653\",\n        \"carne_installment_number\": 1,\n        \"status_code\": \"paid\",\n        \"status_label\": \"Paga\",\n        \"due_date\": \"2026-06-15\",\n        \"total_amount\": \"100.00\",\n        \"payment_methods_display\": \"Boleto, Pix\",\n        \"public_url\": \"https://app.mepagg.com/fatura/GLZOX8K19Q40NVLJ6WJ2PRYD7EV653/\",\n        \"public_boleto_url\": \"https://app.mepagg.com/fatura/conta_publica_exemplo/GLZOX8K19Q40NVLJ6WJ2PRYD7EV653/boleto/\",\n        \"boleto\": {\n          \"linha_digitavel\": \"07791000000000000000123456789012345678901234\",\n          \"codigo_barras\": \"07791234567890123456789012345678901234567890\",\n          \"nosso_numero\": \"1234567890\"\n        },\n        \"items\": [\n          {\n            \"description\": \"Parcela 1/6 - Adesão anual\",\n            \"qty\": 1,\n            \"price\": \"100.00\",\n            \"total\": \"100.00\"\n          }\n        ]\n      },\n      {\n        \"reference_id\": \"KQ38REJLG9O2W2Q86NY7VIP564ZDX0\",\n        \"carne_installment_number\": 2,\n        \"status_code\": \"paid\",\n        \"status_label\": \"Paga\",\n        \"due_date\": \"2026-07-15\",\n        \"total_amount\": \"100.00\",\n        \"payment_methods_display\": \"Boleto, Pix\",\n        \"items\": [\n          {\n            \"description\": \"Parcela 2/6 - Adesão anual\",\n            \"qty\": 1,\n            \"price\": \"100.00\",\n            \"total\": \"100.00\"\n          }\n        ]\n      },\n      {\n        \"reference_id\": \"0ZRQXP248JGDW3EG2WE6VO3L75KYI9\",\n        \"carne_installment_number\": 3,\n        \"status_code\": \"to_expire\",\n        \"status_label\": \"A vencer\",\n        \"due_date\": \"2026-08-15\",\n        \"total_amount\": \"100.00\",\n        \"payment_methods_display\": \"Boleto, Pix\",\n        \"items\": [\n          {\n            \"description\": \"Parcela 3/6 - Adesão anual\",\n            \"qty\": 1,\n            \"price\": \"100.00\",\n            \"total\": \"100.00\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n### Como ler a resposta do carnê\n\n- `summary.status_code` e `summary.status_label` representam a situação consolidada do carnê inteiro.\n- `summary.total_installments`, `paid_installments`, `cancelled_installments` e `open_installments` ajudam a montar indicadores rápidos sem recalcular no sistema da conta.\n- Cada item de `invoices` representa uma parcela individual, com sua própria referência, status, vencimento, itens e formas de pagamento.\n- Para reproduzir a tela de detalhes do carnê, use o cabeçalho do objeto `carne` mais a listagem completa de `invoices`.\n\n### Exemplo de criação\n\n```json\n{\n  \"customer_reference_id\": \"CUST_EXAMPLE_001\",\n  \"description\": \"Parcelamento da adesão anual\",\n  \"installments\": 6,\n  \"total_amount\": \"600.00\",\n  \"due_date\": \"2026-07-10\",\n  \"payment_methods\": [\"boleto\", \"pix\"]\n}\n```\n\n### Exemplo de criação com item único\n\n```json\n{\n  \"customer_reference_id\": \"CUST_EXAMPLE_001\",\n  \"description\": \"Carnê de implantação e licença\",\n  \"installments\": 3,\n  \"due_date\": \"2026-07-10\",\n  \"payment_methods\": [\"boleto\", \"pix\"],\n  \"items\": [\n    {\n      \"description\": \"Implantação inicial\",\n      \"quantity\": 1,\n      \"price\": \"120.00\"\n    }\n  ]\n}\n```\n\nTotal do carnê: `120.00`. Com `installments=3`, a API distribui o valor total nas três parcelas e cada uma aparece em `carne.invoices`.\n\n### Exemplo de cancelamento do carnê\n\n```json\n{\n  \"cancelled_reason\": \"Solicitado pelo cliente.\"\n}\n```\n\n### Como ler o carnê na prática\n\n- `summary` é a leitura consolidada do conjunto inteiro.\n- `invoices` é a grade completa de parcelas, já pronta para a tela de detalhes do carnê.\n- `summary.paid_installments`, `summary.cancelled_installments`, `summary.overdue_installments` e `summary.open_installments` evitam recálculo no sistema da conta.\n- `carne.public_url` permite abrir o modelo público do carnê com todas as parcelas.\n- Cada parcela herda o mesmo contrato de leitura da API de faturas, inclusive `public_url`, `public_boleto_url`, `boleto`, `pix` e `items`.\n\n### Respostas HTTP\n\n| Status | Quando esperar |\n| --- | --- |\n| `200` | Listagem, consulta ou criação processada com sucesso. |\n| `400` | Payload inválido, parcelas inconsistentes ou regra operacional não atendida. |\n| `401` | Chave ausente ou inválida. |\n| `429` | Limite operacional excedido. |\n| `500` | Falha inesperada no backend. |"
    },
    {
      "name": "Links de pagamentos",
      "x-displayName": "Links de pagamentos",
      "description": "- `GET /api/v1/payment-links/`\n- `POST /api/v1/payment-links/`\n- `GET /api/v1/payment-links/{public_token}/`\n\n### Operações disponíveis\n\n| Método | Rota | Uso |\n| --- | --- | --- |\n| `GET` | `/api/v1/payment-links/` | Lista os links de pagamento da conta autenticada. |\n| `POST` | `/api/v1/payment-links/` | Cria um novo link público de cobrança. |\n| `GET` | `/api/v1/payment-links/{public_token}/` | Consulta o estado atual de um link específico. |\n\n### Regras importantes\n\n- Um link pode nascer com valor fixo ou sem valor definido. Quando não houver valor fixo, o pagador informa o valor na tela pública.\n- `due_option` define a validade operacional do link usando a hora real de criação como base.\n- Quando `due_option=none`, o link não expira e a API exige `invoice_due_option` para definir em quantos dias vence cada fatura gerada por esse checkout.\n- Para links com prazo (`today`, `1_day`, `5_days`, `10_days`, `15_days`, `30_days` ou `custom`), a fatura gerada herda a mesma janela de vencimento do link.\n- `usage_limit_mode` controla quantas cobranças esse link pode gerar antes de ficar indisponível.\n- O status do link deve ser lido por `status_code` para regras de sistema e por `status_label` para interface.\n- O campo `issued_via` do link representa a origem da criação do próprio link.\n- `issued_via`, `issued_via_code` e `issued_via_label` são campos somente de resposta, definidos internamente pela Mepagg conforme o canal real da emissão. Não envie esses campos no payload.\n- Quando o link for criado pela API pública, qualquer fatura gerada depois na tela pública desse link será retornada com `type_code=payment_link`, `type_label=Link de pagamento` e `issued_via_code=api`.\n- O evento de webhook `payment_link.status_changed` notifica mudanças de status do link, inclusive expiração por vencimento, desativação manual e limite de usos atingido.\n- Para conciliar cobrança efetivamente gerada pelo checkout do link, continue acompanhando também os webhooks de fatura (`invoice.created`, `invoice.paid`, `invoice.cancelled`, `invoice.expired`, `invoice.refunded`) e leia `invoice.type_code=payment_link` junto com `invoice.issued_via_code`.\n\n### Webhook do link de pagamento\n\n| Evento | Quando dispara | Campos principais |\n| --- | --- | --- |\n| `payment_link.status_changed` | Quando o status calculado do link muda de `active` para `expired`, `limit_reached` ou volta a `active` após edição elegível. | `payment_link_public_token`, `previous_status_code`, `status_code`, `status_reason_code`, `payment_link` |\n\n### Motivos estáveis do webhook\n\n| `status_reason_code` | `status_reason_label` | Quando aparece |\n| --- | --- | --- |\n| `active` | `Ativo` | Link permanece apto a gerar novas cobranças. |\n| `manual_deactivated` | `Desativado manualmente` | Link foi encerrado manualmente no painel ou API. |\n| `due_date_expired` | `Expirado por vencimento` | Prazo operacional do link terminou. |\n| `usage_limit_reached` | `Limite de usos atingido` | Quantidade máxima de cobranças permitidas já foi consumida. |\n\n### Campos principais de criação\n\n| Campo | Tipo | Obrigatório | Regra |\n| --- | --- | --- | --- |\n| `description` | string | Sim | Produto ou serviço exibido na tela pública e copiado para a fatura gerada. |\n| `link_type` | string | Sim | `free` para link sem valor definido ou `fixed` para valor fixo. |\n| `amount` | number\\|string | Condicional | Obrigatório quando `link_type=fixed`. Valor mínimo `5.00`. |\n| `due_option` | string | Sim | `today`, `1_day`, `5_days`, `10_days`, `15_days`, `30_days`, `custom` ou `none`. |\n| `custom_due_days` | integer | Condicional | Obrigatório quando `due_option=custom`. Faixa de `1` a `29`. |\n| `invoice_due_option` | string | Condicional | Obrigatório quando `due_option=none`. Aceita `today`, `1_day`, `5_days`, `10_days`, `15_days`, `20_days`, `30_days` ou `custom`. |\n| `invoice_custom_due_days` | integer | Condicional | Obrigatório quando `due_option=none` e `invoice_due_option=custom`; entre `1` e `29`. |\n| `usage_limit_mode` | string | Sim | `unlimited` ou `limited`. |\n| `usage_limit` | integer | Condicional | Obrigatório quando `usage_limit_mode=limited`. Deve ser maior que `0`. |\n| `payment_methods` | array[string] | Sim* | Lista de slugs das formas de pagamento habilitadas para o link. |\n| `payment_method_ids` | array[integer] | Sim* | Alternativa a `payment_methods`, usando IDs internos. |\n| `base_date` | string | Não | Data base opcional no formato `YYYY-MM-DD` para cálculo do vencimento. |\n\n`payment_methods` ou `payment_method_ids` são obrigatórios. Quando ambos forem enviados, o backend prioriza a lista de slugs.\n\n### Status retornados\n\n| `status_code` | `status_label` | Quando aparece |\n| --- | --- | --- |\n| `active` | `Ativo` | Link disponível para novas cobranças. |\n| `expired` | `Expirado` | Prazo do link já passou. |\n| `limit_reached` | `Limite atingido` | Quantidade máxima de usos já consumida. |\n\n### Exemplo de criação\n\n```json\n{\n  \"description\": \"Link sem vencimento para adesão\",\n  \"link_type\": \"fixed\",\n  \"amount\": \"249.90\",\n  \"due_option\": \"none\",\n  \"invoice_due_option\": \"20_days\",\n  \"usage_limit_mode\": \"limited\",\n  \"usage_limit\": 3,\n  \"payment_methods\": [\"pix\"]\n}\n```\n\n### Exemplo de resposta\n\n```json\n{\n  \"success\": true,\n  \"message\": \"Link de pagamento criado com sucesso.\",\n  \"payment_link\": {\n    \"public_token\": \"4dd78029-fb39-4c52-b0e6-2bc748d2832b\",\n    \"status_code\": \"active\",\n    \"status_label\": \"Ativo\",\n    \"validity_display\": \"Sem vencimento\",\n    \"invoice_due_option\": \"20_days\",\n    \"invoice_due_option_label\": \"20 dias\",\n    \"invoice_due_summary\": \"20 dias após a criação\",\n    \"issued_via\": \"API\",\n    \"issued_via_code\": \"api\",\n    \"issued_via_label\": \"API\",\n    \"public_url\": \"https://app.mepagg.com/link/4dd78029-fb39-4c52-b0e6-2bc748d2832b/\"\n  }\n}\n```"
    },
    {
      "name": "Transferências",
      "x-displayName": "Transferências",
      "x-section-id": "transferencias",
      "description": "Consultas públicas sobre transferências já registradas na conta autenticada.\n\n- `GET /api/v1/transfers/`\n- `GET /api/v1/transfers/pricing/`\n- `GET /api/v1/transfers/pix-keys/`\n- `GET /api/v1/transfers/{reference_id}/`\n- `GET /api/v1/transfers/{reference_id}/receipt/`\n\n> A criação de transferências e as ações operacionais sensíveis ficam disponíveis somente no painel autenticado da Mepagg.\n\n### Operações disponíveis\n\n| Método | Rota | Uso |\n| --- | --- | --- |\n| `GET` | `/api/v1/transfers/` | Lista transferências já registradas na conta autenticada. |\n| `GET` | `/api/v1/transfers/pricing/` | Consulta a tarifação configurada para transferências da conta. |\n| `GET` | `/api/v1/transfers/pix-keys/` | Lista as chaves PIX aprovadas disponíveis para a conta. |\n| `GET` | `/api/v1/transfers/{reference_id}/` | Consulta uma transferência específica pelo `reference_id`. |\n| `GET` | `/api/v1/transfers/{reference_id}/receipt/` | Consulta o recibo de uma transferência aprovada. |\n\n### Filtros da listagem\n\n| Parâmetro | Tipo | Obrigatório | Uso |\n| --- | --- | --- | --- |\n| `limit` | integer | Não | Paginação. Padrão `20`. |\n| `offset` | integer | Não | Paginação. Padrão `0`. |\n\n### Header importante\n\n| Header | Obrigatório | Uso |\n| --- | --- | --- |\n| `X-API-KEY` | Sim | Autentica a conta para consultas de transferências. |\n\n### Campos principais de resposta\n\n| Campo | Tipo | Uso | Exemplo |\n| --- | --- | --- | --- |\n| `reference_id` | string | Identificador público da transferência. | `TRF_XYZ987` |\n| `status_code` | string | Código estável do status. | `completed` |\n| `status_label` | string | Texto amigável para interface. | `Concluída` |\n| `amount` | string | Valor solicitado em reais. | `100.00` |\n| `created_at` | datetime | Data e hora da solicitação. | `2026-06-17T14:25:00-03:00` |\n\n### Respostas HTTP\n\n| Status | Quando esperar |\n| --- | --- |\n| `200` | Listagem ou consulta processada com sucesso. |\n| `400` | Parâmetros inválidos ou consulta incompatível com o estado do recurso. |\n| `401` | Chave ausente ou inválida para consulta. |\n| `429` | Limite operacional excedido. |\n| `500` | Falha inesperada no backend. |"
    },
    {
      "name": "Extrato",
      "x-displayName": "Extrato, saldo e dashboard",
      "x-section-id": "extrato-dashboard",
      "description": "Esta área é a principal fonte para conciliação financeira da conta. Sempre que o sistema da conta depender de confirmação econômica real, consulte extrato, resumo e status do recurso relacionado.\n\n- `GET /api/v1/statement/`\n- `GET /api/v1/statement/summary/`\n- `GET /api/v1/dashboard/overview/`\n- `GET /api/v1/dashboard/widgets/`\n- `GET /api/v1/dashboard/balances/`\n- `GET /api/v1/dashboard/income-preview/`\n- `GET /api/v1/dashboard/invoice-progress/`\n- `GET /api/v1/dashboard/latest-invoices/`\n- `GET /api/v1/dashboard/payment-method-chart/`\n- `GET /api/v1/dashboard/invoice-type-chart/`\n- `GET /api/v1/dashboard/received-calendar/`\n- `GET /api/v1/dashboard/monthly-received-chart/`\n- `GET /api/v1/dashboard/customers/`\n\n### Operações disponíveis\n\n| Método | Rota | Uso |\n| --- | --- | --- |\n| `GET` | `/api/v1/statement/` | Fonte principal para conciliação financeira da conta. |\n| `GET` | `/api/v1/statement/summary/` | Resumo consolidado do período para apoio à conciliação. |\n| `GET` | `/api/v1/dashboard/overview/` | Visão consolidada do dashboard para o mês informado. |\n| `GET` | `/api/v1/dashboard/widgets/` | Coleção de widgets operacionais do dashboard. |\n| `GET` | `/api/v1/dashboard/balances/` | Saldos exibidos no dashboard da conta. |\n| `GET` | `/api/v1/dashboard/income-preview/` | Previsão de recebimentos exibida no dashboard. |\n| `GET` | `/api/v1/dashboard/invoice-progress/` | Resumo de progresso das faturas. |\n| `GET` | `/api/v1/dashboard/latest-invoices/` | Lista de últimas faturas exibidas no dashboard. |\n| `GET` | `/api/v1/dashboard/payment-method-chart/` | Gráfico agregado por forma de pagamento. |\n| `GET` | `/api/v1/dashboard/invoice-type-chart/` | Gráfico agregado por tipo de fatura. |\n| `GET` | `/api/v1/dashboard/received-calendar/` | Calendário de recebimentos do dashboard. |\n| `GET` | `/api/v1/dashboard/monthly-received-chart/` | Série mensal de recebimentos exibida no dashboard. |\n| `GET` | `/api/v1/dashboard/customers/` | Indicadores de clientes usados no dashboard. |\n\n### Filtros do extrato\n\n| Parâmetro | Tipo | Obrigatório | Uso |\n| --- | --- | --- | --- |\n| `q` | string | Não | Busca textual em descrição, referência ou dados relacionados. |\n| `start_date` | date | Não | Data inicial no formato `YYYY-MM-DD`. |\n| `end_date` | date | Não | Data final no formato `YYYY-MM-DD`. |\n| `source` | string | Não | Origem do lançamento, como pagamento, tarifa ou transferência. |\n| `limit` | integer | Não | Paginação. Padrão `20`. |\n| `offset` | integer | Não | Paginação. Padrão `0`. |\n\n### Filtros do resumo financeiro\n\n| Parâmetro | Tipo | Obrigatório | Uso |\n| --- | --- | --- | --- |\n| `start_date` | date | Não | Data inicial do consolidado. |\n| `end_date` | date | Não | Data final do consolidado. |\n\n\n### Extrato\n\n`GET /api/v1/statement/` lista lançamentos com filtros como `q`, `start_date`, `end_date`, `source`, `limit` e `offset`.\n\n\n\n### Resumo\n\n`GET /api/v1/statement/summary/` retorna visão consolidada do período com recebimentos, débitos, tarifas e saldo disponível.\n\n### Campos úteis do extrato\n\n| Campo | Tipo | Uso | Exemplo |\n| --- | --- | --- | --- |\n| `reference_id` | string | Identificador público do lançamento. | `STM_01JABCXYZ` |\n| `entry_type` | string | Tipo do lançamento, como crédito, débito ou tarifa. | `credit` |\n| `source` | string | Origem operacional do lançamento. | `invoice_payment` |\n| `description` | string | Descrição legível do movimento. | `Pagamento da fatura GLZOX8...` |\n| `gross_amount` | string | Valor bruto movimentado. | `5200.00` |\n| `fee_amount` | string | Tarifa associada ao movimento quando houver. | `3.90` |\n| `net_amount` | string | Impacto líquido financeiro do lançamento. | `5196.10` |\n| `occurred_at` | datetime | Momento econômico do lançamento. | `2026-06-15T10:18:00-03:00` |\n| `balance_after` | string | Saldo resultante após o lançamento. | `3811.50` |\n| `related_reference_id` | string | Recurso relacionado, quando existir. | `GLZOX8K19Q40NVLJ6WJ2PRYD7EV653` |\n\n### Exemplo de resposta do extrato\n\n```json\n{\n  \"count\": 2,\n  \"results\": [\n    {\n      \"reference_id\": \"STM_01JABCXYZ\",\n      \"entry_type\": \"credit\",\n      \"source\": \"invoice_payment\",\n      \"description\": \"Pagamento da fatura GLZOX8K19Q40NVLJ6WJ2PRYD7EV653\",\n      \"gross_amount\": \"5200.00\",\n      \"fee_amount\": \"3.90\",\n      \"net_amount\": \"5196.10\",\n      \"occurred_at\": \"2026-06-15T10:18:00-03:00\",\n      \"balance_after\": \"3811.50\",\n      \"related_reference_id\": \"GLZOX8K19Q40NVLJ6WJ2PRYD7EV653\"\n    },\n    {\n      \"reference_id\": \"STM_01JABCXYA\",\n      \"entry_type\": \"debit\",\n      \"source\": \"pix_transfer\",\n      \"description\": \"Transferência PIX TRF_XYZ987\",\n      \"gross_amount\": \"100.00\",\n      \"fee_amount\": \"0.00\",\n      \"net_amount\": \"100.00\",\n      \"occurred_at\": \"2026-06-17T14:25:00-03:00\",\n      \"balance_after\": \"3711.50\",\n      \"related_reference_id\": \"TRF_XYZ987\"\n    }\n  ]\n}\n```\n\n### Exemplo de resposta do resumo financeiro\n\n```json\n{\n  \"success\": true,\n  \"summary\": {\n    \"start_date\": \"2026-06-01\",\n    \"end_date\": \"2026-06-30\",\n    \"gross_received\": \"6220.00\",\n    \"fees_total\": \"9.40\",\n    \"net_received\": \"6210.60\",\n    \"total_debits\": \"2399.10\",\n    \"available_balance\": \"3811.50\"\n  }\n}\n```\n\n### Exemplo de resposta do dashboard overview\n\n```json\n{\n  \"success\": true,\n  \"overview\": {\n    \"overview_month\": \"2026-06\",\n    \"received_total\": \"6220.00\",\n    \"fees_total\": \"9.40\",\n    \"net_total\": \"6210.60\",\n    \"open_invoices\": 14,\n    \"overdue_invoices\": 3,\n    \"paid_invoices\": 82,\n    \"customers_total\": 91\n  }\n}\n```\n\n### Respostas HTTP\n\n| Status | Quando esperar |\n| --- | --- |\n| `200` | Consultas de extrato, resumo e widgets processadas com sucesso. |\n| `400` | Período inválido, paginação incorreta ou filtro incompatível. |\n| `401` | Chave ausente ou inválida. |\n| `429` | Limite operacional excedido. |\n| `500` | Falha inesperada no backend. |"
    },
    {
      "name": "Dashboard",
      "x-displayName": "Dashboard",
      "x-section-id": "extrato-dashboard",
      "description": "Esta área é a principal fonte para conciliação financeira da conta. Sempre que o sistema da conta depender de confirmação econômica real, consulte extrato, resumo e status do recurso relacionado.\n\n- `GET /api/v1/statement/`\n- `GET /api/v1/statement/summary/`\n- `GET /api/v1/dashboard/overview/`\n- `GET /api/v1/dashboard/widgets/`\n- `GET /api/v1/dashboard/balances/`\n- `GET /api/v1/dashboard/income-preview/`\n- `GET /api/v1/dashboard/invoice-progress/`\n- `GET /api/v1/dashboard/latest-invoices/`\n- `GET /api/v1/dashboard/payment-method-chart/`\n- `GET /api/v1/dashboard/invoice-type-chart/`\n- `GET /api/v1/dashboard/received-calendar/`\n- `GET /api/v1/dashboard/monthly-received-chart/`\n- `GET /api/v1/dashboard/customers/`\n\n### Operações disponíveis\n\n| Método | Rota | Uso |\n| --- | --- | --- |\n| `GET` | `/api/v1/statement/` | Fonte principal para conciliação financeira da conta. |\n| `GET` | `/api/v1/statement/summary/` | Resumo consolidado do período para apoio à conciliação. |\n| `GET` | `/api/v1/dashboard/overview/` | Visão consolidada do dashboard para o mês informado. |\n| `GET` | `/api/v1/dashboard/widgets/` | Coleção de widgets operacionais do dashboard. |\n| `GET` | `/api/v1/dashboard/balances/` | Saldos exibidos no dashboard da conta. |\n| `GET` | `/api/v1/dashboard/income-preview/` | Previsão de recebimentos exibida no dashboard. |\n| `GET` | `/api/v1/dashboard/invoice-progress/` | Resumo de progresso das faturas. |\n| `GET` | `/api/v1/dashboard/latest-invoices/` | Lista de últimas faturas exibidas no dashboard. |\n| `GET` | `/api/v1/dashboard/payment-method-chart/` | Gráfico agregado por forma de pagamento. |\n| `GET` | `/api/v1/dashboard/invoice-type-chart/` | Gráfico agregado por tipo de fatura. |\n| `GET` | `/api/v1/dashboard/received-calendar/` | Calendário de recebimentos do dashboard. |\n| `GET` | `/api/v1/dashboard/monthly-received-chart/` | Série mensal de recebimentos exibida no dashboard. |\n| `GET` | `/api/v1/dashboard/customers/` | Indicadores de clientes usados no dashboard. |\n\n### Filtros do extrato\n\n| Parâmetro | Tipo | Obrigatório | Uso |\n| --- | --- | --- | --- |\n| `q` | string | Não | Busca textual em descrição, referência ou dados relacionados. |\n| `start_date` | date | Não | Data inicial no formato `YYYY-MM-DD`. |\n| `end_date` | date | Não | Data final no formato `YYYY-MM-DD`. |\n| `source` | string | Não | Origem do lançamento, como pagamento, tarifa ou transferência. |\n| `limit` | integer | Não | Paginação. Padrão `20`. |\n| `offset` | integer | Não | Paginação. Padrão `0`. |\n\n### Filtros do resumo financeiro\n\n| Parâmetro | Tipo | Obrigatório | Uso |\n| --- | --- | --- | --- |\n| `start_date` | date | Não | Data inicial do consolidado. |\n| `end_date` | date | Não | Data final do consolidado. |\n\n\n### Extrato\n\n`GET /api/v1/statement/` lista lançamentos com filtros como `q`, `start_date`, `end_date`, `source`, `limit` e `offset`.\n\n\n\n### Resumo\n\n`GET /api/v1/statement/summary/` retorna visão consolidada do período com recebimentos, débitos, tarifas e saldo disponível.\n\n### Campos úteis do extrato\n\n| Campo | Tipo | Uso | Exemplo |\n| --- | --- | --- | --- |\n| `reference_id` | string | Identificador público do lançamento. | `STM_01JABCXYZ` |\n| `entry_type` | string | Tipo do lançamento, como crédito, débito ou tarifa. | `credit` |\n| `source` | string | Origem operacional do lançamento. | `invoice_payment` |\n| `description` | string | Descrição legível do movimento. | `Pagamento da fatura GLZOX8...` |\n| `gross_amount` | string | Valor bruto movimentado. | `5200.00` |\n| `fee_amount` | string | Tarifa associada ao movimento quando houver. | `3.90` |\n| `net_amount` | string | Impacto líquido financeiro do lançamento. | `5196.10` |\n| `occurred_at` | datetime | Momento econômico do lançamento. | `2026-06-15T10:18:00-03:00` |\n| `balance_after` | string | Saldo resultante após o lançamento. | `3811.50` |\n| `related_reference_id` | string | Recurso relacionado, quando existir. | `GLZOX8K19Q40NVLJ6WJ2PRYD7EV653` |\n\n### Exemplo de resposta do extrato\n\n```json\n{\n  \"count\": 2,\n  \"results\": [\n    {\n      \"reference_id\": \"STM_01JABCXYZ\",\n      \"entry_type\": \"credit\",\n      \"source\": \"invoice_payment\",\n      \"description\": \"Pagamento da fatura GLZOX8K19Q40NVLJ6WJ2PRYD7EV653\",\n      \"gross_amount\": \"5200.00\",\n      \"fee_amount\": \"3.90\",\n      \"net_amount\": \"5196.10\",\n      \"occurred_at\": \"2026-06-15T10:18:00-03:00\",\n      \"balance_after\": \"3811.50\",\n      \"related_reference_id\": \"GLZOX8K19Q40NVLJ6WJ2PRYD7EV653\"\n    },\n    {\n      \"reference_id\": \"STM_01JABCXYA\",\n      \"entry_type\": \"debit\",\n      \"source\": \"pix_transfer\",\n      \"description\": \"Transferência PIX TRF_XYZ987\",\n      \"gross_amount\": \"100.00\",\n      \"fee_amount\": \"0.00\",\n      \"net_amount\": \"100.00\",\n      \"occurred_at\": \"2026-06-17T14:25:00-03:00\",\n      \"balance_after\": \"3711.50\",\n      \"related_reference_id\": \"TRF_XYZ987\"\n    }\n  ]\n}\n```\n\n### Exemplo de resposta do resumo financeiro\n\n```json\n{\n  \"success\": true,\n  \"summary\": {\n    \"start_date\": \"2026-06-01\",\n    \"end_date\": \"2026-06-30\",\n    \"gross_received\": \"6220.00\",\n    \"fees_total\": \"9.40\",\n    \"net_received\": \"6210.60\",\n    \"total_debits\": \"2399.10\",\n    \"available_balance\": \"3811.50\"\n  }\n}\n```\n\n### Exemplo de resposta do dashboard overview\n\n```json\n{\n  \"success\": true,\n  \"overview\": {\n    \"overview_month\": \"2026-06\",\n    \"received_total\": \"6220.00\",\n    \"fees_total\": \"9.40\",\n    \"net_total\": \"6210.60\",\n    \"open_invoices\": 14,\n    \"overdue_invoices\": 3,\n    \"paid_invoices\": 82,\n    \"customers_total\": 91\n  }\n}\n```\n\n### Respostas HTTP\n\n| Status | Quando esperar |\n| --- | --- |\n| `200` | Consultas de extrato, resumo e widgets processadas com sucesso. |\n| `400` | Período inválido, paginação incorreta ou filtro incompatível. |\n| `401` | Chave ausente ou inválida. |\n| `429` | Limite operacional excedido. |\n| `500` | Falha inesperada no backend. |"
    },
    {
      "name": "SMS",
      "x-displayName": "SMS",
      "x-section-id": "sms",
      "description": "- `POST /api/v1/sms/send/`\n- `POST /api/v1/sms/buy-credits/`\n- `GET /api/v1/sms/usages/`\n\n### Operações disponíveis\n\n| Método | Rota | Uso |\n| --- | --- | --- |\n| `POST` | `/api/v1/sms/send/` | Envia um SMS manual. O campo `content` aceita no máximo 160 caracteres. |\n| `POST` | `/api/v1/sms/buy-credits/` | Adquire créditos de SMS conforme os pacotes disponíveis na conta. |\n| `GET` | `/api/v1/sms/usages/` | Lista mensagens já enviadas com filtros de nome, telefone e período. |\n\n### Headers importantes\n\n| Header | Obrigatório | Uso |\n| --- | --- | --- |\n| `X-API-KEY` | Sim | Autentica a conta. |\n| `Idempotency-Key` | Recomendado no `POST /api/v1/sms/send/` | Previne reenvio duplicado em retries do sistema da conta. |\n\n| Campo | Tipo | Obrigatório | Formato / regra |\n| --- | --- | --- | --- |\n| `phone` | string | Sim | Celular com DDD |\n| `content` | string | Sim | Limite máximo de 160 caracteres |\n\n### Campos da compra de créditos\n\n| Campo | Tipo | Obrigatório | Formato / regra |\n| --- | --- | --- | --- |\n| `sms_credit_package` | string | Sim | Código do pacote disponível para a conta. Exemplo: `500` ou `1000`. |\n| `sms_purchase_method` | string | Sim | No momento, enviar `mepagg_balance`. |\n\n### Exemplo de envio manual\n\n```json\n{\n  \"phone\": \"11987654321\",\n  \"content\": \"Sua cobranca Mepagg vence em 30/06/2026. Acesse o link enviado por e-mail para pagar por boleto ou Pix.\"\n}\n```\n\n### Exemplo de compra de créditos\n\n```json\n{\n  \"sms_credit_package\": \"500\",\n  \"sms_purchase_method\": \"mepagg_balance\"\n}\n```\n\n### Compra de créditos em cURL\n\n```bash\ncurl --request POST \\\n  --url 'https://app.mepagg.com/api/v1/sms/buy-credits/' \\\n  --header 'Content-Type: application/json' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API' \\\n  --data '{\n    \"sms_credit_package\": \"500\",\n    \"sms_purchase_method\": \"mepagg_balance\"\n  }'\n```\n\n### Compra de créditos em JavaScript / Node.js\n\n```js\nimport axios from 'axios';\n\n// Compra um pacote de 500 créditos usando o saldo da conta Mepagg.\nconst response = await axios.post(\n  'https://app.mepagg.com/api/v1/sms/buy-credits/',\n  {\n    sms_credit_package: '500',\n    sms_purchase_method: 'mepagg_balance',\n  },\n  {\n    headers: {\n      'Content-Type': 'application/json',\n      'X-API-KEY': 'SUA_CHAVE_DE_API',\n    },\n    timeout: 30000,\n  }\n);\n\nconsole.log(response.status);\nconsole.log(response.data);\n```\n\n### Compra de créditos em Python\n\n```python\nimport requests\n\n# Compra um pacote de 500 créditos usando o saldo da conta Mepagg.\nresponse = requests.post(\n    'https://app.mepagg.com/api/v1/sms/buy-credits/',\n    headers={\n        'Content-Type': 'application/json',\n        'X-API-KEY': 'SUA_CHAVE_DE_API',\n    },\n    json={\n        'sms_credit_package': '500',\n        'sms_purchase_method': 'mepagg_balance',\n    },\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())\n```\n\n### Compra de créditos em PHP\n\n```php\n  true,\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_HTTPHEADER => [\n        'Content-Type: application/json',\n        'X-API-KEY: SUA_CHAVE_DE_API',\n    ],\n    CURLOPT_POSTFIELDS => json_encode([\n        'sms_credit_package' => '500',\n        'sms_purchase_method' => 'mepagg_balance',\n    ]),\n    CURLOPT_TIMEOUT => 30,\n]);\n\n$body = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $body . PHP_EOL;\n```\n\n### Exemplo de resposta da compra de créditos\n\n```json\n{\n  \"success\": true,\n  \"message\": \"Pacote de SMS comprado com sucesso.\",\n  \"sms_credits\": 1500\n}\n```\n\n### Exemplo de erro de validação\n\n```json\n{\n  \"success\": false,\n  \"message\": \"Pacote de SMS inválido.\"\n}\n```\n\n### Exemplo de erro de autenticação\n\n```json\n{\n  \"success\": false,\n  \"message\": \"Chave de API inválida ou ausente.\"\n}\n```\n\nQuando a compra é concluída, a Mepagg também pode notificar o sistema da conta pelo webhook `sms.credits_purchased` com pacote adquirido, valor, método de compra e saldo final de créditos.\n\n### Exemplo de histórico de uso\n\n```json\n{\n  \"count\": 1,\n  \"results\": [\n    {\n      \"id\": 88,\n      \"phone\": \"11987654321\",\n      \"content\": \"Sua cobranca Mepagg vence em 30/06/2026...\",\n      \"status_code\": \"sent\",\n      \"status_label\": \"Enviado\",\n      \"created_at\": \"2026-06-17T13:45:00-03:00\",\n      \"related_reference_id\": \"GLZOX8K19Q40NVLJ6WJ2PRYD7EV653\"\n    }\n  ]\n}\n```\n\n### Respostas HTTP\n\n| Status | Quando esperar |\n| --- | --- |\n| `200` | Envio, compra de créditos ou consulta de histórico processados com sucesso. |\n| `400` | Telefone inválido, mensagem vazia ou conteúdo acima do limite operacional. |\n| `401` | Chave ausente ou inválida. |\n| `403` | Créditos insuficientes ou recurso bloqueado para a conta. |\n| `409` | Conflito de idempotência no envio manual. |\n| `429` | Limite operacional excedido. |\n| `500` | Falha inesperada no backend. |"
    },
    {
      "name": "E-mails",
      "x-displayName": "E-mails",
      "x-section-id": "emails-enviados",
      "description": "Rota pública: `GET /api/v1/emails/dispatches/`\n\nUse esta consulta para auditoria operacional, rastreio de comunicações e apoio em atendimento.\n\n> Este endpoint retorna fragments HTML renderizados pelo painel dentro de um envelope JSON, e não uma coleção puramente estruturada como os recursos transacionais principais.\n\n### Campos operacionais normalmente úteis\n\n| Campo | Uso | Exemplo |\n| --- | --- | --- |\n| `to` | Destinatário principal do envio. | `financeiro@clienteexemplo.com.br` |\n| `subject` | Assunto da mensagem enviada. | `Cobrança disponível para pagamento` |\n| `status` | Status operacional do disparo. | `sent` |\n| `created_at` | Momento do envio. | `2026-06-17T13:40:00-03:00` |"
    },
    {
      "name": "Conta",
      "x-displayName": "Conta",
      "x-section-id": "dados-da-conta",
      "description": "Rota pública: `GET /api/v1/settings/account/`\n\nA API pública é transacional e pode consultar os dados cadastrais da conta autenticada, mas não expõe gestão administrativa completa da conta por este canal.\n\n### Campos principais de resposta\n\n| Campo | Tipo | Uso | Exemplo |\n| --- | --- | --- | --- |\n| `name` | string | Nome ou razão social da conta. | `Empresa Exemplo de Cobrancas LTDA` |\n| `document` | string | Documento principal da conta. | `12345678000199` |\n| `email` | string | E-mail principal da conta. | `financeiro@empresaexemplo.com.br` |\n| `phone_number` | string | Telefone principal da conta. | `1133334444` |\n| `address` | object | Estrutura com logradouro, bairro, cidade, UF e CEP. | `{...}` |\n| `municipal_registration` | string | Inscrição municipal, quando houver. | `15428` |\n| `municipality_name` | string | Município cadastrado da conta. | `Belo Horizonte` |\n| `municipality_state` | string | UF do município cadastrado. | `MG` |\n\n### Exemplo de resposta\n\n```json\n{\n  \"success\": true,\n  \"account\": {\n    \"name\": \"Empresa Exemplo de Cobrancas LTDA\",\n    \"document\": \"12345678000199\",\n    \"email\": \"financeiro@empresaexemplo.com.br\",\n    \"phone_number\": \"1133334444\",\n    \"municipal_registration\": \"15428\",\n    \"municipality_name\": \"Belo Horizonte\",\n    \"municipality_state\": \"MG\",\n    \"address\": {\n      \"street\": \"Avenida Modelo\",\n      \"number\": \"1000\",\n      \"neighborhood\": \"Savassi\",\n      \"city\": \"Belo Horizonte\",\n      \"state\": \"MG\",\n      \"zipcode\": \"30140071\"\n    }\n  }\n}\n```"
    },
    {
      "name": "Webhooks",
      "x-displayName": "Webhooks",
      "x-section-id": "webhooks",
      "description": "- `GET /api/v1/settings/webhooks/`\n- `POST /api/v1/settings/webhooks/`\n- `PATCH /api/v1/settings/webhooks/{endpoint_id}/`\n- `DELETE /api/v1/settings/webhooks/{endpoint_id}/`\n- `POST /api/v1/settings/webhooks/{endpoint_id}/rotate-secret/`\n- `GET /api/v1/settings/webhooks/deliveries/`\n\n### Operações disponíveis\n\n| Método | Rota | Uso |\n| --- | --- | --- |\n| `GET` | `/api/v1/settings/webhooks/` | Lista os endpoints de webhook cadastrados na conta. |\n| `POST` | `/api/v1/settings/webhooks/` | Cadastra um novo endpoint. O `signing_secret` completo é retornado neste momento. |\n| `PATCH` | `/api/v1/settings/webhooks/{endpoint_id}/` | Atualiza URL, eventos ou estado de um endpoint já cadastrado. |\n| `DELETE` | `/api/v1/settings/webhooks/{endpoint_id}/` | Remove um endpoint de webhook da conta autenticada. |\n| `POST` | `/api/v1/settings/webhooks/{endpoint_id}/rotate-secret/` | Gera um novo `signing_secret` para o endpoint. |\n| `GET` | `/api/v1/settings/webhooks/deliveries/` | Lista as tentativas de entrega por endpoint, status e nome do evento. |\n\n### Filtros do histórico de entregas\n\n| Parâmetro | Tipo | Obrigatório | Uso |\n| --- | --- | --- | --- |\n| `endpoint_id` | integer | Não | Filtra entregas de um endpoint específico. |\n| `status` | string | Não | Filtra pelo status da entrega. |\n| `event_name` | string | Não | Filtra pelo nome do evento enviado. |\n| `limit` | integer | Não | Paginação. Padrão `20`. |\n\n### Campos do endpoint de webhook\n\n| Campo | Tipo | Obrigatório | Formato / regra |\n| --- | --- | --- | --- |\n| `name` | string | Não | Nome amigável interno do endpoint. Se não for enviado, a Mepagg preenche automaticamente a partir da URL. |\n| `target_url` | string | Sim | URL HTTPS pública do sistema da conta. HTTP só é aceito para `localhost` em ambiente controlado. |\n| `subscribed_events` | array[string] | Sim | Lista dos eventos públicos que devem ser entregues para esse endpoint. Você também pode usar `[\"*\"]` para receber todos os eventos suportados. |\n| `is_enabled` | boolean | Não | Indica se o endpoint deve permanecer ativo para novas entregas. |\n\n### Campos do histórico de entregas\n\n| Campo | Uso | Exemplo |\n| --- | --- | --- |\n| `id` | Identificador interno da entrega. | `180` |\n| `endpoint_id` | Identificador do endpoint de webhook. | `12` |\n| `endpoint_name` | Nome do endpoint configurado. | `ERP principal` |\n| `event_id` | Identificador único do evento entregue. | `wh_evt_01JABCXYZ` |\n| `event_type` | Nome do evento entregue. | `invoice.paid` |\n| `status` | Status atual da entrega. | `SENT` |\n| `attempts` | Quantidade de tentativas já realizadas. | `1` |\n| `max_attempts` | Quantidade máxima de tentativas permitidas. | `6` |\n| `next_retry_at` | Próxima tentativa prevista quando houver retry. | `2026-06-17T14:30:00-03:00` |\n| `last_error` | Último erro registrado na entrega. | `timeout` |\n| `response_status_code` | HTTP status code retornado pelo sistema da conta. | `200` |\n| `response_body` | Trecho do corpo de resposta retornado pelo sistema da conta. | `ok` |\n| `payload` | Payload JSON entregue ao endpoint. | `{...}` |\n| `request_headers` | Headers usados na tentativa de entrega. | `{...}` |\n\n### Exemplo de resposta da criação do endpoint\n\n```json\n{\n  \"success\": true,\n  \"message\": \"Endpoint de webhook criado com sucesso.\",\n  \"endpoint\": {\n    \"id\": 12,\n    \"name\": \"erp.exemplo.com / webhooks/mepagg\",\n    \"target_url\": \"https://erp.exemplo.com/webhooks/mepagg\",\n    \"subscribed_events\": [\"customer.created\", \"invoice.paid\", \"invoice.cancelled\", \"transfer.completed\"],\n    \"is_enabled\": true,\n    \"masked_signing_secret\": \"whsec_************************abcd\",\n    \"signing_secret\": \"whsec_xxxxxxxxxxxxxxxxx\"\n  }\n}\n```\n\n### Exemplo do histórico de entregas\n\n```json\n{\n  \"count\": 1,\n  \"results\": [\n    {\n      \"id\": 180,\n      \"endpoint_id\": 12,\n      \"endpoint_name\": \"ERP principal\",\n      \"event_id\": \"wh_evt_01JABCXYZ\",\n      \"event_type\": \"invoice.paid\",\n      \"status\": \"SENT\",\n      \"attempts\": 1,\n      \"max_attempts\": 6,\n      \"response_status_code\": 200,\n      \"response_body\": \"ok\"\n    }\n  ]\n}\n```\n\n### Respostas HTTP\n\n| Status | Quando esperar |\n| --- | --- |\n| `200` | Listagem, criação, atualização, exclusão ou histórico consultado com sucesso. |\n| `400` | URL inválida, eventos incompatíveis ou payload fora da regra. |\n| `401` | Chave ausente ou inválida. |\n| `429` | Limite operacional excedido. |\n| `500` | Falha inesperada no backend. |\n\n### Headers\n\n| Header | Uso |\n| --- | --- |\n| `X-Mepagg-Event` | Nome do evento |\n| `X-Mepagg-Event-Id` | Identificador único do evento para deduplicação |\n| `X-Mepagg-Delivery-Id` | Identificador único da tentativa de entrega |\n| `X-Mepagg-Timestamp` | Unix timestamp da tentativa |\n| `X-Mepagg-Retry-Count` | Número da tentativa de entrega |\n| `X-Mepagg-Signature` | Assinatura HMAC SHA-256 legada |\n| `X-Mepagg-Signature-V2` | Assinatura HMAC SHA-256 com timestamp para reduzir replay |\n\n### Regras de uso\n\n- Preferir validar `X-Mepagg-Signature-V2` usando `X-Mepagg-Timestamp` e o material `${timestamp}.${payload_bruto}`. Se necessário, ajuste a integração.\n- Validar `X-Mepagg-Signature` usando o payload bruto da requisição apenas por compatibilidade.\n- Tratar `X-Mepagg-Event-Id` como chave de deduplicação.\n- Persistir também `X-Mepagg-Delivery-Id` e `X-Mepagg-Retry-Count` para auditoria e replay controlado.\n- Responder HTTP `2xx` rapidamente.\n- Processar em fila assíncrona quando possível.\n- Após receber o evento, consultar novamente o recurso pela API para conciliação final.\n\n> Boas práticas: responda com HTTP `2xx` quando o evento for aceito, prefira validar `X-Mepagg-Signature-V2` e processe o conteúdo com idempotência usando `event_id` e `delivery_id`.\n\n### Eventos importantes\n\n- `customer.created`\n- `customer.updated`\n- `customer.deleted`\n- `invoice.created`\n- `invoice.updated`\n- `invoice.paid`\n- `invoice.cancelled`\n- `invoice.expired`\n- `invoice.expired_final`\n- `invoice.refunded`\n- `subscription.created`\n- `subscription.updated`\n- `subscription.renewed`\n- `carne.cancelled`\n- `transfer.created`\n- `transfer.completed`\n- `sms.credits_purchased`\n- `sms.sent`\n- `email.sent`\n- `payment_link.status_changed`\n\n\n### Evento payment_link.status_changed\n\nUse esse evento para reagir a mudanças de disponibilidade do checkout do link. O payload entrega o status anterior, o status atual, o motivo estável da mudança e um snapshot completo do `payment_link`.\n\n| Campo | Uso | Exemplo |\n| --- | --- | --- |\n| `payment_link_public_token` | Token público do link afetado. | `4dd78029-fb39-4c52-b0e6-2bc748d2832b` |\n| `previous_status_code` | Status anterior para deduplicação e trilha. | `active` |\n| `status_code` | Status atual do link. | `limit_reached` |\n| `status_reason_code` | Motivo estável da mudança. | `usage_limit_reached` |\n| `payment_link.status_label` | Texto amigável do status atual. | `Limite atingido` |\n| `payment_link.public_url` | URL pública de checkout do link. | `https://app.mepagg.com/link/.../` |\n\n### Contrato de fatura enviado nos webhooks\n\nNos eventos de cobrança, leia `invoice.type`, `invoice.type_code`, `invoice.type_label`, `invoice.issued_via`, `invoice.issued_via_code` e `invoice.issued_via_label` como o contrato principal do webhook. O campo `type_display` pode aparecer em respostas de consulta da API como alias de interface, mas a integração de webhook deve se basear em `type_code`, `type_label`, `issued_via_code` e `issued_via_label`.\n\n| `invoice.type` | `invoice.type_code` | `invoice.type_label` | Quando aparece |\n| --- | --- | --- | --- |\n| `2` | `subscription` | `Assinatura` | Fatura gerada por recorrência. |\n| `3` | `oneoff` | `Avulsa` | Fatura avulsa criada para cobrança pontual, inclusive quando emitida pela API pública. |\n| `4` | `carne` | `Carnê` | Parcela ou contexto vinculado a carnê. |\n| `5` | `payment_link` | `Link de pagamento` | Cobrança originada de link de pagamento. |\n| `6` | `payment_button` | `Botão de pagamento` | Cobrança originada de botão de pagamento. |\n\n| `invoice.issued_via` | `invoice.issued_via_code` | `invoice.issued_via_label` | Quando aparece |\n| --- | --- | --- | --- |\n| `PANEL` | `panel` | `Painel` | Fatura emitida pelo painel autenticado da Mepagg. |\n| `API` | `api` | `API` | Fatura emitida pela API pública da Mepagg. |\n\n### Exemplo de cadastro do endpoint\n\n```json\n{\n  \"target_url\": \"https://erp.exemplo.com/webhooks/mepagg\",\n  \"subscribed_events\": [\n    \"customer.created\",\n    \"invoice.paid\",\n    \"invoice.cancelled\",\n    \"payment_link.status_changed\",\n    \"transfer.completed\",\n    \"sms.credits_purchased\"\n  ],\n  \"is_enabled\": true\n}\n```\n\n### Headers enviados pela Mepagg\n\n```http\nX-Mepagg-Event: invoice.paid\nX-Mepagg-Event-Id: wh_evt_01JABCXYZ\nX-Mepagg-Delivery-Id: wh_delivery_01JABCXYZ\nX-Mepagg-Timestamp: 1712345678\nX-Mepagg-Retry-Count: 0\nX-Mepagg-Signature: sha256=HEX_DO_HMAC\nX-Mepagg-Signature-V2: t=1712345678,sha256=HEX_DO_HMAC_V2\nContent-Type: application/json\n```\n\n### Payload exemplo de customer.updated\n\n```json\n{\n  \"id\": \"wh_evt_01JCUSTXYZ\",\n  \"type\": \"customer.updated\",\n  \"occurred_at\": \"2026-06-17T18:42:11-03:00\",\n  \"account\": {\n    \"token\": \"ACC_EXAMPLE_001\",\n    \"name\": \"Empresa Exemplo de Cobrancas LTDA\",\n    \"document\": \"12345678000199\"\n  },\n  \"data\": {\n    \"customer_id\": 248,\n    \"customer_reference_id\": \"CST_EXAMPLE_248\",\n    \"customer\": {\n      \"id\": 248,\n      \"reference_id\": \"CST_EXAMPLE_248\",\n      \"name\": \"Cliente Exemplo LTDA\",\n      \"document\": \"12345678000155\",\n      \"email_primary\": \"financeiro@clienteexemplo.com.br\",\n      \"email_secondary\": \"cobranca@clienteexemplo.com.br\",\n      \"phone_number\": \"3133334444\",\n      \"phone\": \"(31) 3333-4444\",\n      \"state\": \"MG\",\n      \"city\": \"Mariana\",\n      \"street\": \"Rua Direita\",\n      \"neighborhood\": \"Centro\",\n      \"number\": \"120\",\n      \"no_number\": false,\n      \"complement\": \"Sala 03\",\n      \"zipcode\": \"35420000\",\n      \"formatted_address\": \"Rua Direita, 120, Centro, Mariana - MG, CEP 35420-000\",\n      \"observation\": \"\",\n      \"is_blocked\": false,\n      \"blocked_reason\": \"\",\n      \"is_defaulter\": false,\n      \"is_deleted\": false,\n      \"created_at\": \"2026-06-10T09:00:00-03:00\",\n      \"updated_at\": \"2026-06-17T18:42:10-03:00\",\n      \"deleted_at\": null\n    }\n  }\n}\n```\n\n### Payload exemplo de invoice.paid\n\n```json\n{\n  \"id\": \"wh_evt_01JABCXYZ\",\n  \"type\": \"invoice.paid\",\n  \"occurred_at\": \"2026-06-15T10:19:12-03:00\",\n  \"account\": {\n    \"token\": \"ACC_EXAMPLE_001\",\n    \"name\": \"Empresa Exemplo de Cobrancas LTDA\",\n    \"document\": \"12345678000199\"\n  },\n  \"data\": {\n    \"invoice_reference_id\": \"GLZOX8K19Q40NVLJ6WJ2PRYD7EV653\",\n    \"amount_paid\": \"5200.00\",\n    \"paid_at\": \"2026-06-15T10:18:00-03:00\",\n    \"paid_source\": \"pix\",\n    \"invoice\": {\n      \"reference_id\": \"GLZOX8K19Q40NVLJ6WJ2PRYD7EV653\",\n      \"status\": 2,\n      \"status_label\": \"Paga\",\n      \"status_code\": \"paid\",\n      \"type\": 3,\n      \"type_label\": \"Avulsa\",\n      \"type_code\": \"oneoff\",\n      \"type_display\": \"Avulsa\",\n      \"issued_via\": \"API\",\n      \"issued_via_code\": \"api\",\n      \"issued_via_label\": \"API\"\n    }\n  }\n}\n```\n\n\n### Payload exemplo de payment_link.status_changed\n\n```json\n{\n  \"id\": \"wh_evt_01JPLINKXYZ\",\n  \"type\": \"payment_link.status_changed\",\n  \"occurred_at\": \"2026-07-24T11:32:10-03:00\",\n  \"account\": {\n    \"token\": \"ACC_EXAMPLE_001\",\n    \"name\": \"Empresa Exemplo de Cobrancas LTDA\",\n    \"document\": \"12345678000199\"\n  },\n  \"data\": {\n    \"payment_link_public_token\": \"4dd78029-fb39-4c52-b0e6-2bc748d2832b\",\n    \"previous_status_code\": \"active\",\n    \"previous_status_label\": \"Ativo\",\n    \"status_code\": \"limit_reached\",\n    \"status_label\": \"Limite atingido\",\n    \"status_reason_code\": \"usage_limit_reached\",\n    \"status_reason_label\": \"Limite de usos atingido\",\n    \"payment_link\": {\n      \"public_token\": \"4dd78029-fb39-4c52-b0e6-2bc748d2832b\",\n      \"description\": \"Link para adesao anual\",\n      \"amount\": \"249.90\",\n      \"status_code\": \"limit_reached\",\n      \"status_label\": \"Limite atingido\",\n      \"status_reason_code\": \"usage_limit_reached\",\n      \"status_reason_label\": \"Limite de usos atingido\",\n      \"used_count\": 3,\n      \"remaining_uses\": 0,\n      \"usage_limit\": 3,\n      \"public_url\": \"https://app.mepagg.com/link/4dd78029-fb39-4c52-b0e6-2bc748d2832b/\"\n    }\n  }\n}\n```\n\n### Exemplo de payload de transfer.completed\n\n```json\n{\n  \"id\": \"wh_evt_01JTRFXYZ\",\n  \"type\": \"transfer.completed\",\n  \"occurred_at\": \"2026-06-17T14:25:10-03:00\",\n  \"account\": {\n    \"token\": \"ACC_EXAMPLE_001\",\n    \"name\": \"Empresa Exemplo de Cobrancas LTDA\",\n    \"document\": \"12345678000199\"\n  },\n  \"data\": {\n    \"transfer\": {\n      \"reference_id\": \"TRF_EXAMPLE_001\",\n      \"status\": \"APPROVED\",\n      \"status_label\": \"Aprovada\",\n      \"requested_amount\": \"100.00\",\n      \"tariff_amount\": \"0.00\",\n      \"approved_at\": \"2026-06-17T14:25:10-03:00\",\n      \"processed_at\": \"2026-06-17T14:25:10-03:00\",\n      \"pix_key_type\": \"EMAIL\",\n      \"pix_key_value\": \"financeiro@clienteexemplo.com.br\"\n    }\n  }\n}\n```\n\n### Exemplo de payload de carne.cancelled\n\n```json\n{\n  \"id\": \"wh_evt_01JCARXYZ\",\n  \"type\": \"carne.cancelled\",\n  \"occurred_at\": \"2026-06-17T19:15:00-03:00\",\n  \"account\": {\n    \"token\": \"ACC_EXAMPLE_001\",\n    \"name\": \"Empresa Exemplo de Cobrancas LTDA\",\n    \"document\": \"12345678000199\"\n  },\n  \"data\": {\n    \"carne_reference_id\": \"CAR_01JABCXYZ\",\n    \"cancelled_reason\": \"Solicitado pelo cliente.\",\n    \"cancelled_installments\": 3,\n    \"carne\": {\n      \"reference_id\": \"CAR_01JABCXYZ\",\n      \"description\": \"Parcelamento da adesão anual\",\n      \"installments_count\": 3,\n      \"total_amount\": \"120.00\",\n      \"summary\": {\n        \"status_code\": \"cancelled\",\n        \"status_label\": \"Cancelado\",\n        \"total_installments\": 3,\n        \"paid_installments\": 0,\n        \"cancelled_installments\": 3,\n        \"open_installments\": 0\n      }\n    }\n  }\n}\n```\n\n### Exemplo de payload de sms.credits_purchased\n\n```json\n{\n  \"id\": \"wh_evt_01JSMSXYZ\",\n  \"type\": \"sms.credits_purchased\",\n  \"occurred_at\": \"2026-06-17T16:00:00-03:00\",\n  \"account\": {\n    \"token\": \"ACC_EXAMPLE_001\",\n    \"name\": \"Empresa Exemplo de Cobrancas LTDA\",\n    \"document\": \"12345678000199\"\n  },\n  \"data\": {\n    \"sms_credit_purchase\": {\n      \"package_code\": \"500\",\n      \"credits_added\": 500,\n      \"purchase_method\": \"mepagg_balance\",\n      \"package_amount\": \"75.00\",\n      \"sms_credits_balance\": 1500,\n      \"source\": \"api\"\n    }\n  }\n}\n```\n\n### Validação da assinatura em Node.js\n\n```js\nimport crypto from 'node:crypto';\n\nconst rawBody = requestBodyBuffer;\nconst timestamp = request.headers['x-mepagg-timestamp'];\nconst signature = request.headers['x-mepagg-signature-v2'];\nconst signedPayload = `${timestamp}.${rawBody.toString('utf8')}`;\nconst expected = `t=${timestamp},sha256=` + crypto\n  .createHmac('sha256', process.env.MEPAGG_WEBHOOK_SECRET)\n  .update(signedPayload)\n  .digest('hex');\n\nif (signature !== expected) {\n  throw new Error('Assinatura inválida');\n}\n```\n\n### Validação da assinatura em PHP\n\n```php\n$rawBody = file_get_contents('php://input');\n$timestamp = $_SERVER['HTTP_X_MEPAGG_TIMESTAMP'] ?? '';\n$signature = $_SERVER['HTTP_X_MEPAGG_SIGNATURE_V2'] ?? '';\n$signedPayload = $timestamp . '.' . $rawBody;\n$expected = 't=' . $timestamp . ',sha256=' . hash_hmac('sha256', $signedPayload, getenv('MEPAGG_WEBHOOK_SECRET'));\n\nif (!hash_equals($expected, $signature)) {\n    throw new RuntimeException('Assinatura inválida');\n}\n```\n\n### Boas práticas\n\nResponda com HTTP `2xx` quando o evento for aceito, prefira validar `X-Mepagg-Signature-V2` e processe o conteúdo com idempotência usando `event_id` e `delivery_id`.\n\n### Política recomendada de retry\n\nSe o seu endpoint retornar erro ou não responder a tempo, mantenha o processamento idempotente e aceite reentregas. Responda `2xx` rapidamente, persista o evento, processe em fila assíncrona e use `/api/v1/settings/webhooks/deliveries/` para auditoria operacional.\n\n| Tentativa | Backoff previsto |\n| --- | --- |\n| `1` | `1 minuto` |\n| `2` | `5 minutos` |\n| `3` | `15 minutos` |\n| `4` | `60 minutos` |\n| `5` | `180 minutos` |\n| `6` | `720 minutos` |\n\n### Eventos de planos\n\n- `plan.created`\n- `plan.updated`\n- `plan.deleted`\n"
    },
    {
      "name": "Padrão de respostas",
      "x-displayName": "Padrão de respostas",
      "x-section-id": "padrao-de-respostas",
      "description": "A API atual possui envelopes diferentes conforme o recurso. Prefira sempre os campos explicitamente documentados em cada endpoint.\n\n### Sucesso simples\n\n```json\n{\n  \"success\": true,\n  \"message\": \"Operação realizada com sucesso.\"\n}\n```\n\n### Erro simples\n\n```json\n{\n  \"success\": false,\n  \"message\": \"Chave de API inválida.\"\n}\n```\n\n### Listagem\n\n```json\n{\n  \"count\": 1,\n  \"results\": [\n    {\n      \"reference_id\": \"CUST_EXAMPLE_001\",\n      \"name\": \"Cliente Exemplo LTDA\"\n    }\n  ]\n}\n```"
    },
    {
      "name": "Erros comuns",
      "x-displayName": "Erros comuns",
      "x-section-id": "erros-comuns",
      "description": "| HTTP | Código recomendado | Mensagem / cenário | Causa | Solução |\n| --- | --- | --- | --- | --- |\n| `400` | `VALIDATION_ERROR` | `Pacote de SMS inválido.`, `Informe um valor válido...` | Campo obrigatório ausente, pacote inexistente, telefone inválido, valor fora da regra ou formato incorreto. | Validar payload antes do envio e usar apenas formatos documentados. |\n| `401` | `INVALID_API_KEY` | `Chave de API inválida ou ausente.` | Header `X-API-KEY` ausente, incorreto ou pertencente a outra conta. | Enviar a chave correta no header e nunca no body ou query string. |\n| `403` | `INSUFFICIENT_BALANCE` | `Você não possui saldo disponível...` | Saldo insuficiente, conta bloqueada para a operação ou permissão ausente. | Consultar saldo, status da conta e permissões antes da operação crítica. |\n| `404` | `CUSTOMER_NOT_FOUND`, `INVOICE_NOT_FOUND`, `TRANSFER_NOT_FOUND` | `Fatura não encontrada.` | O recurso não existe ou não pertence à conta autenticada. | Persistir `reference_id` corretamente e consultar sempre dentro do contexto da mesma conta. |\n| `409` | `RATE_LIMIT_EXCEEDED` | `Conflito de idempotência`, `Saldo insuficiente` | Repetição incompatível da mesma operação, disputa de estado ou restrição operacional momentânea. | Usar `Idempotency-Key`, evitar retries cegos e reconsultar o recurso antes de repetir. |\n| `422` | `INVALID_DOCUMENT`, `INVALID_EMAIL`, `INVALID_PIX_KEY` | `Documento inválido.`, `E-mail inválido.` | Formato sintaticamente aceito, mas rejeitado pela regra de negócio. | Sanear CPF/CNPJ, CEP, e-mail e chave Pix no sistema da conta antes do POST. |\n| `500` | `INTERNAL_ERROR` | `Erro interno ao processar a requisição.` | Falha inesperada no backend, timeout interno ou indisponibilidade transitória. | Registrar logs, aplicar retry com backoff e reconsultar o recurso para confirmar estado final. |\n\n### Tratamento de erro em JavaScript\n\n```js\nimport axios from 'axios';\n\ntry {\n  const response = await axios.post('https://app.mepagg.com/api/v1/sms/buy-credits/', payload, {\n    headers: { 'X-API-KEY': 'SUA_CHAVE_DE_API' },\n  });\n  console.log(response.data);\n} catch (error) {\n  const status = error.response?.status;\n  const body = error.response?.data;\n\n  if (status === 400 || status === 422) {\n    console.error('Validação rejeitada:', body);\n  } else if (status === 401) {\n    console.error('Falha de autenticação:', body);\n  } else if (status === 403 || status === 409) {\n    console.error('Regra de negócio bloqueou a operação:', body);\n  } else {\n    console.error('Erro inesperado, reconsulte o recurso antes de repetir:', body);\n  }\n}\n```"
    },
    {
      "name": "Catálogo canônico",
      "x-displayName": "Catálogo canônico",
      "x-section-id": "catalogo-canonico",
      "description": "Use esta seção como referência estável para enums, leituras operacionais e convenções públicas da API.\n\n### Formas de pagamento da cobrança\n\n| Valor | Uso | Observação |\n| --- | --- | --- |\n| `boleto` | Habilita pagamento por boleto bancário. | Forma de pagamento da cobrança, não tipo da fatura. |\n| `pix` | Habilita pagamento por PIX. | Forma de pagamento da cobrança, não tipo da fatura. |\n\n### Tipos de desconto\n\n| Valor | Interpretação | Exemplo |\n| --- | --- | --- |\n| `PERCENTAGE` | O campo `discount` representa percentual. | `\"10.00\"` = 10% |\n| `FIXED_VALUE` | O campo `discount` representa valor monetário em reais. | `\"15.00\"` = R$ 15,00 |\n\n### Tipos de fatura expostos pela API e pelos webhooks\n\n| `type` | `type_code` | `type_label` | Quando aparece |\n| --- | --- | --- | --- |\n| `2` | `subscription` | `Assinatura` | Fatura gerada por recorrência. |\n| `3` | `oneoff` | `Avulsa` | Fatura avulsa criada para cobrança pontual. |\n| `4` | `carne` | `Carnê` | Parcela ou contexto vinculado a carnê. |\n| `5` | `payment_link` | `Link de pagamento` | Cobrança originada de link de pagamento. |\n| `6` | `payment_button` | `Botão de pagamento` | Cobrança originada de botão de pagamento. |\n\n### Emitida via\n\n`Emitida via` é a forma humana de ler a origem da emissão da fatura. No contrato da API e dos webhooks isso aparece pelos campos `issued_via`, `issued_via_code` e `issued_via_label`.\n\nEsses três campos são somente leitura. A Mepagg calcula internamente a origem real da emissão e retorna esse trio apenas na resposta da API e nos webhooks.\n\n| Campo | Como usar | Exemplo |\n| --- | --- | --- |\n| `issued_via` | Valor original retornado no payload. | `API` |\n| `issued_via_code` | Código estável para regra, filtro, integração e automação. | `api` |\n| `issued_via_label` | Texto amigável para interface humana. | `API` |\n\n| `issued_via` | `issued_via_code` | `issued_via_label` | Quando aparece |\n| --- | --- | --- | --- |\n| `PANEL` | `panel` | `Painel` | Fatura emitida pelo painel autenticado da Mepagg. |\n| `API` | `api` | `API` | Fatura emitida pela API pública da Mepagg. |\n\n### Leitura dos status de fatura\n\n| Campo | Uso recomendado | Exemplo |\n| --- | --- | --- |\n| `status_label` | Exibição em interface. | `Paga` |\n| `status_code` | Filtros, automações e regra de sistema. | `paid` |\n| `type_label` | Exibição em interface. | `Avulsa` |\n| `type_code` | Regra de sistema e automações. | `oneoff` |\n| `type_display` | Alias atual de interface para `type_label`. | `Avulsa` |\n| `issued_via_label` | Exibição da origem da emissão. | `API` |\n| `issued_via_code` | Regra de sistema da origem da emissão. | `api` |\n\n### Eventos principais de webhook\n\n| Evento | Quando usar | Observação |\n| --- | --- | --- |\n| `customer.created` | Criar ou espelhar um novo pagador no ERP ou sistema da conta. | Útil para manter o cadastro sincronizado logo após o registro no Mepagg. |\n| `customer.updated` | Atualizar dados cadastrais do cliente no sistema da conta. | Use o snapshot completo do objeto `customer` para sobrescrever campos críticos. |\n| `customer.deleted` | Marcar o cliente como removido no sistema da conta. | O payload informa `is_deleted=true` e preenche `deleted_at`. |\n| `invoice.paid` | Reagir a pagamento confirmado. | Consultar a fatura e o extrato para conciliação final. |\n| `invoice.cancelled` | Refletir cancelamento da cobrança. | Evitar novas tentativas de cobrança sobre o mesmo título. |\n| `invoice.refunded` | Atualizar o estado após devolução de valor. | Conciliar com o extrato e registro de atendimento. |\n| `subscription.renewed` | Sincronizar novo ciclo de recorrência. | Associar com a nova fatura gerada. |\n| `carne.cancelled` | Atualizar o estado consolidado de um carnê cancelado. | Complementa os eventos `invoice.cancelled` disparados nas parcelas. |\n| `transfer.created` | Registrar uma solicitação de saída financeira ainda em análise. | Útil para trilha operacional e aprovação interna. |\n| `transfer.completed` | Baixar saída financeira confirmada. | Conciliar com o lançamento de débito no extrato. |\n| `sms.credits_purchased` | Atualizar saldo de créditos SMS do sistema da conta. | Indica compra concluída e informa pacote, valor e saldo final. |"
    },
    {
      "name": "Limites operacionais",
      "x-displayName": "Limites operacionais",
      "x-section-id": "limites-operacionais",
      "description": "Os limites abaixo ajudam o sistema da conta a implementar validações preventivas e tratamento seguro antes de chamar a API.\n\n| Recurso | Limite / regra | Observação |\n| --- | --- | --- |\n| Paginação | `limit` de 1 a 200 | Use paginação progressiva em listagens grandes. |\n| SMS | `content` com até 160 caracteres | Valide antes de enviar para evitar falha desnecessária. |\n| Boleto agenda | `inter_boleto_num_dias_agenda` de 1 a 60 | Aplicável quando a operação usar essa configuração. |\n| Idempotência | `Idempotency-Key` até 255 caracteres | Use uma chave única por operação lógica. |\n| Transferências no painel autenticado | Dependem de saldo disponível e janela operacional | Revalidar no backend do painel antes da efetivação. |\n| Webhooks | Responder HTTP `2xx` rapidamente | Persistir e processar em fila assíncrona no sistema da conta. |"
    },
    {
      "name": "Rastreabilidade e correlação",
      "x-displayName": "Rastreabilidade e correlação",
      "x-section-id": "rastreabilidade-correlacao",
      "description": "Uma integração profissional deve correlacionar recursos financeiros, webhooks e lançamentos contábeis da própria conta.\n\n- Persista sempre `reference_id` do recurso principal.\n- Para faturas, guarde pelo menos `reference_id`, `status_code`, `type_code`, `issued_via_code`, `amount_paid` e `paid_at`.\n- Para webhooks, persista `X-Mepagg-Event-Id`, `X-Mepagg-Delivery-Id`, `X-Mepagg-Timestamp`, `X-Mepagg-Retry-Count`, data de recebimento, status de processamento interno e payload bruto.\n- Para transferências, guarde `reference_id`, `status_code`, `amount` e o vínculo com o lançamento correspondente no extrato.\n- Para conciliação financeira, relacione o recurso transacional com o `related_reference_id` do extrato quando disponível.\n\n> Se houver divergência momentânea entre evento, recurso e extrato, trate o extrato e o resumo financeiro como fonte final de verdade econômica."
    },
    {
      "name": "Versionamento e compatibilidade",
      "x-displayName": "Versionamento e compatibilidade",
      "x-section-id": "versionamento-compatibilidade",
      "description": "A API pública atual está sob `/api/v1/`. Trate a versão como contrato estável e acompanhe o changelog público a cada alteração.\n\n| Tema | Diretriz |\n| --- | --- |\n| Campos novos | O sistema da conta deve ignorar campos desconhecidos sem quebrar o parsing. |\n| Enums | Use os códigos documentados como contrato estável e trate novos valores de forma segura em interface e logs. |\n| Breaking changes | Devem aparecer no changelog público e exigir migração explícita antes de nova versão maior. |\n| OpenAPI | `openapi.json` continua sendo a especificação canônica para SDKs, agentes e validação de contrato. |"
    },
    {
      "name": "Sugestão visual de status",
      "x-displayName": "Sugestão visual de status",
      "x-section-id": "sugestao-visual-de-status",
      "description": "Estas cores são uma convenção recomendada para interface. Para regra de negócio, continue usando `status_code`, `type_code` e os campos estruturados da API.\n\n### Faturas\n\n| Status | Uso sugerido | Cor | Hex |\n| --- | --- | --- | --- |\n| `processing` / Processando | Cobrança em processamento interno | Teal da plataforma | `#03989E` |\n| `to_expire` / A vencer | Cobrança aberta dentro do prazo | Amarelo | `#f6c23e` |\n| `paid` / Paga | Pagamento confirmado | Verde | `#1cc88a` |\n| `expired` / Vencida | Cobrança vencida | Vermelho | `#e74a3b` |\n| `cancelled` / Cancelada | Cobrança cancelada | Roxo | `#9932CC` |\n| `refunded` / Estornada | Valor devolvido | Azul | `#4e73df` |\n| `expired_final` / Expirada | Cobrança encerrada por expiração final | Cinza | `#858796` |\n\n### Assinaturas\n\n| Status | Uso sugerido | Cor | Hex |\n| --- | --- | --- | --- |\n| `ACTIVE` / Ativa | Recorrência em execução | Verde | `#1cc88a` |\n| `SUSPENDED` / Suspensa | Recorrência suspensa | Cinza | `#5a5c69` |\n\n### Carnês\n\n| Status | Uso sugerido | Cor | Hex |\n| --- | --- | --- | --- |\n| `open` / Em aberto | Há parcelas pendentes, vencidas, expiradas finais ou em processamento | Amarelo | `#f6c23e` |\n| `partially_paid` / Parcialmente pago | Há parcelas pagas e canceladas no conjunto | Teal da plataforma | `#03989E` |\n| `paid` / Pago | Todas as parcelas pagas | Verde | `#1cc88a` |\n| `cancelled` / Cancelado | Todas as parcelas canceladas | Roxo | `#9932CC` |\n\n### Clientes\n\n| Indicador | Uso sugerido | Cor | Hex |\n| --- | --- | --- | --- |\n| `is_defaulter=false` / Adimplente | Cliente em situação regular. | Verde | `#1cc88a` |\n| `is_defaulter=true` / Inadimplente | Cliente com pendências relevantes para cobrança. | Vermelho | `#e74a3b` |"
    },
    {
      "name": "FAQ técnica",
      "x-displayName": "FAQ técnica",
      "x-section-id": "faq-tecnica",
      "description": "### Como criar uma cobrança Pix?\n\nCrie a fatura em `/api/v1/invoices/` com `payment_methods: [\"pix\"]`.\n\n### Como criar boleto?\n\nCrie a fatura em `/api/v1/invoices/` com `payment_methods: [\"boleto\"]`.\n\n### Como criar boleto e Pix na mesma cobrança?\n\nCrie a fatura com `payment_methods: [\"boleto\", \"pix\"]`.\n\n### Como saber se a cobrança foi paga?\n\nUse o webhook para reação rápida e depois confirme o estado em `/api/v1/invoices/{reference_id}/` e no extrato.\n\n### Posso confiar apenas no webhook?\n\nNão. O webhook acelera a integração, mas a confirmação econômica final deve considerar a consulta do recurso e, quando necessário, o extrato.\n\n### Como validar a assinatura do webhook?\n\nValide `X-Mepagg-Signature-V2` com HMAC SHA-256 usando o `signing_secret`, o `X-Mepagg-Timestamp` e o payload bruto da requisição. `X-Mepagg-Signature` permanece disponível por compatibilidade.\n\n### Como evitar duplicidade?\n\nUse `Idempotency-Key` nas operações suportadas e `X-Mepagg-Event-Id` para deduplicação dos webhooks.\n\n### Como consultar saldo e extrato?\n\nUse `/api/v1/statement/summary/` para resumo e `/api/v1/statement/` para conciliação detalhada.\n\n### Como realizar transferência?\n\nA criação de transferências é feita somente no painel autenticado da Mepagg. Pela API pública permanecem apenas consultas de leitura sobre transferências da própria conta."
    },
    {
      "name": "Boas práticas de produção",
      "x-displayName": "Boas práticas de produção",
      "x-section-id": "boas-praticas-de-producao",
      "description": "- Guardar `reference_id` como identificador externo estável.\n- Guardar `status_code`, `type_code` e `issued_via_code` para automações.\n- Usar `status_label`, `type_label` e `issued_via_label` apenas para interface.\n- Usar idempotência em webhooks e operações críticas.\n- Nunca confiar apenas no `POST` inicial para confirmação financeira.\n- Revalidar saldo disponível no backend antes de solicitar transferência ou saque.\n- Conciliar pagamentos por fatura, webhook e extrato, não apenas pela resposta inicial da criação.\n- Persistir o `X-Mepagg-Event-Id` para impedir processamento duplicado de webhooks.\n- Registrar `paid_at`, `amount_paid`, `status_code` e `reference_id` no ERP ou sistema da conta."
    },
    {
      "name": "Arquivos técnicos",
      "x-displayName": "Arquivos técnicos",
      "x-section-id": "arquivos-tecnicos",
      "description": "- [openapi.json](./openapi.json): especificação canônica da API.\n- [api-reference.md](./api-reference.md): resumo técnico em texto simples.\n- [llms.txt](./llms.txt): resumo curto para leitura automatizada por IA.\n- [postman_collection.json](./postman_collection.json): apoio para homologação manual.\n- [changelog.html](./changelog.html): histórico público de mudanças."
    }
  ],
  "x-tagGroups": [
    {
      "name": "Comece aqui",
      "tags": [
        "Autenticação",
        "Regras principais",
        "Comece em 5 minutos",
        "Fluxo financeiro",
        "Idempotency-Key",
        "Modelos por linguagem"
      ]
    },
    {
      "name": "Recursos",
      "tags": [
        "Clientes",
        "Faturas",
        "Assinaturas",
        "Planos",
        "Carnês",
        "Links de pagamentos",
        "Transferências",
        "Extrato",
        "Dashboard",
        "SMS",
        "E-mails",
        "Conta",
        "Webhooks"
      ]
    },
    {
      "name": "Referência",
      "tags": [
        "Padrão de respostas",
        "Erros comuns",
        "Catálogo canônico",
        "Limites operacionais",
        "Rastreabilidade e correlação",
        "Versionamento e compatibilidade",
        "Sugestão visual de status",
        "FAQ técnica",
        "Boas práticas de produção",
        "Arquivos técnicos"
      ]
    }
  ],
  "x-navigation": [
    {
      "title": "Comece aqui",
      "items": [
        {
          "id": "visao-geral",
          "label": "Visão geral"
        },
        {
          "id": "autenticacao",
          "label": "Autenticação"
        },
        {
          "id": "regras-principais",
          "label": "Regras principais"
        },
        {
          "id": "comece-5-minutos",
          "label": "Comece em 5 minutos"
        },
        {
          "id": "fluxo-financeiro",
          "label": "Fluxo financeiro"
        },
        {
          "id": "idempotency-key",
          "label": "Idempotency-Key"
        },
        {
          "id": "modelos-por-linguagem",
          "label": "Modelos por linguagem"
        }
      ]
    },
    {
      "title": "Recursos",
      "items": [
        {
          "id": "clientes",
          "label": "Clientes"
        },
        {
          "id": "faturas",
          "label": "Faturas"
        },
        {
          "id": "assinaturas",
          "label": "Assinaturas"
        },
        {
          "id": "planos",
          "label": "Planos"
        },
        {
          "id": "carnes",
          "label": "Carnês"
        },
        {
          "id": "transferencias",
          "label": "Transferências"
        },
        {
          "id": "extrato-dashboard",
          "label": "Extrato, saldo e dashboard"
        },
        {
          "id": "sms",
          "label": "SMS"
        },
        {
          "id": "emails-enviados",
          "label": "E-mails enviados"
        },
        {
          "id": "dados-da-conta",
          "label": "Dados da conta"
        },
        {
          "id": "webhooks",
          "label": "Webhooks"
        }
      ]
    },
    {
      "title": "Referência",
      "items": [
        {
          "id": "padrao-de-respostas",
          "label": "Padrão de respostas"
        },
        {
          "id": "erros-comuns",
          "label": "Erros comuns"
        },
        {
          "id": "catalogo-canonico",
          "label": "Catálogo canônico"
        },
        {
          "id": "limites-operacionais",
          "label": "Limites operacionais"
        },
        {
          "id": "rastreabilidade-correlacao",
          "label": "Rastreabilidade e correlação"
        },
        {
          "id": "versionamento-compatibilidade",
          "label": "Versionamento e compatibilidade"
        },
        {
          "id": "sugestao-visual-de-status",
          "label": "Sugestão visual de status"
        },
        {
          "id": "faq-tecnica",
          "label": "FAQ técnica"
        },
        {
          "id": "boas-praticas-de-producao",
          "label": "Boas práticas de produção"
        },
        {
          "id": "arquivos-tecnicos",
          "label": "Arquivos técnicos"
        }
      ]
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-KEY",
        "description": "Chave de API da conta Mepagg."
      }
    },
    "parameters": {
      "ReferenceId": {
        "name": "reference_id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Identificador público estável do recurso."
      },
      "EndpointId": {
        "name": "endpoint_id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "integer"
        },
        "description": "Identificador interno do endpoint de webhook."
      },
      "WebhookSignature": {
        "name": "X-Mepagg-Signature",
        "in": "header",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Assinatura HMAC SHA-256 do payload bruto do webhook usando o `signing_secret` do endpoint."
      },
      "WebhookEventId": {
        "name": "X-Mepagg-Event-Id",
        "in": "header",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Identificador único do evento. Use como chave de idempotência no sistema da conta."
      },
      "WebhookDeliveryId": {
        "name": "X-Mepagg-Delivery-Id",
        "in": "header",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Identificador único da tentativa de entrega do webhook. Use para rastreabilidade e auditoria."
      },
      "WebhookTimestamp": {
        "name": "X-Mepagg-Timestamp",
        "in": "header",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Unix timestamp da tentativa de entrega. É usado na validação reforçada da assinatura."
      },
      "WebhookRetryCount": {
        "name": "X-Mepagg-Retry-Count",
        "in": "header",
        "required": true,
        "schema": {
          "type": "integer"
        },
        "description": "Número da tentativa de entrega atual. Começa em `0` na primeira entrega."
      },
      "WebhookSignatureV2": {
        "name": "X-Mepagg-Signature-V2",
        "in": "header",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Assinatura HMAC SHA-256 no formato `t=<timestamp>,sha256=<hash>`, calculada sobre `${timestamp}.${payload_bruto}`."
      },
      "Limit": {
        "name": "limit",
        "in": "query",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 200,
          "default": 20
        }
      },
      "Offset": {
        "name": "offset",
        "in": "query",
        "schema": {
          "type": "integer",
          "minimum": 0,
          "default": 0
        }
      },
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string",
          "maxLength": 255
        },
        "description": "Chave única por operação lógica. Repetindo a mesma chave com o mesmo payload, a API devolve a resposta original. Reutilizando a mesma chave com payload diferente, a API retorna conflito."
      },
      "PaymentLinkPublicToken": {
        "name": "public_token",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid"
        },
        "description": "Token público UUID do link de pagamento."
      }
    },
    "schemas": {
      "SuccessMessage": {
        "type": "object",
        "description": "Resposta simples de sucesso para operações sem payload detalhado.",
        "properties": {
          "success": {
            "type": "boolean",
            "description": "Indica se a operação foi concluída com sucesso.",
            "example": true
          },
          "message": {
            "type": "string",
            "description": "Mensagem curta para exibição ou log operacional.",
            "example": "Operação realizada com sucesso."
          }
        }
      },
      "ErrorMessage": {
        "type": "object",
        "description": "Resposta padrão de erro de validação, autenticação ou negócio.",
        "properties": {
          "success": {
            "type": "boolean",
            "description": "Sempre `false` em respostas de erro.",
            "example": false
          },
          "message": {
            "type": "string",
            "description": "Mensagem principal do erro retornado pela API.",
            "example": "Chave de API inválida."
          }
        }
      },
      "PaginatedMeta": {
        "type": "object",
        "description": "Metadados básicos de listagem paginada.",
        "properties": {
          "count": {
            "type": "integer",
            "description": "Quantidade total de registros encontrados antes da paginação.",
            "example": 1
          }
        }
      },
      "Customer": {
        "type": "object",
        "description": "Cliente vinculado à conta autenticada. Pode ser pessoa física ou jurídica.",
        "properties": {
          "reference_id": {
            "type": "string",
            "description": "Identificador público estável do cliente na Mepagg.",
            "example": "CUST_EXAMPLE_001"
          },
          "name": {
            "type": "string",
            "description": "Nome completo ou razão social do cliente.",
            "example": "Cliente Exemplo LTDA"
          },
          "document": {
            "type": "string",
            "description": "CPF ou CNPJ do cliente, retornado sem máscara.",
            "example": "12345678000195"
          },
          "email_primary": {
            "type": "string",
            "format": "email",
            "description": "E-mail principal usado nas comunicações da cobrança.",
            "example": "financeiro@clienteexemplo.com.br"
          },
          "email_secondary": {
            "type": "string",
            "format": "email",
            "nullable": true,
            "description": "E-mail secundário opcional para cobrança ou cópia.",
            "example": "cobranca@clienteexemplo.com.br"
          },
          "phone_number": {
            "type": "string",
            "description": "Telefone do cliente, preferencialmente com DDD e apenas números.",
            "example": "11987654321"
          },
          "street": {
            "type": "string",
            "description": "Logradouro do endereço do cliente.",
            "example": "Avenida Exemplo"
          },
          "neighborhood": {
            "type": "string",
            "description": "Bairro do endereço do cliente.",
            "example": "Centro"
          },
          "city": {
            "type": "string",
            "description": "Cidade do endereço do cliente.",
            "example": "Sao Paulo"
          },
          "state": {
            "type": "string",
            "description": "UF do endereço do cliente.",
            "example": "MG"
          },
          "zipcode": {
            "type": "string",
            "description": "CEP do endereço, retornado com apenas números quando aplicável.",
            "example": "35420000"
          },
          "number": {
            "type": "string",
            "description": "Número do endereço.",
            "example": "50"
          },
          "no_number": {
            "type": "boolean",
            "description": "Indica endereço sem número definido.",
            "example": false
          },
          "complement": {
            "type": "string",
            "nullable": true,
            "description": "Complemento do endereço.",
            "example": "Sala 2"
          },
          "observation": {
            "type": "string",
            "nullable": true,
            "description": "Observação interna do cadastro do cliente.",
            "example": "Cliente com comunicação por e-mail."
          },
          "is_defaulter": {
            "type": "boolean",
            "description": "Indica se o cliente está marcado internamente como inadimplente.",
            "example": false
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Data e hora de criação do cliente."
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "Data e hora da última atualização do cliente."
          }
        }
      },
      "CustomerInput": {
        "type": "object",
        "description": "Payload para criar ou atualizar cliente.\n\nCampos obrigatórios: `name`, `document`, `street`, `neighborhood`, `city`, `state`, `zipcode`.\n\nEnvie `document`, `phone_number` e `zipcode` apenas com números.",
        "required": [
          "name",
          "document",
          "street",
          "neighborhood",
          "city",
          "state",
          "zipcode"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Nome completo ou razão social do cliente.",
            "example": "Cliente Exemplo LTDA"
          },
          "document": {
            "type": "string",
            "description": "CPF ou CNPJ. Enviar apenas números."
          },
          "email_primary": {
            "type": "string",
            "format": "email",
            "description": "E-mail principal para envio de cobranças e notificações.",
            "example": "financeiro@clienteexemplo.com.br"
          },
          "email_secondary": {
            "type": "string",
            "format": "email",
            "description": "E-mail secundário opcional.",
            "example": "cobranca@clienteexemplo.com.br"
          },
          "phone_number": {
            "type": "string",
            "description": "Telefone com DDD. Enviar apenas números.",
            "example": "11987654321"
          },
          "street": {
            "type": "string",
            "description": "Logradouro do endereço.",
            "example": "Avenida Exemplo"
          },
          "neighborhood": {
            "type": "string",
            "description": "Bairro do endereço.",
            "example": "Centro"
          },
          "city": {
            "type": "string",
            "description": "Cidade do endereço.",
            "example": "Sao Paulo"
          },
          "state": {
            "type": "string",
            "minLength": 2,
            "maxLength": 2,
            "description": "UF do endereço com 2 caracteres.",
            "example": "MG"
          },
          "zipcode": {
            "type": "string",
            "description": "CEP do endereço. Enviar apenas números.",
            "example": "35420000"
          },
          "number": {
            "type": "string",
            "description": "Número do endereço.",
            "example": "50"
          },
          "no_number": {
            "type": "boolean",
            "default": false,
            "description": "Use `true` quando o endereço não tiver número."
          },
          "complement": {
            "type": "string",
            "description": "Complemento do endereço.",
            "example": "Sala 2"
          },
          "observation": {
            "type": "string",
            "description": "Observação interna do cadastro.",
            "example": "Contato financeiro prefere e-mail."
          }
        },
        "example": {
          "name": "Cliente Exemplo LTDA",
          "document": "12345678000195",
          "email_primary": "financeiro@clienteexemplo.com.br",
          "phone_number": "11987654321",
          "street": "Avenida Exemplo",
          "neighborhood": "Jardim Modelo",
          "number": "100",
          "zipcode": "01311000",
          "city": "Sao Paulo",
          "state": "SP"
        }
      },
      "InvoiceItemInput": {
        "type": "object",
        "description": "Item individual da cobrança. O total da fatura é calculado a partir da soma dos itens e ajustes aplicáveis.",
        "required": [
          "description",
          "price"
        ],
        "properties": {
          "description": {
            "type": "string",
            "description": "Descrição exibida para o pagador na cobrança.",
            "example": "Mensalidade da plataforma"
          },
          "qty": {
            "oneOf": [
              {
                "type": "number"
              },
              {
                "type": "string"
              }
            ],
            "description": "Quantidade do item. A API aceita `qty` ou `quantity`. A resposta retorna `qty` como campo canônico.",
            "example": 1
          },
          "quantity": {
            "oneOf": [
              {
                "type": "number"
              },
              {
                "type": "string"
              }
            ],
            "description": "Alias aceito para quantidade do item.",
            "example": 1
          },
          "price": {
            "oneOf": [
              {
                "type": "number"
              },
              {
                "type": "string"
              }
            ],
            "description": "Valor unitário do item em reais.",
            "example": "120.00"
          }
        }
      },
      "InvoiceInput": {
        "type": "object",
        "description": "Payload para criacao de fatura avulsa. A cobranca pode usar boleto, Pix ou ambos como formas de pagamento. Voce pode enviar um ou varios itens com descricoes e valores diferentes; o total da fatura e calculado pela soma dos itens, antes dos ajustes de juros, multa e desconto. O valor minimo total para criacao e R$ 5,00.",
        "required": [
          "due_date",
          "payment_methods",
          "items"
        ],
        "properties": {
          "customer_reference_id": {
            "type": "string",
            "description": "Referência pública do cliente que receberá a cobrança.",
            "example": "CUST_EXAMPLE_001"
          },
          "customer_id": {
            "type": "integer",
            "description": "ID interno do cliente. Use apenas quando necessário.",
            "example": 814
          },
          "due_date": {
            "type": "string",
            "format": "date",
            "description": "Data de vencimento no formato YYYY-MM-DD. Nao pode ser retroativa.",
            "example": "2026-06-30"
          },
          "payment_methods": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "boleto",
                "pix"
              ]
            },
            "example": [
              "boleto",
              "pix"
            ],
            "description": "Formas de pagamento aceitas na cobranca publica. Use `boleto`, `pix` ou ambos."
          },
          "items": {
            "type": "array",
            "description": "Itens que compoem a cobranca. Voce pode enviar um ou varios itens com descricoes e valores diferentes.",
            "items": {
              "$ref": "#/components/schemas/InvoiceItemInput"
            },
            "minItems": 1
          },
          "fees": {
            "oneOf": [
              {
                "type": "number"
              },
              {
                "type": "string"
              }
            ],
            "description": "Juros ou encargos aplicados à cobrança em valor monetário.",
            "example": "1.00"
          },
          "fines": {
            "oneOf": [
              {
                "type": "number"
              },
              {
                "type": "string"
              }
            ],
            "description": "Multa aplicada à cobrança em valor monetário.",
            "example": "2.00"
          },
          "discount_type": {
            "type": "string",
            "enum": [
              "PERCENTAGE",
              "FIXED_VALUE"
            ],
            "description": "Formato do desconto aplicado.",
            "example": "FIXED_VALUE"
          },
          "discount": {
            "oneOf": [
              {
                "type": "number"
              },
              {
                "type": "string"
              }
            ],
            "description": "Valor do desconto conforme `discount_type`.",
            "example": "10.00"
          },
          "inter_boleto_num_dias_agenda": {
            "type": "integer",
            "minimum": 1,
            "maximum": 60,
            "description": "Prazo de agenda do boleto quando aplicável.",
            "example": 3
          }
        },
        "example": {
          "customer_reference_id": "CUST_EXAMPLE_001",
          "due_date": "2026-06-30",
          "payment_methods": [
            "boleto",
            "pix"
          ],
          "fees": "1.50",
          "fines": "2.00",
          "discount_type": "FIXED_VALUE",
          "discount": "10.00",
          "inter_boleto_num_dias_agenda": 3,
          "items": [
            {
              "description": "Mensalidade da plataforma",
              "quantity": 1,
              "price": "120.00"
            },
            {
              "description": "Implantacao inicial",
              "qty": 2,
              "price": "35.00"
            }
          ]
        }
      },
      "Invoice": {
        "type": "object",
        "description": "Fatura avulsa da conta autenticada.",
        "properties": {
          "reference_id": {
            "type": "string",
            "description": "Identificador público estável da fatura.",
            "example": "GLZOX8K19Q40NVLJ6WJ2PRYD7EV653"
          },
          "status": {
            "type": "integer",
            "description": "Código numérico do status da fatura.",
            "example": 2
          },
          "status_code": {
            "type": "string",
            "description": "Código estável do status. Use para regras de sistema.",
            "example": "paid"
          },
          "status_label": {
            "type": "string",
            "description": "Texto amigável do status. Use para interface.",
            "example": "Paga"
          },
          "type": {
            "type": "integer",
            "description": "Código numérico do tipo de fatura.",
            "example": 3
          },
          "type_code": {
            "type": "string",
            "description": "Código estável do tipo. Use para regras de sistema.",
            "example": "oneoff"
          },
          "type_label": {
            "type": "string",
            "description": "Texto amigável do tipo. Use para interface.",
            "example": "Avulsa"
          },
          "type_display": {
            "type": "string",
            "description": "Alias atual de interface para o mesmo valor de `type_label`.",
            "example": "Avulsa"
          },
          "issued_via": {
            "type": "string",
            "description": "Emitida via. Valor original retornado no payload para indicar a origem da emissão da fatura. Campo somente de resposta e webhook, definido internamente pela Mepagg.",
            "example": "API"
          },
          "issued_via_code": {
            "type": "string",
            "description": "Código estável da origem de emissão. Use para regras de sistema.",
            "example": "api"
          },
          "issued_via_label": {
            "type": "string",
            "description": "Texto amigável da origem de emissão. Use para interface.",
            "example": "API"
          },
          "total": {
            "type": "string",
            "description": "Valor total faturado em reais.",
            "example": "5200.00"
          },
          "amount_paid": {
            "type": "string",
            "description": "Valor efetivamente pago em reais.",
            "example": "5200.00"
          },
          "paid_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Data e hora da compensação do pagamento quando houver.",
            "example": "2026-06-15T10:18:00-03:00"
          },
          "due_date": {
            "type": "string",
            "format": "date",
            "description": "Data de vencimento da fatura.",
            "example": "2026-06-15"
          },
          "public_url": {
            "type": "string",
            "format": "uri",
            "description": "Link público da cobrança para abrir o modelo Mepagg.",
            "example": "https://app.mepagg.com/fatura/GLZOX8K19Q40NVLJ6WJ2PRYD7EV653/"
          },
          "public_boleto_url": {
            "type": "string",
            "format": "uri",
            "description": "Link público do boleto para impressão direta quando aplicável.",
            "example": "https://app.mepagg.com/fatura/conta_publica_exemplo/GLZOX8K19Q40NVLJ6WJ2PRYD7EV653/boleto/"
          },
          "boleto": {
            "type": "object",
            "description": "Campos estruturados para impressão própria do boleto ou uso do modelo Mepagg.",
            "properties": {
              "public_url": {
                "type": "string",
                "format": "uri",
                "description": "Link público do boleto na Mepagg.",
                "example": "https://app.mepagg.com/fatura/conta_publica_exemplo/GLZOX8K19Q40NVLJ6WJ2PRYD7EV653/boleto/"
              },
              "pdf_url": {
                "type": "string",
                "format": "uri",
                "description": "PDF do boleto fornecido pelo provedor bancário quando disponível.",
                "example": "https://boleto.exemplo.test/arquivo.pdf"
              },
              "linha_digitavel": {
                "type": "string",
                "description": "Linha digitável do boleto.",
                "example": "07791000000000000000123456789012345678901234"
              },
              "codigo_barras": {
                "type": "string",
                "description": "Código de barras numérico do boleto.",
                "example": "07791234567890123456789012345678901234567890"
              },
              "nosso_numero": {
                "type": "string",
                "description": "Nosso número do boleto.",
                "example": "1234567890"
              }
            }
          },
          "pix": {
            "type": "object",
            "description": "Campos estruturados do Pix da cobrança quando disponíveis.",
            "properties": {
              "public_url": {
                "type": "string",
                "format": "uri",
                "description": "Link público da cobrança para exibir o Pix no modelo Mepagg.",
                "example": "https://app.mepagg.com/fatura/GLZOX8K19Q40NVLJ6WJ2PRYD7EV653/"
              },
              "txid": {
                "type": "string",
                "description": "Identificador da cobrança Pix.",
                "example": "pix_txid_exemplo_001"
              },
              "copia_e_cola": {
                "type": "string",
                "description": "Código Pix copia e cola quando disponível.",
                "example": "00020101021226850014br.gov.bcb.pix..."
              }
            }
          },
          "payment_methods": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "boleto",
                "pix"
              ]
            },
            "description": "Formas de pagamento habilitadas para a cobrança.",
            "example": [
              "boleto",
              "pix"
            ]
          }
        }
      },
      "Subscription": {
        "type": "object",
        "description": "Assinatura ou recorrência vinculada a um cliente.",
        "properties": {
          "id": {
            "type": "integer",
            "description": "Identificador interno da assinatura.",
            "example": 91
          },
          "reference_id": {
            "type": "string",
            "description": "Identificador público da assinatura.",
            "example": "SUB_A1B2C3"
          },
          "status": {
            "type": "string",
            "description": "Código interno do status da assinatura.",
            "example": "ACTIVE"
          },
          "status_code": {
            "type": "string",
            "description": "Código estável em minúsculas para uso em interface e integração.",
            "example": "active"
          },
          "status_label": {
            "type": "string",
            "description": "Texto amigável do status da assinatura.",
            "example": "Ativa"
          },
          "interval": {
            "type": "string",
            "description": "Periodicidade da recorrencia. Valores aceitos: WEEKLY (Semanal), BIWEEKLY (Quinzenal), MONTHLY (Mensal), BIMONTHLY (Bimestral), QUARTERLY (Trimestral), FOUR_MONTHS (Quadrimestral), SEMIANNUAL (Semestral), YEARLY (Anual).",
            "example": "MONTHLY",
            "enum": [
              "WEEKLY",
              "BIWEEKLY",
              "MONTHLY",
              "BIMONTHLY",
              "QUARTERLY",
              "FOUR_MONTHS",
              "SEMIANNUAL",
              "YEARLY"
            ],
            "x-enumDescriptions": [
              "Semanal",
              "Quinzenal",
              "Mensal",
              "Bimestral",
              "Trimestral",
              "Quadrimestral",
              "Semestral",
              "Anual"
            ]
          },
          "next_due_date": {
            "type": "string",
            "format": "date",
            "description": "Próximo vencimento previsto.",
            "example": "2026-07-10"
          },
          "last_due_date": {
            "type": "string",
            "format": "date",
            "nullable": true,
            "description": "Último vencimento previsto para a assinatura."
          },
          "date_billing_next": {
            "type": "string",
            "format": "date",
            "nullable": true,
            "description": "Próxima data de faturamento prevista."
          },
          "due_day_anchor": {
            "type": "integer",
            "nullable": true,
            "description": "Dia âncora de vencimento usado na recorrência.",
            "example": 10
          },
          "interval_label": {
            "type": "string",
            "description": "Texto amigável da periodicidade.",
            "example": "Mensal"
          },
          "cycles": {
            "type": "integer",
            "description": "Quantidade de ciclos configurados. `0` normalmente representa recorrência sem limite fixo.",
            "example": 12
          },
          "fees": {
            "type": "string",
            "description": "Juros aplicáveis à assinatura em valor monetário.",
            "example": "1.00"
          },
          "fines": {
            "type": "string",
            "description": "Multa aplicável à assinatura em valor monetário.",
            "example": "2.00"
          },
          "discount_type": {
            "type": "string",
            "nullable": true,
            "description": "Formato do desconto da assinatura.",
            "example": "FIXED_VALUE"
          },
          "discount": {
            "type": "string",
            "description": "Valor do desconto conforme `discount_type`.",
            "example": "10.00"
          },
          "has_overdue_invoices": {
            "type": "boolean",
            "description": "Indica se a assinatura possui faturas vencidas em aberto.",
            "example": false
          },
          "payment_methods": {
            "type": "array",
            "description": "Formas de pagamento vinculadas à assinatura.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer",
                  "description": "Identificador interno da forma de pagamento.",
                  "example": 1
                },
                "name": {
                  "type": "string",
                  "description": "Nome da forma de pagamento.",
                  "example": "Boleto"
                },
                "slug": {
                  "type": "string",
                  "description": "Slug estável da forma de pagamento.",
                  "example": "boleto"
                }
              }
            }
          },
          "customer": {
            "type": "object",
            "nullable": true,
            "description": "Cliente vinculado à assinatura.",
            "properties": {
              "id": {
                "type": "integer",
                "description": "Identificador interno do cliente.",
                "example": 814
              },
              "reference_id": {
                "type": "string",
                "description": "Referência pública do cliente.",
                "example": "CUST_EXAMPLE_001"
              },
              "name": {
                "type": "string",
                "description": "Nome ou razão social do cliente.",
                "example": "Cliente Exemplo LTDA"
              },
              "email_primary": {
                "type": "string",
                "format": "email",
                "description": "E-mail principal do cliente.",
                "example": "financeiro@clienteexemplo.com.br"
              }
            }
          },
          "items": {
            "type": "array",
            "description": "Itens recorrentes da assinatura. O total_amount corresponde a soma de todos os itens.",
            "items": {
              "$ref": "#/components/schemas/InvoiceItemInput"
            }
          },
          "total_amount": {
            "type": "string",
            "description": "Valor total calculado da recorrência.",
            "example": "120.00"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Data e hora de criação da assinatura."
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "Data e hora da última atualização da assinatura."
          }
        }
      },
      "SubscriptionInput": {
        "type": "object",
        "description": "Payload para criacao de assinatura. A assinatura pode conter um ou varios itens recorrentes, e o `total_amount` retornado e a soma de `qty x price` de todos os itens. Use `interval` para a periodicidade, `last_due_date` para o ultimo vencimento previsto e `status` para definir o estado operacional inicial quando aplicavel. O valor minimo total para criacao e R$ 5,00.",
        "required": [
          "interval",
          "last_due_date",
          "payment_methods",
          "items"
        ],
        "properties": {
          "customer_reference_id": {
            "type": "string",
            "example": "CUST_EXAMPLE_001"
          },
          "customer_id": {
            "type": "integer",
            "example": 814
          },
          "interval": {
            "type": "string",
            "example": "MONTHLY",
            "enum": [
              "WEEKLY",
              "BIWEEKLY",
              "MONTHLY",
              "BIMONTHLY",
              "QUARTERLY",
              "FOUR_MONTHS",
              "SEMIANNUAL",
              "YEARLY"
            ],
            "description": "Periodicidade da recorrencia. Valores aceitos: WEEKLY (Semanal), BIWEEKLY (Quinzenal), MONTHLY (Mensal), BIMONTHLY (Bimestral), QUARTERLY (Trimestral), FOUR_MONTHS (Quadrimestral), SEMIANNUAL (Semestral), YEARLY (Anual).",
            "x-enumDescriptions": [
              "Semanal",
              "Quinzenal",
              "Mensal",
              "Bimestral",
              "Trimestral",
              "Quadrimestral",
              "Semestral",
              "Anual"
            ]
          },
          "cycles": {
            "type": "integer",
            "example": 12,
            "description": "Quantidade de ciclos da assinatura. Aceita valores entre 0 e 120. Use 0 para recorrencia sem limite fixo."
          },
          "last_due_date": {
            "type": "string",
            "format": "date",
            "example": "2026-07-10",
            "description": "Ultimo vencimento previsto no formato YYYY-MM-DD. Nao pode ser anterior a data atual."
          },
          "status": {
            "type": "string",
            "example": "ACTIVE",
            "description": "Estado operacional inicial da assinatura. Valores publicos aceitos: ACTIVE ou SUSPENDED."
          },
          "payment_methods": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "boleto",
                "pix"
              ]
            },
            "description": "Obrigatorio na criacao publica. Use `boleto`, `pix` ou ambos."
          },
          "items": {
            "type": "array",
            "description": "Itens recorrentes da assinatura. Voce pode enviar um ou varios produtos ou servicos recorrentes.",
            "items": {
              "$ref": "#/components/schemas/InvoiceItemInput"
            },
            "minItems": 1
          },
          "fees": {
            "oneOf": [
              {
                "type": "number"
              },
              {
                "type": "string"
              }
            ],
            "example": "1.00"
          },
          "fines": {
            "oneOf": [
              {
                "type": "number"
              },
              {
                "type": "string"
              }
            ],
            "example": "2.00"
          },
          "discount_type": {
            "type": "string",
            "enum": [
              "PERCENTAGE",
              "FIXED_VALUE"
            ],
            "example": "FIXED_VALUE"
          },
          "discount": {
            "oneOf": [
              {
                "type": "number"
              },
              {
                "type": "string"
              }
            ],
            "example": "10.00"
          }
        },
        "example": {
          "customer_reference_id": "CUST_EXAMPLE_001",
          "interval": "MONTHLY",
          "cycles": 12,
          "last_due_date": "2027-06-10",
          "status": "ACTIVE",
          "payment_methods": [
            "boleto",
            "pix"
          ],
          "fees": "1.00",
          "fines": "2.00",
          "discount_type": "FIXED_VALUE",
          "discount": "10.00",
          "items": [
            {
              "description": "Licenca principal",
              "qty": 1,
              "price": "49.90"
            },
            {
              "description": "Usuario adicional",
              "quantity": 2,
              "price": "15.00"
            }
          ]
        }
      },
      "Carne": {
        "type": "object",
        "description": "Carnê com múltiplas parcelas vinculado a um cliente.",
        "properties": {
          "id": {
            "type": "integer",
            "description": "Identificador interno do carnê.",
            "example": 17
          },
          "reference_id": {
            "type": "string",
            "description": "Identificador público do carnê.",
            "example": "CAR_01JABCXYZ"
          },
          "description": {
            "type": "string",
            "description": "Descrição principal do carnê.",
            "example": "Parcelamento da adesão anual"
          },
          "installments_count": {
            "type": "integer",
            "description": "Quantidade total de parcelas.",
            "example": 6
          },
          "total_amount": {
            "type": "string",
            "description": "Valor total do carnê em reais.",
            "example": "600.00"
          },
          "first_due_date": {
            "type": "string",
            "format": "date",
            "nullable": true,
            "description": "Primeiro vencimento previsto do carnê."
          },
          "public_url": {
            "type": "string",
            "format": "uri",
            "description": "Link público do carnê na Mepagg com todas as parcelas.",
            "example": "https://app.mepagg.com/carne/CAR_01JABCXYZ/"
          },
          "customer": {
            "type": "object",
            "nullable": true,
            "description": "Cliente vinculado ao carnê.",
            "properties": {
              "id": {
                "type": "integer",
                "description": "Identificador interno do cliente.",
                "example": 814
              },
              "reference_id": {
                "type": "string",
                "description": "Referência pública do cliente.",
                "example": "CUST_EXAMPLE_001"
              },
              "name": {
                "type": "string",
                "description": "Nome ou razão social do cliente.",
                "example": "Cliente Exemplo LTDA"
              },
              "email_primary": {
                "type": "string",
                "format": "email",
                "description": "E-mail principal do cliente.",
                "example": "financeiro@clienteexemplo.com.br"
              }
            }
          },
          "summary": {
            "type": "object",
            "description": "Resumo consolidado das parcelas do carnê.",
            "properties": {
              "status_code": {
                "type": "string",
                "description": "Código estável do estado consolidado do carnê.",
                "example": "open"
              },
              "total_installments": {
                "type": "integer",
                "description": "Quantidade total de parcelas.",
                "example": 6
              },
              "paid_installments": {
                "type": "integer",
                "description": "Quantidade de parcelas já pagas.",
                "example": 2
              },
              "cancelled_installments": {
                "type": "integer",
                "description": "Quantidade de parcelas canceladas.",
                "example": 1
              },
              "overdue_installments": {
                "type": "integer",
                "description": "Quantidade de parcelas vencidas ou expiradas.",
                "example": 1
              },
              "processing_installments": {
                "type": "integer",
                "description": "Quantidade de parcelas ainda em processamento operacional.",
                "example": 1
              },
              "to_expire_installments": {
                "type": "integer",
                "description": "Quantidade de parcelas em aberto dentro do prazo.",
                "example": 2
              },
              "open_installments": {
                "type": "integer",
                "description": "Quantidade total de parcelas ainda não quitadas nem canceladas.",
                "example": 3
              },
              "status_label": {
                "type": "string",
                "description": "Resumo textual do estado do carnê.",
                "example": "Em aberto"
              }
            }
          },
          "invoices": {
            "type": "array",
            "description": "Parcelas do carnê representadas como faturas.",
            "items": {
              "$ref": "#/components/schemas/Invoice"
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Data e hora de criação do carnê."
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "Data e hora da última atualização do carnê."
          }
        }
      },
      "CarneInput": {
        "type": "object",
        "description": "Payload para criacao de carne. Voce pode criar o carne com `description` e `total_amount`, ou enviar `items` detalhados. Quando `items` e enviado, o carne aceita apenas um item, a API calcula o valor total a partir dele e distribui esse total entre as parcelas, mantendo cada parcela disponivel em `carne.invoices` com sua propria estrutura de fatura. O valor minimo total para criacao e R$ 5,00.",
        "required": [
          "installments",
          "due_date",
          "payment_methods"
        ],
        "properties": {
          "customer_reference_id": {
            "type": "string",
            "example": "CUST_EXAMPLE_001"
          },
          "customer_id": {
            "type": "integer",
            "example": 814
          },
          "description": {
            "type": "string",
            "description": "Descrição geral do carnê. Se `items` for enviado, serve como resumo.",
            "example": "Carnê de implantação e licença"
          },
          "items": {
            "type": "array",
            "description": "Produtos ou servicos que compoem o valor total do carne. Quando enviado, aceita apenas um item.",
            "items": {
              "$ref": "#/components/schemas/InvoiceItemInput"
            },
            "minItems": 1,
            "maxItems": 1
          },
          "total_amount": {
            "oneOf": [
              {
                "type": "number"
              },
              {
                "type": "string"
              }
            ],
            "description": "Obrigatório quando `items` não for enviado. Se informado junto com `items`, deve ser igual à soma dos itens.",
            "example": "120.00"
          },
          "installments": {
            "type": "integer",
            "minimum": 2,
            "maximum": 60,
            "example": 3
          },
          "due_date": {
            "type": "string",
            "format": "date",
            "example": "2026-07-10",
            "description": "Primeiro vencimento no formato YYYY-MM-DD. Nao pode ser retroativo."
          },
          "payment_methods": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "boleto",
                "pix"
              ]
            },
            "description": "Obrigatorio na criacao publica do carne. Use `boleto`, `pix` ou ambos."
          },
          "fees": {
            "oneOf": [
              {
                "type": "number"
              },
              {
                "type": "string"
              }
            ],
            "example": "0.00"
          },
          "fines": {
            "oneOf": [
              {
                "type": "number"
              },
              {
                "type": "string"
              }
            ],
            "example": "0.00"
          },
          "discount_type": {
            "type": "string",
            "enum": [
              "PERCENTAGE",
              "FIXED_VALUE"
            ],
            "example": "PERCENTAGE"
          },
          "discount": {
            "oneOf": [
              {
                "type": "number"
              },
              {
                "type": "string"
              }
            ],
            "example": "0.00"
          }
        },
        "example": {
          "customer_reference_id": "CUST_EXAMPLE_001",
          "description": "Carne de implantacao e licenca",
          "installments": 3,
          "due_date": "2026-07-10",
          "payment_methods": [
            "boleto",
            "pix"
          ],
          "fees": "1.00",
          "fines": "2.00",
          "discount_type": "PERCENTAGE",
          "discount": "5.00",
          "items": [
            {
              "description": "Implantacao inicial",
              "qty": 1,
              "price": "90.00"
            },
            {
              "description": "Licenca complementar",
              "quantity": 2,
              "price": "15.00"
            }
          ]
        }
      },
      "Transfer": {
        "type": "object",
        "description": "Transferência ou saque solicitado pela conta autenticada.",
        "properties": {
          "reference_id": {
            "type": "string",
            "description": "Identificador público da transferência.",
            "example": "TRF_XYZ987"
          },
          "status_code": {
            "type": "string",
            "description": "Código estável do status da transferência.",
            "example": "completed"
          },
          "status_label": {
            "type": "string",
            "description": "Texto amigável do status da transferência.",
            "example": "Concluída"
          },
          "amount": {
            "type": "string",
            "description": "Valor solicitado em reais.",
            "example": "100.00"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Data e hora da criação da solicitação."
          }
        }
      },
      "Account": {
        "type": "object",
        "description": "Dados cadastrais da conta autenticada disponíveis em modo consulta.",
        "properties": {
          "company_name": {
            "type": "string",
            "description": "Razão social da conta.",
            "example": "Empresa Exemplo de Cobrancas LTDA"
          },
          "document": {
            "type": "string",
            "description": "CNPJ da conta, retornado sem máscara.",
            "example": "12345678000199"
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "E-mail cadastrado da conta.",
            "example": "financeiro@empresaexemplo.com.br"
          },
          "city": {
            "type": "string",
            "description": "Cidade do cadastro da conta.",
            "example": "Belo Horizonte"
          },
          "state": {
            "type": "string",
            "description": "UF do cadastro da conta.",
            "example": "MG"
          }
        }
      },
      "WebhookEndpointInput": {
        "type": "object",
        "description": "Configuracao do endpoint que recebera eventos transacionais da Mepagg. Cadastre uma URL HTTPS publica do sistema da conta, guarde o `signing_secret` retornado na criacao e valide a assinatura HMAC SHA-256 no recebimento de cada evento.",
        "required": [
          "name",
          "target_url",
          "subscribed_events"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Nome interno do endpoint para identificação operacional.",
            "example": "ERP principal"
          },
          "target_url": {
            "type": "string",
            "format": "uri",
            "description": "URL publica HTTPS do endpoint que recebera os eventos. HTTP so e aceito para localhost em ambiente controlado.",
            "example": "https://erp.exemplo.com/webhooks/mepagg"
          },
          "subscribed_events": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Lista de eventos publicos assinados. Voce tambem pode usar `*` para receber todos os eventos suportados.",
            "example": [
              "customer.created",
              "invoice.paid",
              "invoice.cancelled",
              "payment_link.status_changed",
              "transfer.completed",
              "sms.credits_purchased"
            ]
          },
          "is_enabled": {
            "type": "boolean",
            "default": true,
            "description": "Define se o endpoint começa ativo para entregas."
          }
        },
        "example": {
          "name": "ERP principal",
          "target_url": "https://erp.exemplo.com/webhooks/mepagg",
          "subscribed_events": [
            "customer.created",
            "customer.updated",
            "customer.deleted",
            "invoice.created",
            "invoice.updated",
            "invoice.paid",
            "invoice.cancelled",
            "invoice.refunded",
            "subscription.created",
            "subscription.updated",
            "subscription.renewed",
            "plan.deleted",
            "plan.updated",
            "plan.created",
            "payment_link.status_changed",
            "carne.cancelled",
            "transfer.created",
            "transfer.completed",
            "sms.credits_purchased",
            "sms.sent",
            "email.sent"
          ],
          "is_enabled": true
        }
      },
      "WebhookEndpoint": {
        "type": "object",
        "description": "Endpoint de webhook cadastrado na conta.",
        "properties": {
          "id": {
            "type": "integer",
            "description": "Identificador interno do endpoint.",
            "example": 12
          },
          "name": {
            "type": "string",
            "description": "Nome amigável do endpoint quando configurado.",
            "example": "ERP principal"
          },
          "target_url": {
            "type": "string",
            "format": "uri",
            "description": "URL publica HTTPS do endpoint que recebera os eventos. HTTP so e aceito para localhost em ambiente controlado.",
            "example": "https://erp.exemplo.com/webhooks/mepagg"
          },
          "subscribed_events": {
            "type": "array",
            "description": "Lista de eventos publicos assinados. Voce tambem pode usar `*` para receber todos os eventos suportados.",
            "items": {
              "type": "string"
            }
          },
          "is_enabled": {
            "type": "boolean",
            "description": "Indica se o endpoint está habilitado para novas entregas.",
            "example": true
          },
          "masked_signing_secret": {
            "type": "string",
            "description": "Versão mascarada do segredo atual para conferência visual.",
            "example": "whsec_************************abcd"
          },
          "signing_secret": {
            "type": "string",
            "description": "Segredo completo retornado apenas na criação ou rotação do endpoint.",
            "example": "whsec_xxxxxxxxxxxxxxxxx"
          },
          "last_delivery_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Data e hora da última tentativa de entrega."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Data e hora de criação do endpoint."
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Data e hora da última atualização do endpoint."
          }
        }
      },
      "WebhookInvoicePaidEvent": {
        "type": "object",
        "description": "Payload real enviado quando uma fatura é paga.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Identificador único da entrega lógica do evento.",
            "example": "wh_evt_01JABCXYZ"
          },
          "type": {
            "type": "string",
            "description": "Nome do evento disparado.",
            "example": "invoice.paid"
          },
          "occurred_at": {
            "type": "string",
            "format": "date-time",
            "description": "Momento em que a Mepagg criou o evento.",
            "example": "2026-06-15T10:19:12-03:00"
          },
          "account": {
            "type": "object",
            "properties": {
              "token": {
                "type": "string",
                "example": "ACC_EXAMPLE_001"
              },
              "name": {
                "type": "string",
                "example": "Empresa Exemplo de Cobrancas LTDA"
              },
              "document": {
                "type": "string",
                "example": "12345678000199"
              }
            }
          },
          "data": {
            "type": "object",
            "properties": {
              "invoice_reference_id": {
                "type": "string",
                "example": "GLZOX8K19Q40NVLJ6WJ2PRYD7EV653"
              },
              "amount_paid": {
                "type": "string",
                "example": "5200.00"
              },
              "paid_at": {
                "type": "string",
                "format": "date-time",
                "example": "2026-06-15T10:18:00-03:00"
              },
              "paid_source": {
                "type": "string",
                "example": "pix"
              },
              "invoice": {
                "$ref": "#/components/schemas/Invoice"
              }
            }
          }
        }
      },
      "WebhookTransferCompletedEvent": {
        "type": "object",
        "description": "Payload real enviado quando uma transferência é concluída.",
        "properties": {
          "id": {
            "type": "string",
            "example": "wh_evt_01JTRFXYZ"
          },
          "type": {
            "type": "string",
            "example": "transfer.completed"
          },
          "occurred_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-06-17T14:25:10-03:00"
          },
          "account": {
            "type": "object",
            "properties": {
              "token": {
                "type": "string",
                "example": "ACC_EXAMPLE_001"
              },
              "name": {
                "type": "string",
                "example": "Empresa Exemplo de Cobrancas LTDA"
              },
              "document": {
                "type": "string",
                "example": "12345678000199"
              }
            }
          },
          "data": {
            "type": "object",
            "properties": {
              "transfer": {
                "type": "object",
                "properties": {
                  "reference_id": {
                    "type": "string",
                    "example": "TRF_EXAMPLE_001"
                  },
                  "status": {
                    "type": "string",
                    "example": "APPROVED"
                  },
                  "status_label": {
                    "type": "string",
                    "example": "Aprovada"
                  },
                  "requested_amount": {
                    "type": "string",
                    "example": "100.00"
                  },
                  "tariff_amount": {
                    "type": "string",
                    "example": "0.00"
                  },
                  "approved_at": {
                    "type": "string",
                    "format": "date-time",
                    "example": "2026-06-17T14:25:10-03:00"
                  },
                  "processed_at": {
                    "type": "string",
                    "format": "date-time",
                    "example": "2026-06-17T14:25:10-03:00"
                  },
                  "pix_key_type": {
                    "type": "string",
                    "example": "EMAIL"
                  },
                  "pix_key_value": {
                    "type": "string",
                    "example": "financeiro@clienteexemplo.com.br"
                  }
                }
              }
            }
          }
        }
      },
      "WebhookSmsCreditsPurchasedEvent": {
        "type": "object",
        "description": "Payload real enviado quando a conta compra um pacote de créditos SMS.",
        "properties": {
          "id": {
            "type": "string",
            "example": "wh_evt_01JSMSXYZ"
          },
          "type": {
            "type": "string",
            "example": "sms.credits_purchased"
          },
          "occurred_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-06-17T16:00:00-03:00"
          },
          "account": {
            "type": "object",
            "properties": {
              "token": {
                "type": "string",
                "example": "ACC_EXAMPLE_001"
              },
              "name": {
                "type": "string",
                "example": "Empresa Exemplo de Cobrancas LTDA"
              },
              "document": {
                "type": "string",
                "example": "12345678000199"
              }
            }
          },
          "data": {
            "type": "object",
            "properties": {
              "sms_credit_purchase": {
                "type": "object",
                "properties": {
                  "package_code": {
                    "type": "string",
                    "example": "500"
                  },
                  "credits_added": {
                    "type": "integer",
                    "example": 500
                  },
                  "purchase_method": {
                    "type": "string",
                    "example": "mepagg_balance"
                  },
                  "package_amount": {
                    "type": "string",
                    "example": "75.00"
                  },
                  "sms_credits_balance": {
                    "type": "integer",
                    "example": 1500
                  },
                  "source": {
                    "type": "string",
                    "example": "api"
                  }
                }
              }
            }
          }
        }
      },
      "WebhookCustomerEvent": {
        "type": "object",
        "description": "Payload enviado quando um cliente é criado, atualizado ou removido na conta.",
        "properties": {
          "id": {
            "type": "string",
            "example": "wh_evt_01JCUSTXYZ"
          },
          "type": {
            "type": "string",
            "example": "customer.updated"
          },
          "occurred_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-06-17T18:42:11-03:00"
          },
          "account": {
            "type": "object",
            "properties": {
              "token": {
                "type": "string",
                "example": "ACC_EXAMPLE_001"
              },
              "name": {
                "type": "string",
                "example": "Empresa Exemplo de Cobrancas LTDA"
              },
              "document": {
                "type": "string",
                "example": "12345678000199"
              }
            }
          },
          "data": {
            "type": "object",
            "properties": {
              "customer_id": {
                "type": "integer",
                "example": 248
              },
              "customer_reference_id": {
                "type": "string",
                "example": "CST_EXAMPLE_248"
              },
              "customer": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "integer",
                    "example": 248
                  },
                  "reference_id": {
                    "type": "string",
                    "example": "CST_EXAMPLE_248"
                  },
                  "name": {
                    "type": "string",
                    "example": "Cliente Exemplo LTDA"
                  },
                  "document": {
                    "type": "string",
                    "example": "12345678000155"
                  },
                  "email_primary": {
                    "type": "string",
                    "example": "financeiro@clienteexemplo.com.br"
                  },
                  "email_secondary": {
                    "type": "string",
                    "example": "cobranca@clienteexemplo.com.br"
                  },
                  "phone_number": {
                    "type": "string",
                    "example": "3133334444"
                  },
                  "phone": {
                    "type": "string",
                    "example": "(31) 3333-4444"
                  },
                  "state": {
                    "type": "string",
                    "example": "MG"
                  },
                  "city": {
                    "type": "string",
                    "example": "Mariana"
                  },
                  "street": {
                    "type": "string",
                    "example": "Rua Direita"
                  },
                  "neighborhood": {
                    "type": "string",
                    "example": "Centro"
                  },
                  "number": {
                    "type": "string",
                    "example": "120"
                  },
                  "no_number": {
                    "type": "boolean",
                    "example": false
                  },
                  "complement": {
                    "type": "string",
                    "example": "Sala 03"
                  },
                  "zipcode": {
                    "type": "string",
                    "example": "35420000"
                  },
                  "formatted_address": {
                    "type": "string",
                    "example": "Rua Direita, 120, Centro, Mariana - MG, CEP 35420-000"
                  },
                  "observation": {
                    "type": "string",
                    "example": ""
                  },
                  "is_blocked": {
                    "type": "boolean",
                    "example": false
                  },
                  "blocked_reason": {
                    "type": "string",
                    "example": ""
                  },
                  "is_defaulter": {
                    "type": "boolean",
                    "example": false
                  },
                  "is_deleted": {
                    "type": "boolean",
                    "example": false
                  },
                  "created_at": {
                    "type": "string",
                    "format": "date-time",
                    "example": "2026-06-10T09:00:00-03:00"
                  },
                  "updated_at": {
                    "type": "string",
                    "format": "date-time",
                    "example": "2026-06-17T18:42:10-03:00"
                  },
                  "deleted_at": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true,
                    "example": null
                  }
                }
              }
            }
          }
        }
      },
      "WebhookCarneCancelledEvent": {
        "type": "object",
        "description": "Payload enviado quando um carnê é cancelado. Esse evento complementa os `invoice.cancelled` enviados para cada parcela afetada.",
        "properties": {
          "id": {
            "type": "string",
            "example": "wh_evt_01JCARXYZ"
          },
          "type": {
            "type": "string",
            "example": "carne.cancelled"
          },
          "occurred_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-06-17T19:15:00-03:00"
          },
          "account": {
            "type": "object",
            "properties": {
              "token": {
                "type": "string",
                "example": "ACC_EXAMPLE_001"
              },
              "name": {
                "type": "string",
                "example": "Empresa Exemplo de Cobrancas LTDA"
              },
              "document": {
                "type": "string",
                "example": "12345678000199"
              }
            }
          },
          "data": {
            "type": "object",
            "properties": {
              "carne_reference_id": {
                "type": "string",
                "example": "CAR_01JABCXYZ"
              },
              "cancelled_reason": {
                "type": "string",
                "example": "Solicitado pelo cliente."
              },
              "cancelled_installments": {
                "type": "integer",
                "example": 3
              },
              "carne": {
                "$ref": "#/components/schemas/Carne"
              }
            }
          }
        }
      },
      "CustomerEnvelope": {
        "type": "object",
        "description": "Resposta com um único cliente.",
        "properties": {
          "customer": {
            "$ref": "#/components/schemas/Customer"
          }
        }
      },
      "CustomerListResponse": {
        "type": "object",
        "description": "Lista paginada de clientes.",
        "properties": {
          "count": {
            "type": "integer",
            "description": "Quantidade total de registros encontrados antes da paginação.",
            "example": 1
          },
          "results": {
            "type": "array",
            "description": "Coleção de clientes retornados na página atual.",
            "items": {
              "$ref": "#/components/schemas/Customer"
            }
          }
        }
      },
      "InvoiceEnvelope": {
        "type": "object",
        "description": "Resposta com uma única fatura.",
        "properties": {
          "invoice": {
            "$ref": "#/components/schemas/Invoice"
          }
        }
      },
      "InvoiceCreateResponse": {
        "type": "object",
        "description": "Resposta de criação de fatura.",
        "properties": {
          "success": {
            "type": "boolean",
            "description": "Indica se a criação da fatura foi concluída com sucesso.",
            "example": true
          },
          "invoice": {
            "$ref": "#/components/schemas/Invoice"
          }
        }
      },
      "InvoiceListResponse": {
        "type": "object",
        "description": "Lista paginada de faturas.",
        "properties": {
          "count": {
            "type": "integer",
            "description": "Quantidade total de registros encontrados antes da paginação.",
            "example": 1
          },
          "results": {
            "type": "array",
            "description": "Coleção de faturas retornadas na página atual.",
            "items": {
              "$ref": "#/components/schemas/Invoice"
            }
          }
        }
      },
      "SubscriptionEnvelope": {
        "type": "object",
        "description": "Resposta com uma única assinatura.",
        "properties": {
          "subscription": {
            "$ref": "#/components/schemas/Subscription"
          }
        }
      },
      "SubscriptionListResponse": {
        "type": "object",
        "description": "Lista paginada de assinaturas.",
        "properties": {
          "count": {
            "type": "integer",
            "description": "Quantidade total de registros encontrados antes da paginação.",
            "example": 1
          },
          "results": {
            "type": "array",
            "description": "Coleção de assinaturas retornadas na página atual.",
            "items": {
              "$ref": "#/components/schemas/Subscription"
            }
          }
        }
      },
      "CarneEnvelope": {
        "type": "object",
        "description": "Resposta com um único carnê.",
        "properties": {
          "carne": {
            "$ref": "#/components/schemas/Carne"
          }
        }
      },
      "CarneListResponse": {
        "type": "object",
        "description": "Lista paginada de carnês.",
        "properties": {
          "count": {
            "type": "integer",
            "description": "Quantidade total de registros encontrados antes da paginação.",
            "example": 1
          },
          "results": {
            "type": "array",
            "description": "Coleção de carnês retornados na página atual.",
            "items": {
              "$ref": "#/components/schemas/Carne"
            }
          }
        }
      },
      "TransferEnvelope": {
        "type": "object",
        "description": "Resposta com uma única transferência.",
        "properties": {
          "transfer": {
            "$ref": "#/components/schemas/Transfer"
          }
        }
      },
      "PixKey": {
        "type": "object",
        "description": "Chave PIX aprovada para transferências.",
        "properties": {
          "id": {
            "type": "integer",
            "description": "Identificador interno da chave PIX.",
            "example": 4
          },
          "key_type": {
            "type": "string",
            "description": "Código interno do tipo da chave.",
            "example": "EMAIL"
          },
          "key_type_label": {
            "type": "string",
            "description": "Texto amigável do tipo da chave.",
            "example": "E-mail"
          },
          "key": {
            "type": "string",
            "description": "Valor bruto da chave PIX.",
            "example": "financeiro@clienteexemplo.com.br"
          },
          "formatted_key": {
            "type": "string",
            "description": "Valor formatado da chave PIX para interface.",
            "example": "financeiro@clienteexemplo.com.br"
          },
          "status": {
            "type": "string",
            "description": "Código interno do status da chave PIX.",
            "example": "APPROVED"
          },
          "status_label": {
            "type": "string",
            "description": "Texto amigável do status da chave PIX.",
            "example": "Aprovada"
          }
        }
      },
      "TransferListResponse": {
        "type": "object",
        "description": "Lista paginada de transferências.",
        "properties": {
          "count": {
            "type": "integer",
            "description": "Quantidade total de registros encontrados antes da paginação.",
            "example": 1
          },
          "results": {
            "type": "array",
            "description": "Coleção de transferências retornadas na página atual.",
            "items": {
              "$ref": "#/components/schemas/Transfer"
            }
          }
        }
      },
      "TransferPricing": {
        "type": "object",
        "description": "Regras atuais de tarifação da transferência.",
        "properties": {
          "tariff_amount": {
            "type": "string",
            "description": "Valor da tarifa unitária em reais.",
            "example": "3.50"
          },
          "free_per_day": {
            "type": "integer",
            "description": "Quantidade de transferências gratuitas por dia.",
            "example": 1
          },
          "used_free_today": {
            "type": "integer",
            "description": "Quantidade já utilizada no dia.",
            "example": 0
          },
          "has_free_slot": {
            "type": "boolean",
            "description": "Indica se ainda há gratuidade disponível no dia.",
            "example": true
          },
          "is_always_free": {
            "type": "boolean",
            "description": "Indica se a conta opera sem tarifa de transferência.",
            "example": false
          }
        }
      },
      "TransferMetaResponse": {
        "type": "object",
        "description": "Metadados operacionais de transferência para a conta autenticada.",
        "properties": {
          "success": {
            "type": "boolean",
            "description": "Indica se a consulta foi concluída com sucesso.",
            "example": true
          },
          "available_balance": {
            "type": "string",
            "description": "Saldo disponível para transferência.",
            "example": "8200.00"
          },
          "approved_pix_keys": {
            "type": "array",
            "description": "Chaves PIX aprovadas para uso.",
            "items": {
              "$ref": "#/components/schemas/PixKey"
            }
          },
          "transfer_pricing": {
            "$ref": "#/components/schemas/TransferPricing"
          },
          "can_request_transfer": {
            "type": "boolean",
            "description": "Indica se a conta pode solicitar transferência neste momento.",
            "example": true
          },
          "transfer_request_block_reason": {
            "type": "string",
            "nullable": true,
            "description": "Motivo do bloqueio operacional quando a solicitação não é permitida."
          }
        }
      },
      "PixKeyListResponse": {
        "type": "object",
        "description": "Lista de chaves PIX aprovadas para a conta.",
        "properties": {
          "success": {
            "type": "boolean",
            "description": "Indica se a consulta foi concluída com sucesso.",
            "example": true
          },
          "count": {
            "type": "integer",
            "description": "Quantidade de chaves retornadas.",
            "example": 2
          },
          "results": {
            "type": "array",
            "description": "Chaves PIX aprovadas.",
            "items": {
              "$ref": "#/components/schemas/PixKey"
            }
          }
        }
      },
      "TransferReceipt": {
        "type": "object",
        "description": "Resumo estruturado do recibo de transferência.",
        "properties": {
          "reference_id": {
            "type": "string",
            "description": "Referência pública da transferência.",
            "example": "TRF_XYZ987"
          },
          "status": {
            "type": "string",
            "description": "Código interno do status da transferência.",
            "example": "APPROVED"
          },
          "status_label": {
            "type": "string",
            "description": "Texto amigável do status da transferência.",
            "example": "Aprovada"
          },
          "requested_amount": {
            "type": "string",
            "description": "Valor solicitado em reais.",
            "example": "100.00"
          },
          "tariff_amount": {
            "type": "string",
            "description": "Tarifa aplicada em reais.",
            "example": "3.50"
          },
          "total_debited": {
            "type": "string",
            "description": "Valor total debitado da conta.",
            "example": "103.50"
          },
          "pix_key_type": {
            "type": "string",
            "description": "Tipo da chave PIX usada.",
            "example": "EMAIL"
          },
          "pix_key_value": {
            "type": "string",
            "description": "Valor da chave PIX usada.",
            "example": "financeiro@clienteexemplo.com.br"
          },
          "approved_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Data e hora da aprovação da transferência."
          },
          "processed_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Data e hora do processamento final da transferência."
          },
          "statement_entry": {
            "type": "object",
            "nullable": true,
            "description": "Lançamento do extrato associado ao recibo.",
            "properties": {
              "id": {
                "type": "integer",
                "description": "Identificador do lançamento.",
                "example": 901
              },
              "description": {
                "type": "string",
                "description": "Descrição do lançamento.",
                "example": "Transferência enviada"
              },
              "amount": {
                "type": "string",
                "description": "Valor do lançamento.",
                "example": "100.00"
              },
              "occurred_at": {
                "type": "string",
                "format": "date-time",
                "nullable": true,
                "description": "Momento do lançamento."
              }
            }
          }
        }
      },
      "TransferReceiptResponse": {
        "type": "object",
        "description": "Resposta de consulta do recibo de transferência.",
        "properties": {
          "success": {
            "type": "boolean",
            "description": "Indica se a consulta foi concluída com sucesso.",
            "example": true
          },
          "receipt": {
            "$ref": "#/components/schemas/TransferReceipt"
          },
          "html": {
            "type": "string",
            "description": "Versão HTML do recibo para exibição direta.",
            "example": "<html>...</html>"
          },
          "default_email": {
            "type": "string",
            "description": "E-mail padrão sugerido para envio do recibo.",
            "example": "financeiro@empresaexemplo.com.br"
          }
        }
      },
      "AccountEnvelope": {
        "type": "object",
        "description": "Resposta com os dados cadastrais da conta autenticada.",
        "properties": {
          "account": {
            "$ref": "#/components/schemas/Account"
          }
        }
      },
      "StatementEntry": {
        "type": "object",
        "description": "Lançamento individual do extrato.",
        "properties": {
          "id": {
            "type": "integer",
            "description": "Identificador interno do lançamento.",
            "example": 5012
          },
          "entry_type": {
            "type": "string",
            "description": "Tipo do lançamento no extrato.",
            "example": "CREDIT"
          },
          "entry_type_label": {
            "type": "string",
            "description": "Texto amigável do tipo do lançamento.",
            "example": "Crédito"
          },
          "event_type": {
            "type": "string",
            "description": "Categoria do evento que originou o lançamento.",
            "example": "INVOICE_PAYMENT"
          },
          "event_type_label": {
            "type": "string",
            "description": "Texto amigável da categoria do evento.",
            "example": "Pagamento de fatura"
          },
          "description": {
            "type": "string",
            "description": "Descrição operacional do lançamento.",
            "example": "Recebimento da fatura GLZOX8K19Q40NVLJ6WJ2PRYD7EV653"
          },
          "amount": {
            "type": "string",
            "description": "Valor absoluto do lançamento em reais.",
            "example": "5200.00"
          },
          "signed_amount": {
            "type": "string",
            "description": "Valor do lançamento com sinal para leitura rápida.",
            "example": "+5200.00"
          },
          "payment_source": {
            "type": "string",
            "nullable": true,
            "description": "Origem do pagamento ou recebimento quando aplicável.",
            "example": "pix"
          },
          "occurred_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Momento em que o lançamento ocorreu."
          },
          "invoice": {
            "type": "object",
            "nullable": true,
            "description": "Resumo da fatura vinculada ao lançamento quando existir.",
            "properties": {
              "id": {
                "type": "integer",
                "description": "Identificador interno da fatura.",
                "example": 1203
              },
              "reference_id": {
                "type": "string",
                "description": "Referência pública da fatura.",
                "example": "GLZOX8K19Q40NVLJ6WJ2PRYD7EV653"
              },
              "customer_name": {
                "type": "string",
                "description": "Nome do cliente da fatura.",
                "example": "Cliente Exemplo LTDA"
              }
            }
          },
          "transfer": {
            "type": "object",
            "nullable": true,
            "description": "Resumo da transferência vinculada ao lançamento quando existir.",
            "properties": {
              "id": {
                "type": "integer",
                "description": "Identificador interno da transferência.",
                "example": 77
              },
              "reference_id": {
                "type": "string",
                "description": "Referência pública da transferência.",
                "example": "TRF_XYZ987"
              },
              "pix_key_value": {
                "type": "string",
                "nullable": true,
                "description": "Chave PIX associada quando aplicável.",
                "example": "financeiro@clienteexemplo.com.br"
              }
            }
          },
          "tariff": {
            "type": "object",
            "nullable": true,
            "description": "Resumo da tarifa vinculada ao lançamento quando existir.",
            "properties": {
              "id": {
                "type": "integer",
                "description": "Identificador interno da tarifa.",
                "example": 9
              },
              "name": {
                "type": "string",
                "description": "Nome amigável da tarifa.",
                "example": "Tarifa de transferência"
              }
            }
          }
        }
      },
      "StatementSummary": {
        "type": "object",
        "description": "Resumo financeiro consolidado do extrato.",
        "properties": {
          "total_credits": {
            "type": "string",
            "description": "Total de créditos do período em reais.",
            "example": "10000.00"
          },
          "total_debits": {
            "type": "string",
            "description": "Total de débitos do período em reais.",
            "example": "1800.00"
          },
          "total_tariffs": {
            "type": "string",
            "description": "Total de tarifas debitadas no período em reais.",
            "example": "120.00"
          },
          "tariffs_percentage": {
            "type": "string",
            "description": "Percentual das tarifas sobre os créditos do período.",
            "example": "1.20"
          },
          "available_balance": {
            "type": "string",
            "description": "Saldo disponível reconciliado da conta.",
            "example": "8200.00"
          }
        }
      },
      "StatementListResponse": {
        "type": "object",
        "description": "Resposta paginada do extrato.",
        "properties": {
          "success": {
            "type": "boolean",
            "description": "Indica se a consulta foi concluída com sucesso.",
            "example": true
          },
          "total": {
            "type": "integer",
            "description": "Quantidade total de lançamentos encontrados.",
            "example": 142
          },
          "count": {
            "type": "integer",
            "description": "Quantidade de lançamentos retornados na página atual.",
            "example": 20
          },
          "offset": {
            "type": "integer",
            "description": "Deslocamento atual da paginação.",
            "example": 0
          },
          "limit": {
            "type": "integer",
            "description": "Limite aplicado na consulta.",
            "example": 20
          },
          "has_more": {
            "type": "boolean",
            "description": "Indica se há mais registros após a página atual.",
            "example": true
          },
          "next_offset": {
            "type": "integer",
            "nullable": true,
            "description": "Próximo offset sugerido para continuar a paginação.",
            "example": 20
          },
          "filters": {
            "type": "object",
            "description": "Filtros efetivamente aplicados na consulta.",
            "properties": {
              "q": {
                "type": "string",
                "nullable": true,
                "description": "Busca textual aplicada."
              },
              "start_date": {
                "type": "string",
                "format": "date",
                "nullable": true,
                "description": "Data inicial aplicada."
              },
              "end_date": {
                "type": "string",
                "format": "date",
                "nullable": true,
                "description": "Data final aplicada."
              },
              "source": {
                "type": "string",
                "nullable": true,
                "description": "Filtro de origem aplicado."
              }
            }
          },
          "summary": {
            "$ref": "#/components/schemas/StatementSummary"
          },
          "results": {
            "type": "array",
            "description": "Lançamentos retornados na página atual.",
            "items": {
              "$ref": "#/components/schemas/StatementEntry"
            }
          }
        }
      },
      "StatementSummaryResponse": {
        "type": "object",
        "description": "Resposta resumida do extrato sem lista de lançamentos.",
        "properties": {
          "success": {
            "type": "boolean",
            "description": "Indica se a consulta foi concluída com sucesso.",
            "example": true
          },
          "filters": {
            "type": "object",
            "description": "Filtros efetivamente aplicados na consulta.",
            "properties": {
              "q": {
                "type": "string",
                "nullable": true,
                "description": "Busca textual aplicada."
              },
              "start_date": {
                "type": "string",
                "format": "date",
                "nullable": true,
                "description": "Data inicial aplicada."
              },
              "end_date": {
                "type": "string",
                "format": "date",
                "nullable": true,
                "description": "Data final aplicada."
              },
              "source": {
                "type": "string",
                "nullable": true,
                "description": "Filtro de origem aplicado."
              }
            }
          },
          "summary": {
            "$ref": "#/components/schemas/StatementSummary"
          }
        }
      },
      "WebhookDelivery": {
        "type": "object",
        "description": "Tentativa de entrega de evento de webhook.",
        "properties": {
          "id": {
            "type": "integer",
            "description": "Identificador interno da entrega.",
            "example": 180
          },
          "endpoint_id": {
            "type": "integer",
            "description": "Identificador do endpoint de webhook.",
            "example": 12
          },
          "endpoint_name": {
            "type": "string",
            "description": "Nome do endpoint configurado.",
            "example": "ERP principal"
          },
          "event_id": {
            "type": "string",
            "description": "Identificador único do evento entregue.",
            "example": "wh_evt_01JABCXYZ"
          },
          "event_type": {
            "type": "string",
            "description": "Nome do evento entregue.",
            "example": "invoice.paid"
          },
          "status": {
            "type": "string",
            "description": "Status atual da entrega.",
            "example": "SENT"
          },
          "attempts": {
            "type": "integer",
            "description": "Quantidade de tentativas já realizadas.",
            "example": 1
          },
          "max_attempts": {
            "type": "integer",
            "description": "Quantidade máxima de tentativas permitidas.",
            "example": 6
          },
          "next_retry_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Data/hora prevista para próxima tentativa quando houver."
          },
          "last_error": {
            "type": "string",
            "description": "Último erro registrado na entrega.",
            "example": ""
          },
          "response_status_code": {
            "type": "integer",
            "nullable": true,
            "description": "HTTP status code retornado pelo sistema da conta.",
            "example": 200
          },
          "response_body": {
            "type": "string",
            "description": "Trecho do corpo de resposta retornado pelo sistema da conta.",
            "example": "ok"
          },
          "sent_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Data/hora do envio realizado."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Data/hora de criação do registro."
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Data/hora da última atualização do registro."
          },
          "payload": {
            "type": "object",
            "description": "Payload JSON enviado ao sistema da conta."
          },
          "request_headers": {
            "type": "object",
            "description": "Headers usados na tentativa de entrega."
          }
        }
      },
      "WebhookDeliveryListResponse": {
        "type": "object",
        "description": "Histórico paginado de entregas de webhook.",
        "properties": {
          "success": {
            "type": "boolean",
            "description": "Indica se a consulta foi concluída com sucesso.",
            "example": true
          },
          "total": {
            "type": "integer",
            "description": "Quantidade total de entregas encontradas.",
            "example": 34
          },
          "count": {
            "type": "integer",
            "description": "Quantidade de entregas retornadas na página atual.",
            "example": 20
          },
          "offset": {
            "type": "integer",
            "description": "Deslocamento atual da paginação.",
            "example": 0
          },
          "limit": {
            "type": "integer",
            "description": "Limite aplicado na consulta.",
            "example": 50
          },
          "has_more": {
            "type": "boolean",
            "description": "Indica se há mais entregas após a página atual.",
            "example": false
          },
          "next_offset": {
            "type": "integer",
            "nullable": true,
            "description": "Próximo offset sugerido para paginação."
          },
          "results": {
            "type": "array",
            "description": "Entregas retornadas na página atual.",
            "items": {
              "$ref": "#/components/schemas/WebhookDelivery"
            }
          }
        }
      },
      "SmsCreditPurchaseResponse": {
        "type": "object",
        "description": "Resposta da compra de pacote de SMS.",
        "properties": {
          "success": {
            "type": "boolean",
            "description": "Indica se a compra foi concluída com sucesso.",
            "example": true
          },
          "message": {
            "type": "string",
            "description": "Mensagem operacional da compra.",
            "example": "Pacote de SMS comprado com sucesso."
          },
          "sms_credits": {
            "type": "integer",
            "description": "Saldo atualizado de créditos SMS da conta.",
            "example": 500
          }
        }
      },
      "HtmlFragmentListResponse": {
        "type": "object",
        "description": "Resposta em JSON contendo fragments HTML renderizados pelo painel.",
        "properties": {
          "success": {
            "type": "boolean",
            "description": "Indica se a consulta foi concluída com sucesso.",
            "example": true
          },
          "results_html": {
            "type": "string",
            "description": "HTML da listagem já renderizada.",
            "example": "<tr>...</tr>"
          },
          "pagination_html": {
            "type": "string",
            "description": "HTML da paginação já renderizada.",
            "example": "<nav>...</nav>"
          }
        }
      },
      "WebhookEndpointEnvelope": {
        "type": "object",
        "description": "Resposta com dados do endpoint recém-criado ou atualizado.",
        "properties": {
          "success": {
            "type": "boolean",
            "description": "Indica se a operação foi concluída com sucesso.",
            "example": true
          },
          "message": {
            "type": "string",
            "description": "Mensagem operacional da criação ou atualização.",
            "example": "Endpoint de webhook criado com sucesso."
          },
          "endpoint": {
            "$ref": "#/components/schemas/WebhookEndpoint"
          },
          "signing_secret": {
            "type": "string",
            "description": "Segredo de assinatura retornado integralmente apenas na criação ou rotação. Armazene com segurança no sistema da conta.",
            "example": "whsec_xxxxxxxxxxxxxxxxx"
          }
        }
      },
      "WebhookEndpointListResponse": {
        "type": "object",
        "description": "Lista de endpoints de webhook cadastrados na conta.",
        "properties": {
          "results": {
            "type": "array",
            "description": "Coleção de endpoints cadastrados na conta.",
            "items": {
              "$ref": "#/components/schemas/WebhookEndpoint"
            }
          }
        }
      },
      "WebhookSecretRotateResponse": {
        "type": "object",
        "description": "Resposta após rotação do segredo de assinatura.",
        "properties": {
          "success": {
            "type": "boolean",
            "description": "Indica se a rotação foi concluída com sucesso.",
            "example": true
          },
          "message": {
            "type": "string",
            "description": "Mensagem operacional da rotação.",
            "example": "Segredo do webhook rotacionado com sucesso."
          },
          "signing_secret": {
            "type": "string",
            "description": "Novo segredo que deve ser atualizado imediatamente no sistema da conta.",
            "example": "whsec_novosegredo_xxxxxxxxx"
          }
        }
      },
      "DashboardMonthContext": {
        "type": "object",
        "description": "Contexto de navegação mensal retornado pelos endpoints do dashboard.",
        "properties": {
          "success": {
            "type": "boolean",
            "description": "Indica se a consulta foi concluída com sucesso.",
            "example": true
          },
          "selected_month": {
            "type": "string",
            "description": "Mês selecionado no formato `YYYY-MM`.",
            "example": "2026-06"
          },
          "selected_month_label": {
            "type": "string",
            "description": "Texto amigável do mês selecionado.",
            "example": "junho de 2026"
          },
          "previous_month": {
            "type": "string",
            "description": "Mês anterior no formato `YYYY-MM`.",
            "example": "2026-05"
          },
          "next_month": {
            "type": "string",
            "description": "Mês seguinte no formato `YYYY-MM`.",
            "example": "2026-07"
          }
        }
      },
      "DashboardBalances": {
        "type": "object",
        "description": "Resumo financeiro principal do dashboard.",
        "properties": {
          "available_balance_amount": {
            "type": "string",
            "description": "Saldo disponível da conta.",
            "example": "8200.00"
          },
          "in_transit_amount": {
            "type": "string",
            "description": "Valor em análise ou trânsito.",
            "example": "350.00"
          },
          "to_receive_amount": {
            "type": "string",
            "description": "Valor ainda a receber.",
            "example": "1250.00"
          },
          "contested_amount": {
            "type": "string",
            "description": "Valor contestado.",
            "example": "0.00"
          },
          "received_amount_this_month": {
            "type": "string",
            "description": "Total recebido no mês atual.",
            "example": "5200.00"
          },
          "received_amount_prev_month": {
            "type": "string",
            "description": "Total recebido no mês anterior.",
            "example": "4800.00"
          },
          "ticket_avg_amount": {
            "type": "string",
            "description": "Ticket médio do mês.",
            "example": "260.00"
          },
          "transacted_total_amount": {
            "type": "string",
            "description": "Total transacionado acumulado.",
            "example": "154000.00"
          }
        }
      },
      "DashboardIncomePreviewBucket": {
        "type": "object",
        "description": "Faixa de previsão de recebimento.",
        "properties": {
          "count": {
            "type": "integer",
            "description": "Quantidade de cobranças previstas na faixa.",
            "example": 4
          },
          "total_amount": {
            "type": "string",
            "description": "Valor total previsto na faixa.",
            "example": "1200.00"
          }
        }
      },
      "DashboardIncomePreview": {
        "type": "object",
        "description": "Previsão de recebimentos por faixa temporal.",
        "properties": {
          "today": {
            "$ref": "#/components/schemas/DashboardIncomePreviewBucket"
          },
          "next_7_days": {
            "$ref": "#/components/schemas/DashboardIncomePreviewBucket"
          },
          "next_15_days": {
            "$ref": "#/components/schemas/DashboardIncomePreviewBucket"
          },
          "next_30_days": {
            "$ref": "#/components/schemas/DashboardIncomePreviewBucket"
          }
        }
      },
      "DashboardInvoiceProgressBlock": {
        "type": "object",
        "description": "Bloco de progresso por status de fatura.",
        "properties": {
          "title": {
            "type": "string",
            "description": "Título do bloco.",
            "example": "Pagas"
          },
          "num_of_invoices": {
            "type": "integer",
            "description": "Quantidade de faturas no bloco.",
            "example": 20
          },
          "total_amount": {
            "type": "string",
            "description": "Soma do valor das faturas do bloco.",
            "example": "5200.00"
          },
          "css_class": {
            "type": "string",
            "description": "Classe visual usada internamente no dashboard.",
            "example": "bg-paid"
          }
        }
      },
      "DashboardInvoiceProgress": {
        "type": "object",
        "description": "Resumo de progresso das faturas no mês selecionado.",
        "properties": {
          "selected_month": {
            "type": "string",
            "description": "Mês selecionado no formato `YYYY-MM`.",
            "example": "2026-06"
          },
          "label": {
            "type": "string",
            "description": "Texto amigável do mês selecionado.",
            "example": "junho de 2026"
          },
          "invoice_total": {
            "type": "integer",
            "description": "Quantidade total de faturas consideradas.",
            "example": 32
          },
          "invoice_total_amount": {
            "type": "string",
            "description": "Valor total das faturas consideradas.",
            "example": "18450.00"
          },
          "blocks": {
            "type": "array",
            "description": "Blocos por status de fatura.",
            "items": {
              "$ref": "#/components/schemas/DashboardInvoiceProgressBlock"
            }
          }
        }
      },
      "DashboardPaymentMethodChart": {
        "type": "object",
        "description": "Dados do gráfico por forma de pagamento.",
        "properties": {
          "selected_month": {
            "type": "string",
            "description": "Mês selecionado no formato `YYYY-MM`.",
            "example": "2026-06"
          },
          "label": {
            "type": "string",
            "description": "Texto amigável do mês selecionado.",
            "example": "junho de 2026"
          },
          "labels": {
            "type": "array",
            "description": "Rótulos do gráfico.",
            "items": {
              "type": "string"
            },
            "example": [
              "Pix",
              "Boleto"
            ]
          },
          "data": {
            "type": "array",
            "description": "Contagens por forma de pagamento.",
            "items": {
              "type": "integer"
            },
            "example": [
              15,
              8
            ]
          },
          "colors": {
            "type": "array",
            "description": "Cores principais do gráfico.",
            "items": {
              "type": "string"
            }
          },
          "hover_colors": {
            "type": "array",
            "description": "Cores de hover do gráfico.",
            "items": {
              "type": "string"
            }
          },
          "has_data": {
            "type": "boolean",
            "description": "Indica se houve dados reais no período.",
            "example": true
          },
          "total_paid_invoices": {
            "type": "integer",
            "description": "Total de faturas pagas consideradas.",
            "example": 23
          }
        }
      },
      "DashboardInvoiceTypeChart": {
        "type": "object",
        "description": "Dados do gráfico por tipo de fatura.",
        "properties": {
          "selected_month": {
            "type": "string",
            "description": "Mês selecionado no formato `YYYY-MM`.",
            "example": "2026-06"
          },
          "label": {
            "type": "string",
            "description": "Texto amigável do mês selecionado.",
            "example": "junho de 2026"
          },
          "labels": {
            "type": "array",
            "description": "Rótulos do gráfico.",
            "items": {
              "type": "string"
            }
          },
          "counts": {
            "type": "array",
            "description": "Contagens por tipo.",
            "items": {
              "type": "integer"
            }
          },
          "items": {
            "type": "array",
            "description": "Itens detalhados do gráfico.",
            "items": {
              "type": "object",
              "properties": {
                "label": {
                  "type": "string",
                  "description": "Nome do tipo de fatura.",
                  "example": "Avulsa"
                },
                "count": {
                  "type": "integer",
                  "description": "Quantidade de faturas do tipo.",
                  "example": 18
                },
                "width_pct": {
                  "type": "number",
                  "description": "Percentual de largura calculado.",
                  "example": 100
                },
                "width_pct_int": {
                  "type": "integer",
                  "description": "Percentual arredondado para inteiro.",
                  "example": 100
                }
              }
            }
          }
        }
      },
      "DashboardReceivedCalendar": {
        "type": "object",
        "description": "Calendário de recebimentos do mês selecionado.",
        "properties": {
          "selected_month": {
            "type": "string",
            "description": "Mês selecionado no formato `YYYY-MM`.",
            "example": "2026-06"
          },
          "label": {
            "type": "string",
            "description": "Texto amigável do mês selecionado.",
            "example": "junho de 2026"
          },
          "weekdays": {
            "type": "array",
            "description": "Rótulos dos dias da semana.",
            "items": {
              "type": "string"
            }
          },
          "month_weeks": {
            "type": "array",
            "description": "Estrutura de semanas do mês.",
            "items": {
              "type": "array",
              "items": {
                "type": "integer"
              }
            }
          },
          "paid_days": {
            "type": "array",
            "description": "Dias do mês com recebimentos.",
            "items": {
              "type": "integer"
            },
            "example": [
              2,
              5,
              15
            ]
          },
          "invoices_by_day": {
            "type": "object",
            "description": "Mapa de dia para lista de faturas recebidas naquele dia.",
            "additionalProperties": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/Invoice"
              }
            }
          }
        }
      },
      "DashboardLatestInvoices": {
        "type": "object",
        "description": "Coleções de últimas faturas do dashboard.",
        "properties": {
          "received": {
            "type": "array",
            "description": "Últimas faturas recebidas.",
            "items": {
              "$ref": "#/components/schemas/Invoice"
            }
          },
          "to_expire_today": {
            "type": "array",
            "description": "Faturas a vencer no dia atual.",
            "items": {
              "$ref": "#/components/schemas/Invoice"
            }
          },
          "expired": {
            "type": "array",
            "description": "Últimas faturas vencidas.",
            "items": {
              "$ref": "#/components/schemas/Invoice"
            }
          }
        }
      },
      "DashboardMonthlyReceived": {
        "type": "object",
        "description": "Série mensal de recebimentos.",
        "properties": {
          "labels": {
            "type": "array",
            "description": "Rótulos mensais.",
            "items": {
              "type": "string"
            }
          },
          "amounts": {
            "type": "array",
            "description": "Valores mensais recebidos.",
            "items": {
              "type": "string"
            }
          },
          "items": {
            "type": "array",
            "description": "Itens detalhados da série mensal.",
            "items": {
              "type": "object",
              "properties": {
                "month": {
                  "type": "string",
                  "description": "Mês no formato `YYYY-MM`.",
                  "example": "2026-06"
                },
                "label": {
                  "type": "string",
                  "description": "Rótulo amigável do mês.",
                  "example": "jun/26"
                },
                "amount": {
                  "type": "string",
                  "description": "Valor recebido no mês.",
                  "example": "5200.00"
                }
              }
            }
          }
        }
      },
      "DashboardCustomers": {
        "type": "object",
        "description": "Indicadores de clientes do dashboard.",
        "properties": {
          "total": {
            "type": "integer",
            "description": "Quantidade total de clientes.",
            "example": 91
          },
          "adimplentes": {
            "type": "integer",
            "description": "Quantidade de clientes adimplentes.",
            "example": 86
          },
          "inadimplentes": {
            "type": "integer",
            "description": "Quantidade de clientes inadimplentes.",
            "example": 5
          },
          "chart": {
            "type": "array",
            "description": "Itens do gráfico de clientes.",
            "items": {
              "type": "object",
              "properties": {
                "title": {
                  "type": "string",
                  "description": "Título do grupo.",
                  "example": "Adimplentes"
                },
                "count": {
                  "type": "integer",
                  "description": "Quantidade no grupo.",
                  "example": 86
                }
              }
            }
          }
        }
      },
      "DashboardOverviewResponse": {
        "type": "object",
        "description": "Visão consolidada do dashboard.",
        "properties": {
          "success": {
            "type": "boolean",
            "description": "Indica se a consulta foi concluída com sucesso.",
            "example": true
          },
          "selected_month": {
            "type": "string",
            "description": "Mês selecionado no formato `YYYY-MM`.",
            "example": "2026-06"
          },
          "selected_month_label": {
            "type": "string",
            "description": "Texto amigável do mês selecionado.",
            "example": "junho de 2026"
          },
          "previous_month": {
            "type": "string",
            "description": "Mês anterior no formato `YYYY-MM`.",
            "example": "2026-05"
          },
          "next_month": {
            "type": "string",
            "description": "Mês seguinte no formato `YYYY-MM`.",
            "example": "2026-07"
          },
          "visible_widgets": {
            "type": "array",
            "description": "Widgets habilitados para a conta.",
            "items": {
              "type": "string"
            }
          },
          "balances": {
            "$ref": "#/components/schemas/DashboardBalances"
          },
          "income_preview": {
            "$ref": "#/components/schemas/DashboardIncomePreview"
          },
          "invoice_progress": {
            "$ref": "#/components/schemas/DashboardInvoiceProgress"
          },
          "latest_invoices": {
            "$ref": "#/components/schemas/DashboardLatestInvoices"
          },
          "payment_method_chart": {
            "$ref": "#/components/schemas/DashboardPaymentMethodChart"
          },
          "invoice_type_chart": {
            "$ref": "#/components/schemas/DashboardInvoiceTypeChart"
          },
          "received_calendar": {
            "$ref": "#/components/schemas/DashboardReceivedCalendar"
          },
          "monthly_received_chart": {
            "$ref": "#/components/schemas/DashboardMonthlyReceived"
          },
          "customers": {
            "$ref": "#/components/schemas/DashboardCustomers"
          },
          "expired_final_invoices_count": {
            "type": "integer",
            "description": "Quantidade de faturas definitivamente expiradas.",
            "example": 3
          }
        }
      },
      "InvoiceCancelInput": {
        "type": "object",
        "description": "Payload para cancelamento de fatura. Informe o motivo operacional do cancelamento.",
        "required": [
          "cancelled_reason"
        ],
        "properties": {
          "cancelled_reason": {
            "type": "string",
            "description": "Motivo do cancelamento da cobrança.",
            "example": "Cobranca substituida por nova emissao."
          }
        },
        "example": {
          "cancelled_reason": "Cobranca substituida por nova emissao."
        }
      },
      "InvoiceRefundInput": {
        "type": "object",
        "description": "Payload para solicitação de estorno de uma fatura paga.",
        "required": [
          "refund_reason"
        ],
        "properties": {
          "refund_reason": {
            "type": "string",
            "description": "Motivo operacional do estorno.",
            "example": "Pagamento recebido em duplicidade."
          }
        },
        "example": {
          "refund_reason": "Pagamento recebido em duplicidade."
        }
      },
      "SubscriptionStatusInput": {
        "type": "object",
        "description": "Payload para alteração do status operacional da assinatura.",
        "required": [
          "status"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "ACTIVE",
              "SUSPENDED"
            ],
            "description": "Novo status da assinatura.",
            "example": "SUSPENDED"
          }
        },
        "example": {
          "status": "SUSPENDED"
        }
      },
      "CarneCancelInput": {
        "type": "object",
        "description": "Payload para cancelamento consolidado do carne.",
        "required": [
          "cancelled_reason"
        ],
        "properties": {
          "cancelled_reason": {
            "type": "string",
            "description": "Motivo operacional do cancelamento do carne.",
            "example": "Solicitado pelo cliente."
          }
        },
        "example": {
          "cancelled_reason": "Solicitado pelo cliente."
        }
      },
      "SmsBuyCreditsInput": {
        "type": "object",
        "description": "Payload para compra de pacote de creditos SMS com saldo Mepagg.",
        "required": [
          "sms_credit_package",
          "sms_purchase_method"
        ],
        "properties": {
          "sms_credit_package": {
            "type": "string",
            "description": "Codigo do pacote de creditos disponivel para a conta.",
            "example": "500"
          },
          "sms_purchase_method": {
            "type": "string",
            "description": "Metodo de compra do pacote. No momento, use `mepagg_balance`.",
            "example": "mepagg_balance"
          }
        },
        "example": {
          "sms_credit_package": "500",
          "sms_purchase_method": "mepagg_balance"
        }
      },
      "SubscriptionPlan": {
        "type": "object",
        "description": "Plano de assinatura da conta autenticada.",
        "properties": {
          "id": {
            "type": "integer",
            "description": "Identificador interno do plano.",
            "example": 18
          },
          "reference_id": {
            "type": "string",
            "description": "Identificador público do plano.",
            "example": "PLAN_01JABCXYZ"
          },
          "name": {
            "type": "string",
            "description": "Nome comercial do plano.",
            "example": "Mensalidade hospedagem"
          },
          "amount": {
            "type": "string",
            "description": "Valor base do plano em reais.",
            "example": "85.00"
          },
          "interval": {
            "type": "string",
            "example": "MONTHLY",
            "enum": [
              "WEEKLY",
              "BIWEEKLY",
              "MONTHLY",
              "BIMONTHLY",
              "QUARTERLY",
              "FOUR_MONTHS",
              "SEMIANNUAL",
              "YEARLY"
            ],
            "description": "Periodicidade do plano.",
            "x-enumDescriptions": [
              "Semanal",
              "Quinzenal",
              "Mensal",
              "Bimestral",
              "Trimestral",
              "Quadrimestral",
              "Semestral",
              "Anual"
            ]
          },
          "interval_label": {
            "type": "string",
            "description": "Texto amigável da recorrência.",
            "example": "Mensal"
          },
          "subscriptions_count": {
            "type": "integer",
            "description": "Quantidade de assinaturas vinculadas ao plano.",
            "example": 3
          },
          "fees": {
            "type": "string",
            "description": "Juros em reais.",
            "example": "1.00"
          },
          "fines": {
            "type": "string",
            "description": "Multa em reais.",
            "example": "2.00"
          },
          "discount_type": {
            "type": "string",
            "description": "Tipo do desconto.",
            "enum": [
              "PERCENTAGE",
              "FIXED_VALUE"
            ],
            "example": "FIXED_VALUE"
          },
          "discount": {
            "type": "string",
            "description": "Valor do desconto conforme `discount_type`.",
            "example": "5.00"
          },
          "inter_boleto_num_dias_agenda": {
            "type": "integer",
            "description": "Prazo de agenda do boleto quando aplicável.",
            "example": 3
          },
          "payment_methods": {
            "type": "array",
            "description": "Formas de pagamento vinculadas ao plano.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer",
                  "example": 1
                },
                "name": {
                  "type": "string",
                  "example": "Boleto"
                },
                "slug": {
                  "type": "string",
                  "example": "boleto"
                }
              }
            }
          },
          "is_active": {
            "type": "boolean",
            "description": "Indica se o plano está ativo.",
            "example": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Data de criação do plano."
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "Data da última atualização do plano."
          }
        }
      },
      "SubscriptionPlanInput": {
        "type": "object",
        "description": "Payload para criação ou edição de plano de assinatura. O plano define valor, recorrência e regras financeiras reutilizáveis para múltiplas assinaturas.",
        "required": [
          "name",
          "amount",
          "interval",
          "payment_method_ids"
        ],
        "properties": {
          "name": {
            "type": "string",
            "example": "Mensalidade hospedagem"
          },
          "amount": {
            "type": "string",
            "example": "85.00",
            "description": "Valor base do plano em reais."
          },
          "interval": {
            "type": "string",
            "example": "MONTHLY",
            "enum": [
              "WEEKLY",
              "BIWEEKLY",
              "MONTHLY",
              "BIMONTHLY",
              "QUARTERLY",
              "FOUR_MONTHS",
              "SEMIANNUAL",
              "YEARLY"
            ],
            "description": "Periodicidade do plano.",
            "x-enumDescriptions": [
              "Semanal",
              "Quinzenal",
              "Mensal",
              "Bimestral",
              "Trimestral",
              "Quadrimestral",
              "Semestral",
              "Anual"
            ]
          },
          "fees": {
            "type": "string",
            "example": "1.00"
          },
          "fines": {
            "type": "string",
            "example": "2.00"
          },
          "discount_type": {
            "type": "string",
            "enum": [
              "PERCENTAGE",
              "FIXED_VALUE"
            ],
            "example": "FIXED_VALUE"
          },
          "discount": {
            "type": "string",
            "example": "5.00"
          },
          "inter_boleto_num_dias_agenda": {
            "type": "integer",
            "example": 3
          },
          "payment_method_ids": {
            "type": "array",
            "items": {
              "type": "integer"
            },
            "example": [
              1,
              2
            ]
          },
          "is_active": {
            "type": "boolean",
            "example": true
          }
        },
        "example": {
          "name": "Mensalidade hospedagem",
          "amount": "85.00",
          "interval": "MONTHLY",
          "fees": "1.00",
          "fines": "2.00",
          "discount_type": "FIXED_VALUE",
          "discount": "5.00",
          "inter_boleto_num_dias_agenda": 3,
          "payment_method_ids": [
            1,
            2
          ],
          "is_active": true
        }
      },
      "SubscriptionPlanEnvelope": {
        "type": "object",
        "description": "Resposta com um único plano.",
        "properties": {
          "plan": {
            "$ref": "#/components/schemas/SubscriptionPlan"
          }
        }
      },
      "SubscriptionPlanListResponse": {
        "type": "object",
        "description": "Lista paginada de planos.",
        "properties": {
          "count": {
            "type": "integer",
            "description": "Quantidade de registros retornados nesta página.",
            "example": 2
          },
          "total": {
            "type": "integer",
            "description": "Quantidade total de planos encontrados.",
            "example": 18
          },
          "offset": {
            "type": "integer",
            "example": 0
          },
          "limit": {
            "type": "integer",
            "example": 20
          },
          "has_more": {
            "type": "boolean",
            "example": false
          },
          "next_offset": {
            "type": "integer",
            "nullable": true,
            "example": null
          },
          "results": {
            "type": "array",
            "description": "Coleção de planos retornados na página atual.",
            "items": {
              "$ref": "#/components/schemas/SubscriptionPlan"
            }
          }
        }
      },
      "WebhookPlanEvent": {
        "type": "object",
        "description": "Evento de webhook relacionado a criação, atualização ou remoção de planos.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Identificador único do evento.",
            "example": "wh_evt_01JPLANXYZ"
          },
          "type": {
            "type": "string",
            "description": "Nome do evento.",
            "example": "plan.updated"
          },
          "occurred_at": {
            "type": "string",
            "format": "date-time",
            "description": "Data e hora da ocorrência do evento."
          },
          "account": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer",
                "example": 12
              },
              "reference_id": {
                "type": "string",
                "example": "ACC_EXAMPLE_001"
              },
              "name": {
                "type": "string",
                "example": "Conta Exemplo"
              }
            }
          },
          "data": {
            "type": "object",
            "properties": {
              "plan_id": {
                "type": "integer",
                "example": 18
              },
              "plan_reference_id": {
                "type": "string",
                "example": "PLAN_01JABCXYZ"
              },
              "plan": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/SubscriptionPlan"
                  }
                ],
                "properties": {
                  "is_deleted": {
                    "type": "boolean",
                    "example": false
                  }
                }
              }
            }
          }
        }
      },
      "PaymentLink": {
        "type": "object",
        "description": "Link público de cobrança da conta autenticada.",
        "properties": {
          "id": {
            "type": "integer",
            "description": "Identificador interno do link.",
            "example": 91
          },
          "public_token": {
            "type": "string",
            "format": "uuid",
            "description": "Token público UUID usado na URL pública do link.",
            "example": "4dd78029-fb39-4c52-b0e6-2bc748d2832b"
          },
          "description": {
            "type": "string",
            "description": "Produto ou serviço exibido na tela pública e copiado para a fatura gerada.",
            "example": "Adesao plano enterprise"
          },
          "has_defined_amount": {
            "type": "boolean",
            "description": "Indica se o link possui valor fixo pré-definido.",
            "example": true
          },
          "amount": {
            "type": "string",
            "nullable": true,
            "description": "Valor fixo do link em reais. Quando `null`, a tela pública pede o valor ao pagador.",
            "example": "249.90"
          },
          "due_option": {
            "type": "string",
            "description": "Código estável da regra de vencimento.",
            "enum": [
              "today",
              "1_day",
              "5_days",
              "10_days",
              "15_days",
              "30_days",
              "custom",
              "none"
            ],
            "example": "none"
          },
          "due_option_label": {
            "type": "string",
            "description": "Texto amigável da regra de vencimento.",
            "example": "Sem vencimento"
          },
          "custom_due_days": {
            "type": "integer",
            "nullable": true,
            "description": "Quantidade personalizada de dias usada quando `due_option=custom`.",
            "example": null
          },
          "invoice_due_option": {
            "type": "string",
            "description": "Regra de vencimento das faturas geradas quando `due_option=none`.",
            "enum": [
              "today",
              "1_day",
              "5_days",
              "10_days",
              "15_days",
              "20_days",
              "30_days",
              "custom"
            ],
            "nullable": true,
            "example": "20_days"
          },
          "invoice_due_option_label": {
            "type": "string",
            "description": "Texto amigável da regra de vencimento das faturas geradas.",
            "example": "20 dias"
          },
          "invoice_custom_due_days": {
            "type": "integer",
            "nullable": true,
            "description": "Quantidade personalizada de dias usada quando `invoice_due_option=custom`.",
            "example": null
          },
          "usage_limit_mode": {
            "type": "string",
            "description": "Modo do limite de usos.",
            "enum": [
              "unlimited",
              "limited"
            ],
            "example": "limited"
          },
          "usage_limit_mode_label": {
            "type": "string",
            "description": "Texto amigável do modo do limite de usos.",
            "example": "Definir limite"
          },
          "usage_limit": {
            "type": "integer",
            "nullable": true,
            "description": "Quantidade máxima de cobranças que o link pode gerar.",
            "example": 3
          },
          "has_usage_limit": {
            "type": "boolean",
            "description": "Indica se o link possui limite de usos configurado.",
            "example": true
          },
          "used_count": {
            "type": "integer",
            "description": "Quantidade de faturas já geradas a partir do link.",
            "example": 1
          },
          "remaining_uses": {
            "type": "integer",
            "nullable": true,
            "description": "Quantidade restante de usos disponíveis.",
            "example": 2
          },
          "usage_limit_display": {
            "type": "string",
            "description": "Texto pronto para interface com o uso atual do link.",
            "example": "1 de 3"
          },
          "due_date": {
            "type": "string",
            "format": "date",
            "nullable": true,
            "description": "Data final calculada para o link.",
            "example": "2026-08-02"
          },
          "due_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Data e hora final calculadas para o link.",
            "example": "2026-08-02T14:30:00-03:00"
          },
          "validity_display": {
            "type": "string",
            "description": "Texto pronto para interface sobre a validade do link. Quando o link não expira, retorna `Sem vencimento`.",
            "example": "Sem vencimento"
          },
          "is_active": {
            "type": "boolean",
            "description": "Indica se o prazo ainda está válido.",
            "example": true
          },
          "can_generate_invoice": {
            "type": "boolean",
            "description": "Indica se o link ainda pode gerar novas cobranças.",
            "example": true
          },
          "status_code": {
            "type": "string",
            "description": "Código estável do status do link. Use para filtros e automações.",
            "enum": [
              "active",
              "expired",
              "limit_reached"
            ],
            "example": "active"
          },
          "status_label": {
            "type": "string",
            "description": "Texto amigável do status do link. Use para interface.",
            "example": "Ativo"
          },
          "invoice_due_summary": {
            "type": "string",
            "description": "Resumo pronto para interface sobre o vencimento das faturas geradas quando o link não expira.",
            "example": "20 dias após a criação"
          },
          "issued_via": {
            "type": "string",
            "description": "Origem da criação do link. Valor original retornado no payload.",
            "example": "API"
          },
          "issued_via_code": {
            "type": "string",
            "description": "Código estável da origem do link. Use para regra, filtros e integração.",
            "example": "api"
          },
          "issued_via_label": {
            "type": "string",
            "description": "Texto amigável da origem do link.",
            "example": "API"
          },
          "payment_methods": {
            "type": "array",
            "description": "Formas de pagamento habilitadas para o link.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer",
                  "example": 7
                },
                "name": {
                  "type": "string",
                  "example": "Pix"
                },
                "slug": {
                  "type": "string",
                  "example": "pix"
                }
              }
            }
          },
          "payment_methods_display": {
            "type": "string",
            "description": "Texto amigável com as formas de pagamento separadas por vírgula.",
            "example": "Boleto, Pix"
          },
          "public_url": {
            "type": "string",
            "format": "uri",
            "description": "URL pública do checkout do link.",
            "example": "https://app.mepagg.com/link/4dd78029-fb39-4c52-b0e6-2bc748d2832b/"
          },
          "public_urls": {
            "type": "object",
            "description": "Coleção de URLs públicas relacionadas ao link.",
            "properties": {
              "checkout": {
                "type": "string",
                "format": "uri",
                "example": "https://app.mepagg.com/link/4dd78029-fb39-4c52-b0e6-2bc748d2832b/"
              }
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Data e hora de criação do link.",
            "example": "2026-07-18T14:30:00-03:00"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "Data e hora da última atualização do link.",
            "example": "2026-07-18T14:30:00-03:00"
          },
          "status_reason_code": {
            "type": "string",
            "description": "Motivo estável do status atual do link.",
            "enum": [
              "active",
              "manual_deactivated",
              "due_date_expired",
              "usage_limit_reached"
            ],
            "example": "active"
          },
          "status_reason_label": {
            "type": "string",
            "description": "Texto amigável do motivo do status atual.",
            "example": "Ativo"
          },
          "manual_deactivated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Data/hora em que o link foi desativado manualmente, quando aplicável.",
            "example": null
          }
        }
      },
      "PaymentLinkInput": {
        "type": "object",
        "description": "Payload de criação ou atualização de um link de pagamento. Quando `link_type=fixed`, o campo `amount` passa a ser obrigatório e deve ser pelo menos `5.00`. Quando `due_option=custom`, `custom_due_days` deve ser enviado com valor entre `1` e `29`. Quando `due_option=none`, `invoice_due_option` passa a ser obrigatório para definir em quantos dias vence cada fatura gerada; se `invoice_due_option=custom`, envie `invoice_custom_due_days` entre `1` e `29`. Quando `usage_limit_mode=limited`, `usage_limit` se torna obrigatório. Envie `payment_methods` com slugs ou `payment_method_ids` com IDs internos. Não envie `issued_via*`: a origem do link é definida internamente pela Mepagg conforme o canal real da emissão. Se este link for criado via API, qualquer fatura gerada depois na tela pública sairá com `type_code=payment_link` e `issued_via_code=api`.",
        "properties": {
          "description": {
            "type": "string",
            "description": "Produto ou serviço exibido na tela pública.",
            "example": "Link sem vencimento para adesao"
          },
          "link_type": {
            "type": "string",
            "enum": [
              "free",
              "fixed"
            ],
            "description": "Define se o valor será informado pelo cliente (`free`) ou fixo (`fixed`).",
            "example": "fixed"
          },
          "has_defined_amount": {
            "type": "boolean",
            "description": "Compatibilidade adicional para indicar valor fixo. Se `link_type` também for enviado, ele prevalece.",
            "example": true
          },
          "amount": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "description": "Valor fixo do link em reais. Obrigatório quando `link_type=fixed`.",
            "example": "249.90"
          },
          "due_option": {
            "type": "string",
            "enum": [
              "today",
              "1_day",
              "5_days",
              "10_days",
              "15_days",
              "30_days",
              "custom",
              "none"
            ],
            "description": "Regra de validade do link.",
            "example": "none"
          },
          "custom_due_days": {
            "type": "integer",
            "minimum": 1,
            "maximum": 29,
            "nullable": true,
            "description": "Quantidade de dias quando `due_option=custom`.",
            "example": 7
          },
          "invoice_due_option": {
            "type": "string",
            "enum": [
              "today",
              "1_day",
              "5_days",
              "10_days",
              "15_days",
              "20_days",
              "30_days",
              "custom"
            ],
            "description": "Regra de vencimento das faturas geradas quando `due_option=none`. Use `today` para a leitura humana `No mesmo dia`.",
            "nullable": true,
            "example": "20_days"
          },
          "invoice_custom_due_days": {
            "type": "integer",
            "minimum": 1,
            "maximum": 29,
            "nullable": true,
            "description": "Quantidade de dias quando `due_option=none` e `invoice_due_option=custom`.",
            "example": 7
          },
          "usage_limit_mode": {
            "type": "string",
            "enum": [
              "unlimited",
              "limited"
            ],
            "description": "Modo do limite de usos.",
            "example": "limited"
          },
          "usage_limit": {
            "type": "integer",
            "minimum": 1,
            "nullable": true,
            "description": "Quantidade máxima de cobranças geradas quando `usage_limit_mode=limited`.",
            "example": 3
          },
          "payment_methods": {
            "type": "array",
            "description": "Lista de slugs das formas de pagamento.",
            "items": {
              "type": "string"
            },
            "example": [
              "boleto",
              "pix"
            ]
          },
          "payment_method_ids": {
            "type": "array",
            "description": "Lista alternativa com IDs internos das formas de pagamento.",
            "items": {
              "type": "integer"
            },
            "example": [
              11,
              12
            ]
          },
          "base_date": {
            "type": "string",
            "format": "date",
            "description": "Data base opcional para cálculo do vencimento.",
            "example": "2026-07-18"
          }
        },
        "required": [
          "description",
          "due_option",
          "usage_limit_mode"
        ]
      },
      "PaymentLinkEnvelope": {
        "type": "object",
        "description": "Resposta com um único link de pagamento.",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "message": {
            "type": "string",
            "example": "Link de pagamento criado com sucesso."
          },
          "payment_link": {
            "$ref": "#/components/schemas/PaymentLink"
          }
        }
      },
      "PaymentLinkListResponse": {
        "type": "object",
        "description": "Lista paginada de links de pagamento.",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "total": {
            "type": "integer",
            "description": "Quantidade total de links encontrados antes da paginação.",
            "example": 2
          },
          "count": {
            "type": "integer",
            "description": "Quantidade de links retornados nesta página.",
            "example": 2
          },
          "offset": {
            "type": "integer",
            "description": "Deslocamento aplicado na consulta.",
            "example": 0
          },
          "limit": {
            "type": "integer",
            "description": "Limite aplicado na consulta.",
            "example": 20
          },
          "has_more": {
            "type": "boolean",
            "description": "Indica se existe próxima página.",
            "example": false
          },
          "next_offset": {
            "type": "integer",
            "nullable": true,
            "description": "Próximo offset disponível quando `has_more=true`.",
            "example": null
          },
          "results": {
            "type": "array",
            "description": "Coleção de links retornados na página atual.",
            "items": {
              "$ref": "#/components/schemas/PaymentLink"
            }
          }
        }
      },
      "WebhookPaymentLinkStatusChangedEvent": {
        "type": "object",
        "description": "Payload enviado quando um link de pagamento muda de status. O evento cobre expiração por vencimento, desativação manual e limite de usos atingido.",
        "properties": {
          "id": {
            "type": "string",
            "example": "wh_evt_01JPLINKXYZ"
          },
          "type": {
            "type": "string",
            "example": "payment_link.status_changed"
          },
          "occurred_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-07-24T11:32:10-03:00"
          },
          "account": {
            "type": "object",
            "properties": {
              "token": {
                "type": "string",
                "example": "ACC_EXAMPLE_001"
              },
              "name": {
                "type": "string",
                "example": "Empresa Exemplo de Cobrancas LTDA"
              },
              "document": {
                "type": "string",
                "example": "12345678000199"
              }
            }
          },
          "data": {
            "type": "object",
            "properties": {
              "payment_link_public_token": {
                "type": "string",
                "format": "uuid",
                "example": "4dd78029-fb39-4c52-b0e6-2bc748d2832b"
              },
              "previous_status_code": {
                "type": "string",
                "example": "active"
              },
              "previous_status_label": {
                "type": "string",
                "example": "Ativo"
              },
              "status_code": {
                "type": "string",
                "example": "limit_reached"
              },
              "status_label": {
                "type": "string",
                "example": "Limite atingido"
              },
              "status_reason_code": {
                "type": "string",
                "example": "usage_limit_reached"
              },
              "status_reason_label": {
                "type": "string",
                "example": "Limite de usos atingido"
              },
              "payment_link": {
                "$ref": "#/components/schemas/PaymentLink"
              }
            }
          }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Chave de API ausente ou inválida.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorMessage"
            }
          }
        }
      },
      "ValidationError": {
        "description": "Falha de validação de negócio.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorMessage"
            }
          }
        }
      }
    }
  },
  "webhooks": {
    "customerCreated": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Evento customer.created",
        "description": "Webhook enviado quando um cliente é cadastrado na conta. Use o snapshot de `data.customer` para espelhar o cadastro no sistema da conta.",
        "parameters": [
          {
            "$ref": "#/components/parameters/WebhookSignature"
          },
          {
            "$ref": "#/components/parameters/WebhookEventId"
          },
          {
            "$ref": "#/components/parameters/WebhookDeliveryId"
          },
          {
            "$ref": "#/components/parameters/WebhookTimestamp"
          },
          {
            "$ref": "#/components/parameters/WebhookRetryCount"
          },
          {
            "$ref": "#/components/parameters/WebhookSignatureV2"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookCustomerEvent"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook aceito pelo sistema da conta."
          }
        }
      }
    },
    "customerUpdated": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Evento customer.updated",
        "description": "Webhook enviado quando um cliente é editado no Mepagg. O payload contém o snapshot completo mais recente do cliente.",
        "parameters": [
          {
            "$ref": "#/components/parameters/WebhookSignature"
          },
          {
            "$ref": "#/components/parameters/WebhookEventId"
          },
          {
            "$ref": "#/components/parameters/WebhookDeliveryId"
          },
          {
            "$ref": "#/components/parameters/WebhookTimestamp"
          },
          {
            "$ref": "#/components/parameters/WebhookRetryCount"
          },
          {
            "$ref": "#/components/parameters/WebhookSignatureV2"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookCustomerEvent"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook aceito pelo sistema da conta."
          }
        }
      }
    },
    "customerDeleted": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Evento customer.deleted",
        "description": "Webhook enviado quando um cliente é removido logicamente da conta. O sistema da conta deve observar `data.customer.is_deleted=true` e `data.customer.deleted_at`.",
        "parameters": [
          {
            "$ref": "#/components/parameters/WebhookSignature"
          },
          {
            "$ref": "#/components/parameters/WebhookEventId"
          },
          {
            "$ref": "#/components/parameters/WebhookDeliveryId"
          },
          {
            "$ref": "#/components/parameters/WebhookTimestamp"
          },
          {
            "$ref": "#/components/parameters/WebhookRetryCount"
          },
          {
            "$ref": "#/components/parameters/WebhookSignatureV2"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookCustomerEvent"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook aceito pelo sistema da conta."
          }
        }
      }
    },
    "carneCancelled": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Evento carne.cancelled",
        "description": "Webhook enviado quando um carnê é cancelado. O sistema da conta recebe o estado consolidado do carnê e continua recebendo também os `invoice.cancelled` das parcelas afetadas.",
        "parameters": [
          {
            "$ref": "#/components/parameters/WebhookSignature"
          },
          {
            "$ref": "#/components/parameters/WebhookEventId"
          },
          {
            "$ref": "#/components/parameters/WebhookDeliveryId"
          },
          {
            "$ref": "#/components/parameters/WebhookTimestamp"
          },
          {
            "$ref": "#/components/parameters/WebhookRetryCount"
          },
          {
            "$ref": "#/components/parameters/WebhookSignatureV2"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookCarneCancelledEvent"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook aceito pelo sistema da conta."
          }
        }
      }
    },
    "invoicePaid": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Evento invoice.paid",
        "description": "Webhook enviado quando uma fatura é compensada. Prefira validar `X-Mepagg-Signature-V2`, usar `X-Mepagg-Event-Id` como idempotência e responder `2xx` rapidamente.",
        "parameters": [
          {
            "$ref": "#/components/parameters/WebhookSignature"
          },
          {
            "$ref": "#/components/parameters/WebhookEventId"
          },
          {
            "$ref": "#/components/parameters/WebhookDeliveryId"
          },
          {
            "$ref": "#/components/parameters/WebhookTimestamp"
          },
          {
            "$ref": "#/components/parameters/WebhookRetryCount"
          },
          {
            "$ref": "#/components/parameters/WebhookSignatureV2"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookInvoicePaidEvent"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook aceito pelo sistema da conta."
          }
        }
      }
    },
    "transferCompleted": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Evento transfer.completed",
        "description": "Webhook enviado quando uma transferência sai do estado em análise e é concluída. Prefira validar `X-Mepagg-Signature-V2`, usar `X-Mepagg-Event-Id` como deduplicação e conciliar com o extrato.",
        "parameters": [
          {
            "$ref": "#/components/parameters/WebhookSignature"
          },
          {
            "$ref": "#/components/parameters/WebhookEventId"
          },
          {
            "$ref": "#/components/parameters/WebhookDeliveryId"
          },
          {
            "$ref": "#/components/parameters/WebhookTimestamp"
          },
          {
            "$ref": "#/components/parameters/WebhookRetryCount"
          },
          {
            "$ref": "#/components/parameters/WebhookSignatureV2"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookTransferCompletedEvent"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook aceito pelo sistema da conta."
          }
        }
      }
    },
    "smsCreditsPurchased": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Evento sms.credits_purchased",
        "description": "Webhook enviado quando a conta compra créditos SMS. O payload informa o pacote adquirido, a forma de pagamento, o valor e o novo saldo de créditos.",
        "parameters": [
          {
            "$ref": "#/components/parameters/WebhookSignature"
          },
          {
            "$ref": "#/components/parameters/WebhookEventId"
          },
          {
            "$ref": "#/components/parameters/WebhookDeliveryId"
          },
          {
            "$ref": "#/components/parameters/WebhookTimestamp"
          },
          {
            "$ref": "#/components/parameters/WebhookRetryCount"
          },
          {
            "$ref": "#/components/parameters/WebhookSignatureV2"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookSmsCreditsPurchasedEvent"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook aceito pelo sistema da conta."
          }
        }
      }
    },
    "planCreated": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Evento plan.created",
        "description": "Webhook enviado quando um plano é criado na conta. O payload traz o snapshot completo do plano recém-criado.",
        "parameters": [
          {
            "$ref": "#/components/parameters/WebhookSignature"
          },
          {
            "$ref": "#/components/parameters/WebhookEventId"
          },
          {
            "$ref": "#/components/parameters/WebhookDeliveryId"
          },
          {
            "$ref": "#/components/parameters/WebhookTimestamp"
          },
          {
            "$ref": "#/components/parameters/WebhookRetryCount"
          },
          {
            "$ref": "#/components/parameters/WebhookSignatureV2"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookPlanEvent"
              },
              "example": {
                "id": "wh_evt_01JPLANXYZ",
                "type": "plan.created",
                "occurred_at": "2026-07-11T10:40:00-03:00",
                "account": {
                  "id": 12,
                  "reference_id": "ACC_EXAMPLE_001",
                  "name": "Conta Exemplo"
                },
                "data": {
                  "plan_id": 18,
                  "plan_reference_id": "PLAN_01JABCXYZ",
                  "plan": {
                    "id": 18,
                    "reference_id": "PLAN_01JABCXYZ",
                    "name": "Mensalidade hospedagem",
                    "amount": "85.00",
                    "interval": "MONTHLY",
                    "interval_label": "Mensal",
                    "subscriptions_count": 3,
                    "fees": "1.00",
                    "fines": "2.00",
                    "discount_type": "FIXED_VALUE",
                    "discount": "5.00",
                    "inter_boleto_num_dias_agenda": 3,
                    "payment_methods": [
                      {
                        "id": 1,
                        "name": "Boleto",
                        "slug": "boleto"
                      }
                    ],
                    "is_active": true,
                    "is_deleted": false
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook aceito pelo sistema da conta."
          }
        }
      }
    },
    "planUpdated": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Evento plan.updated",
        "description": "Webhook enviado quando um plano é atualizado. Use o snapshot em `data.plan` para sincronizar o catálogo local de planos.",
        "parameters": [
          {
            "$ref": "#/components/parameters/WebhookSignature"
          },
          {
            "$ref": "#/components/parameters/WebhookEventId"
          },
          {
            "$ref": "#/components/parameters/WebhookDeliveryId"
          },
          {
            "$ref": "#/components/parameters/WebhookTimestamp"
          },
          {
            "$ref": "#/components/parameters/WebhookRetryCount"
          },
          {
            "$ref": "#/components/parameters/WebhookSignatureV2"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookPlanEvent"
              },
              "example": {
                "id": "wh_evt_01JPLANXYZ",
                "type": "plan.updated",
                "occurred_at": "2026-07-11T10:40:00-03:00",
                "account": {
                  "id": 12,
                  "reference_id": "ACC_EXAMPLE_001",
                  "name": "Conta Exemplo"
                },
                "data": {
                  "plan_id": 18,
                  "plan_reference_id": "PLAN_01JABCXYZ",
                  "plan": {
                    "id": 18,
                    "reference_id": "PLAN_01JABCXYZ",
                    "name": "Mensalidade hospedagem",
                    "amount": "85.00",
                    "interval": "MONTHLY",
                    "interval_label": "Mensal",
                    "subscriptions_count": 3,
                    "fees": "1.00",
                    "fines": "2.00",
                    "discount_type": "FIXED_VALUE",
                    "discount": "5.00",
                    "inter_boleto_num_dias_agenda": 3,
                    "payment_methods": [
                      {
                        "id": 1,
                        "name": "Boleto",
                        "slug": "boleto"
                      }
                    ],
                    "is_active": true,
                    "is_deleted": false
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook aceito pelo sistema da conta."
          }
        }
      }
    },
    "planDeleted": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Evento plan.deleted",
        "description": "Webhook enviado quando um plano é removido logicamente. O payload retorna `data.plan.is_deleted=true` para facilitar a baixa no sistema da conta.",
        "parameters": [
          {
            "$ref": "#/components/parameters/WebhookSignature"
          },
          {
            "$ref": "#/components/parameters/WebhookEventId"
          },
          {
            "$ref": "#/components/parameters/WebhookDeliveryId"
          },
          {
            "$ref": "#/components/parameters/WebhookTimestamp"
          },
          {
            "$ref": "#/components/parameters/WebhookRetryCount"
          },
          {
            "$ref": "#/components/parameters/WebhookSignatureV2"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookPlanEvent"
              },
              "example": {
                "id": "wh_evt_01JPLANXYZ",
                "type": "plan.deleted",
                "occurred_at": "2026-07-11T10:40:00-03:00",
                "account": {
                  "id": 12,
                  "reference_id": "ACC_EXAMPLE_001",
                  "name": "Conta Exemplo"
                },
                "data": {
                  "plan_id": 18,
                  "plan_reference_id": "PLAN_01JABCXYZ",
                  "plan": {
                    "id": 18,
                    "reference_id": "PLAN_01JABCXYZ",
                    "name": "Mensalidade hospedagem",
                    "amount": "85.00",
                    "interval": "MONTHLY",
                    "interval_label": "Mensal",
                    "subscriptions_count": 3,
                    "fees": "1.00",
                    "fines": "2.00",
                    "discount_type": "FIXED_VALUE",
                    "discount": "5.00",
                    "inter_boleto_num_dias_agenda": 3,
                    "payment_methods": [
                      {
                        "id": 1,
                        "name": "Boleto",
                        "slug": "boleto"
                      }
                    ],
                    "is_active": true,
                    "is_deleted": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook aceito pelo sistema da conta."
          }
        }
      }
    },
    "paymentLinkStatusChanged": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Evento payment_link.status_changed",
        "description": "Webhook enviado quando um link de pagamento muda de status calculado. Use `status_code` e `status_reason_code` para identificar se o link expirou, foi desativado manualmente ou atingiu o limite de usos.",
        "parameters": [
          {
            "$ref": "#/components/parameters/WebhookSignature"
          },
          {
            "$ref": "#/components/parameters/WebhookEventId"
          },
          {
            "$ref": "#/components/parameters/WebhookDeliveryId"
          },
          {
            "$ref": "#/components/parameters/WebhookTimestamp"
          },
          {
            "$ref": "#/components/parameters/WebhookRetryCount"
          },
          {
            "$ref": "#/components/parameters/WebhookSignatureV2"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookPaymentLinkStatusChangedEvent"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook aceito pelo sistema da conta."
          }
        }
      }
    }
  },
  "paths": {
    "/api/v1/customers/": {
      "get": {
        "tags": [
          "Clientes"
        ],
        "summary": "Listar clientes",
        "description": "Lista os clientes da conta autenticada com filtros por busca textual, localização e inadimplência. Use `limit` e `offset` para paginação.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Busca textual por nome, documento, e-mail ou referência."
          },
          {
            "name": "state",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "city",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "is_defaulter",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/Offset"
          }
        ],
        "responses": {
          "200": {
            "description": "Clientes listados.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerListResponse"
                },
                "examples": {
                  "default": {
                    "value": {
                      "count": 1,
                      "results": [
                        {
                          "reference_id": "CUST_EXAMPLE_001",
                          "name": "Cliente Exemplo LTDA",
                          "document": "12345678000195",
                          "email_primary": "financeiro@clienteexemplo.com.br",
                          "city": "Sao Paulo",
                          "state": "SP"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "get_api_v1_customers",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request GET \\\n  --url 'https://app.mepagg.com/api/v1/customers/?limit=20&offset=0' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const response = await fetch('https://app.mepagg.com/api/v1/customers/?limit=20&offset=0', {\n  method: 'GET',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API'\n  }}\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.get(\n    'https://app.mepagg.com/api/v1/customers/?limit=20&offset=0',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\"\n},\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/customers/?limit=20&offset=0',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'GET',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API'],\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      },
      "post": {
        "tags": [
          "Clientes"
        ],
        "summary": "Criar cliente",
        "description": "Cria um cliente para uso em cobranças avulsas, assinaturas e carnês.\n\n### Regras importantes\n- envie `document` com apenas números\n- envie `zipcode` com apenas números\n- envie `phone_number` com DDD e apenas números\n- persista o `reference_id` retornado para usar nas operações futuras",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request POST \\\n  --url 'https://app.mepagg.com/api/v1/customers/?limit=20&offset=0' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const response = await fetch('https://app.mepagg.com/api/v1/customers/?limit=20&offset=0', {\n  method: 'POST',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API'\n  }}\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.post(\n    'https://app.mepagg.com/api/v1/customers/?limit=20&offset=0',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\"\n},\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/customers/?limit=20&offset=0',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'POST',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API'],\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CustomerInput"
              },
              "examples": {
                "pessoa-juridica": {
                  "value": {
                    "name": "Cliente Exemplo LTDA",
                    "document": "12345678000195",
                    "email_primary": "financeiro@clienteexemplo.com.br",
                    "phone_number": "11987654321",
                    "street": "Avenida Exemplo",
                    "neighborhood": "Jardim Modelo",
                    "number": "100",
                    "zipcode": "01311000",
                    "city": "Sao Paulo",
                    "state": "SP"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Cliente criado.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "customer": {
                      "$ref": "#/components/schemas/Customer"
                    }
                  }
                },
                "examples": {
                  "default": {
                    "value": {
                      "success": true,
                      "customer": {
                        "reference_id": "CUST_EXAMPLE_001",
                        "name": "Cliente Exemplo LTDA",
                        "document": "12345678000195"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "post_api_v1_customers"
      }
    },
    "/api/v1/customers/{reference_id}/": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ReferenceId"
        }
      ],
      "get": {
        "tags": [
          "Clientes"
        ],
        "summary": "Detalhar cliente",
        "description": "Retorna o cadastro completo de um cliente a partir do `reference_id`.",
        "responses": {
          "200": {
            "description": "Cliente localizado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerEnvelope"
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "get_api_v1_customers_by_reference_id",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request GET \\\n  --url 'https://app.mepagg.com/api/v1/customers/CUST_EXAMPLE_001/' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const response = await fetch('https://app.mepagg.com/api/v1/customers/CUST_EXAMPLE_001/', {\n  method: 'GET',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API'\n  }}\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.get(\n    'https://app.mepagg.com/api/v1/customers/CUST_EXAMPLE_001/',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\"\n},\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/customers/CUST_EXAMPLE_001/',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'GET',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API'],\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      },
      "put": {
        "tags": [
          "Clientes"
        ],
        "summary": "Substituir cliente",
        "description": "Substitui integralmente os dados do cliente informado. Quando houver endpoint inscrito, a Mepagg também envia o webhook `customer.updated`.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CustomerInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Cliente substituído.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerEnvelope"
                }
              }
            }
          },
          "400": {
            "description": "Requisição inválida.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "VALIDATION_ERROR",
                    "message": "Existem campos inválidos na requisição.",
                    "details": {}
                  }
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "put_api_v1_customers_by_reference_id",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request PUT \\\n  --url 'https://app.mepagg.com/api/v1/customers/CUST_EXAMPLE_001/' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const response = await fetch('https://app.mepagg.com/api/v1/customers/CUST_EXAMPLE_001/', {\n  method: 'PUT',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API'\n  }}\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.put(\n    'https://app.mepagg.com/api/v1/customers/CUST_EXAMPLE_001/',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\"\n},\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/customers/CUST_EXAMPLE_001/',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'PUT',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API'],\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      },
      "patch": {
        "tags": [
          "Clientes"
        ],
        "summary": "Atualizar parcialmente cliente",
        "description": "Atualiza apenas os campos enviados no payload. Quando houver endpoint inscrito, a Mepagg também envia o webhook `customer.updated`.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CustomerInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Cliente atualizado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerEnvelope"
                }
              }
            }
          },
          "400": {
            "description": "Requisição inválida.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "VALIDATION_ERROR",
                    "message": "Existem campos inválidos na requisição.",
                    "details": {}
                  }
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "patch_api_v1_customers_by_reference_id",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request PATCH \\\n  --url 'https://app.mepagg.com/api/v1/customers/CUST_EXAMPLE_001/' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const response = await fetch('https://app.mepagg.com/api/v1/customers/CUST_EXAMPLE_001/', {\n  method: 'PATCH',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API'\n  }}\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.patch(\n    'https://app.mepagg.com/api/v1/customers/CUST_EXAMPLE_001/',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\"\n},\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/customers/CUST_EXAMPLE_001/',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'PATCH',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API'],\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      },
      "delete": {
        "tags": [
          "Clientes"
        ],
        "summary": "Remover cliente",
        "description": "Exclui logicamente o cliente informado da conta autenticada. Quando houver endpoint inscrito, a Mepagg também envia o webhook `customer.deleted`.",
        "responses": {
          "200": {
            "description": "Cliente removido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessMessage"
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "delete_api_v1_customers_by_reference_id",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request DELETE \\\n  --url 'https://app.mepagg.com/api/v1/customers/CUST_EXAMPLE_001/' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const response = await fetch('https://app.mepagg.com/api/v1/customers/CUST_EXAMPLE_001/', {\n  method: 'DELETE',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API'\n  }}\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.delete(\n    'https://app.mepagg.com/api/v1/customers/CUST_EXAMPLE_001/',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\"\n},\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/customers/CUST_EXAMPLE_001/',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'DELETE',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API'],\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      }
    },
    "/api/v1/invoices/": {
      "get": {
        "tags": [
          "Faturas"
        ],
        "summary": "Listar faturas",
        "description": "Para interface, priorize `status_label`, `type_label`, `type_display` e `issued_via_label`. Para regras de sistema, filtros e automações, use `status_code`, `type_code` e `issued_via_code`. `type_display` é um alias de interface para `type_label`.\n\n### Emitida via\n\n`Emitida via` representa a origem da emissão da fatura.\n\n- `issued_via`: valor original retornado no payload\n- `issued_via_code`: código estável para filtros, integrações e automações\n- `issued_via_label`: texto amigável para interface\n- `issued_via*` é somente leitura: a Mepagg calcula internamente esse trio e o retorna na resposta e nos webhooks\n\nExemplos:\n- `PANEL` / `panel` / `Painel`\n- `API` / `api` / `API`",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "customer_reference_id",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "start_due_date",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "end_due_date",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/Offset"
          }
        ],
        "responses": {
          "200": {
            "description": "Faturas listadas.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InvoiceListResponse"
                },
                "examples": {
                  "default": {
                    "value": {
                      "count": 1,
                      "results": [
                        {
                          "reference_id": "GLZOX8K19Q40NVLJ6WJ2PRYD7EV653",
                          "status": 2,
                          "status_code": "paid",
                          "status_label": "Paga",
                          "type": 3,
                          "type_code": "oneoff",
                          "type_label": "Avulsa",
                          "type_display": "Avulsa",
                          "issued_via": "API",
                          "issued_via_code": "api",
                          "issued_via_label": "API",
                          "payment_methods": [
                            "boleto",
                            "pix"
                          ],
                          "due_date": "2026-06-15",
                          "total": "5200.00"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "get_api_v1_invoices",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request GET \\\n  --url 'https://app.mepagg.com/api/v1/invoices/?limit=20&offset=0' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const response = await fetch('https://app.mepagg.com/api/v1/invoices/?limit=20&offset=0', {\n  method: 'GET',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API'\n  }}\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.get(\n    'https://app.mepagg.com/api/v1/invoices/?limit=20&offset=0',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\"\n},\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/invoices/?limit=20&offset=0',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'GET',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API'],\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      },
      "post": {
        "tags": [
          "Faturas"
        ],
        "summary": "Criar fatura",
        "description": "Cria uma fatura avulsa com boleto, Pix ou ambos como formas de pagamento.\n\n### Regras importantes\n- a cobranca pode ter um ou varios itens\n- o total da cobranca e calculado pela soma dos itens antes dos ajustes financeiros\n- o valor minimo total para criacao e R$ 5,00\n- o vencimento nao pode ser retroativo\n- para boleto e/ou pix, o vencimento no mesmo dia e bloqueado a partir das 20h\n- `fees` e `fines` sao valores monetarios em reais\n- `discount` depende de `discount_type`\n- use `Idempotency-Key` para impedir duplicidade em retries",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request POST \\\n  --url 'https://app.mepagg.com/api/v1/invoices/?limit=20&offset=0' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API' \\\n  --header 'Idempotency-Key: 8f5b5820-2d19-4be3-8f57-64c3d5d9e2f7'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const response = await fetch('https://app.mepagg.com/api/v1/invoices/?limit=20&offset=0', {\n  method: 'POST',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API',\n    'Idempotency-Key': '8f5b5820-2d19-4be3-8f57-64c3d5d9e2f7'\n  }}\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.post(\n    'https://app.mepagg.com/api/v1/invoices/?limit=20&offset=0',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\",\n    \"Idempotency-Key\": \"8f5b5820-2d19-4be3-8f57-64c3d5d9e2f7\"\n},\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/invoices/?limit=20&offset=0',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'POST',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API', 'Idempotency-Key: 8f5b5820-2d19-4be3-8f57-64c3d5d9e2f7'],\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InvoiceInput"
              },
              "examples": {
                "boleto-e-pix": {
                  "value": {
                    "customer_reference_id": "CUST_EXAMPLE_001",
                    "due_date": "2026-06-30",
                    "payment_methods": [
                      "boleto",
                      "pix"
                    ],
                    "discount_type": "FIXED_VALUE",
                    "discount": "10.00",
                    "items": [
                      {
                        "description": "Mensalidade da plataforma",
                        "quantity": 1,
                        "price": "120.00"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Fatura criada.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InvoiceCreateResponse"
                },
                "examples": {
                  "default": {
                    "value": {
                      "success": true,
                      "invoice": {
                        "reference_id": "GLZOX8K19Q40NVLJ6WJ2PRYD7EV653",
                        "status_code": "pending",
                        "status_label": "Pendente",
                        "type_code": "oneoff",
                        "type_label": "Avulsa",
                        "type_display": "Avulsa",
                        "issued_via": "API",
                        "issued_via_code": "api",
                        "issued_via_label": "API",
                        "payment_methods": [
                          "boleto",
                          "pix"
                        ],
                        "total": "110.00"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "post_api_v1_invoices"
      }
    },
    "/api/v1/invoices/{reference_id}/": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ReferenceId"
        }
      ],
      "get": {
        "tags": [
          "Faturas"
        ],
        "summary": "Detalhar fatura",
        "description": "Consulta o estado atual da fatura.\n\n### type_display\n\n`type_display` é um alias de interface para `type_label`. Use `type_display` ou `type_label` para exibição visual e `type_code` para filtros, automações e regras de negócio.\n\n### Emitida via\n\n`Emitida via` é a leitura humana da origem da emissão da fatura.\n\n| Campo | Uso |\n| --- | --- |\n| `issued_via` | Valor original retornado no payload |\n| `issued_via_code` | Regras de negócio, filtros, integrações e automações |\n| `issued_via_label` | Exibição visual em interface |\n\nEsse trio é somente leitura: a origem da emissão é calculada internamente pela Mepagg e retornada na resposta e nos webhooks.\n\nExemplos visíveis:\n- `PANEL` / `panel` / `Painel`\n- `API` / `api` / `API`\n\n### Campos importantes\n- `status_code` e `status_label`\n- `type_code`, `type_label` e `type_display`\n- `issued_via`, `issued_via_code` e `issued_via_label`\n- `amount_paid` e `paid_at`\n- `public_url` e `public_boleto_url`\n- `boleto` e `pix`",
        "responses": {
          "200": {
            "description": "Fatura localizada.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InvoiceEnvelope"
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "get_api_v1_invoices_by_reference_id",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request GET \\\n  --url 'https://app.mepagg.com/api/v1/invoices/INV_EXAMPLE_001/' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const response = await fetch('https://app.mepagg.com/api/v1/invoices/INV_EXAMPLE_001/', {\n  method: 'GET',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API'\n  }}\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.get(\n    'https://app.mepagg.com/api/v1/invoices/INV_EXAMPLE_001/',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\"\n},\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/invoices/INV_EXAMPLE_001/',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'GET',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API'],\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      }
    },
    "/api/v1/invoices/{reference_id}/cancel/": {
      "post": {
        "tags": [
          "Faturas"
        ],
        "summary": "Cancelar fatura",
        "description": "Cancela uma fatura ainda elegível para cancelamento. Envie `Idempotency-Key` em retries do sistema da conta.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ReferenceId"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "responses": {
          "200": {
            "description": "Fatura cancelada.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessMessage"
                }
              }
            }
          },
          "400": {
            "description": "Requisição inválida.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "VALIDATION_ERROR",
                    "message": "Existem campos inválidos na requisição.",
                    "details": {}
                  }
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "post_api_v1_invoices_by_reference_id_cancel",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InvoiceCancelInput"
              },
              "example": {
                "cancelled_reason": "Cobranca substituida por nova emissao."
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request POST \\\n  --url 'https://app.mepagg.com/api/v1/invoices/INV_EXAMPLE_001/cancel/' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API' \\\n  --header 'Content-Type: application/json' \\\n  --header 'Idempotency-Key: 8f5b5820-2d19-4be3-8f57-64c3d5d9e2f7' \\\n  --data '{\n  \"cancelled_reason\": \"Cobranca substituida por nova emissao.\"\n}'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const payload = {\n  \"cancelled_reason\": \"Cobranca substituida por nova emissao.\"\n};\n\nconst response = await fetch('https://app.mepagg.com/api/v1/invoices/INV_EXAMPLE_001/cancel/', {\n  method: 'POST',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API',\n    'Content-Type': 'application/json',\n    'Idempotency-Key': '8f5b5820-2d19-4be3-8f57-64c3d5d9e2f7'\n  },\n  body: JSON.stringify(payload)\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\npayload = {\n    \"cancelled_reason\": \"Cobranca substituida por nova emissao.\"\n}\n\nresponse = requests.post(\n    'https://app.mepagg.com/api/v1/invoices/INV_EXAMPLE_001/cancel/',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\",\n    \"Content-Type\": \"application/json\",\n    \"Idempotency-Key\": \"8f5b5820-2d19-4be3-8f57-64c3d5d9e2f7\"\n},\n    json=payload,\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$payload = [\n    'cancelled_reason' => 'Cobranca substituida por nova emissao.'\n];\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/invoices/INV_EXAMPLE_001/cancel/',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'POST',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API', 'Content-Type: application/json', 'Idempotency-Key: 8f5b5820-2d19-4be3-8f57-64c3d5d9e2f7'],\n    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      }
    },
    "/api/v1/invoices/{reference_id}/refund/": {
      "post": {
        "tags": [
          "Faturas"
        ],
        "summary": "Solicitar estorno",
        "description": "Solicita estorno de uma fatura paga quando a regra operacional permitir. Envie `Idempotency-Key` em retries do sistema da conta.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ReferenceId"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "responses": {
          "200": {
            "description": "Estorno solicitado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessMessage"
                }
              }
            }
          },
          "400": {
            "description": "Requisição inválida.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "VALIDATION_ERROR",
                    "message": "Existem campos inválidos na requisição.",
                    "details": {}
                  }
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "post_api_v1_invoices_by_reference_id_refund",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InvoiceRefundInput"
              },
              "example": {
                "refund_reason": "Pagamento recebido em duplicidade."
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request POST \\\n  --url 'https://app.mepagg.com/api/v1/invoices/INV_EXAMPLE_001/refund/' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API' \\\n  --header 'Content-Type: application/json' \\\n  --header 'Idempotency-Key: 8f5b5820-2d19-4be3-8f57-64c3d5d9e2f7' \\\n  --data '{\n  \"refund_reason\": \"Pagamento recebido em duplicidade.\"\n}'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const payload = {\n  \"refund_reason\": \"Pagamento recebido em duplicidade.\"\n};\n\nconst response = await fetch('https://app.mepagg.com/api/v1/invoices/INV_EXAMPLE_001/refund/', {\n  method: 'POST',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API',\n    'Content-Type': 'application/json',\n    'Idempotency-Key': '8f5b5820-2d19-4be3-8f57-64c3d5d9e2f7'\n  },\n  body: JSON.stringify(payload)\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\npayload = {\n    \"refund_reason\": \"Pagamento recebido em duplicidade.\"\n}\n\nresponse = requests.post(\n    'https://app.mepagg.com/api/v1/invoices/INV_EXAMPLE_001/refund/',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\",\n    \"Content-Type\": \"application/json\",\n    \"Idempotency-Key\": \"8f5b5820-2d19-4be3-8f57-64c3d5d9e2f7\"\n},\n    json=payload,\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$payload = [\n    'refund_reason' => 'Pagamento recebido em duplicidade.'\n];\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/invoices/INV_EXAMPLE_001/refund/',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'POST',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API', 'Content-Type: application/json', 'Idempotency-Key: 8f5b5820-2d19-4be3-8f57-64c3d5d9e2f7'],\n    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      }
    },
    "/api/v1/invoices/{reference_id}/second-copy/": {
      "get": {
        "tags": [
          "Faturas"
        ],
        "summary": "Consultar segunda via",
        "description": "Retorna os dados atualizados para consulta da segunda via da cobrança.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ReferenceId"
          }
        ],
        "responses": {
          "200": {
            "description": "Segunda via consultada.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InvoiceEnvelope"
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "get_api_v1_invoices_by_reference_id_second_copy",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request GET \\\n  --url 'https://app.mepagg.com/api/v1/invoices/INV_EXAMPLE_001/second-copy/' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const response = await fetch('https://app.mepagg.com/api/v1/invoices/INV_EXAMPLE_001/second-copy/', {\n  method: 'GET',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API'\n  }}\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.get(\n    'https://app.mepagg.com/api/v1/invoices/INV_EXAMPLE_001/second-copy/',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\"\n},\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/invoices/INV_EXAMPLE_001/second-copy/',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'GET',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API'],\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      }
    },
    "/api/v1/invoices/{reference_id}/resend-email/": {
      "post": {
        "tags": [
          "Faturas"
        ],
        "summary": "Reenviar e-mail da fatura",
        "description": "Reenvia a comunicação de cobrança por e-mail para a fatura informada.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ReferenceId"
          }
        ],
        "responses": {
          "200": {
            "description": "E-mail reenviado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessMessage"
                }
              }
            }
          },
          "400": {
            "description": "Requisição inválida.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "VALIDATION_ERROR",
                    "message": "Existem campos inválidos na requisição.",
                    "details": {}
                  }
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "post_api_v1_invoices_by_reference_id_resend_email",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request POST \\\n  --url 'https://app.mepagg.com/api/v1/invoices/INV_EXAMPLE_001/resend-email/' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const response = await fetch('https://app.mepagg.com/api/v1/invoices/INV_EXAMPLE_001/resend-email/', {\n  method: 'POST',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API'\n  }}\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.post(\n    'https://app.mepagg.com/api/v1/invoices/INV_EXAMPLE_001/resend-email/',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\"\n},\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/invoices/INV_EXAMPLE_001/resend-email/',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'POST',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API'],\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      }
    },
    "/api/v1/invoices/{reference_id}/resend-sms/": {
      "post": {
        "tags": [
          "Faturas"
        ],
        "summary": "Reenviar SMS da fatura",
        "description": "Reenvia a comunicação de cobrança por SMS para a fatura informada.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ReferenceId"
          }
        ],
        "responses": {
          "200": {
            "description": "SMS reenviado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessMessage"
                }
              }
            }
          },
          "400": {
            "description": "Requisição inválida.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "VALIDATION_ERROR",
                    "message": "Existem campos inválidos na requisição.",
                    "details": {}
                  }
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "post_api_v1_invoices_by_reference_id_resend_sms",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request POST \\\n  --url 'https://app.mepagg.com/api/v1/invoices/INV_EXAMPLE_001/resend-sms/' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const response = await fetch('https://app.mepagg.com/api/v1/invoices/INV_EXAMPLE_001/resend-sms/', {\n  method: 'POST',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API'\n  }}\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.post(\n    'https://app.mepagg.com/api/v1/invoices/INV_EXAMPLE_001/resend-sms/',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\"\n},\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/invoices/INV_EXAMPLE_001/resend-sms/',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'POST',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API'],\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      }
    },
    "/api/v1/subscriptions/": {
      "get": {
        "tags": [
          "Assinaturas"
        ],
        "summary": "Listar assinaturas",
        "description": "Lista as assinaturas da conta autenticada.",
        "responses": {
          "200": {
            "description": "Assinaturas listadas.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubscriptionListResponse"
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "get_api_v1_subscriptions",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request GET \\\n  --url 'https://app.mepagg.com/api/v1/subscriptions/' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const response = await fetch('https://app.mepagg.com/api/v1/subscriptions/', {\n  method: 'GET',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API'\n  }}\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.get(\n    'https://app.mepagg.com/api/v1/subscriptions/',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\"\n},\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/subscriptions/',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'GET',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API'],\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      },
      "post": {
        "tags": [
          "Assinaturas"
        ],
        "summary": "Criar assinatura",
        "description": "Cria uma assinatura para recorrencia previsivel.\n\n### Regras importantes\n- a assinatura pode ter um ou varios itens recorrentes\n- o `total_amount` retornado corresponde a soma dos itens\n- o valor minimo total para criacao e R$ 5,00\n- `payment_methods` e obrigatorio na criacao publica\n- use `interval` para a periodicidade da recorrencia\n- `cycles` aceita valores entre 0 e 120\n- `last_due_date` define o ultimo vencimento previsto",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SubscriptionInput"
              },
              "example": {
                "customer_reference_id": "CUST_EXAMPLE_001",
                "interval": "MONTHLY",
                "cycles": 12,
                "last_due_date": "2027-06-10",
                "status": "ACTIVE",
                "payment_methods": [
                  "boleto",
                  "pix"
                ],
                "fees": "1.00",
                "fines": "2.00",
                "discount_type": "FIXED_VALUE",
                "discount": "10.00",
                "items": [
                  {
                    "description": "Licenca principal",
                    "qty": 1,
                    "price": "49.90"
                  },
                  {
                    "description": "Usuario adicional",
                    "quantity": 2,
                    "price": "15.00"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Assinatura criada.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubscriptionEnvelope"
                }
              }
            }
          },
          "400": {
            "description": "Requisição inválida.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "VALIDATION_ERROR",
                    "message": "Existem campos inválidos na requisição.",
                    "details": {}
                  }
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "post_api_v1_subscriptions",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request POST \\\n  --url 'https://app.mepagg.com/api/v1/subscriptions/' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API' \\\n  --header 'Content-Type: application/json' \\\n  --data '{\n  \"customer_reference_id\": \"CUST_EXAMPLE_001\",\n  \"interval\": \"MONTHLY\",\n  \"cycles\": 12,\n  \"last_due_date\": \"2027-06-10\",\n  \"status\": \"ACTIVE\",\n  \"payment_methods\": [\n    \"boleto\",\n    \"pix\"\n  ],\n  \"fees\": \"1.00\",\n  \"fines\": \"2.00\",\n  \"discount_type\": \"FIXED_VALUE\",\n  \"discount\": \"10.00\",\n  \"items\": [\n    {\n      \"description\": \"Licenca principal\",\n      \"qty\": 1,\n      \"price\": \"49.90\"\n    },\n    {\n      \"description\": \"Usuario adicional\",\n      \"quantity\": 2,\n      \"price\": \"15.00\"\n    }\n  ]\n}'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const payload = {\n  \"customer_reference_id\": \"CUST_EXAMPLE_001\",\n  \"interval\": \"MONTHLY\",\n  \"cycles\": 12,\n  \"last_due_date\": \"2027-06-10\",\n  \"status\": \"ACTIVE\",\n  \"payment_methods\": [\n    \"boleto\",\n    \"pix\"\n  ],\n  \"fees\": \"1.00\",\n  \"fines\": \"2.00\",\n  \"discount_type\": \"FIXED_VALUE\",\n  \"discount\": \"10.00\",\n  \"items\": [\n    {\n      \"description\": \"Licenca principal\",\n      \"qty\": 1,\n      \"price\": \"49.90\"\n    },\n    {\n      \"description\": \"Usuario adicional\",\n      \"quantity\": 2,\n      \"price\": \"15.00\"\n    }\n  ]\n};\n\nconst response = await fetch('https://app.mepagg.com/api/v1/subscriptions/', {\n  method: 'POST',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API',\n    'Content-Type': 'application/json'\n  },\n  body: JSON.stringify(payload)\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\npayload = {\n    \"customer_reference_id\": \"CUST_EXAMPLE_001\",\n    \"interval\": \"MONTHLY\",\n    \"cycles\": 12,\n    \"last_due_date\": \"2027-06-10\",\n    \"status\": \"ACTIVE\",\n    \"payment_methods\": [\n        \"boleto\",\n        \"pix\"\n    ],\n    \"fees\": \"1.00\",\n    \"fines\": \"2.00\",\n    \"discount_type\": \"FIXED_VALUE\",\n    \"discount\": \"10.00\",\n    \"items\": [\n        {\n            \"description\": \"Licenca principal\",\n            \"qty\": 1,\n            \"price\": \"49.90\"\n        },\n        {\n            \"description\": \"Usuario adicional\",\n            \"quantity\": 2,\n            \"price\": \"15.00\"\n        }\n    ]\n}\n\nresponse = requests.post(\n    'https://app.mepagg.com/api/v1/subscriptions/',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\",\n    \"Content-Type\": \"application/json\"\n},\n    json=payload,\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$payload = [\n    'customer_reference_id' => 'CUST_EXAMPLE_001',\n    'interval' => 'MONTHLY',\n    'cycles' => 12,\n    'last_due_date' => '2027-06-10',\n    'status' => 'ACTIVE',\n    'payment_methods' => [\n        'boleto',\n        'pix'\n    ],\n    'fees' => '1.00',\n    'fines' => '2.00',\n    'discount_type' => 'FIXED_VALUE',\n    'discount' => '10.00',\n    'items' => [\n        [\n            'description' => 'Licenca principal',\n            'qty' => 1,\n            'price' => '49.90'\n        ],\n        [\n            'description' => 'Usuario adicional',\n            'quantity' => 2,\n            'price' => '15.00'\n        ]\n    ]\n];\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/subscriptions/',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'POST',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API', 'Content-Type: application/json'],\n    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      }
    },
    "/api/v1/subscriptions/{reference_id}/": {
      "get": {
        "tags": [
          "Assinaturas"
        ],
        "summary": "Detalhar assinatura",
        "description": "Retorna os dados principais da assinatura informada.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ReferenceId"
          }
        ],
        "responses": {
          "200": {
            "description": "Assinatura localizada.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubscriptionEnvelope"
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "get_api_v1_subscriptions_by_reference_id",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request GET \\\n  --url 'https://app.mepagg.com/api/v1/subscriptions/SUB_EXAMPLE_001/' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const response = await fetch('https://app.mepagg.com/api/v1/subscriptions/SUB_EXAMPLE_001/', {\n  method: 'GET',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API'\n  }}\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.get(\n    'https://app.mepagg.com/api/v1/subscriptions/SUB_EXAMPLE_001/',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\"\n},\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/subscriptions/SUB_EXAMPLE_001/',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'GET',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API'],\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      }
    },
    "/api/v1/subscriptions/{reference_id}/status/": {
      "post": {
        "tags": [
          "Assinaturas"
        ],
        "summary": "Alterar status da assinatura",
        "description": "Altera o status operacional da assinatura informada.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ReferenceId"
          }
        ],
        "responses": {
          "200": {
            "description": "Status alterado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessMessage"
                }
              }
            }
          },
          "400": {
            "description": "Requisição inválida.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "VALIDATION_ERROR",
                    "message": "Existem campos inválidos na requisição.",
                    "details": {}
                  }
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "post_api_v1_subscriptions_by_reference_id_status",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SubscriptionStatusInput"
              },
              "example": {
                "status": "SUSPENDED"
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request POST \\\n  --url 'https://app.mepagg.com/api/v1/subscriptions/SUB_EXAMPLE_001/status/' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API' \\\n  --header 'Content-Type: application/json' \\\n  --data '{\n  \"status\": \"SUSPENDED\"\n}'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const payload = {\n  \"status\": \"SUSPENDED\"\n};\n\nconst response = await fetch('https://app.mepagg.com/api/v1/subscriptions/SUB_EXAMPLE_001/status/', {\n  method: 'POST',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API',\n    'Content-Type': 'application/json'\n  },\n  body: JSON.stringify(payload)\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\npayload = {\n    \"status\": \"SUSPENDED\"\n}\n\nresponse = requests.post(\n    'https://app.mepagg.com/api/v1/subscriptions/SUB_EXAMPLE_001/status/',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\",\n    \"Content-Type\": \"application/json\"\n},\n    json=payload,\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$payload = [\n    'status' => 'SUSPENDED'\n];\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/subscriptions/SUB_EXAMPLE_001/status/',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'POST',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API', 'Content-Type: application/json'],\n    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      }
    },
    "/api/v1/carnes/": {
      "get": {
        "tags": [
          "Carnês"
        ],
        "summary": "Listar carnês",
        "description": "Lista os carnês vinculados à conta autenticada.",
        "responses": {
          "200": {
            "description": "Carnês listados.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CarneListResponse"
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "get_api_v1_carnes",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request GET \\\n  --url 'https://app.mepagg.com/api/v1/carnes/' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const response = await fetch('https://app.mepagg.com/api/v1/carnes/', {\n  method: 'GET',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API'\n  }}\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.get(\n    'https://app.mepagg.com/api/v1/carnes/',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\"\n},\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/carnes/',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'GET',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API'],\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      },
      "post": {
        "tags": [
          "Carnês"
        ],
        "summary": "Criar carnê",
        "description": "Cria um carne com multiplas parcelas para o cliente informado.\n\n### Regras importantes\n- voce pode criar com `description` + `total_amount` ou com `items`\n- quando `items` e enviado, o carne aceita apenas um item\n- a API calcula o total a partir desse item e distribui esse valor entre as parcelas\n- o valor minimo total para criacao e R$ 5,00\n- o vencimento nao pode ser retroativo\n- para boleto e/ou pix, o vencimento no mesmo dia e bloqueado a partir das 20h\n- `schedule` e opcional, mas quando enviado deve ter a mesma quantidade de `installments`\n- cada parcela fica disponivel em `carne.invoices` com estrutura de fatura",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CarneInput"
              },
              "example": {
                "customer_reference_id": "CUST_EXAMPLE_001",
                "description": "Carne de implantacao e licenca",
                "installments": 3,
                "due_date": "2026-07-10",
                "payment_methods": [
                  "boleto",
                  "pix"
                ],
                "fees": "1.00",
                "fines": "2.00",
                "discount_type": "PERCENTAGE",
                "discount": "5.00",
                "items": [
                  {
                    "description": "Implantacao inicial",
                    "qty": 1,
                    "price": "90.00"
                  },
                  {
                    "description": "Licenca complementar",
                    "quantity": 2,
                    "price": "15.00"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Carnê criado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CarneEnvelope"
                }
              }
            }
          },
          "400": {
            "description": "Requisição inválida.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "VALIDATION_ERROR",
                    "message": "Existem campos inválidos na requisição.",
                    "details": {}
                  }
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "post_api_v1_carnes",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request POST \\\n  --url 'https://app.mepagg.com/api/v1/carnes/' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API' \\\n  --header 'Content-Type: application/json' \\\n  --data '{\n  \"customer_reference_id\": \"CUST_EXAMPLE_001\",\n  \"description\": \"Carne de implantacao\",\n  \"installments\": 3,\n  \"due_date\": \"2026-07-10\",\n  \"payment_methods\": [\n    \"boleto\",\n    \"pix\"\n  ],\n  \"fees\": \"1.00\",\n  \"fines\": \"2.00\",\n  \"discount_type\": \"PERCENTAGE\",\n  \"discount\": \"5.00\",\n  \"items\": [\n    {\n      \"description\": \"Implantacao inicial\",\n      \"quantity\": 1,\n      \"price\": \"120.00\"\n    }\n  ]\n}'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const payload = {\n  \"customer_reference_id\": \"CUST_EXAMPLE_001\",\n  \"description\": \"Carne de implantacao\",\n  \"installments\": 3,\n  \"due_date\": \"2026-07-10\",\n  \"payment_methods\": [\n    \"boleto\",\n    \"pix\"\n  ],\n  \"fees\": \"1.00\",\n  \"fines\": \"2.00\",\n  \"discount_type\": \"PERCENTAGE\",\n  \"discount\": \"5.00\",\n  \"items\": [\n    {\n      \"description\": \"Implantacao inicial\",\n      \"quantity\": 1,\n      \"price\": \"120.00\"\n    }\n  ]\n};\n\nconst response = await fetch('https://app.mepagg.com/api/v1/carnes/', {\n  method: 'POST',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API',\n    'Content-Type': 'application/json'\n  },\n  body: JSON.stringify(payload)\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\npayload = {\n    \"customer_reference_id\": \"CUST_EXAMPLE_001\",\n    \"description\": \"Carne de implantacao\",\n    \"installments\": 3,\n    \"due_date\": \"2026-07-10\",\n    \"payment_methods\": [\n        \"boleto\",\n        \"pix\"\n    ],\n    \"fees\": \"1.00\",\n    \"fines\": \"2.00\",\n    \"discount_type\": \"PERCENTAGE\",\n    \"discount\": \"5.00\",\n    \"items\": [\n        {\n            \"description\": \"Implantacao inicial\",\n            \"quantity\": 1,\n            \"price\": \"120.00\"\n        }\n    ]\n}\n\nresponse = requests.post(\n    'https://app.mepagg.com/api/v1/carnes/',\n    headers={\n        \"X-API-KEY\": \"SUA_CHAVE_DE_API\",\n        \"Content-Type\": \"application/json\"\n    },\n    json=payload,\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$payload = [\n    'customer_reference_id' => 'CUST_EXAMPLE_001',\n    'description' => 'Carne de implantacao',\n    'installments' => 3,\n    'due_date' => '2026-07-10',\n    'payment_methods' => [\n        'boleto',\n        'pix'\n    ],\n    'fees' => '1.00',\n    'fines' => '2.00',\n    'discount_type' => 'PERCENTAGE',\n    'discount' => '5.00',\n    'items' => [\n        [\n            'description' => 'Implantacao inicial',\n            'quantity' => 1,\n            'price' => '120.00'\n        ]\n    ]\n];\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/carnes/',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'POST',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API', 'Content-Type: application/json'],\n    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      }
    },
    "/api/v1/carnes/{reference_id}/": {
      "get": {
        "tags": [
          "Carnês"
        ],
        "summary": "Detalhar carnê",
        "description": "Retorna a visualização completa do carnê informado, incluindo resumo consolidado, `public_url` do carnê e a lista completa de parcelas em `carne.invoices`. Cada item do array representa uma parcela individual com a mesma estrutura base usada na API de faturas, inclusive com links públicos e campos estruturados de boleto e Pix quando disponíveis.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ReferenceId"
          }
        ],
        "responses": {
          "200": {
            "description": "Carnê localizado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CarneEnvelope"
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "get_api_v1_carnes_by_reference_id",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request GET \\\n  --url 'https://app.mepagg.com/api/v1/carnes/CARNE_EXAMPLE_001/' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const response = await fetch('https://app.mepagg.com/api/v1/carnes/CARNE_EXAMPLE_001/', {\n  method: 'GET',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API'\n  }}\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.get(\n    'https://app.mepagg.com/api/v1/carnes/CARNE_EXAMPLE_001/',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\"\n},\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/carnes/CARNE_EXAMPLE_001/',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'GET',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API'],\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      }
    },
    "/api/v1/carnes/{reference_id}/cancel/": {
      "post": {
        "tags": [
          "Carnês"
        ],
        "summary": "Cancelar carnê",
        "description": "Cancela o carnê informado quando a regra operacional permitir. Além dos `invoice.cancelled` de cada parcela, a Mepagg também envia o webhook consolidado `carne.cancelled` quando houver endpoint inscrito.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ReferenceId"
          }
        ],
        "responses": {
          "200": {
            "description": "Carnê cancelado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessMessage"
                }
              }
            }
          },
          "400": {
            "description": "Requisição inválida.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "VALIDATION_ERROR",
                    "message": "Existem campos inválidos na requisição.",
                    "details": {}
                  }
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "post_api_v1_carnes_by_reference_id_cancel",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CarneCancelInput"
              },
              "example": {
                "cancelled_reason": "Solicitado pelo cliente."
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request POST \\\n  --url 'https://app.mepagg.com/api/v1/carnes/CARNE_EXAMPLE_001/cancel/' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API' \\\n  --header 'Content-Type: application/json' \\\n  --data '{\n  \"cancelled_reason\": \"Solicitado pelo cliente.\"\n}'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const payload = {\n  \"cancelled_reason\": \"Solicitado pelo cliente.\"\n};\n\nconst response = await fetch('https://app.mepagg.com/api/v1/carnes/CARNE_EXAMPLE_001/cancel/', {\n  method: 'POST',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API',\n    'Content-Type': 'application/json'\n  },\n  body: JSON.stringify(payload)\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\npayload = {\n    \"cancelled_reason\": \"Solicitado pelo cliente.\"\n}\n\nresponse = requests.post(\n    'https://app.mepagg.com/api/v1/carnes/CARNE_EXAMPLE_001/cancel/',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\",\n    \"Content-Type\": \"application/json\"\n},\n    json=payload,\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$payload = [\n    'cancelled_reason' => 'Solicitado pelo cliente.'\n];\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/carnes/CARNE_EXAMPLE_001/cancel/',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'POST',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API', 'Content-Type: application/json'],\n    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      }
    },
    "/api/v1/carnes/{reference_id}/send-email/": {
      "post": {
        "tags": [
          "Carnês"
        ],
        "summary": "Enviar carnê por e-mail",
        "description": "Envia o carnê para o e-mail cadastrado do cliente.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ReferenceId"
          }
        ],
        "responses": {
          "200": {
            "description": "Carnê enviado por e-mail.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessMessage"
                }
              }
            }
          },
          "400": {
            "description": "Requisição inválida.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "VALIDATION_ERROR",
                    "message": "Existem campos inválidos na requisição.",
                    "details": {}
                  }
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "post_api_v1_carnes_by_reference_id_send_email",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request POST \\\n  --url 'https://app.mepagg.com/api/v1/carnes/CARNE_EXAMPLE_001/send-email/' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const response = await fetch('https://app.mepagg.com/api/v1/carnes/CARNE_EXAMPLE_001/send-email/', {\n  method: 'POST',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API'\n  }}\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.post(\n    'https://app.mepagg.com/api/v1/carnes/CARNE_EXAMPLE_001/send-email/',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\"\n},\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/carnes/CARNE_EXAMPLE_001/send-email/',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'POST',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API'],\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      }
    },
    "/api/v1/payment-links/": {
      "get": {
        "tags": [
          "Links de pagamentos"
        ],
        "summary": "Listar links de pagamento",
        "description": "Lista os links de pagamento da conta autenticada.\n\n### Filtros disponíveis\n\n| Parâmetro | Tipo | Obrigatório | Uso |\n| --- | --- | --- | --- |\n| `q` | string | Não | Busca textual por descrição do produto ou serviço. |\n| `status` | string | Não | Filtra por `active`, `expired` ou `limit_reached`. |\n| `due_option` | string | Não | Filtra pela regra de validade do link. |\n| `has_defined_amount` | boolean | Não | Filtra links com valor fixo (`true`) ou sem valor (`false`). |\n| `limit` | integer | Não | Paginação entre `1` e `200`. |\n| `offset` | integer | Não | Deslocamento da paginação. |\n\n### Observações operacionais\n\n- `status_code` é o campo recomendado para filtros e automações.\n- `due_at` é a data e hora final efetiva do link, já considerando a hora real da criação.\n- Quando `due_option=none`, use `validity_display`, `invoice_due_option_label` e `invoice_due_summary` para exibir a regra do checkout sem depender de lógica adicional.\n- `used_count`, `remaining_uses` e `usage_limit_display` ajudam a monitorar consumo do link sem consultar faturas individualmente.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Busca textual por descrição do link."
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "active",
                "expired",
                "limit_reached"
              ]
            },
            "description": "Filtra pelo status calculado do link."
          },
          {
            "name": "due_option",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "today",
                "1_day",
                "5_days",
                "10_days",
                "15_days",
                "30_days",
                "custom",
                "none"
              ]
            },
            "description": "Filtra pela regra de validade do link."
          },
          {
            "name": "has_defined_amount",
            "in": "query",
            "schema": {
              "type": "boolean"
            },
            "description": "Filtra links com valor fixo ou sem valor definido."
          },
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/Offset"
          }
        ],
        "responses": {
          "200": {
            "description": "Links listados.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentLinkListResponse"
                },
                "example": {
                  "success": true,
                  "total": 2,
                  "count": 2,
                  "offset": 0,
                  "limit": 20,
                  "has_more": false,
                  "next_offset": null,
                  "results": [
                    {
                      "id": 91,
                      "public_token": "4dd78029-fb39-4c52-b0e6-2bc748d2832b",
                      "description": "Adesao plano enterprise",
                      "has_defined_amount": true,
                      "amount": "249.90",
                      "due_option": "15_days",
                      "due_option_label": "15 dias",
                      "custom_due_days": null,
                      "invoice_due_option": null,
                      "invoice_due_option_label": null,
                      "invoice_custom_due_days": null,
                      "validity_display": "15 dias",
                      "invoice_due_summary": "Mesmo prazo do link",
                      "usage_limit_mode": "limited",
                      "usage_limit_mode_label": "Definir limite",
                      "usage_limit": 3,
                      "has_usage_limit": true,
                      "used_count": 1,
                      "remaining_uses": 2,
                      "usage_limit_display": "1 de 3",
                      "due_date": "2026-08-02",
                      "due_at": "2026-08-02T14:30:00-03:00",
                      "is_active": true,
                      "can_generate_invoice": true,
                      "status_code": "active",
                      "status_label": "Ativo",
                      "issued_via": "API",
                      "issued_via_code": "api",
                      "issued_via_label": "API",
                      "payment_methods": [
                        {
                          "id": 11,
                          "name": "Boleto",
                          "slug": "boleto"
                        },
                        {
                          "id": 12,
                          "name": "Pix",
                          "slug": "pix"
                        }
                      ],
                      "payment_methods_display": "Boleto, Pix",
                      "public_url": "https://app.mepagg.com/link/4dd78029-fb39-4c52-b0e6-2bc748d2832b/",
                      "public_urls": {
                        "checkout": "https://app.mepagg.com/link/4dd78029-fb39-4c52-b0e6-2bc748d2832b/"
                      },
                      "created_at": "2026-07-18T14:30:00-03:00",
                      "updated_at": "2026-07-18T14:30:00-03:00"
                    },
                    {
                      "id": 92,
                      "public_token": "7a325d2d-4a3f-4039-8cd7-91aeb5cc1f34",
                      "description": "Link sem vencimento para doacao recorrente",
                      "has_defined_amount": false,
                      "amount": null,
                      "due_option": "none",
                      "due_option_label": "Sem vencimento",
                      "custom_due_days": null,
                      "invoice_due_option": "20_days",
                      "invoice_due_option_label": "20 dias",
                      "invoice_custom_due_days": null,
                      "validity_display": "Sem vencimento",
                      "invoice_due_summary": "20 dias após a criação",
                      "usage_limit_mode": "unlimited",
                      "usage_limit_mode_label": "Uso ilimitado",
                      "usage_limit": null,
                      "has_usage_limit": false,
                      "used_count": 0,
                      "remaining_uses": null,
                      "usage_limit_display": "Ilimitado",
                      "due_date": null,
                      "due_at": null,
                      "is_active": true,
                      "can_generate_invoice": true,
                      "status_code": "active",
                      "status_label": "Ativo",
                      "issued_via": "PANEL",
                      "issued_via_code": "panel",
                      "issued_via_label": "Painel",
                      "payment_methods": [
                        {
                          "id": 12,
                          "name": "Pix",
                          "slug": "pix"
                        }
                      ],
                      "payment_methods_display": "Pix",
                      "public_url": "https://app.mepagg.com/link/7a325d2d-4a3f-4039-8cd7-91aeb5cc1f34/",
                      "public_urls": {
                        "checkout": "https://app.mepagg.com/link/7a325d2d-4a3f-4039-8cd7-91aeb5cc1f34/"
                      },
                      "created_at": "2026-07-18T09:15:00-03:00",
                      "updated_at": "2026-07-18T09:15:00-03:00"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "message": "Chave de API inválida ou ausente."
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "message": "Muitas requisições em sequência. Tente novamente em instantes."
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "message": "Erro interno ao processar a requisição."
                }
              }
            }
          }
        },
        "operationId": "get_api_v1_payment_links",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request GET \\\n  --url 'https://app.mepagg.com/api/v1/payment-links/?status=active&limit=20&offset=0' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const response = await fetch('https://app.mepagg.com/api/v1/payment-links/?status=active&limit=20&offset=0', {\n  method: 'GET',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API'\n  }\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.get(\n    'https://app.mepagg.com/api/v1/payment-links/?status=active&limit=20&offset=0',\n    headers={\n        'X-API-KEY': 'SUA_CHAVE_DE_API'\n    },\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/payment-links/?status=active&limit=20&offset=0',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'GET',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API'],\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      },
      "post": {
        "tags": [
          "Links de pagamentos"
        ],
        "summary": "Criar link de pagamento",
        "description": "Cria um novo link público de cobrança.\n\n### Regras importantes\n\n- Quando `link_type=fixed`, `amount` se torna obrigatório e o valor mínimo é `R$ 5,00`.\n- Quando `link_type=free`, o payload deve omitir `amount` ou enviar `null`; o valor será informado pelo cliente na tela pública.\n- Quando `due_option=custom`, envie `custom_due_days` entre `1` e `29`.\n- Quando `due_option=none`, envie `invoice_due_option` para definir em quantos dias vence cada fatura gerada pelo checkout.\n- Quando `invoice_due_option=custom`, envie `invoice_custom_due_days` entre `1` e `29`.\n- Quando `usage_limit_mode=limited`, envie `usage_limit` maior que `0`.\n- Você pode enviar `payment_methods` com slugs ou `payment_method_ids` com IDs internos.\n- Não envie `issued_via`, `issued_via_code` nem `issued_via_label`; a Mepagg calcula a origem real da emissão internamente.\n- `POST /api/v1/payment-links/` aceita `Idempotency-Key`.\n- O link criado via API fica marcado com origem `API`, e as faturas geradas futuramente por esse checkout manterão `type_code=payment_link` e `issued_via_code=api`.\n- Hoje não existe webhook dedicado `payment_link.created`; a integração deve observar os eventos `invoice.*` quando a cobrança for efetivamente gerada.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PaymentLinkInput"
              },
              "example": {
                "description": "Link sem vencimento para adesao",
                "link_type": "fixed",
                "amount": "249.90",
                "due_option": "none",
                "invoice_due_option": "20_days",
                "usage_limit_mode": "limited",
                "usage_limit": 3,
                "payment_methods": [
                  "pix"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Link criado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentLinkEnvelope"
                },
                "example": {
                  "success": true,
                  "message": "Link de pagamento criado com sucesso.",
                  "payment_link": {
                    "id": 91,
                    "public_token": "4dd78029-fb39-4c52-b0e6-2bc748d2832b",
                    "description": "Link sem vencimento para adesao",
                    "has_defined_amount": true,
                    "amount": "249.90",
                    "due_option": "none",
                    "due_option_label": "Sem vencimento",
                    "custom_due_days": null,
                    "invoice_due_option": "20_days",
                    "invoice_due_option_label": "20 dias",
                    "invoice_custom_due_days": null,
                    "validity_display": "Sem vencimento",
                    "invoice_due_summary": "20 dias após a criação",
                    "usage_limit_mode": "limited",
                    "usage_limit_mode_label": "Definir limite",
                    "usage_limit": 3,
                    "has_usage_limit": true,
                    "used_count": 1,
                    "remaining_uses": 2,
                    "usage_limit_display": "1 de 3",
                    "due_date": "2026-08-02",
                    "due_at": "2026-08-02T14:30:00-03:00",
                    "is_active": true,
                    "can_generate_invoice": true,
                    "status_code": "active",
                    "status_label": "Ativo",
                    "issued_via": "API",
                    "issued_via_code": "api",
                    "issued_via_label": "API",
                    "payment_methods": [
                      {
                        "id": 12,
                        "name": "Pix",
                        "slug": "pix"
                      }
                    ],
                    "payment_methods_display": "Pix",
                    "public_url": "https://app.mepagg.com/link/4dd78029-fb39-4c52-b0e6-2bc748d2832b/",
                    "public_urls": {
                      "checkout": "https://app.mepagg.com/link/4dd78029-fb39-4c52-b0e6-2bc748d2832b/"
                    },
                    "created_at": "2026-07-18T14:30:00-03:00",
                    "updated_at": "2026-07-18T14:30:00-03:00"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Requisição inválida.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "message": "Existem campos inválidos na requisição."
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "message": "Chave de API inválida ou ausente."
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "message": "Muitas requisições em sequência. Tente novamente em instantes."
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "message": "Erro interno ao processar a requisição."
                }
              }
            }
          }
        },
        "operationId": "post_api_v1_payment_links",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request POST \\\n  --url 'https://app.mepagg.com/api/v1/payment-links/' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API' \\\n  --header 'Idempotency-Key: {{UUID_UNICO_DA_OPERACAO}}' \\\n  --header 'Content-Type: application/json' \\\n  --data '{\n  \"description\": \"Link sem vencimento para adesao\",\n  \"link_type\": \"fixed\",\n  \"amount\": \"249.90\",\n  \"due_option\": \"none\",\n  \"invoice_due_option\": \"20_days\",\n  \"usage_limit_mode\": \"limited\",\n  \"usage_limit\": 3,\n  \"payment_methods\": [\"pix\"]\n}'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const payload = {\n  description: 'Link sem vencimento para adesao',\n  link_type: 'fixed',\n  amount: '249.90',\n  due_option: 'none',\n  invoice_due_option: '20_days',\n  usage_limit_mode: 'limited',\n  usage_limit: 3,\n  payment_methods: ['pix']\n};\n\nconst response = await fetch('https://app.mepagg.com/api/v1/payment-links/', {\n  method: 'POST',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API',\n    'Idempotency-Key': '{{UUID_UNICO_DA_OPERACAO}}',\n    'Content-Type': 'application/json'\n  },\n  body: JSON.stringify(payload)\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\npayload = {\n    'description': 'Link sem vencimento para adesao',\n    'link_type': 'fixed',\n    'amount': '249.90',\n    'due_option': 'none',\n    'invoice_due_option': '20_days',\n    'usage_limit_mode': 'limited',\n    'usage_limit': 3,\n    'payment_methods': ['pix']\n}\n\nresponse = requests.post(\n    'https://app.mepagg.com/api/v1/payment-links/',\n    headers={\n        'X-API-KEY': 'SUA_CHAVE_DE_API',\n        'Idempotency-Key': '{{UUID_UNICO_DA_OPERACAO}}',\n        'Content-Type': 'application/json'\n    },\n    json=payload,\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$payload = [\n    'description' => 'Link sem vencimento para adesao',\n    'link_type' => 'fixed',\n    'amount' => '249.90',\n    'due_option' => 'none',\n    'invoice_due_option' => '20_days',\n    'usage_limit_mode' => 'limited',\n    'usage_limit' => 3,\n    'payment_methods' => ['pix'],\n];\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/payment-links/',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'POST',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API', 'Idempotency-Key: {{UUID_UNICO_DA_OPERACAO}}', 'Content-Type: application/json'],\n    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      }
    },
    "/api/v1/payment-links/{public_token}/": {
      "get": {
        "tags": [
          "Links de pagamentos"
        ],
        "summary": "Detalhar link de pagamento",
        "description": "Retorna o estado atual do link informado, incluindo validade calculada, uso atual, formas de pagamento, URLs públicas e origem da criação.\n\n### Campos importantes\n- `status_code` e `status_label`\n- `issued_via`, `issued_via_code` e `issued_via_label`\n- `due_date` e `due_at`\n- `validity_display`, `invoice_due_option_label` e `invoice_due_summary`\n- `used_count`, `remaining_uses` e `usage_limit_display`\n- `public_url` e `public_urls.checkout`\n\n`issued_via*` é retornado somente para leitura. A origem é calculada internamente pela Mepagg e não pode ser enviada nem sobrescrita pelo integrador.",
        "parameters": [
          {
            "$ref": "#/components/parameters/PaymentLinkPublicToken"
          }
        ],
        "responses": {
          "200": {
            "description": "Link localizado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentLinkEnvelope"
                },
                "example": {
                  "success": true,
                  "payment_link": {
                    "id": 91,
                    "public_token": "4dd78029-fb39-4c52-b0e6-2bc748d2832b",
                    "description": "Link sem vencimento para adesao",
                    "has_defined_amount": true,
                    "amount": "249.90",
                    "due_option": "none",
                    "due_option_label": "Sem vencimento",
                    "custom_due_days": null,
                    "invoice_due_option": "20_days",
                    "invoice_due_option_label": "20 dias",
                    "invoice_custom_due_days": null,
                    "validity_display": "Sem vencimento",
                    "invoice_due_summary": "20 dias após a criação",
                    "usage_limit_mode": "limited",
                    "usage_limit_mode_label": "Definir limite",
                    "usage_limit": 3,
                    "has_usage_limit": true,
                    "used_count": 1,
                    "remaining_uses": 2,
                    "usage_limit_display": "1 de 3",
                    "due_date": "2026-08-02",
                    "due_at": "2026-08-02T14:30:00-03:00",
                    "is_active": true,
                    "can_generate_invoice": true,
                    "status_code": "active",
                    "status_label": "Ativo",
                    "issued_via": "API",
                    "issued_via_code": "api",
                    "issued_via_label": "API",
                    "payment_methods": [
                      {
                        "id": 12,
                        "name": "Pix",
                        "slug": "pix"
                      }
                    ],
                    "payment_methods_display": "Pix",
                    "public_url": "https://app.mepagg.com/link/4dd78029-fb39-4c52-b0e6-2bc748d2832b/",
                    "public_urls": {
                      "checkout": "https://app.mepagg.com/link/4dd78029-fb39-4c52-b0e6-2bc748d2832b/"
                    },
                    "created_at": "2026-07-18T14:30:00-03:00",
                    "updated_at": "2026-07-18T14:30:00-03:00"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "message": "Chave de API inválida ou ausente."
                }
              }
            }
          },
          "404": {
            "description": "Link não encontrado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "message": "Link de pagamento não encontrado."
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "message": "Muitas requisições em sequência. Tente novamente em instantes."
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "message": "Erro interno ao processar a requisição."
                }
              }
            }
          }
        },
        "operationId": "get_api_v1_payment_links_by_public_token",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request GET \\\n  --url 'https://app.mepagg.com/api/v1/payment-links/4dd78029-fb39-4c52-b0e6-2bc748d2832b/' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const response = await fetch('https://app.mepagg.com/api/v1/payment-links/4dd78029-fb39-4c52-b0e6-2bc748d2832b/', {\n  method: 'GET',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API'\n  }\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.get(\n    'https://app.mepagg.com/api/v1/payment-links/4dd78029-fb39-4c52-b0e6-2bc748d2832b/',\n    headers={\n        'X-API-KEY': 'SUA_CHAVE_DE_API'\n    },\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/payment-links/4dd78029-fb39-4c52-b0e6-2bc748d2832b/',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'GET',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API'],\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      }
    },
    "/api/v1/transfers/": {
      "get": {
        "tags": [
          "Transferências"
        ],
        "summary": "Listar transferências",
        "description": "Lista transferências já registradas na conta autenticada.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/Offset"
          }
        ],
        "responses": {
          "200": {
            "description": "Transferências listadas.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TransferListResponse"
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "get_api_v1_transfers",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request GET \\\n  --url 'https://app.mepagg.com/api/v1/transfers/?limit=20&offset=0' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const response = await fetch('https://app.mepagg.com/api/v1/transfers/?limit=20&offset=0', {\n  method: 'GET',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API'\n  }}\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.get(\n    'https://app.mepagg.com/api/v1/transfers/?limit=20&offset=0',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\"\n},\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/transfers/?limit=20&offset=0',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'GET',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API'],\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      }
    },
    "/api/v1/transfers/pricing/": {
      "get": {
        "tags": [
          "Transferências"
        ],
        "summary": "Consultar tarifação de transferências",
        "description": "Consulta a tarifação configurada para transferências da conta.",
        "responses": {
          "200": {
            "description": "Tarifação consultada.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TransferMetaResponse"
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "get_api_v1_transfers_pricing",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request GET \\\n  --url 'https://app.mepagg.com/api/v1/transfers/pricing/' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const response = await fetch('https://app.mepagg.com/api/v1/transfers/pricing/', {\n  method: 'GET',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API'\n  }}\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.get(\n    'https://app.mepagg.com/api/v1/transfers/pricing/',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\"\n},\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/transfers/pricing/',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'GET',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API'],\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      }
    },
    "/api/v1/transfers/pix-keys/": {
      "get": {
        "tags": [
          "Transferências"
        ],
        "summary": "Listar chaves PIX disponíveis",
        "description": "Lista as chaves PIX aprovadas disponíveis para a conta.",
        "responses": {
          "200": {
            "description": "Chaves listadas.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PixKeyListResponse"
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "get_api_v1_transfers_pix_keys",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request GET \\\n  --url 'https://app.mepagg.com/api/v1/transfers/pix-keys/' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const response = await fetch('https://app.mepagg.com/api/v1/transfers/pix-keys/', {\n  method: 'GET',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API'\n  }}\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.get(\n    'https://app.mepagg.com/api/v1/transfers/pix-keys/',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\"\n},\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/transfers/pix-keys/',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'GET',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API'],\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      }
    },
    "/api/v1/transfers/{reference_id}/": {
      "get": {
        "tags": [
          "Transferências"
        ],
        "summary": "Detalhar transferência",
        "description": "Consulta uma transferência específica pelo `reference_id`.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ReferenceId"
          }
        ],
        "responses": {
          "200": {
            "description": "Transferência localizada.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TransferEnvelope"
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "get_api_v1_transfers_by_reference_id",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request GET \\\n  --url 'https://app.mepagg.com/api/v1/transfers/TRANSFER_EXAMPLE_001/' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const response = await fetch('https://app.mepagg.com/api/v1/transfers/TRANSFER_EXAMPLE_001/', {\n  method: 'GET',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API'\n  }}\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.get(\n    'https://app.mepagg.com/api/v1/transfers/TRANSFER_EXAMPLE_001/',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\"\n},\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/transfers/TRANSFER_EXAMPLE_001/',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'GET',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API'],\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      }
    },
    "/api/v1/transfers/{reference_id}/receipt/": {
      "get": {
        "tags": [
          "Transferências"
        ],
        "summary": "Consultar recibo",
        "description": "Consulta o recibo de uma transferência aprovada.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ReferenceId"
          }
        ],
        "responses": {
          "200": {
            "description": "Recibo consultado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TransferReceiptResponse"
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "get_api_v1_transfers_by_reference_id_receipt",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request GET \\\n  --url 'https://app.mepagg.com/api/v1/transfers/TRANSFER_EXAMPLE_001/receipt/' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const response = await fetch('https://app.mepagg.com/api/v1/transfers/TRANSFER_EXAMPLE_001/receipt/', {\n  method: 'GET',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API'\n  }}\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.get(\n    'https://app.mepagg.com/api/v1/transfers/TRANSFER_EXAMPLE_001/receipt/',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\"\n},\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/transfers/TRANSFER_EXAMPLE_001/receipt/',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'GET',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API'],\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      }
    },
    "/api/v1/statement/": {
      "get": {
        "tags": [
          "Extrato"
        ],
        "summary": "Consultar extrato",
        "description": "Consulta o extrato detalhado da conta.\n\n### Filtros disponíveis\n- `q` - `start_date` - `end_date` - `source` - `limit` - `offset`",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "start_date",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "end_date",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "source",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/Offset"
          }
        ],
        "responses": {
          "200": {
            "description": "Extrato consultado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatementListResponse"
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "get_api_v1_statement",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request GET \\\n  --url 'https://app.mepagg.com/api/v1/statement/?limit=20&offset=0&start_date=2026-06-01&end_date=2026-06-30' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const response = await fetch('https://app.mepagg.com/api/v1/statement/?limit=20&offset=0&start_date=2026-06-01&end_date=2026-06-30', {\n  method: 'GET',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API'\n  }}\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.get(\n    'https://app.mepagg.com/api/v1/statement/?limit=20&offset=0&start_date=2026-06-01&end_date=2026-06-30',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\"\n},\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/statement/?limit=20&offset=0&start_date=2026-06-01&end_date=2026-06-30',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'GET',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API'],\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      }
    },
    "/api/v1/statement/summary/": {
      "get": {
        "tags": [
          "Extrato"
        ],
        "summary": "Consultar resumo financeiro",
        "description": "Retorna o resumo consolidado do período informado para apoio à conciliação financeira.",
        "parameters": [
          {
            "name": "start_date",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "end_date",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Resumo consultado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatementSummaryResponse"
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "get_api_v1_statement_summary",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request GET \\\n  --url 'https://app.mepagg.com/api/v1/statement/summary/?start_date=2026-06-01&end_date=2026-06-30' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const response = await fetch('https://app.mepagg.com/api/v1/statement/summary/?start_date=2026-06-01&end_date=2026-06-30', {\n  method: 'GET',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API'\n  }}\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.get(\n    'https://app.mepagg.com/api/v1/statement/summary/?start_date=2026-06-01&end_date=2026-06-30',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\"\n},\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/statement/summary/?start_date=2026-06-01&end_date=2026-06-30',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'GET',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API'],\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      }
    },
    "/api/v1/dashboard/overview/": {
      "get": {
        "tags": [
          "Dashboard"
        ],
        "summary": "Consultar visão geral do dashboard",
        "description": "Retorna a visão consolidada do dashboard para o mês informado em `overview_month`.",
        "parameters": [
          {
            "name": "overview_month",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "2026-06"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Dashboard consultado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DashboardOverviewResponse"
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "get_api_v1_dashboard_overview",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request GET \\\n  --url 'https://app.mepagg.com/api/v1/dashboard/overview/?overview_month=2026-06' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const response = await fetch('https://app.mepagg.com/api/v1/dashboard/overview/?overview_month=2026-06', {\n  method: 'GET',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API'\n  }}\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.get(\n    'https://app.mepagg.com/api/v1/dashboard/overview/?overview_month=2026-06',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\"\n},\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/dashboard/overview/?overview_month=2026-06',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'GET',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API'],\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      }
    },
    "/api/v1/dashboard/widgets/": {
      "get": {
        "tags": [
          "Dashboard"
        ],
        "summary": "Consultar widgets do dashboard",
        "description": "Retorna a coleção de widgets operacionais do dashboard.",
        "responses": {
          "200": {
            "description": "Widgets consultados.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/DashboardMonthContext"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "visible_widgets": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Widgets habilitados para a conta."
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "get_api_v1_dashboard_widgets",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request GET \\\n  --url 'https://app.mepagg.com/api/v1/dashboard/widgets/' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const response = await fetch('https://app.mepagg.com/api/v1/dashboard/widgets/', {\n  method: 'GET',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API'\n  }}\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.get(\n    'https://app.mepagg.com/api/v1/dashboard/widgets/',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\"\n},\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/dashboard/widgets/',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'GET',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API'],\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      }
    },
    "/api/v1/dashboard/balances/": {
      "get": {
        "tags": [
          "Dashboard"
        ],
        "summary": "Consultar saldos",
        "description": "Retorna os saldos exibidos no dashboard da conta.",
        "responses": {
          "200": {
            "description": "Saldos consultados.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/DashboardMonthContext"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "balances": {
                          "$ref": "#/components/schemas/DashboardBalances"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "get_api_v1_dashboard_balances",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request GET \\\n  --url 'https://app.mepagg.com/api/v1/dashboard/balances/' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const response = await fetch('https://app.mepagg.com/api/v1/dashboard/balances/', {\n  method: 'GET',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API'\n  }}\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.get(\n    'https://app.mepagg.com/api/v1/dashboard/balances/',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\"\n},\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/dashboard/balances/',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'GET',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API'],\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      }
    },
    "/api/v1/dashboard/income-preview/": {
      "get": {
        "tags": [
          "Dashboard"
        ],
        "summary": "Consultar previsão de recebimentos",
        "description": "Retorna a previsão de recebimentos exibida no dashboard.",
        "responses": {
          "200": {
            "description": "Previsão consultada.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/DashboardMonthContext"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "income_preview": {
                          "$ref": "#/components/schemas/DashboardIncomePreview"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "get_api_v1_dashboard_income_preview",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request GET \\\n  --url 'https://app.mepagg.com/api/v1/dashboard/income-preview/' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const response = await fetch('https://app.mepagg.com/api/v1/dashboard/income-preview/', {\n  method: 'GET',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API'\n  }}\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.get(\n    'https://app.mepagg.com/api/v1/dashboard/income-preview/',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\"\n},\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/dashboard/income-preview/',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'GET',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API'],\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      }
    },
    "/api/v1/dashboard/invoice-progress/": {
      "get": {
        "tags": [
          "Dashboard"
        ],
        "summary": "Consultar progresso de faturas",
        "description": "Retorna o resumo de progresso das faturas no dashboard.",
        "responses": {
          "200": {
            "description": "Progresso consultado.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/DashboardMonthContext"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "invoice_progress": {
                          "$ref": "#/components/schemas/DashboardInvoiceProgress"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "get_api_v1_dashboard_invoice_progress",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request GET \\\n  --url 'https://app.mepagg.com/api/v1/dashboard/invoice-progress/' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const response = await fetch('https://app.mepagg.com/api/v1/dashboard/invoice-progress/', {\n  method: 'GET',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API'\n  }}\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.get(\n    'https://app.mepagg.com/api/v1/dashboard/invoice-progress/',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\"\n},\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/dashboard/invoice-progress/',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'GET',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API'],\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      }
    },
    "/api/v1/dashboard/latest-invoices/": {
      "get": {
        "tags": [
          "Dashboard"
        ],
        "summary": "Consultar últimas faturas",
        "description": "Retorna a lista de últimas faturas exibidas no dashboard.",
        "responses": {
          "200": {
            "description": "Últimas faturas consultadas.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/DashboardMonthContext"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "latest_invoices": {
                          "$ref": "#/components/schemas/DashboardLatestInvoices"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "get_api_v1_dashboard_latest_invoices",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request GET \\\n  --url 'https://app.mepagg.com/api/v1/dashboard/latest-invoices/' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const response = await fetch('https://app.mepagg.com/api/v1/dashboard/latest-invoices/', {\n  method: 'GET',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API'\n  }}\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.get(\n    'https://app.mepagg.com/api/v1/dashboard/latest-invoices/',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\"\n},\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/dashboard/latest-invoices/',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'GET',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API'],\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      }
    },
    "/api/v1/dashboard/payment-method-chart/": {
      "get": {
        "tags": [
          "Dashboard"
        ],
        "summary": "Consultar gráfico por forma de pagamento",
        "description": "Retorna os dados agregados do gráfico por forma de pagamento.",
        "responses": {
          "200": {
            "description": "Gráfico consultado.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/DashboardMonthContext"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "payment_method_chart": {
                          "$ref": "#/components/schemas/DashboardPaymentMethodChart"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "get_api_v1_dashboard_payment_method_chart",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request GET \\\n  --url 'https://app.mepagg.com/api/v1/dashboard/payment-method-chart/' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const response = await fetch('https://app.mepagg.com/api/v1/dashboard/payment-method-chart/', {\n  method: 'GET',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API'\n  }}\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.get(\n    'https://app.mepagg.com/api/v1/dashboard/payment-method-chart/',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\"\n},\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/dashboard/payment-method-chart/',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'GET',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API'],\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      }
    },
    "/api/v1/dashboard/invoice-type-chart/": {
      "get": {
        "tags": [
          "Dashboard"
        ],
        "summary": "Consultar gráfico por tipo de fatura",
        "description": "Retorna os dados agregados do gráfico por tipo de fatura.",
        "responses": {
          "200": {
            "description": "Gráfico consultado.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/DashboardMonthContext"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "invoice_type_chart": {
                          "$ref": "#/components/schemas/DashboardInvoiceTypeChart"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "get_api_v1_dashboard_invoice_type_chart",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request GET \\\n  --url 'https://app.mepagg.com/api/v1/dashboard/invoice-type-chart/' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const response = await fetch('https://app.mepagg.com/api/v1/dashboard/invoice-type-chart/', {\n  method: 'GET',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API'\n  }}\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.get(\n    'https://app.mepagg.com/api/v1/dashboard/invoice-type-chart/',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\"\n},\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/dashboard/invoice-type-chart/',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'GET',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API'],\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      }
    },
    "/api/v1/dashboard/received-calendar/": {
      "get": {
        "tags": [
          "Dashboard"
        ],
        "summary": "Consultar calendário de recebimentos",
        "description": "Retorna os dados do calendário de recebimentos do dashboard.",
        "responses": {
          "200": {
            "description": "Calendário consultado.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/DashboardMonthContext"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "received_calendar": {
                          "$ref": "#/components/schemas/DashboardReceivedCalendar"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "get_api_v1_dashboard_received_calendar",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request GET \\\n  --url 'https://app.mepagg.com/api/v1/dashboard/received-calendar/' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const response = await fetch('https://app.mepagg.com/api/v1/dashboard/received-calendar/', {\n  method: 'GET',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API'\n  }}\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.get(\n    'https://app.mepagg.com/api/v1/dashboard/received-calendar/',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\"\n},\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/dashboard/received-calendar/',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'GET',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API'],\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      }
    },
    "/api/v1/dashboard/monthly-received-chart/": {
      "get": {
        "tags": [
          "Dashboard"
        ],
        "summary": "Consultar gráfico mensal de recebimentos",
        "description": "Retorna a série mensal de recebimentos exibida no dashboard.",
        "responses": {
          "200": {
            "description": "Gráfico consultado.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/DashboardMonthContext"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "monthly_received_chart": {
                          "$ref": "#/components/schemas/DashboardMonthlyReceived"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "get_api_v1_dashboard_monthly_received_chart",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request GET \\\n  --url 'https://app.mepagg.com/api/v1/dashboard/monthly-received-chart/' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const response = await fetch('https://app.mepagg.com/api/v1/dashboard/monthly-received-chart/', {\n  method: 'GET',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API'\n  }}\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.get(\n    'https://app.mepagg.com/api/v1/dashboard/monthly-received-chart/',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\"\n},\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/dashboard/monthly-received-chart/',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'GET',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API'],\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      }
    },
    "/api/v1/dashboard/customers/": {
      "get": {
        "tags": [
          "Dashboard"
        ],
        "summary": "Consultar indicadores de clientes",
        "description": "Retorna os indicadores de clientes usados no dashboard da conta.",
        "responses": {
          "200": {
            "description": "Indicadores consultados.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/DashboardMonthContext"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "customers": {
                          "$ref": "#/components/schemas/DashboardCustomers"
                        },
                        "expired_final_invoices_count": {
                          "type": "integer",
                          "description": "Quantidade de faturas definitivamente expiradas.",
                          "example": 3
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "get_api_v1_dashboard_customers",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request GET \\\n  --url 'https://app.mepagg.com/api/v1/dashboard/customers/' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const response = await fetch('https://app.mepagg.com/api/v1/dashboard/customers/', {\n  method: 'GET',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API'\n  }}\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.get(\n    'https://app.mepagg.com/api/v1/dashboard/customers/',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\"\n},\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/dashboard/customers/',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'GET',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API'],\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      }
    },
    "/api/v1/sms/send/": {
      "post": {
        "tags": [
          "SMS"
        ],
        "summary": "Enviar SMS",
        "description": "Envia um SMS manual pela conta autenticada. O campo `content` aceita no máximo 160 caracteres.",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "phone",
                  "content"
                ],
                "properties": {
                  "phone": {
                    "type": "string",
                    "example": "11987654321"
                  },
                  "content": {
                    "type": "string",
                    "maxLength": 160,
                    "example": "Seu boleto Mepagg foi gerado com sucesso."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SMS enviado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessMessage"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "post_api_v1_sms_send",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request POST \\\n  --url 'https://app.mepagg.com/api/v1/sms/send/' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API' \\\n  --header 'Idempotency-Key: 8f5b5820-2d19-4be3-8f57-64c3d5d9e2f7'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const response = await fetch('https://app.mepagg.com/api/v1/sms/send/', {\n  method: 'POST',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API',\n    'Idempotency-Key': '8f5b5820-2d19-4be3-8f57-64c3d5d9e2f7'\n  }}\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.post(\n    'https://app.mepagg.com/api/v1/sms/send/',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\",\n    \"Idempotency-Key\": \"8f5b5820-2d19-4be3-8f57-64c3d5d9e2f7\"\n},\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/sms/send/',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'POST',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API', 'Idempotency-Key: 8f5b5820-2d19-4be3-8f57-64c3d5d9e2f7'],\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      }
    },
    "/api/v1/sms/buy-credits/": {
      "post": {
        "tags": [
          "SMS"
        ],
        "summary": "Comprar créditos de SMS",
        "description": "Compra um pacote de créditos SMS usando o saldo da conta Mepagg.\n\n### Payload\n- `sms_credit_package` - `sms_purchase_method` com valor `mepagg_balance`",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request POST \\\n  --url 'https://app.mepagg.com/api/v1/sms/buy-credits/' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API' \\\n  --header 'Content-Type: application/json' \\\n  --data '{\n  \"sms_credit_package\": \"500\",\n  \"sms_purchase_method\": \"mepagg_balance\"\n}'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const payload = {\n  \"sms_credit_package\": \"500\",\n  \"sms_purchase_method\": \"mepagg_balance\"\n};\n\nconst response = await fetch('https://app.mepagg.com/api/v1/sms/buy-credits/', {\n  method: 'POST',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API',\n    'Content-Type': 'application/json'\n  },\n  body: JSON.stringify(payload)\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\npayload = {\n    \"sms_credit_package\": \"500\",\n    \"sms_purchase_method\": \"mepagg_balance\"\n}\n\nresponse = requests.post(\n    'https://app.mepagg.com/api/v1/sms/buy-credits/',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\",\n    \"Content-Type\": \"application/json\"\n},\n    json=payload,\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$payload = [\n    'sms_credit_package' => '500',\n    'sms_purchase_method' => 'mepagg_balance'\n];\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/sms/buy-credits/',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'POST',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API', 'Content-Type: application/json'],\n    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SmsBuyCreditsInput"
              },
              "example": {
                "sms_credit_package": "500",
                "sms_purchase_method": "mepagg_balance"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Créditos adquiridos.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SmsCreditPurchaseResponse"
                }
              }
            }
          },
          "400": {
            "description": "Requisição inválida.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "VALIDATION_ERROR",
                    "message": "Existem campos inválidos na requisição.",
                    "details": {}
                  }
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "post_api_v1_sms_buy_credits"
      }
    },
    "/api/v1/sms/usages/": {
      "get": {
        "tags": [
          "SMS"
        ],
        "summary": "Consultar histórico de SMS",
        "description": "Lista mensagens SMS já enviadas pela conta com filtros de nome, telefone e período.\n\nObservação: este endpoint retorna fragments HTML renderizados pelo painel dentro de um envelope JSON, e não uma coleção transacional pura de objetos.",
        "parameters": [
          {
            "name": "name",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "phone",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "start_date",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "end_date",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Histórico consultado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HtmlFragmentListResponse"
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "get_api_v1_sms_usages",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request GET \\\n  --url 'https://app.mepagg.com/api/v1/sms/usages/?limit=20' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const response = await fetch('https://app.mepagg.com/api/v1/sms/usages/?limit=20', {\n  method: 'GET',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API'\n  }}\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.get(\n    'https://app.mepagg.com/api/v1/sms/usages/?limit=20',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\"\n},\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/sms/usages/?limit=20',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'GET',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API'],\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      }
    },
    "/api/v1/emails/dispatches/": {
      "get": {
        "tags": [
          "E-mails"
        ],
        "summary": "Consultar e-mails enviados",
        "description": "Lista os disparos de e-mail realizados pela conta autenticada.\n\nObservação: este endpoint retorna fragments HTML renderizados pelo painel dentro de um envelope JSON, e não uma coleção transacional pura de objetos.",
        "parameters": [
          {
            "name": "recipient",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "start_date",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "end_date",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "E-mails consultados.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HtmlFragmentListResponse"
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "get_api_v1_emails_dispatches",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request GET \\\n  --url 'https://app.mepagg.com/api/v1/emails/dispatches/?limit=20' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const response = await fetch('https://app.mepagg.com/api/v1/emails/dispatches/?limit=20', {\n  method: 'GET',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API'\n  }}\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.get(\n    'https://app.mepagg.com/api/v1/emails/dispatches/?limit=20',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\"\n},\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/emails/dispatches/?limit=20',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'GET',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API'],\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      }
    },
    "/api/v1/settings/account/": {
      "get": {
        "tags": [
          "Conta"
        ],
        "summary": "Consultar dados da conta autenticada",
        "description": "Retorna os dados cadastrais da conta autenticada em modo leitura.",
        "responses": {
          "200": {
            "description": "Dados consultados.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountEnvelope"
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "get_api_v1_settings_account",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request GET \\\n  --url 'https://app.mepagg.com/api/v1/settings/account/' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const response = await fetch('https://app.mepagg.com/api/v1/settings/account/', {\n  method: 'GET',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API'\n  }}\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.get(\n    'https://app.mepagg.com/api/v1/settings/account/',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\"\n},\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/settings/account/',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'GET',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API'],\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      }
    },
    "/api/v1/settings/webhooks/": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Listar endpoints de webhook",
        "description": "Lista os endpoints de webhook cadastrados na conta.",
        "responses": {
          "200": {
            "description": "Endpoints listados.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookEndpointListResponse"
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "get_api_v1_settings_webhooks",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request GET \\\n  --url 'https://app.mepagg.com/api/v1/settings/webhooks/' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const response = await fetch('https://app.mepagg.com/api/v1/settings/webhooks/', {\n  method: 'GET',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API'\n  }}\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.get(\n    'https://app.mepagg.com/api/v1/settings/webhooks/',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\"\n},\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/settings/webhooks/',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'GET',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API'],\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      },
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Criar endpoint de webhook",
        "description": "Cadastra um novo endpoint de webhook.\n\n### Regras importantes\n- cadastre uma URL HTTPS publica do sistema da conta\n- HTTP so e aceito para localhost em ambiente controlado\n- `subscribed_events` aceita uma lista explicita ou `*` para todos os eventos publicos\n- o `signing_secret` completo e retornado na criacao\n- guarde esse segredo com seguranca\n- valide a assinatura HMAC SHA-256 no recebimento",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request POST \\\n  --url 'https://app.mepagg.com/api/v1/settings/webhooks/' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API' \\\n  --header 'Content-Type: application/json' \\\n  --data '{\n  \"name\": \"ERP principal\",\n  \"target_url\": \"https://erp.exemplo.com/webhooks/mepagg\",\n  \"subscribed_events\": [\n    \"customer.created\",\n    \"customer.updated\",\n    \"customer.deleted\",\n    \"invoice.created\",\n    \"invoice.updated\",\n    \"invoice.paid\",\n    \"invoice.cancelled\",\n    \"invoice.refunded\",\n    \"subscription.created\",\n    \"subscription.updated\",\n    \"subscription.renewed\",\n    \"carne.cancelled\",\n    \"transfer.created\",\n    \"transfer.completed\",\n    \"sms.credits_purchased\",\n    \"sms.sent\",\n    \"email.sent\"\n  ],\n  \"is_enabled\": true\n}'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const payload = {\n  \"name\": \"ERP principal\",\n  \"target_url\": \"https://erp.exemplo.com/webhooks/mepagg\",\n  \"subscribed_events\": [\n    \"customer.created\",\n    \"customer.updated\",\n    \"customer.deleted\",\n    \"invoice.created\",\n    \"invoice.updated\",\n    \"invoice.paid\",\n    \"invoice.cancelled\",\n    \"invoice.refunded\",\n    \"subscription.created\",\n    \"subscription.updated\",\n    \"subscription.renewed\",\n    \"carne.cancelled\",\n    \"transfer.created\",\n    \"transfer.completed\",\n    \"sms.credits_purchased\",\n    \"sms.sent\",\n    \"email.sent\"\n  ],\n  \"is_enabled\": true\n};\n\nconst response = await fetch('https://app.mepagg.com/api/v1/settings/webhooks/', {\n  method: 'POST',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API',\n    'Content-Type': 'application/json'\n  },\n  body: JSON.stringify(payload)\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\npayload = {\n    \"name\": \"ERP principal\",\n    \"target_url\": \"https://erp.exemplo.com/webhooks/mepagg\",\n    \"subscribed_events\": [\n        \"customer.created\",\n        \"customer.updated\",\n        \"customer.deleted\",\n        \"invoice.created\",\n        \"invoice.updated\",\n        \"invoice.paid\",\n        \"invoice.cancelled\",\n        \"invoice.refunded\",\n        \"subscription.created\",\n        \"subscription.updated\",\n        \"subscription.renewed\",\n        \"carne.cancelled\",\n        \"transfer.created\",\n        \"transfer.completed\",\n        \"sms.credits_purchased\",\n        \"sms.sent\",\n        \"email.sent\"\n    ],\n    \"is_enabled\": True\n}\n\nresponse = requests.post(\n    'https://app.mepagg.com/api/v1/settings/webhooks/',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\",\n    \"Content-Type\": \"application/json\"\n},\n    json=payload,\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$payload = [\n    'name' => 'ERP principal',\n    'target_url' => 'https://erp.exemplo.com/webhooks/mepagg',\n    'subscribed_events' => [\n        'customer.created',\n        'customer.updated',\n        'customer.deleted',\n        'invoice.created',\n        'invoice.updated',\n        'invoice.paid',\n        'invoice.cancelled',\n        'invoice.refunded',\n        'subscription.created',\n        'subscription.updated',\n        'subscription.renewed',\n        'carne.cancelled',\n        'transfer.created',\n        'transfer.completed',\n        'sms.credits_purchased',\n        'sms.sent',\n        'email.sent'\n    ],\n    'is_enabled' => true\n];\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/settings/webhooks/',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'POST',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API', 'Content-Type: application/json'],\n    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookEndpointInput"
              },
              "example": {
                "name": "ERP principal",
                "target_url": "https://erp.exemplo.com/webhooks/mepagg",
                "subscribed_events": [
                  "customer.created",
                  "customer.updated",
                  "customer.deleted",
                  "invoice.created",
                  "invoice.updated",
                  "invoice.paid",
                  "invoice.cancelled",
                  "invoice.refunded",
                  "subscription.created",
                  "subscription.updated",
                  "subscription.renewed",
                  "carne.cancelled",
                  "transfer.created",
                  "transfer.completed",
                  "sms.credits_purchased",
                  "sms.sent",
                  "email.sent"
                ],
                "is_enabled": true
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Endpoint criado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookEndpointEnvelope"
                },
                "examples": {
                  "default": {
                    "value": {
                      "success": true,
                      "message": "Endpoint de webhook criado com sucesso.",
                      "endpoint": {
                        "id": 12,
                        "name": "ERP principal",
                        "target_url": "https://erp.exemplo.com/webhooks/mepagg",
                        "subscribed_events": [
                          "customer.created",
                          "customer.updated",
                          "customer.deleted",
                          "invoice.paid",
                          "payment_link.status_changed",
                          "transfer.completed",
                          "sms.credits_purchased"
                        ],
                        "is_enabled": true,
                        "signing_secret": "whsec_xxxxxxxxxxxxxxxxx"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Requisição inválida.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "VALIDATION_ERROR",
                    "message": "Existem campos inválidos na requisição.",
                    "details": {}
                  }
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "post_api_v1_settings_webhooks"
      }
    },
    "/api/v1/settings/webhooks/{endpoint_id}/": {
      "patch": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Atualizar endpoint de webhook",
        "description": "Atualiza URL, eventos ou estado de um endpoint de webhook já cadastrado.",
        "parameters": [
          {
            "$ref": "#/components/parameters/EndpointId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookEndpointInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Endpoint atualizado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookEndpointEnvelope"
                }
              }
            }
          },
          "400": {
            "description": "Requisição inválida.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "VALIDATION_ERROR",
                    "message": "Existem campos inválidos na requisição.",
                    "details": {}
                  }
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "patch_api_v1_settings_webhooks_by_endpoint_id",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request PATCH \\\n  --url 'https://app.mepagg.com/api/v1/settings/webhooks/12/' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const response = await fetch('https://app.mepagg.com/api/v1/settings/webhooks/12/', {\n  method: 'PATCH',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API'\n  }}\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.patch(\n    'https://app.mepagg.com/api/v1/settings/webhooks/12/',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\"\n},\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/settings/webhooks/12/',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'PATCH',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API'],\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      },
      "delete": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Excluir endpoint de webhook",
        "description": "Remove um endpoint de webhook da conta autenticada.",
        "parameters": [
          {
            "$ref": "#/components/parameters/EndpointId"
          }
        ],
        "responses": {
          "200": {
            "description": "Endpoint excluído.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessMessage"
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "delete_api_v1_settings_webhooks_by_endpoint_id",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request DELETE \\\n  --url 'https://app.mepagg.com/api/v1/settings/webhooks/12/' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const response = await fetch('https://app.mepagg.com/api/v1/settings/webhooks/12/', {\n  method: 'DELETE',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API'\n  }}\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.delete(\n    'https://app.mepagg.com/api/v1/settings/webhooks/12/',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\"\n},\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/settings/webhooks/12/',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'DELETE',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API'],\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      }
    },
    "/api/v1/settings/webhooks/{endpoint_id}/rotate-secret/": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Rotacionar segredo do webhook",
        "description": "Gera um novo `signing_secret` para o endpoint. Atualize o segredo no sistema da conta antes de aceitar novas entregas assinadas.",
        "parameters": [
          {
            "$ref": "#/components/parameters/EndpointId"
          }
        ],
        "responses": {
          "200": {
            "description": "Segredo rotacionado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookSecretRotateResponse"
                },
                "examples": {
                  "default": {
                    "value": {
                      "success": true,
                      "message": "Segredo do webhook rotacionado com sucesso.",
                      "signing_secret": "whsec_novosegredo_xxxxxxxxx"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Requisição inválida.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "VALIDATION_ERROR",
                    "message": "Existem campos inválidos na requisição.",
                    "details": {}
                  }
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "post_api_v1_settings_webhooks_by_endpoint_id_rotate_secret",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request POST \\\n  --url 'https://app.mepagg.com/api/v1/settings/webhooks/12/rotate-secret/' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const response = await fetch('https://app.mepagg.com/api/v1/settings/webhooks/12/rotate-secret/', {\n  method: 'POST',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API'\n  }}\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.post(\n    'https://app.mepagg.com/api/v1/settings/webhooks/12/rotate-secret/',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\"\n},\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/settings/webhooks/12/rotate-secret/',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'POST',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API'],\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      }
    },
    "/api/v1/settings/webhooks/deliveries/": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Consultar histórico de entregas",
        "description": "Lista as tentativas de entrega de eventos de webhook por endpoint, status e nome do evento.",
        "parameters": [
          {
            "name": "endpoint_id",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "event_name",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/Limit"
          }
        ],
        "responses": {
          "200": {
            "description": "Histórico consultado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookDeliveryListResponse"
                }
              }
            }
          },
          "401": {
            "description": "Falha de autenticação.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INVALID_API_KEY",
                    "message": "Chave de API inválida ou ausente.",
                    "details": {}
                  }
                }
              }
            }
          },
          "429": {
            "description": "Limite de requisições excedido.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "RATE_LIMIT_EXCEEDED",
                    "message": "Muitas requisições em sequência. Tente novamente em instantes.",
                    "details": {}
                  }
                }
              }
            }
          },
          "500": {
            "description": "Erro interno inesperado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": {
                    "code": "INTERNAL_ERROR",
                    "message": "Erro interno ao processar a requisição.",
                    "details": {}
                  }
                }
              }
            }
          }
        },
        "operationId": "get_api_v1_settings_webhooks_deliveries",
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request GET \\\n  --url 'https://app.mepagg.com/api/v1/settings/webhooks/deliveries/?limit=20' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API'"
          },
          {
            "lang": "javascript",
            "label": "JavaScript",
            "source": "const response = await fetch('https://app.mepagg.com/api/v1/settings/webhooks/deliveries/?limit=20', {\n  method: 'GET',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API'\n  }}\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.get(\n    'https://app.mepagg.com/api/v1/settings/webhooks/deliveries/?limit=20',\n    headers={\n    \"X-API-KEY\": \"SUA_CHAVE_DE_API\"\n},\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/settings/webhooks/deliveries/?limit=20',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'GET',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API'],\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      }
    },
    "/api/v1/subscription-plans/": {
      "get": {
        "tags": [
          "Planos"
        ],
        "summary": "Listar planos",
        "description": "Lista os planos cadastrados na conta autenticada. Use `q`, `interval`, `limit` e `offset` para paginação e filtros.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Busca textual por nome do plano ou `reference_id`."
          },
          {
            "name": "interval",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filtro pela recorrência do plano."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 100
            },
            "description": "Quantidade máxima por página."
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            },
            "description": "Deslocamento da paginação."
          }
        ],
        "responses": {
          "200": {
            "description": "Planos listados.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubscriptionPlanListResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request GET \\\n  --url 'https://app.mepagg.com/api/v1/subscription-plans/?limit=20&offset=0' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API'"
          },
          {
            "lang": "javascript",
            "label": "Node.js",
            "source": "const response = await fetch('https://app.mepagg.com/api/v1/subscription-plans/?limit=20&offset=0', {\n  method: 'GET',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API'\n  }\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\nresponse = requests.get(\n    'https://app.mepagg.com/api/v1/subscription-plans/?limit=20&offset=0',\n    headers={\n        'X-API-KEY': 'SUA_CHAVE_DE_API'\n    },\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/subscription-plans/?limit=20&offset=0',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'GET',\n    CURLOPT_HTTPHEADER => ['X-API-KEY: SUA_CHAVE_DE_API'],\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      },
      "post": {
        "tags": [
          "Planos"
        ],
        "summary": "Criar plano",
        "description": "Cria um plano reutilizável para assinaturas. Use `Idempotency-Key` para evitar duplicidade em retries.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SubscriptionPlanInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Plano criado com sucesso.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubscriptionPlanEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl --request POST \\\n  --url 'https://app.mepagg.com/api/v1/subscription-plans/' \\\n  --header 'X-API-KEY: SUA_CHAVE_DE_API' \\\n  --header 'Content-Type: application/json' \\\n  --header 'Idempotency-Key: 8f5b5820-2d19-4be3-8f57-64c3d5d9e2f7' \\\n  --data '{\n  \"name\": \"Mensalidade hospedagem\",\n  \"amount\": \"85.00\",\n  \"interval\": \"MONTHLY\",\n  \"fees\": \"1.00\",\n  \"fines\": \"2.00\",\n  \"discount_type\": \"FIXED_VALUE\",\n  \"discount\": \"5.00\",\n  \"inter_boleto_num_dias_agenda\": 3,\n  \"payment_method_ids\": [1, 2],\n  \"is_active\": true\n}'"
          },
          {
            "lang": "javascript",
            "label": "Node.js",
            "source": "const payload = {\n  name: 'Mensalidade hospedagem',\n  amount: '85.00',\n  interval: 'MONTHLY',\n  fees: '1.00',\n  fines: '2.00',\n  discount_type: 'FIXED_VALUE',\n  discount: '5.00',\n  inter_boleto_num_dias_agenda: 3,\n  payment_method_ids: [1, 2],\n  is_active: true\n};\n\nconst response = await fetch('https://app.mepagg.com/api/v1/subscription-plans/', {\n  method: 'POST',\n  headers: {\n    'X-API-KEY': 'SUA_CHAVE_DE_API',\n    'Content-Type': 'application/json',\n    'Idempotency-Key': '8f5b5820-2d19-4be3-8f57-64c3d5d9e2f7'\n  },\n  body: JSON.stringify(payload)\n});\n\nconst data = await response.json();\nconsole.log(response.status, data);"
          },
          {
            "lang": "python",
            "label": "Python",
            "source": "import requests\n\npayload = {\n    'name': 'Mensalidade hospedagem',\n    'amount': '85.00',\n    'interval': 'MONTHLY',\n    'fees': '1.00',\n    'fines': '2.00',\n    'discount_type': 'FIXED_VALUE',\n    'discount': '5.00',\n    'inter_boleto_num_dias_agenda': 3,\n    'payment_method_ids': [1, 2],\n    'is_active': True,\n}\n\nresponse = requests.post(\n    'https://app.mepagg.com/api/v1/subscription-plans/',\n    headers={\n        'X-API-KEY': 'SUA_CHAVE_DE_API',\n        'Content-Type': 'application/json',\n        'Idempotency-Key': '8f5b5820-2d19-4be3-8f57-64c3d5d9e2f7',\n    },\n    json=payload,\n    timeout=30,\n)\n\nprint(response.status_code)\nprint(response.json())"
          },
          {
            "lang": "php",
            "label": "PHP",
            "source": "<?php\n\n$payload = [\n    'name' => 'Mensalidade hospedagem',\n    'amount' => '85.00',\n    'interval' => 'MONTHLY',\n    'fees' => '1.00',\n    'fines' => '2.00',\n    'discount_type' => 'FIXED_VALUE',\n    'discount' => '5.00',\n    'inter_boleto_num_dias_agenda' => 3,\n    'payment_method_ids' => [1, 2],\n    'is_active' => true,\n];\n\n$ch = curl_init();\n\ncurl_setopt_array($ch, [\n    CURLOPT_URL => 'https://app.mepagg.com/api/v1/subscription-plans/',\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_CUSTOMREQUEST => 'POST',\n    CURLOPT_HTTPHEADER => [\n        'X-API-KEY: SUA_CHAVE_DE_API',\n        'Content-Type: application/json',\n        'Idempotency-Key: 8f5b5820-2d19-4be3-8f57-64c3d5d9e2f7'\n    ],\n    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),\n]);\n\n$response = curl_exec($ch);\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\ncurl_close($ch);\n\necho $httpCode . PHP_EOL;\necho $response . PHP_EOL;"
          }
        ]
      }
    },
    "/api/v1/subscription-plans/{reference_id}/": {
      "parameters": [
        {
          "name": "reference_id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          },
          "description": "Identificador público do plano."
        }
      ],
      "get": {
        "tags": [
          "Planos"
        ],
        "summary": "Detalhar plano",
        "description": "Retorna os dados completos de um plano da conta autenticada.",
        "responses": {
          "200": {
            "description": "Plano encontrado.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubscriptionPlanEnvelope"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      },
      "put": {
        "tags": [
          "Planos"
        ],
        "summary": "Atualizar plano",
        "description": "Atualiza completamente um plano existente. Use `Idempotency-Key` para retries seguros.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SubscriptionPlanInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Plano atualizado com sucesso.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubscriptionPlanEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "patch": {
        "tags": [
          "Planos"
        ],
        "summary": "Atualizar parcialmente plano",
        "description": "Atualiza apenas os campos enviados do plano. Também aceita `Idempotency-Key`.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SubscriptionPlanInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Plano atualizado com sucesso.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubscriptionPlanEnvelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "delete": {
        "tags": [
          "Planos"
        ],
        "summary": "Remover plano",
        "description": "Remove logicamente um plano quando não houver assinaturas vinculadas a ele. Também aceita `Idempotency-Key`.",
        "responses": {
          "200": {
            "description": "Plano removido com sucesso.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string",
                      "example": "Plano removido com sucesso."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ValidationError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    }
  }
}