{"openapi":"3.0.3","info":{"title":"Solarz OpenAPI Seller - Solarz Pay","version":"1.0.0","description":"API **somente leitura** dos dados do Solarz Pay: cobranças (vendas avulsas e cobranças de\nassinatura), assinaturas recorrentes dos clientes finais do integrador, régua de cobrança, saldo e\nsaques da conta.\n\nTodas as rotas ficam em `/openApi/seller/pay/v1`. Uma versão incompatível futura será `/v2`; a `v1`\ncontinua no ar até ser descontinuada. Este contrato fica público, em JSON, em\n`GET /v3/api-docs/pay-open-api`; muda só com deploy e pode ser guardado em cache.\n\n## Autenticação\nBasic Auth com as credenciais de **Usuário de API** (username `oa_...` + senha, geradas no painel do\nSolarz), igual às demais rotas `/openApi/seller/**`. Login por e-mail/senha é\nrecusado com `401 OPEN_API_USER_REQUIRED`. A credencial age com os privilégios do usuário dono dela.\n\n## Autorização (em toda requisição)\n1. **Acesso à API:** o dono da conta sempre tem. Um colaborador precisa do privilégio\n   `PAY_API_ACCESS`. Sem ele: `403 PAY_API_ACCESS_DENIED`.\n2. **Privilégio do recurso:** indicado em `x-required-privilege` em cada operação. Sem ele: `403 FORBIDDEN`.\n\nOs dados são sempre filtrados pela conta do integrador. Um ID de outra conta responde `404`, igual a\num ID inexistente. Mudanças de privilégio valem na requisição seguinte.\n\n## Guia rápido para agentes de IA\n1. **Todas as operações são GET**, idempotentes e seguras para repetir. Mesmo assim, reaproveite a\n   resposta anterior em vez de repetir a mesma chamada.\n2. **Paginação:** comece em `page=1` e pare quando `page.hasNext = false`. `pageSize` padrão 50,\n   máximo 200; `page` vai até 100. Para ir além, estreite os filtros (datas, `stage`, `status`, `customerId`).\n3. **Reduza tokens com `fields=`**: ex. `fields=id,stage,price,dueDate`. O `id` sempre vem.\n4. **Datas:** envie `YYYY-MM-DD`, com no máximo 12 meses por consulta. Para períodos maiores, divida\n   em janelas e some os resultados. Datas-hora voltam em ISO 8601 com offset (`2026-08-10T14:32:00-03:00`).\n5. **Dinheiro:** `amountCents` é inteiro em centavos (`152035` = R$ 1.520,35), sempre com `currency`.\n6. **Erros:** decida pelo `code` (estável). Com `retryable: false`, corrija a requisição em vez de repetir.\n   Com `retryable: true`, repita com backoff exponencial e jitter (1s, 2s, 4s, 8s, 16s; no máximo 5 tentativas).\n7. **Rate limit:** as respostas autenticadas trazem o estado do limite mais apertado no momento:\n   - `X-RateLimit-Limit`: requisições por minuto desse limite (na cota diária, por dia).\n   - `X-RateLimit-Burst`: quantas requisições seguidas ele aceita.\n   - `X-RateLimit-Remaining`: quantas ainda cabem agora.\n   - `X-RateLimit-Reset`: quando ele volta a ficar cheio, em epoch (segundos, UTC).\n\n   Os limites podem ser diferentes em cada conta: leia os headers em vez de fixar números.\n   - **Chame em sequência, não em paralelo.** O limite vale por credencial e também para a conta inteira,\n     somando todas as credenciais. Com `X-RateLimit-Remaining: 0`, espere até `X-RateLimit-Reset`.\n   - **`429 RATE_LIMIT_EXCEEDED`:** espere os segundos do header `Retry-After` e repita a mesma requisição.\n     Esse tempo substitui o backoff do item 6.\n   - **`429 DAILY_QUOTA_EXCEEDED`:** a cota diária da credencial acabou e só volta à meia-noite (horário de\n     Brasília). O `Retry-After` é de horas: não fique esperando nem repita. Avise o usuário de quando volta.\n   - **`503 SERVICE_UNAVAILABLE`:** a proteção de carga está fora do ar. Repita depois do `Retry-After`,\n     com o backoff do item 6.\n   - Requisição recusada não gasta o limite.\n8. **Parâmetro desconhecido é erro** (`INVALID_PARAMETER`), não é ignorado: use só os nomes documentados.\n9. **Saldo não é tempo real:** `GET /balance` devolve o último saldo lido (uma vez por dia), com `asOf`.\n   Não some recebimentos nem subtraia saques a ele para \"atualizar\"; diga ao usuário a data do saldo.\n\n## Limites\n| Limite | Valor |\n|---|---|\n| `pageSize` | padrão 50, máximo 200 |\n| `page` | 1 a 100 |\n| Intervalo de datas | 12 meses |\n"},"servers":[{"url":"https://app.solarz.com.br","description":"Produção"}],"security":[{"OpenApiUserBasic":[]}],"tags":[{"name":"Vendas e cobranças","description":"Cobranças. Inclui vendas avulsas e as cobranças geradas por assinaturas."},{"name":"Assinaturas","description":"Assinaturas recorrentes dos clientes finais."},{"name":"Régua de cobrança","description":"Regras de geração e cancelamento das cobranças de assinatura e mensagens de cobrança."},{"name":"Financeiro","description":"Saldo e saques da conta Solarz Pay. Só dados gravados no Solarz; nada é consultado no banco/gateway na hora."},{"name":"Catálogo","description":"Planos e produtos (itens) cadastrados no Solarz Pay, como nas telas de planos e produtos do painel."},{"name":"Chargebacks","description":"Contestações de compra no cartão (chargebacks) das cobranças, como na tela de chargebacks do painel."}],"paths":{"/openApi/seller/pay/v1/sales":{"get":{"tags":["Vendas e cobranças"],"operationId":"listSales","summary":"Lista cobranças (vendas avulsas e cobranças de assinatura)","x-required-privilege":"SALE_CLIENT_VIEW (tipo SIMPLES_SALE) e/ou SUBSCRIPTION_CLIENT_LIST (tipos SUBSCRIPTION e SUBSCRIPTION_SIMPLES_SALE). Sem nenhum dos dois: 403.","description":"Lista as cobranças da conta. O campo `type` diz a origem: `SIMPLES_SALE` (venda avulsa),\n`SUBSCRIPTION` (gerada por uma assinatura) ou `SUBSCRIPTION_SIMPLES_SALE` (venda avulsa vinculada a\numa assinatura).\n\nÉ obrigatório informar **exatamente um** intervalo de datas: `dueDateFrom/dueDateTo` (vencimento),\n`paidAtFrom/paidAtTo` (pagamento) ou `createdAtFrom/createdAtTo` (criação), com no máximo 12 meses.\n\nSe o usuário tiver só um dos privilégios, a API retorna apenas os tipos permitidos e lista os\ncortados em `meta.restrictedTypes`.\n\nUse para: \"quais cobranças venceram em agosto\", \"o que o cliente X pagou este ano\",\n\"cobranças em atraso da usina Y\".\n","parameters":[{"$ref":"#/components/parameters/DueDateFrom"},{"$ref":"#/components/parameters/DueDateTo"},{"$ref":"#/components/parameters/PaidAtFrom"},{"$ref":"#/components/parameters/PaidAtTo"},{"$ref":"#/components/parameters/CreatedAtFrom"},{"$ref":"#/components/parameters/CreatedAtTo"},{"name":"stage","in":"query","description":"Filtra por um ou mais estágios, separados por vírgula.","style":"form","explode":false,"schema":{"type":"array","items":{"$ref":"#/components/schemas/SaleStage"}},"example":["WAITING_PAYMENT","EXPIRED"]},{"name":"type","in":"query","description":"Filtra por um ou mais tipos, separados por vírgula. Pedir só tipos sem privilégio responde 403.","style":"form","explode":false,"schema":{"type":"array","items":{"$ref":"#/components/schemas/SaleType"}}},{"name":"paymentMethod","in":"query","description":"Forma de pagamento usada pelo cliente, separadas por vírgula.","style":"form","explode":false,"schema":{"type":"array","items":{"$ref":"#/components/schemas/PaymentMethod"}}},{"$ref":"#/components/parameters/CustomerId"},{"$ref":"#/components/parameters/ResponsibleId"},{"$ref":"#/components/parameters/PlantId"},{"name":"subscriptionId","in":"query","description":"Retorna apenas as cobranças de uma assinatura (campo `id` de /subscriptions).","schema":{"type":"integer","format":"int64"}},{"name":"crmCardId","in":"query","description":"Busca a cobrança pelo ID do card no CRM (atual ou anterior).","schema":{"type":"integer","format":"int64"}},{"name":"sort","in":"query","description":"Ordenação. Prefixo `-` = decrescente. Empates são desfeitos por `id` decrescente.","schema":{"type":"string","enum":["dueDate","-dueDate","paidAt","-paidAt","createdAt","-createdAt"],"default":"-dueDate"}},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"},{"name":"fields","in":"query","description":"Campos de `SaleSummary` a devolver, separados por vírgula (o `id` sempre vem). Ex.: `id,stage,price,dueDate`.","schema":{"type":"string"}}],"responses":{"200":{"description":"Página de cobranças.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PageEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SaleSummary"}}}}]},"example":{"data":[{"id":98231,"type":"SUBSCRIPTION","stage":"EXPIRED","subscriptionId":4410,"customer":{"id":7781,"name":"Maria Souza","documentMasked":"***.456.789-**","emailMasked":"ma***a@exemplo.com"},"responsible":{"id":512,"name":"João Vendas"},"plantIds":[3301],"price":{"amountCents":152035,"currency":"BRL"},"expectedAmount":{"amountCents":152035,"currency":"BRL"},"paidAmount":{"amountCents":0,"currency":"BRL"},"paymentMethod":"BOLETO","installments":null,"dueDate":"2026-08-10","paidAt":null,"crmCardId":null,"createdAt":"2026-07-25T09:12:44-03:00"}],"page":{"number":1,"size":50,"totalElements":1,"totalPages":1,"hasNext":false},"meta":{"requestId":"req_5f0c1e7a-2b1d-4c1e-9a55-7d1f0e6c3b21","filters":{"dueDateFrom":"2026-08-01","dueDateTo":"2026-08-31","stage":["EXPIRED"],"sort":"-dueDate"},"restrictedTypes":[]}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/openApi/seller/pay/v1/sales/{saleId}":{"get":{"tags":["Vendas e cobranças"],"operationId":"getSale","summary":"Detalhe de uma cobrança","x-required-privilege":"SALE_CLIENT_VIEW ou SUBSCRIPTION_CLIENT_LIST, conforme o tipo da cobrança. Tipo sem privilégio responde 404.","description":"Retorna a cobrança completa: itens, cliente, responsável, usinas, taxas, multa e juros, CRM,\nresumo das faturas no gateway e chargebacks.\n","parameters":[{"name":"saleId","in":"path","required":true,"description":"ID da cobrança (campo `id` da listagem de vendas).","schema":{"type":"integer","format":"int64"}},{"name":"fields","in":"query","description":"Campos de `SaleDetail` a devolver, separados por vírgula (o `id` sempre vem).","schema":{"type":"string"}}],"responses":{"200":{"description":"Cobrança encontrada.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SaleDetail"},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"data":{"id":98231,"type":"SIMPLES_SALE","stage":"DONE","subscriptionId":null,"customer":{"id":7781,"name":"Maria Souza","documentMasked":"***.456.789-**","emailMasked":"ma***a@exemplo.com"},"responsible":{"id":512,"name":"João Vendas"},"plantIds":[3301],"price":{"amountCents":50000,"currency":"BRL"},"expectedAmount":{"amountCents":50000,"currency":"BRL"},"paidAmount":{"amountCents":50000,"currency":"BRL"},"paymentMethod":"PIX","installments":null,"dueDate":"2026-08-10","paidAt":"2026-08-09T18:03:12-03:00","crmCardId":null,"createdAt":"2026-07-25T09:12:44-03:00","lostType":null,"justification":null,"gateway":"ASAAS","items":[{"productId":12,"productName":"Limpeza de placas","category":"SERVICE","unitPrice":{"amountCents":50000,"currency":"BRL"},"quantity":1,"recurrent":false}],"plants":[{"id":3301,"name":"UC 123456"}],"payableOptions":["PIX","BOLETO"],"maxInstallments":12,"installmentsFee":null,"passServicesFeeToCustomer":false,"passInstallmentsFeeToCustomer":false,"feesAmount":{"amountCents":199,"currency":"BRL"},"originalDueDate":"2026-08-10","paymentDeadline":null,"expectedReceiptDate":"2026-08-10","receivedDate":"2026-08-10","paidExternally":false,"systemGenerated":false,"paymentLink":"https://app.solarz.com.br/pay/abc123","lateFees":{"finePercentage":2,"fineCents":null,"dailyInterestPercentage":1,"dailyInterestCents":null},"notifications":{"whatsapp":true,"email":true,"lastBillingMessageAt":"2026-08-05T08:00:00-03:00"},"crm":{"cardId":null,"previousCardIds":[]},"installmentsSummary":{"total":1,"open":0,"refunded":0},"chargebackIds":[],"createdBy":{"id":512,"name":"João Vendas"}},"meta":{"requestId":"req_1"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/openApi/seller/pay/v1/sales/{saleId}/installments":{"get":{"tags":["Vendas e cobranças"],"operationId":"listSaleInstallments","summary":"Lista as parcelas de repasse de uma cobrança","x-required-privilege":"SALE_CLIENT_VIEW ou SUBSCRIPTION_CLIENT_LIST, conforme o tipo da cobrança. Tipo sem privilégio responde 404.","description":"Parcelas de repasse da cobrança: quando e quanto cai na conta, com a taxa do gateway. São as mesmas da aba\nde parcelas do painel, ordenadas pela data de repasse. Cobrança à vista tem uma parcela; cartão parcelado\ntem uma por mês. Sem parcelas gravadas no gateway, vem a parcela única da fatura. Cobrança ainda sem\nfatura (ex.: `PENDING`) devolve lista vazia.\n\n`amount`, `taxes` e `commission` são `Money`, em centavos. Valor ou data que não puderam ser lidos vêm `null`.\nPáginas de **6** itens (o tamanho do painel); `pageSize` não é aceito.\n\nUse para: \"quando recebo o dinheiro desta venda\", \"quanto o gateway cobrou de taxa\".\n","parameters":[{"name":"saleId","in":"path","required":true,"description":"ID da cobrança (campo `id` da listagem de vendas).","schema":{"type":"integer","format":"int64"}},{"$ref":"#/components/parameters/Page"},{"name":"fields","in":"query","description":"Campos de `SaleInstallment` a devolver, separados por vírgula (o `id` sempre vem).","schema":{"type":"string"}}],"responses":{"200":{"description":"Página de parcelas.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PageEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SaleInstallment"}}}}]},"example":{"data":[{"id":7001,"billingHubId":"A1B2C3","installment":1,"returnDate":"2026-09-10","status":"paid","amount":{"amountCents":152035,"currency":"BRL"},"taxes":{"amountCents":499,"currency":"BRL"},"commission":null,"executedDate":"2026-09-10","advanced":false,"createdAt":"2026-08-10T14:32:00-03:00"}],"page":{"number":1,"size":6,"totalElements":1,"totalPages":1,"hasNext":false},"meta":{"requestId":"req_10","filters":{"saleId":"98231"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/openApi/seller/pay/v1/sales/{saleId}/charges":{"get":{"tags":["Vendas e cobranças"],"operationId":"listSaleCharges","summary":"Lista as cobranças automáticas de uma cobrança e suas tentativas","x-required-privilege":"SALE_CLIENT_VIEW ou SUBSCRIPTION_CLIENT_LIST, conforme o tipo da cobrança. Tipo sem privilégio responde 404.","description":"Cobranças automáticas feitas pelo Solarz para esta cobrança (cartão recorrente, Pix Automático, boleto da\nrégua) e cada tentativa, como na aba de cobranças do painel. Mostra por que um cartão foi recusado\n(`attempts[].lr`, `attempts[].message`) e quando será a próxima tentativa (`nextAttempt`).\nPáginas de **10** itens (o tamanho do painel); `pageSize` não é aceito.\n\nUse para: \"por que o cartão desta cobrança não passou\", \"quando o sistema tenta de novo\".\n","parameters":[{"name":"saleId","in":"path","required":true,"description":"ID da cobrança (campo `id` da listagem de vendas).","schema":{"type":"integer","format":"int64"}},{"$ref":"#/components/parameters/Page"},{"name":"fields","in":"query","description":"Campos de `SaleCharge` a devolver, separados por vírgula (o `id` sempre vem).","schema":{"type":"string"}}],"responses":{"200":{"description":"Página de cobranças automáticas.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PageEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SaleCharge"}}}}]},"example":{"data":[{"id":551,"type":"CREDIT_CARD","stage":"FAILED","externalId":null,"attempt":3,"onFailedRetry":3,"timeout":60,"lastAttempt":"2026-09-10T10:00:00-03:00","nextAttempt":null,"createdAt":"2026-09-10T08:00:00-03:00","attempts":[{"id":9001,"attempt":1,"success":false,"lr":"51","message":"Saldo insuficiente","description":null,"cardNumber":"XXXX-XXXX-XXXX-1234","brand":"VISA","createdAt":"2026-09-10T08:00:00-03:00"}]}],"page":{"number":1,"size":10,"totalElements":1,"totalPages":1,"hasNext":false},"meta":{"requestId":"req_11","filters":{"saleId":"98231"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/openApi/seller/pay/v1/sales/{saleId}/messages":{"get":{"tags":["Vendas e cobranças"],"operationId":"listSaleMessages","summary":"Lista as mensagens de cobrança enviadas ao cliente sobre uma cobrança","x-required-privilege":"SALE_CLIENT_VIEW ou SUBSCRIPTION_CLIENT_LIST, conforme o tipo da cobrança. Tipo sem privilégio responde 404.","description":"Mensagens de cobrança (e-mail e WhatsApp) desta cobrança, da régua ou enviadas manualmente, e cada\ntentativa de envio, como na aba de mensagens do painel. Mostra o que foi dito ao cliente, quando\n(`processedAt`), o que está agendado (`nextAttempt`) e por que um envio falhou (`attempts[].errorMessage`).\nOrdenadas pela próxima tentativa, da mais recente para a mais antiga.\nPáginas de **5** itens (o tamanho do painel); `pageSize` não é aceito.\n\nUse para: \"o cliente foi avisado desta cobrança\", \"por que o WhatsApp não chegou\", \"qual a próxima mensagem\".\n","parameters":[{"name":"saleId","in":"path","required":true,"description":"ID da cobrança (campo `id` da listagem de vendas).","schema":{"type":"integer","format":"int64"}},{"$ref":"#/components/parameters/Page"},{"name":"fields","in":"query","description":"Campos de `SaleMessage` a devolver, separados por vírgula (o `id` sempre vem).","schema":{"type":"string"}}],"responses":{"200":{"description":"Página de mensagens de cobrança.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PageEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SaleMessage"}}}}]},"example":{"data":[{"id":7712,"stage":"FAILED","type":"WHATSAPP","originType":"RULER","period":"POS_VENCIMENTO","days":3,"message":"Olá, Maria! Sua fatura de R$ 199,00 venceu há 3 dias.","lastAttempt":"2026-09-13T09:00:00-03:00","nextAttempt":"2026-09-13T09:00:00-03:00","processedAt":null,"createdAt":"2026-09-13T08:59:00-03:00","solarzChatMessageId":null,"solarzChatConversationId":null,"attempts":[{"id":9101,"success":false,"errorMessage":"Número sem WhatsApp","createdAt":"2026-09-13T09:00:00-03:00"}]}],"page":{"number":1,"size":5,"totalElements":1,"totalPages":1,"hasNext":false},"meta":{"requestId":"req_12","filters":{"saleId":"98231"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/openApi/seller/pay/v1/subscriptions":{"get":{"tags":["Assinaturas"],"operationId":"listSubscriptions","summary":"Lista assinaturas dos clientes finais","x-required-privilege":"SUBSCRIPTION_CLIENT_LIST","description":"Lista as assinaturas recorrentes da conta. Os intervalos de data são opcionais (máximo 12 meses cada).\n`status=ACTIVE` é um **grupo**: traz ACTIVATING, REGULAR, OVERDUE e IRREGULAR. A resposta sempre\ntraz o status concreto.\n\nUse para: \"quantas assinaturas estão inadimplentes\" (`status=OVERDUE`), \"assinaturas do cliente X\",\n\"o que renova na próxima semana\" (`nextRenewFrom/nextRenewTo`).\n","parameters":[{"name":"status","in":"query","description":"Um ou mais status, separados por vírgula. `ACTIVE` = grupo das assinaturas ativas.","style":"form","explode":false,"schema":{"type":"array","items":{"$ref":"#/components/schemas/SubscriptionStatusFilter"}},"example":["ACTIVE"]},{"name":"planId","in":"query","description":"ID do plano da assinatura.","schema":{"type":"integer","format":"int64"}},{"name":"cycle","in":"query","description":"Periodicidade da assinatura.","schema":{"$ref":"#/components/schemas/PlanCycle"}},{"$ref":"#/components/parameters/CustomerId"},{"$ref":"#/components/parameters/ResponsibleId"},{"$ref":"#/components/parameters/PlantId"},{"name":"externalIdentifier","in":"query","description":"Identificador externo da assinatura (definido pelo integrador), comparação exata.","schema":{"type":"string","maxLength":128}},{"name":"nextRenewFrom","in":"query","description":"Renovação prevista a partir desta data (YYYY-MM-DD, inclusive). Use junto com `nextRenewTo`.","schema":{"type":"string","format":"date"}},{"name":"nextRenewTo","in":"query","description":"Renovação prevista até esta data (YYYY-MM-DD, inclusive).","schema":{"type":"string","format":"date"}},{"$ref":"#/components/parameters/CreatedAtFrom"},{"$ref":"#/components/parameters/CreatedAtTo"},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"},{"name":"fields","in":"query","description":"Campos de `SubscriptionSummary` a devolver, separados por vírgula (o `id` sempre vem).","schema":{"type":"string"}}],"responses":{"200":{"description":"Página de assinaturas, da mais recente para a mais antiga.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PageEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SubscriptionSummary"}}}}]},"example":{"data":[{"id":4410,"externalIdentifier":"CONTRATO-2026-001","status":"OVERDUE","planId":88,"planName":"Manutenção mensal","cycle":"MENSAL","customer":{"id":7781,"name":"Maria Souza","documentMasked":"***.456.789-**","emailMasked":"ma***a@exemplo.com"},"responsible":{"id":512,"name":"João Vendas"},"plantIds":[3301],"paymentMethod":"CREDIT_CARD","recurringAmount":{"amountCents":19900,"currency":"BRL"},"nextRenewAt":"2026-10-01T00:00:00-03:00","expiresAt":"2026-10-01T00:00:00-03:00","createdAt":"2026-01-10T10:00:00-03:00"}],"page":{"number":1,"size":50,"totalElements":1,"totalPages":1,"hasNext":false},"meta":{"requestId":"req_2","filters":{"status":["OVERDUE"]}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/openApi/seller/pay/v1/subscriptions/{subscriptionId}":{"get":{"tags":["Assinaturas"],"operationId":"getSubscription","summary":"Detalhe de uma assinatura","x-required-privilege":"SUBSCRIPTION_CLIENT_LIST","description":"Retorna a assinatura com plano, itens, cliente, responsável, usinas, regras de renovação, multa e juros.\nPara ver as cobranças geradas por ela, use `GET /openApi/seller/pay/v1/sales?subscriptionId={id}` com um intervalo de datas.\n","parameters":[{"name":"subscriptionId","in":"path","required":true,"description":"ID da assinatura (campo `id` da listagem de assinaturas).","schema":{"type":"integer","format":"int64"}},{"name":"fields","in":"query","description":"Campos de `SubscriptionDetail` a devolver, separados por vírgula (o `id` sempre vem).","schema":{"type":"string"}}],"responses":{"200":{"description":"Assinatura encontrada.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SubscriptionDetail"},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"data":{"id":4410,"status":"REGULAR","cycle":"MENSAL","recurringAmount":{"amountCents":19900,"currency":"BRL"},"autoRenew":true,"renewedTimes":8,"maxRenewTimes":null},"meta":{"requestId":"req_3"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/openApi/seller/pay/v1/subscriptions/{subscriptionId}/cycles":{"get":{"tags":["Assinaturas"],"operationId":"listSubscriptionCycles","summary":"Lista os ciclos de uma assinatura","x-required-privilege":"SUBSCRIPTION_CLIENT_LIST","description":"Ciclos (períodos de cobrança) da assinatura, do mais recente para o mais antigo, com o status e os totais\ndo painel. Valores em `Money` (centavos). `saleIds` são as cobranças do ciclo: para os detalhes, use\n`GET /openApi/seller/pay/v1/sales/{saleId}` ou a listagem de vendas com `subscriptionId`.\n\nUse para: \"quais meses desta assinatura estão em aberto\", \"quanto recebi neste ciclo\".\n","parameters":[{"name":"subscriptionId","in":"path","required":true,"description":"ID da assinatura (campo `id` da listagem de assinaturas).","schema":{"type":"integer","format":"int64"}},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"},{"name":"fields","in":"query","description":"Campos de `SubscriptionCycle` a devolver, separados por vírgula (o `id` sempre vem).","schema":{"type":"string"}}],"responses":{"200":{"description":"Página de ciclos.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PageEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SubscriptionCycle"}}}}]},"example":{"data":[{"id":3301,"status":"PARTIALLY_PAID","startAt":"2026-09-01","endAt":"2026-09-30","renewDueDate":"2026-09-10","priceCycle":{"amountCents":19900,"currency":"BRL"},"totalReceived":{"amountCents":9950,"currency":"BRL"},"totalExpected":{"amountCents":9950,"currency":"BRL"},"totalLated":{"amountCents":0,"currency":"BRL"},"totalLost":null,"paidExternally":false,"consideredLoss":false,"finished":false,"justificationLost":null,"saleIds":[98231,98232],"createdAt":"2026-08-25T03:00:00-03:00"}],"page":{"number":1,"size":50,"totalElements":1,"totalPages":1,"hasNext":false},"meta":{"requestId":"req_12","filters":{"subscriptionId":"4410"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/openApi/seller/pay/v1/billing-ruler":{"get":{"tags":["Régua de cobrança"],"operationId":"getBillingRuler","summary":"Régua de cobrança da conta","x-required-privilege":"BILLING_RULER_PAGE_ACCESS","description":"A régua de cobrança da conta, igual à tela \"Régua de cobrança\" do painel.\n\n- `generateDaysBeforeCharge`: com quantos dias de antecedência do vencimento a cobrança da assinatura\n  é gerada (regra geral). `generateChargeWithDuration`: por quantos dias depois do vencimento a cobrança\n  continua pagável antes de ser cancelada. `sendChargeMessageAfterDays`: intervalo de reenvio da\n  mensagem de cobrança vencida (0 = não reenvia).\n- `automations[]` traz uma regra por slot. `paymentForm: null` é a regra geral; `CREDIT_CARD`,\n  `PIX_AUTOMATIC` e `BOLETO_PIX` valem para assinaturas cobradas só naquela forma. `triggerValue` é o\n  número de dias (texto). `isBase: true` = padrão do Solarz Pay; `false` = configurado pela conta.\n- As mensagens enviadas ao cliente ficam em `GET /billing-ruler/messages`.\n\nSe a conta ainda não tem régua, a régua padrão é criada nesta chamada, como acontece ao abrir a tela.\n\nUse para: \"com quantos dias de antecedência as cobranças são geradas\", \"a régua do cartão é\ndiferente da do boleto?\".\n","parameters":[{"name":"fields","in":"query","description":"Campos de `BillingRuler` a devolver, separados por vírgula (o `id` sempre vem).","schema":{"type":"string"}}],"responses":{"200":{"description":"Régua da conta.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BillingRuler"},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"data":{"id":310,"generateDaysBeforeCharge":7,"sendChargeMessageAfterDays":3,"generateChargeWithDuration":10,"customBillingMessage":"Olá @[Cliente](#user_name), sua cobrança de @[Valor](#valor_cobranca) vence em @[Vencimento](#vencimento).","automations":[{"id":9001,"trigger":"DAYS_BEFORE_DUEDATE","triggerValue":"7","action":"CREATE_SUBSCRIPTION_BILLING","actionValue":null,"paymentForm":null,"isBase":false},{"id":3,"trigger":"DAYS_BEFORE_DUEDATE","triggerValue":"10","action":"CREATE_SUBSCRIPTION_BILLING","actionValue":null,"paymentForm":"PIX_AUTOMATIC","isBase":true}]},"meta":{"requestId":"req_4"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/openApi/seller/pay/v1/billing-ruler/messages":{"get":{"tags":["Régua de cobrança"],"operationId":"listBillingRulerMessages","summary":"Mensagens de cobrança da régua","x-required-privilege":"BILLING_RULER_PAGE_ACCESS","description":"Mensagens que o Solarz Pay envia ao cliente final ao longo da cobrança, iguais à tela de mensagens da\nrégua, 10 por página, das mais antigas para as mais novas.\n\n- `period` + `days`: quando a mensagem sai (`CRIACAO_COBRANCA`, `ANTES_VENCIMENTO`, `IN_VENCIMENTO`,\n  `POS_VENCIMENTO`). `type`: canal (`EMAIL`, `WHATSAPP`, `WHATSAPP_EMAIL`).\n- `text` vem com os placeholders sem substituir: `@[Rótulo](#token)`, com os tokens `#valor_cobranca`,\n  `#link_pagamento`, `#servicos`, `#integrador_name`, `#user_name`, `#plant_name`, `#forma_pagamento`,\n  `#vencimento` e `#mes_ano`; mensagens antigas usam `{{...}}`.\n","parameters":[{"name":"paymentForm","in":"query","description":"Só as mensagens desta forma de pagamento.","schema":{"$ref":"#/components/schemas/BillingRulerMessagePaymentForm"}},{"$ref":"#/components/parameters/Page"},{"name":"fields","in":"query","description":"Campos de `BillingRulerMessage` a devolver, separados por vírgula (o `id` sempre vem).","schema":{"type":"string"}}],"responses":{"200":{"description":"Página de mensagens (10 por página).","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PageEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BillingRulerMessage"}}}}]},"example":{"data":[{"id":3021,"days":3,"type":"WHATSAPP_EMAIL","period":"ANTES_VENCIMENTO","paymentForm":"BOLETO_PIX","text":"Olá @[Cliente](#user_name), ...","gupshupTemplateId":null,"gupshupTemplateParams":null,"inboxId":null,"templateCategory":"UTILITY"}],"page":{"number":1,"size":10,"totalElements":1,"totalPages":1,"hasNext":false},"meta":{"requestId":"req_5","filters":{}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/openApi/seller/pay/v1/balance":{"get":{"tags":["Financeiro"],"operationId":"getBalance","summary":"Saldo em conta do integrador","x-required-privilege":"ACCOUNT_INTEGRADOR_VIEW_STATEMENT","description":"Saldo da conta Solarz Pay ativa, do último registro de saldo gravado pelo Solarz (leitura diária).\n**Não é tempo real:** recebimentos e saques depois de `asOf` não estão nele. Sem registro de saldo,\n`balance` e `asOf` vêm nulos.\n\nUse para: \"qual era meu saldo hoje de manhã\". Para saques, use `GET /withdrawals`.\n","parameters":[{"name":"fields","in":"query","description":"Campos de `Balance` a devolver, separados por vírgula.","schema":{"type":"string"}}],"responses":{"200":{"description":"Saldo.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Balance"},"meta":{"$ref":"#/components/schemas/Meta"}}},"example":{"data":{"accountId":81,"balance":{"amountCents":152035,"currency":"BRL"},"asOf":"2026-10-06T07:00:12-03:00"},"meta":{"requestId":"req_6"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/openApi/seller/pay/v1/withdrawals":{"get":{"tags":["Financeiro"],"operationId":"listWithdrawals","summary":"Lista os saques da conta","x-required-privilege":"ACCOUNT_INTEGRADOR_VIEW_STATEMENT","description":"Saques pedidos pelas contas Solarz Pay do integrador, do mais recente para o mais antigo (por `createdAt`).\nO intervalo de datas é opcional (máximo 12 meses) e filtra o mesmo `createdAt`.\n\n`amount` e `transferFee` são `Money`, em centavos, como o `balance` de `GET /balance`. `status` é o status\ndo gateway (ex.: `PENDING`, `DONE`, `FAILED`, `CANCELLED`). `accountId` diz de qual conta saiu o saque.\n\n**Lacunas conhecidas:** saques Iugu antigos feitos pela tela legada não foram registrados no Solarz, e\nalguns saques antigos não puderam ser ligados a uma conta. Nenhum dos dois aparece aqui.\n\nUse para: \"quanto saquei em setembro\" (`createdAtFrom/createdAtTo`, some `amount.amountCents` dos `DONE`),\n\"tem saque falhado?\" (`status=FAILED`).\n","parameters":[{"name":"status","in":"query","description":"Um ou mais status do gateway, separados por vírgula (sem diferenciar maiúsculas).","style":"form","explode":false,"schema":{"type":"array","items":{"type":"string"}},"example":["DONE"]},{"$ref":"#/components/parameters/CreatedAtFrom"},{"$ref":"#/components/parameters/CreatedAtTo"},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"},{"name":"fields","in":"query","description":"Campos de `Withdrawal` a devolver, separados por vírgula (o `id` sempre vem).","schema":{"type":"string"}}],"responses":{"200":{"description":"Página de saques.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PageEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Withdrawal"}}}}]},"example":{"data":[{"id":912,"accountId":81,"withdrawId":"tra_000012345678","amount":{"amountCents":500000,"currency":"BRL"},"transferFee":{"amountCents":0,"currency":"BRL"},"status":"DONE","operationType":"PIX","createdAt":"2026-10-02T09:15:43-03:00","payingAt":"2026-10-02"}],"page":{"number":1,"size":50,"totalElements":1,"totalPages":1,"hasNext":false},"meta":{"requestId":"req_7","filters":{"status":["DONE"]}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/openApi/seller/pay/v1/plans":{"get":{"tags":["Catálogo"],"operationId":"listPlans","summary":"Lista os planos","x-required-privilege":"PLAN_AND_ITEMS_VIEW_PLANS","description":"Planos de assinatura da conta, iguais à listagem de planos do painel, do mais novo para o mais antigo.\n\n- `price` do plano em **reais**; `items[].price` e `items[].item.price` em **centavos**.\n- `subscribers`: quantas assinaturas usam o plano.\n- `intervalType` + `intervals`: periodicidade (ex.: `MENSAL`, 12 ciclos); `intervalCycleOption` diz se o\n  número de ciclos é limitado.\n- `payableWith`: formas de pagamento aceitas (JSON em texto, ex. `[\"credit_card\",\"pix\"]`).\n\nUse para: \"quais planos tenho ativos\", \"quantos assinantes tem o plano X\", \"o que vem no plano X\".\n","parameters":[{"name":"query","in":"query","description":"Busca no nome (contém, sem diferenciar maiúsculas). Vazio = todos.","schema":{"type":"string","default":""}},{"name":"status","in":"query","description":"Situação do cadastro.","schema":{"type":"string","enum":["ALL","ACTIVE","INACTIVE"],"default":"ALL"}},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"},{"name":"fields","in":"query","description":"Campos de `Plan` a devolver, separados por vírgula (o `id` sempre vem).","schema":{"type":"string"}}],"responses":{"200":{"description":"Página de planos.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PageEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Plan"}}}}]},"example":{"data":[{"id":88,"name":"Manutenção mensal","identifier":"manutencao_mensal","intervalType":"MENSAL","intervals":"12","subscribers":41,"price":199.0,"status":"ACTIVE","items":[{"id":301,"item":{"id":12,"name":"Limpeza","description":null,"price":19900,"type":{"id":4,"name":"Serviço","category":"SERVICE","status":"ACTIVE","createdAt":"2026-01-10T10:00:00"},"status":"ACTIVE","createdAt":"2026-01-10T10:00:00"},"price":19900,"quantity":1,"isRecurrent":true,"createdAt":"2026-01-10T10:00:00"}],"payableWith":"[\"credit_card\",\"pix\"]","intervalCycleOption":"LIMITED"}],"page":{"number":1,"size":50,"totalElements":1,"totalPages":1,"hasNext":false},"meta":{"requestId":"req_8","filters":{}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/openApi/seller/pay/v1/products":{"get":{"tags":["Catálogo"],"operationId":"listProducts","summary":"Lista os produtos","x-required-privilege":"PLAN_AND_ITEMS_VIEW_PRODUCTS","description":"Produtos (itens que compõem planos e vendas) da conta, iguais à listagem de produtos do painel, do mais\nnovo para o mais antigo. `price` em **centavos**. Como no painel, `status=ALL` (padrão) inclui os\nprodutos excluídos (`status: DELETED`); use `status=ACTIVE` para só os disponíveis.\n\nUse para: \"quanto custa o produto X\", \"quais produtos estão inativos\".\n","parameters":[{"name":"query","in":"query","description":"Busca no nome (contém, sem diferenciar maiúsculas). Vazio = todos.","schema":{"type":"string","default":""}},{"name":"status","in":"query","description":"Situação do cadastro.","schema":{"type":"string","enum":["ALL","ACTIVE","INACTIVE"],"default":"ALL"}},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"},{"name":"fields","in":"query","description":"Campos de `Product` a devolver, separados por vírgula (o `id` sempre vem).","schema":{"type":"string"}}],"responses":{"200":{"description":"Página de produtos.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PageEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}}}}]},"example":{"data":[{"id":12,"name":"Limpeza","status":"ACTIVE","price":19900,"type":{"id":4,"name":"Serviço","category":"SERVICE"}}],"page":{"number":1,"size":50,"totalElements":1,"totalPages":1,"hasNext":false},"meta":{"requestId":"req_9","filters":{}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/openApi/seller/pay/v1/chargebacks":{"get":{"tags":["Chargebacks"],"operationId":"listChargebacks","summary":"Lista os chargebacks","x-required-privilege":"CHARGEBACK_PAGE_ACCESS","description":"Chargebacks (contestações de compra no cartão feitas pelo cliente junto ao banco) das cobranças da conta,\ndo mais recente para o mais antigo, como na tela de chargebacks do painel. Só contas Asaas têm chargeback.\n`expiresAt` é o prazo para contestar no painel. `salePrice` em centavos.\nContestar e aceitar um chargeback só pelo painel.\n\nUse para: \"tenho chargeback pendente?\" (`status=PENDING`), \"qual o prazo para contestar\".\n","parameters":[{"name":"status","in":"query","description":"Um ou mais status, separados por vírgula.","style":"form","explode":false,"schema":{"type":"array","items":{"$ref":"#/components/schemas/ChargebackStatus"}}},{"name":"saleStage","in":"query","description":"Estágio da cobrança contestada.","schema":{"$ref":"#/components/schemas/SaleStage"}},{"name":"saleId","in":"query","description":"ID da cobrança contestada.","schema":{"type":"integer","format":"int64"}},{"name":"customerId","in":"query","description":"Um ou mais IDs de cliente (até 50), separados por vírgula.","style":"form","explode":false,"schema":{"type":"array","maxItems":50,"items":{"type":"integer","format":"int64"}}},{"name":"reason","in":"query","description":"Um ou mais motivos, separados por vírgula.","style":"form","explode":false,"schema":{"type":"array","items":{"$ref":"#/components/schemas/ChargebackReason"}}},{"name":"details","in":"query","description":"Busca no motivo (`details`), contém, sem diferenciar maiúsculas.","schema":{"type":"string"}},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"},{"name":"fields","in":"query","description":"Campos de `Chargeback` a devolver, separados por vírgula (o `id` sempre vem).","schema":{"type":"string"}}],"responses":{"200":{"description":"Página de chargebacks.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PageEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Chargeback"}}}}]},"example":{"data":[{"id":77,"chargebackHubId":"chbk_123","status":"PENDING","details":"Desacordo comercial","justification":null,"expiresAt":"2026-10-20","createdAt":"2026-10-05T10:00:00-03:00","saleId":98231,"saleStage":"IN_DISPUTE","salePrice":{"amountCents":152035,"currency":"BRL"},"customerId":7781,"customerName":"Maria Souza"}],"page":{"number":1,"size":50,"totalElements":1,"totalPages":1,"hasNext":false},"meta":{"requestId":"req_13","filters":{"status":["PENDING"]}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalError"}}}}},"components":{"securitySchemes":{"OpenApiUserBasic":{"type":"http","scheme":"basic","description":"Username (`oa_...`) e senha do Usuário de API (gerados no painel do Solarz). Login por e-mail não é aceito."}},"parameters":{"Page":{"name":"page","in":"query","description":"Número da página, começando em 1. Máximo 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":1}},"PageSize":{"name":"pageSize","in":"query","description":"Itens por página. Padrão 50, máximo 200.","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},"CustomerId":{"name":"customerId","in":"query","description":"ID do cliente final (id do usuário do cliente; o mesmo `customer.id` das respostas).","schema":{"type":"integer","format":"int64"}},"ResponsibleId":{"name":"responsibleId","in":"query","description":"ID do usuário responsável (quem é dono da cobrança/assinatura dentro da conta).","schema":{"type":"integer","format":"int64"}},"PlantId":{"name":"plantId","in":"query","description":"Uma ou mais usinas vinculadas (até 50 IDs, separados por vírgula). Mesmo ID de /openApi/seller/plant/list.","style":"form","explode":false,"schema":{"type":"array","maxItems":50,"items":{"type":"integer","format":"int64"}}},"DueDateFrom":{"name":"dueDateFrom","in":"query","description":"Vencimento a partir de (YYYY-MM-DD, inclusive). Use junto com `dueDateTo`.","schema":{"type":"string","format":"date"}},"DueDateTo":{"name":"dueDateTo","in":"query","description":"Vencimento até (YYYY-MM-DD, inclusive). No máximo 12 meses após `dueDateFrom`.","schema":{"type":"string","format":"date"}},"PaidAtFrom":{"name":"paidAtFrom","in":"query","description":"Pago a partir de (YYYY-MM-DD, inclusive). Use junto com `paidAtTo`.","schema":{"type":"string","format":"date"}},"PaidAtTo":{"name":"paidAtTo","in":"query","description":"Pago até (YYYY-MM-DD, inclusive). No máximo 12 meses após `paidAtFrom`.","schema":{"type":"string","format":"date"}},"CreatedAtFrom":{"name":"createdAtFrom","in":"query","description":"Criado a partir de (YYYY-MM-DD, inclusive). Use junto com `createdAtTo`.","schema":{"type":"string","format":"date"}},"CreatedAtTo":{"name":"createdAtTo","in":"query","description":"Criado até (YYYY-MM-DD, inclusive). No máximo 12 meses após `createdAtFrom`.","schema":{"type":"string","format":"date"}}},"headers":{"X-Request-Id":{"description":"ID único da requisição. Informe ao suporte em caso de problema.","schema":{"type":"string"}}},"schemas":{"SaleType":{"type":"string","description":"Origem da cobrança.\n- `SIMPLES_SALE`: venda avulsa\n- `SUBSCRIPTION`: cobrança gerada pelo ciclo de uma assinatura\n- `SUBSCRIPTION_SIMPLES_SALE`: venda avulsa vinculada a uma assinatura\n","enum":["SIMPLES_SALE","SUBSCRIPTION","SUBSCRIPTION_SIMPLES_SALE"]},"SaleStage":{"type":"string","description":"Estágio da cobrança.\n- `PENDING`: criada, ainda não enviada ao gateway\n- `WAITING_PAYMENT`: aguardando pagamento\n- `PARTIALLY_PAID`: parcialmente paga\n- `DONE`: paga\n- `EXPIRED`: vencida e não paga, **mas ainda pode ser paga**\n- `LAPSED`: caducada, **não pode mais ser paga**\n- `PAYMENT_FAILED`: tentativa de pagamento falhou (ex.: cartão recusado)\n- `LOST`: considerada perdida (ver `lostType`)\n- `CANCELED`: cancelada\n- `REFUNDED`: estornada\n- `IN_DISPUTE`: em disputa (chargeback aberto)\n- `IN_PROTEST`: em protesto\n","enum":["PENDING","WAITING_PAYMENT","PARTIALLY_PAID","DONE","EXPIRED","LAPSED","PAYMENT_FAILED","LOST","CANCELED","REFUNDED","IN_DISPUTE","IN_PROTEST"]},"LostType":{"type":"string","nullable":true,"description":"Motivo da perda, quando `stage = LOST`.","enum":["FORGIVEN","RENEGOTIATED","CANCELED","OTHERS","CHARGEBACk"]},"PaymentMethod":{"type":"string","description":"Forma de pagamento.","enum":["BOLETO","CREDIT_CARD","PIX","PIX_AUTOMATIC","WALLET","EXTERNAL","OTHERS"]},"Gateway":{"type":"string","description":"Gateway de pagamento da cobrança/assinatura.","enum":["ASAAS","IUGU"]},"SubscriptionStatus":{"type":"string","description":"Status da assinatura.\n- `ACTIVATING`: em ativação (aguardando o primeiro pagamento)\n- `REGULAR`: em dia\n- `OVERDUE`: em atraso (inadimplente)\n- `IRREGULAR`: com pendência em algum ciclo\n- `CHURN`: cliente perdido\n- `CANCELED`: cancelada\n- `FINISHED`: encerrada (atingiu o número de renovações)\n- `FINISHED_WITH_DEPENDENCIES`: encerrada com pendências\n- `ACTIVE`, `INACTIVE`, `FAILURE_RENEW`: **legados**, só em registros antigos\n","enum":["ACTIVATING","REGULAR","OVERDUE","IRREGULAR","CHURN","CANCELED","FINISHED","FINISHED_WITH_DEPENDENCIES","ACTIVE","INACTIVE","FAILURE_RENEW"]},"SubscriptionStatusFilter":{"type":"string","description":"Valor aceito no filtro `status`. Além dos status concretos, `ACTIVE` é o **grupo** das\nassinaturas ativas (ACTIVATING, REGULAR, OVERDUE, IRREGULAR e o legado ACTIVE).\n","enum":["ACTIVE","ACTIVATING","REGULAR","OVERDUE","IRREGULAR","CHURN","CANCELED","FINISHED","FINISHED_WITH_DEPENDENCIES","INACTIVE","FAILURE_RENEW"]},"PlanCycle":{"type":"string","description":"Periodicidade do plano/assinatura.","enum":["MENSAL","TRIMESTRAL","SEMESTRAL","ANUAL","BIENAL"]},"ProductCategory":{"type":"string","enum":["SERVICE","PRODUCT"]},"Money":{"type":"object","nullable":true,"description":"Valor monetário em centavos (inteiro, sem arredondamento). Divida por 100 para exibir.","required":["amountCents","currency"],"properties":{"amountCents":{"type":"integer","format":"int64","example":152035},"currency":{"type":"string","example":"BRL"}}},"PersonRef":{"type":"object","nullable":true,"description":"Usuário interno da conta (ex.: responsável).","properties":{"id":{"type":"integer","format":"int64"},"name":{"type":"string"}}},"CustomerRef":{"type":"object","nullable":true,"description":"Cliente final pagador. `id` é o id do usuário do cliente (único no sistema; use em `customerId`).\nE-mail e documento vêm sempre mascarados.\n","properties":{"id":{"type":"integer","format":"int64"},"name":{"type":"string"},"documentMasked":{"type":"string","nullable":true,"example":"***.456.789-**","description":"CPF `***.456.789-**`, CNPJ `**.345.678/0001-**`."},"emailMasked":{"type":"string","nullable":true,"example":"ma***a@exemplo.com","description":"Domínio inteiro; meio da parte local censurado."}}},"PlantRef":{"type":"object","properties":{"id":{"type":"integer","format":"int64","description":"Mesmo ID de /openApi/seller/plant/list."},"name":{"type":"string","nullable":true}}},"LineItem":{"type":"object","description":"Item cobrado (produto ou serviço) com preço e quantidade no momento da venda/assinatura.","properties":{"productId":{"type":"integer","format":"int64","nullable":true},"productName":{"type":"string","nullable":true},"category":{"$ref":"#/components/schemas/ProductCategory"},"unitPrice":{"$ref":"#/components/schemas/Money"},"quantity":{"type":"integer","nullable":true},"recurrent":{"type":"boolean","nullable":true,"description":"`true` se o item é cobrado em todo ciclo; `false` se só na primeira cobrança."}}},"LateFees":{"type":"object","description":"Multa e juros por atraso, com o valor gravado na cobrança/assinatura.","properties":{"finePercentage":{"type":"integer","nullable":true},"fineCents":{"type":"integer","nullable":true},"dailyInterestPercentage":{"type":"integer","nullable":true},"dailyInterestCents":{"type":"integer","nullable":true}}},"SaleSummary":{"type":"object","description":"Cobrança resumida, para listagens.","properties":{"id":{"type":"integer","format":"int64"},"type":{"$ref":"#/components/schemas/SaleType"},"stage":{"$ref":"#/components/schemas/SaleStage"},"subscriptionId":{"type":"integer","format":"int64","nullable":true,"description":"Assinatura de origem","se houver.":null},"customer":{"$ref":"#/components/schemas/CustomerRef"},"responsible":{"$ref":"#/components/schemas/PersonRef"},"plantIds":{"type":"array","items":{"type":"integer","format":"int64"}},"price":{"$ref":"#/components/schemas/Money"},"expectedAmount":{"$ref":"#/components/schemas/Money"},"paidAmount":{"$ref":"#/components/schemas/Money"},"paymentMethod":{"$ref":"#/components/schemas/PaymentMethod"},"installments":{"type":"integer","nullable":true,"description":"Número de parcelas no cartão."},"dueDate":{"type":"string","format":"date","nullable":true,"description":"Vencimento (YYYY-MM-DD)."},"paidAt":{"type":"string","format":"date-time","nullable":true,"example":"2026-08-10T14:32:00-03:00"},"crmCardId":{"type":"integer","format":"int64","nullable":true,"description":"Card ativo no CRM."},"createdAt":{"type":"string","format":"date-time","example":"2026-07-25T09:12:44-03:00"}}},"SaleDetail":{"allOf":[{"$ref":"#/components/schemas/SaleSummary"},{"type":"object","properties":{"lostType":{"$ref":"#/components/schemas/LostType"},"justification":{"type":"string","nullable":true,"description":"Texto livre informado ao cancelar/perder. Pode conter dados pessoais."},"gateway":{"$ref":"#/components/schemas/Gateway"},"items":{"type":"array","items":{"$ref":"#/components/schemas/LineItem"}},"plants":{"type":"array","items":{"$ref":"#/components/schemas/PlantRef"}},"payableOptions":{"type":"array","items":{"$ref":"#/components/schemas/PaymentMethod"},"description":"Formas de pagamento aceitas."},"maxInstallments":{"type":"integer","nullable":true},"installmentsFee":{"$ref":"#/components/schemas/Money"},"passServicesFeeToCustomer":{"type":"boolean","nullable":true,"description":"Taxa do gateway repassada ao cliente."},"passInstallmentsFeeToCustomer":{"type":"boolean","nullable":true,"description":"Juros de parcelamento repassados ao cliente."},"feesAmount":{"$ref":"#/components/schemas/Money"},"originalDueDate":{"type":"string","format":"date","nullable":true,"description":"Vencimento original","antes de qualquer alteração.":null},"paymentDeadline":{"type":"string","format":"date","nullable":true,"description":"Data limite para pagamento após o vencimento."},"expectedReceiptDate":{"type":"string","format":"date","nullable":true,"description":"Previsão de o dinheiro cair na conta."},"receivedDate":{"type":"string","format":"date","nullable":true,"description":"Data em que o dinheiro caiu na conta."},"paidExternally":{"type":"boolean","nullable":true,"description":"Marcada como paga fora do Solarz Pay."},"systemGenerated":{"type":"boolean","nullable":true,"description":"Criada automaticamente pelo sistema (ex.: renovação)."},"paymentLink":{"type":"string","nullable":true,"description":"Link de pagamento para enviar ao cliente."},"lateFees":{"$ref":"#/components/schemas/LateFees"},"notifications":{"type":"object","properties":{"whatsapp":{"type":"boolean","nullable":true},"email":{"type":"boolean","nullable":true},"lastBillingMessageAt":{"type":"string","format":"date-time","nullable":true}}},"crm":{"type":"object","description":"Vínculo da cobrança com o CRM.","properties":{"cardId":{"type":"integer","format":"int64","nullable":true,"description":"Card ativo no CRM."},"previousCardIds":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Cards anteriores."}}},"installmentsSummary":{"type":"object","description":"Contagem das faturas no gateway desta cobrança.","properties":{"total":{"type":"integer"},"open":{"type":"integer"},"refunded":{"type":"integer"}}},"chargebackIds":{"type":"array","items":{"type":"integer","format":"int64"}},"createdBy":{"$ref":"#/components/schemas/PersonRef"}}}]},"SubscriptionSummary":{"type":"object","description":"Assinatura resumida, para listagens.","properties":{"id":{"type":"integer","format":"int64"},"externalIdentifier":{"type":"string","nullable":true},"status":{"$ref":"#/components/schemas/SubscriptionStatus"},"planId":{"type":"integer","format":"int64","nullable":true},"planName":{"type":"string","nullable":true},"cycle":{"$ref":"#/components/schemas/PlanCycle"},"customer":{"$ref":"#/components/schemas/CustomerRef"},"responsible":{"$ref":"#/components/schemas/PersonRef"},"plantIds":{"type":"array","items":{"type":"integer","format":"int64"}},"paymentMethod":{"$ref":"#/components/schemas/PaymentMethod"},"recurringAmount":{"$ref":"#/components/schemas/Money"},"nextRenewAt":{"type":"string","format":"date-time","nullable":true,"description":"Próxima renovação prevista."},"expiresAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"SubscriptionDetail":{"allOf":[{"$ref":"#/components/schemas/SubscriptionSummary"},{"type":"object","properties":{"gateway":{"$ref":"#/components/schemas/Gateway"},"items":{"type":"array","items":{"$ref":"#/components/schemas/LineItem"}},"plants":{"type":"array","items":{"$ref":"#/components/schemas/PlantRef"}},"payableOptions":{"type":"array","items":{"$ref":"#/components/schemas/PaymentMethod"}},"activated":{"type":"boolean","nullable":true},"autoRenew":{"type":"boolean","nullable":true,"description":"Renova automaticamente ao fim do ciclo."},"renewedTimes":{"type":"integer","nullable":true},"maxRenewTimes":{"type":"integer","nullable":true,"description":"`null` = sem limite."},"maxInstallments":{"type":"integer","nullable":true},"renewInstallments":{"type":"integer","nullable":true},"onlyCreateWhenPayable":{"type":"boolean","nullable":true},"suspendOnInvoiceExpired":{"type":"boolean","nullable":true},"passServicesFeeToCustomer":{"type":"boolean","nullable":true},"passInstallmentsFeeToCustomer":{"type":"boolean","nullable":true},"lateFees":{"$ref":"#/components/schemas/LateFees"},"notifications":{"type":"object","properties":{"whatsapp":{"type":"boolean","nullable":true},"email":{"type":"boolean","nullable":true}}},"lastCycledAt":{"type":"string","format":"date-time","nullable":true},"finishedAt":{"type":"string","format":"date-time","nullable":true},"justification":{"type":"string","nullable":true},"createdBy":{"$ref":"#/components/schemas/PersonRef"}}}]},"BillingRuler":{"type":"object","description":"Régua de cobrança da conta (o mesmo objeto da tela do painel).","properties":{"id":{"type":"integer","format":"int64"},"generateDaysBeforeCharge":{"type":"integer","nullable":true,"description":"Dias antes do vencimento em que a cobrança da assinatura é gerada (regra geral)."},"sendChargeMessageAfterDays":{"type":"integer","nullable":true,"description":"Dias entre reenvios da mensagem de cobrança vencida. 0 = não reenvia."},"generateChargeWithDuration":{"type":"integer","nullable":true,"description":"Dias depois do vencimento em que a cobrança ainda pode ser paga (regra geral)."},"customBillingMessage":{"type":"string","nullable":true,"description":"Mensagem geral de cobrança; a padrão do Solarz Pay quando a conta não tem uma."},"automations":{"type":"array","items":{"$ref":"#/components/schemas/BillingRulerAutomation"}}}},"BillingRulerAutomation":{"type":"object","description":"Uma regra da régua.","properties":{"id":{"type":"integer","format":"int64"},"trigger":{"type":"string","enum":["DAYS_BEFORE_DUEDATE","DAYS_AFTER_DUEDATE"]},"triggerValue":{"type":"string","nullable":true,"description":"Número de dias","em texto.":null},"action":{"type":"string","enum":["CREATE_SUBSCRIPTION_BILLING","CANCEL_BILLING"],"description":"`CREATE_SUBSCRIPTION_BILLING` = gera a cobrança da assinatura `triggerValue` dias antes do vencimento. `CANCEL_BILLING` = cancela a cobrança `triggerValue` dias depois do vencimento."},"actionValue":{"type":"string","nullable":true},"paymentForm":{"type":"string","nullable":true,"enum":["CREDIT_CARD","PIX_AUTOMATIC","BOLETO_PIX"],"description":"Forma de pagamento da regra. Nulo = regra geral."},"isBase":{"type":"boolean","description":"`true` = padrão do Solarz Pay; `false` = configurado pela conta."}}},"BillingRulerMessagePaymentForm":{"type":"string","enum":["BOLETO_PIX","CARTAO","PIX_AUTOMATIC"]},"BillingRulerMessage":{"type":"object","description":"Mensagem de cobrança enviada ao cliente final (o mesmo objeto da tela de mensagens).","properties":{"id":{"type":"integer","format":"int64"},"days":{"type":"integer","format":"int64","nullable":true},"type":{"type":"string","nullable":true,"enum":["EMAIL","WHATSAPP","WHATSAPP_EMAIL"],"description":"Canal."},"period":{"type":"string","nullable":true,"enum":["CRIACAO_COBRANCA","ANTES_VENCIMENTO","IN_VENCIMENTO","POS_VENCIMENTO"]},"paymentForm":{"$ref":"#/components/schemas/BillingRulerMessagePaymentForm"},"text":{"type":"string","nullable":true,"description":"Texto com os placeholders sem substituir (`@[Rótulo](#token)` ou `{{...}}`)."},"gupshupTemplateId":{"type":"string","nullable":true,"description":"Template de WhatsApp usado no envio."},"gupshupTemplateParams":{"type":"string","nullable":true},"inboxId":{"type":"integer","format":"int64","nullable":true},"templateCategory":{"type":"string","nullable":true,"description":"Categoria do template de WhatsApp (MARKETING, UTILITY, AUTHENTICATION)."},"templateCategoryCheckedAt":{"type":"string","format":"date-time","nullable":true,"description":"Quando a categoria do template foi verificada."}}},"Balance":{"type":"object","properties":{"accountId":{"type":"integer","format":"int64"},"balance":{"$ref":"#/components/schemas/Money"},"asOf":{"type":"string","format":"date-time","nullable":true,"description":"Quando o saldo foi lido."}}},"Withdrawal":{"type":"object","description":"Saque de uma conta Solarz Pay.","properties":{"id":{"type":"integer","format":"int64"},"accountId":{"type":"integer","format":"int64","description":"Conta Solarz Pay de onde saiu o saque (a mesma de `GET /balance`)."},"withdrawId":{"type":"string","nullable":true,"description":"ID do saque no gateway."},"amount":{"$ref":"#/components/schemas/Money"},"transferFee":{"$ref":"#/components/schemas/Money"},"status":{"type":"string","nullable":true,"description":"Status do gateway."},"operationType":{"type":"string","nullable":true,"description":"Tipo da transferência (ex.: PIX, TED)."},"createdAt":{"type":"string","format":"date-time","description":"Quando o saque foi pedido. É o campo de `createdAtFrom/createdAtTo` e da ordenação."},"payingAt":{"type":"string","format":"date","nullable":true,"description":"Data prevista da transferência."}}},"Plan":{"type":"object","description":"Plano de assinatura (o mesmo objeto da listagem de planos do painel).","properties":{"id":{"type":"integer","format":"int64"},"name":{"type":"string"},"identifier":{"type":"string","nullable":true},"intervalType":{"type":"string","nullable":true,"description":"Periodicidade (ex.: MENSAL, ANUAL)."},"intervals":{"type":"string","nullable":true,"description":"Número de ciclos."},"subscribers":{"type":"integer","format":"int64","description":"Assinaturas que usam o plano."},"price":{"type":"number","nullable":true,"description":"Preço do plano em **reais**."},"status":{"type":"string","enum":["ACTIVE","INACTIVE"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/PlanItem"}},"payableWith":{"type":"string","nullable":true,"description":"Formas de pagamento aceitas, JSON em texto (ex. `[\"credit_card\",\"pix\"]`)."},"intervalCycleOption":{"type":"string","nullable":true,"enum":["LIMITED","ILIMITED"],"description":"`LIMITED` = número de ciclos limitado a `intervals`; `ILIMITED` = renova sem limite."}}},"PlanItem":{"type":"object","description":"Item de um plano.","properties":{"id":{"type":"integer","format":"int64"},"item":{"$ref":"#/components/schemas/PlanItemProduct"},"price":{"type":"integer","nullable":true,"description":"Preço do item no plano","em **centavos**.":null},"quantity":{"type":"integer"},"isRecurrent":{"type":"boolean","nullable":true,"description":"`true` = cobrado em todo ciclo; `false` = só na primeira cobrança."},"createdAt":{"type":"string","format":"date-time"}}},"PlanItemProduct":{"type":"object","description":"Produto do item de plano.","properties":{"id":{"type":"integer","format":"int64"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"price":{"type":"integer","nullable":true,"description":"Preço de tabela do produto","em **centavos**.":null},"type":{"$ref":"#/components/schemas/PlanItemProductType"},"status":{"type":"string","enum":["ACTIVE","INACTIVE","DELETED"]},"createdAt":{"type":"string","format":"date-time"}}},"PlanItemProductType":{"type":"object","nullable":true,"properties":{"id":{"type":"integer","format":"int64"},"name":{"type":"string"},"category":{"type":"string","nullable":true},"status":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"Product":{"type":"object","description":"Produto (o mesmo objeto da listagem de produtos do painel).","properties":{"id":{"type":"integer","format":"int64"},"name":{"type":"string"},"status":{"type":"string","enum":["ACTIVE","INACTIVE","DELETED"]},"price":{"type":"integer","nullable":true,"description":"Preço em **centavos**."},"type":{"$ref":"#/components/schemas/ProductType"}}},"ProductType":{"type":"object","nullable":true,"properties":{"id":{"type":"integer","format":"int64"},"name":{"type":"string"},"category":{"type":"string","nullable":true}}},"SaleInstallment":{"type":"object","description":"Parcela de repasse de uma cobrança (o que cai na conta e quando).","properties":{"id":{"type":"integer","format":"int64"},"billingHubId":{"type":"string","nullable":true,"description":"ID da fatura no gateway."},"installment":{"type":"integer","nullable":true,"description":"Número da parcela (1 = primeira)."},"returnDate":{"type":"string","format":"date","nullable":true,"description":"Data prevista do repasse."},"status":{"type":"string","nullable":true,"description":"Status do repasse no gateway, como gravado (ex.: pending, paid)."},"amount":{"$ref":"#/components/schemas/Money"},"taxes":{"$ref":"#/components/schemas/Money"},"commission":{"$ref":"#/components/schemas/Money"},"executedDate":{"type":"string","format":"date","nullable":true,"description":"Data em que o repasse foi feito."},"advanced":{"type":"boolean","nullable":true,"description":"Parcela antecipada."},"createdAt":{"type":"string","format":"date-time","nullable":true}}},"SaleCharge":{"type":"object","description":"Cobrança automática feita pelo Solarz para uma cobrança (cartão, Pix Automático ou boleto).","properties":{"id":{"type":"integer","format":"int64"},"type":{"type":"string","enum":["CREDIT_CARD","PIX","BANK_SLIP","PIX_AUTOMATIC"]},"stage":{"type":"string","description":"Situação da cobrança automática.\n- `PROCESSING`, `SUBMITTING`, `WAITING_OUTBOX`: em andamento\n- `CONCLUDED`: cobrada com sucesso\n- `FAILED`: falhou depois de todas as tentativas\n- `CANCELED`, `IGNORED`: não será mais tentada\n- `SCHEDULED_EXTERNALLY`: Pix Automático aceito pelo banco do pagador; o débito ocorre no vencimento\n- `INTERRUPTED`: tentativa agendada interrompida por um pagamento feito na hora\n- `AWAITING_PAYER_ACTION`: desafio 3D Secure emitido; aguarda o pagador autenticar no emissor\n","enum":["PROCESSING","SUBMITTING","WAITING_OUTBOX","CANCELED","CONCLUDED","FAILED","IGNORED","SCHEDULED_EXTERNALLY","INTERRUPTED","AWAITING_PAYER_ACTION"]},"externalId":{"type":"string","nullable":true,"description":"ID do objeto do gateway que originou a cobrança (hoje: instrução do Pix Automático)."},"attempt":{"type":"integer","format":"int64","nullable":true,"description":"Tentativas feitas."},"onFailedRetry":{"type":"integer","format":"int64","nullable":true,"description":"Máximo de tentativas."},"timeout":{"type":"integer","format":"int64","nullable":true,"description":"Minutos entre tentativas."},"lastAttempt":{"type":"string","format":"date-time","nullable":true},"nextAttempt":{"type":"string","format":"date-time","nullable":true,"description":"Próxima tentativa agendada."},"createdAt":{"type":"string","format":"date-time","nullable":true},"attempts":{"type":"array","items":{"$ref":"#/components/schemas/SaleChargeAttempt"}}}},"SaleChargeAttempt":{"type":"object","description":"Tentativa de uma cobrança automática.","properties":{"id":{"type":"integer","format":"int64"},"attempt":{"type":"integer","format":"int64","nullable":true,"description":"Número da tentativa."},"success":{"type":"boolean","nullable":true},"lr":{"type":"string","nullable":true,"description":"Código de retorno do gateway/adquirente."},"message":{"type":"string","nullable":true,"description":"Mensagem de retorno do gateway."},"description":{"type":"string","nullable":true},"cardNumber":{"type":"string","nullable":true,"description":"Número do cartão mascarado (só os últimos dígitos)."},"brand":{"type":"string","nullable":true,"description":"Bandeira do cartão."},"createdAt":{"type":"string","format":"date-time","nullable":true}}},"SaleMessage":{"type":"object","description":"Mensagem de cobrança enviada (ou agendada) ao cliente final sobre uma cobrança.","properties":{"id":{"type":"integer","format":"int64"},"stage":{"type":"string","description":"Situação do envio.\n- `SCHEDULED`: agendada para `nextAttempt`\n- `PROCESSING`, `SUBMITTING`: em envio\n- `CONCLUDED`: enviada\n- `FAILED`: falhou depois de todas as tentativas\n- `CANCELED`, `EXPIRED`: não será mais enviada\n","enum":["SCHEDULED","EXPIRED","PROCESSING","CANCELED","CONCLUDED","FAILED","SUBMITTING"]},"type":{"type":"string","nullable":true,"enum":["EMAIL","WHATSAPP","WHATSAPP_EMAIL"],"description":"Canal."},"originType":{"type":"string","nullable":true,"enum":["RULER","MANUAL"],"description":"`RULER` = régua de cobrança; `MANUAL` = enviada pelo painel."},"period":{"type":"string","nullable":true,"enum":["CRIACAO_COBRANCA","ANTES_VENCIMENTO","IN_VENCIMENTO","POS_VENCIMENTO"],"description":"Momento da régua que gerou a mensagem."},"days":{"type":"integer","format":"int64","nullable":true,"description":"Dias antes/depois do vencimento","conforme `period`.":null},"message":{"type":"string","nullable":true,"description":"Texto enviado."},"lastAttempt":{"type":"string","format":"date-time","nullable":true},"nextAttempt":{"type":"string","format":"date-time","nullable":true,"description":"Próxima tentativa (ou envio agendado)."},"processedAt":{"type":"string","format":"date-time","nullable":true,"description":"Quando o envio foi concluído."},"createdAt":{"type":"string","format":"date-time","nullable":true},"solarzChatMessageId":{"type":"string","nullable":true,"description":"ID da mensagem no Solarz Chat (WhatsApp)."},"solarzChatConversationId":{"type":"string","nullable":true,"description":"ID da conversa no Solarz Chat (WhatsApp)."},"attempts":{"type":"array","items":{"$ref":"#/components/schemas/SaleMessageAttempt"}}}},"SaleMessageAttempt":{"type":"object","description":"Tentativa de envio de uma mensagem de cobrança.","properties":{"id":{"type":"integer","format":"int64"},"success":{"type":"boolean","nullable":true},"errorMessage":{"type":"string","nullable":true,"description":"Motivo da falha","quando houver.":null},"createdAt":{"type":"string","format":"date-time","nullable":true}}},"SubscriptionCycleStatus":{"type":"string","description":"Status do ciclo, como no painel.\n- `WAITING`: aguardando pagamento\n- `PARTIALLY_PAID`: parte das cobranças paga\n- `PAID`: pago\n- `PAID_EXTERNALLY`: marcado como pago por fora\n- `IRREGULAR`: com cobrança em atraso\n- `CANCELLED`: cancelado\n- `LOST`: considerado perdido\n- `FINISHED`: não vai ocorrer (a assinatura encerrou)\n","enum":["WAITING","PARTIALLY_PAID","PAID","PAID_EXTERNALLY","IRREGULAR","CANCELLED","LOST","FINISHED"]},"SubscriptionCycle":{"type":"object","description":"Ciclo (período de cobrança) de uma assinatura.","properties":{"id":{"type":"integer","format":"int64"},"status":{"$ref":"#/components/schemas/SubscriptionCycleStatus"},"startAt":{"type":"string","format":"date","nullable":true,"description":"Início do período."},"endAt":{"type":"string","format":"date","nullable":true,"description":"Fim do período."},"renewDueDate":{"type":"string","format":"date","nullable":true,"description":"Vencimento da cobrança do ciclo."},"priceCycle":{"$ref":"#/components/schemas/Money"},"totalReceived":{"$ref":"#/components/schemas/Money"},"totalExpected":{"$ref":"#/components/schemas/Money"},"totalLated":{"$ref":"#/components/schemas/Money"},"totalLost":{"$ref":"#/components/schemas/Money"},"paidExternally":{"type":"boolean","nullable":true},"consideredLoss":{"type":"boolean","nullable":true},"finished":{"type":"boolean","nullable":true},"justificationLost":{"type":"string","nullable":true,"description":"Justificativa de perda","quando `consideredLoss`.":null},"saleIds":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Cobranças do ciclo (use em `GET /sales/{saleId}`)."},"createdAt":{"type":"string","format":"date-time","nullable":true}}},"ChargebackStatus":{"type":"string","description":"Status do chargeback.\n- `PENDING`: aguardando ação (contestar ou aceitar) até `expiresAt`\n- `CONTESTED_BY_CLIENT`, `WAITING_RESOLUTION`: contestado, aguardando decisão\n- `WON`: contestação ganha\n- `LOST`: contestação perdida\n- `ACCEPTED`, `ACCEPTED_BY_CLIENT`, `ACCEPTED_AUTOMATICALLY`: aceito (o valor é devolvido ao pagador)\n- `REVERTED`: revertido\n","enum":["PENDING","ACCEPTED_BY_CLIENT","ACCEPTED_AUTOMATICALLY","CONTESTED_BY_CLIENT","WAITING_RESOLUTION","LOST","WON","ACCEPTED","REVERTED"]},"ChargebackReason":{"type":"string","description":"Motivo do chargeback informado pelo gateway (filtro `reason`; na resposta, o texto vem em `details`).","enum":["ABSENCE_OF_PRINT","ABSENT_CARD_FRAUD","CARD_ACTIVATED_PHONE_TRANSACTION","CARD_FRAUD","CARD_RECOVERY_BULLETIN","COMMERCIAL_DISAGREEMENT","COPY_NOT_RECEIVED","CREDIT_OR_DEBIT_PRESENTATION_ERROR","DIFFERENT_PAY_METHOD","FRAUD","INCORRECT_TRANSACTION_VALUE","INVALID_CURRENCY","INVALID_DATA","LATE_PRESENTATION","LOCAL_REGULATORY_OR_LEGAL_DISPUTE","MULTIPLE_ROCS","ORIGINAL_CREDIT_TRANSACTION_NOT_ACCEPTED","OTHER_ABSENT_CARD_FRAUD","PROCESS_ERROR","RECEIVED_COPY_ILLEGIBLE_OR_INCOMPLETE","RECURRENCE_CANCELED","REQUIRED_AUTHORIZATION_NOT_GRANTED","RIGHT_OF_FULL_RECOURSE_FOR_FRAUD","SALE_CANCELED","SERVICE_DISAGREEMENT_OR_DEFECTIVE_PRODUCT","SERVICE_NOT_RECEIVED","SPLIT_SALE","TRANSFERS_OF_DIVERSE_RESPONSIBILITIES","UNQUALIFIED_CAR_RENTAL_DEBIT","USA_CARDHOLDER_DISPUTE","VISA_FRAUD_MONITORING_PROGRAM","WARNING_BULLETIN_FILE"]},"Chargeback":{"type":"object","description":"Chargeback de uma cobrança.","properties":{"id":{"type":"integer","format":"int64"},"chargebackHubId":{"type":"string","nullable":true,"description":"ID do chargeback no gateway."},"status":{"$ref":"#/components/schemas/ChargebackStatus"},"details":{"type":"string","nullable":true,"description":"Motivo informado pelo gateway (ex.: Desacordo comercial)."},"justification":{"type":"string","nullable":true,"description":"Justificativa enviada na contestação ou no aceite."},"expiresAt":{"type":"string","format":"date","nullable":true,"description":"Prazo para contestar."},"createdAt":{"type":"string","format":"date-time","nullable":true},"saleId":{"type":"integer","format":"int64","nullable":true,"description":"Cobrança contestada (use em `GET /sales/{saleId}`)."},"saleStage":{"type":"string","nullable":true,"description":"Estágio da cobrança contestada (valores de `SaleStage`)."},"salePrice":{"$ref":"#/components/schemas/Money"},"customerId":{"type":"integer","format":"int64","nullable":true,"description":"ID do usuário do cliente (o mesmo de `customerId` nas outras rotas)."},"customerName":{"type":"string","nullable":true}}},"Meta":{"type":"object","properties":{"requestId":{"type":"string"},"filters":{"type":"object","additionalProperties":true,"description":"Eco dos filtros aplicados."},"restrictedTypes":{"type":"array","items":{"$ref":"#/components/schemas/SaleType"},"description":"Tipos de cobrança omitidos por falta de privilégio."}}},"PageEnvelope":{"type":"object","required":["data","page","meta"],"properties":{"data":{"type":"array","items":{}},"page":{"type":"object","properties":{"number":{"type":"integer","description":"Página atual (base 1)."},"size":{"type":"integer"},"totalElements":{"type":"integer","format":"int64"},"totalPages":{"type":"integer"},"hasNext":{"type":"boolean","description":"Se `false`, não há mais páginas: não chame de novo."}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"Error":{"type":"object","description":"Formato de erro. `code` é estável; `msg` diz o que corrigir.","required":["code","msg","retryable","requestId"],"properties":{"code":{"type":"string","enum":["INVALID_PARAMETER","MISSING_DATE_RANGE","DATE_RANGE_TOO_LARGE","PAGE_TOO_DEEP","UNAUTHORIZED","OPEN_API_USER_REQUIRED","PAY_NOT_ENABLED","ACCOUNT_DISABLED","PAY_API_ACCESS_DENIED","FORBIDDEN","NOT_FOUND","INTERNAL_ERROR"]},"msg":{"type":"string","description":"O que aconteceu e o que fazer."},"details":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"issue":{"type":"string"}}}},"requiredPrivilege":{"type":"string","nullable":true,"description":"Em 403, o privilégio que falta."},"retryable":{"type":"boolean","description":"`true` = pode repetir igual, com backoff; `false` = mude a requisição."},"requestId":{"type":"string"}}}},"responses":{"BadRequest":{"description":"Parâmetro inválido. Corrija antes de tentar de novo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missingRange":{"value":{"code":"MISSING_DATE_RANGE","msg":"Informe um intervalo de datas: dueDateFrom/dueDateTo, paidAtFrom/paidAtTo, createdAtFrom/createdAtTo.","details":[],"requiredPrivilege":null,"retryable":false,"requestId":"req_1"}},"rangeTooLarge":{"value":{"code":"DATE_RANGE_TOO_LARGE","msg":"O intervalo máximo é de 12 meses. Divida a consulta em períodos menores.","details":[{"field":"dueDateTo","issue":"máximo 12 meses após dueDateFrom"}],"requiredPrivilege":null,"retryable":false,"requestId":"req_2"}},"pageTooDeep":{"value":{"code":"PAGE_TOO_DEEP","msg":"A paginação vai até a página 100. Use filtros (datas, stage, status, customerId) para reduzir o resultado.","details":[{"field":"page","issue":"máximo 100"}],"requiredPrivilege":null,"retryable":false,"requestId":"req_3"}},"invalidEnum":{"value":{"code":"INVALID_PARAMETER","msg":"Parâmetro(s) inválido(s): stage (valor 'OPEN' não aceito. Valores aceitos: PENDING, WAITING_PAYMENT, ...).","details":[{"field":"stage","issue":"valor 'OPEN' não aceito. Valores aceitos: PENDING, WAITING_PAYMENT, ..."}],"requiredPrivilege":null,"retryable":false,"requestId":"req_4"}},"unknownParameter":{"value":{"code":"INVALID_PARAMETER","msg":"Parâmetro(s) não reconhecido(s): startDate. Parâmetros aceitos: createdAtFrom, ...","details":[{"field":"startDate","issue":"parâmetro não reconhecido"}],"requiredPrivilege":null,"retryable":false,"requestId":"req_5"}}}}}},"Unauthorized":{"description":"Credencial ausente, inválida, de usuário bloqueado ou que não é de Usuário de API. Credencial\nausente ou inválida responde **sem corpo**, só com o header `WWW-Authenticate` (mesmo\ncomportamento das demais rotas `/openApi/seller/**`). Login por e-mail/senha responde com o corpo\nabaixo (`OPEN_API_USER_REQUIRED`). Em qualquer caso, não repita: corrija a credencial.\n","headers":{"WWW-Authenticate":{"schema":{"type":"string"},"description":"Basic realm=\"...\""}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"emailLogin":{"value":{"code":"OPEN_API_USER_REQUIRED","msg":"Chamadas à Open API devem usar as credenciais de Usuário de API. Contate o suporte para mais informações."}}}}}},"Forbidden":{"description":"Conta sem Solarz Pay, conta desativada, usuário sem acesso à API ou sem o privilégio do recurso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"noApiAccess":{"value":{"code":"PAY_API_ACCESS_DENIED","msg":"O usuário não tem acesso à API do Solarz Pay. Peça ao dono da conta o privilégio PAY_API_ACCESS.","details":[],"requiredPrivilege":"PAY_API_ACCESS","retryable":false,"requestId":"req_7"}},"noPrivilege":{"value":{"code":"FORBIDDEN","msg":"O usuário não tem permissão para este recurso. Peça ao dono da conta o privilégio SUBSCRIPTION_CLIENT_LIST.","details":[],"requiredPrivilege":"SUBSCRIPTION_CLIENT_LIST","retryable":false,"requestId":"req_8"}},"accountDisabled":{"value":{"code":"ACCOUNT_DISABLED","msg":"A conta do integrador está desativada. Não repita a chamada: fale com o dono da conta.","details":[],"requiredPrivilege":null,"retryable":false,"requestId":"req_9"}}}}}},"NotFound":{"description":"Recurso inexistente, de outra conta ou fora dos tipos que o usuário pode ver (mesma resposta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"NOT_FOUND","msg":"Cobrança não encontrada. Verifique o saleId retornado pela listagem de vendas.","details":[],"requiredPrivilege":null,"retryable":false,"requestId":"req_10"}}}},"InternalError":{"description":"Erro inesperado. Pode repetir com backoff; se persistir, informe o requestId ao suporte.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}