openapi: 3.1.0
info:
  title: Allya Payments API
  version: v1
  description: >-
    API pública da Allya Payments. Use `Authorization: Bearer sk_test_...` em sandbox ou `sk_live_...` em produção.
    Schemas e rotas são gerados a partir dos schemas Zod do código — qualquer divergência quebra o typecheck.
  contact:
    name: Allya Payments
    url: https://payments.allyasolutions.com
servers:
  - url: https://payments-api.allyasolutions.com
    description: Produção e sandbox (ambiente é resolvido pelo prefixo da API key).
security:
  - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Allya API Key
      description: 'Use a API key do projeto/ambiente como bearer token: `Authorization: Bearer sk_test_...` ou `sk_live_...`.'
  schemas:
    ValidationIssue:
      type: object
      properties:
        path:
          type: array
          items:
            anyOf:
              - type: string
              - type: number
          description: Caminho do campo inválido no payload (formato Zod).
        message:
          type: string
          description: Descrição do problema encontrado.
      required:
        - path
        - message
      description: Detalhe individual de uma validação de payload.
    ErrorInvalidInput:
      type: object
      properties:
        error:
          type: string
          enum:
            - invalid_input
        issues:
          type: array
          items:
            $ref: '#/components/schemas/ValidationIssue'
      required:
        - error
        - issues
      description: Payload rejeitado pelo Zod ou regra de domínio. `issues[]` lista cada campo problemático.
    ErrorInvalidJson:
      type: object
      properties:
        error:
          type: string
          enum:
            - invalid_json
      required:
        - error
      description: Body recebido não é JSON válido.
    ErrorUnauthorized:
      type: object
      properties:
        error:
          type: string
          enum:
            - unauthorized
        message:
          type: string
      required:
        - error
      description: Header `Authorization` ausente, malformado ou contém API key revogada.
    ErrorNotFound:
      type: object
      properties:
        error:
          type: string
          enum:
            - not_found
      required:
        - error
      description: Recurso não existe no ambiente da API key.
    ErrorRateLimit:
      type: object
      properties:
        error:
          type: string
          enum:
            - rate_limit_exceeded
      required:
        - error
      description: Limite por API key excedido. Consulte o header `Retry-After` na resposta.
    ErrorGateway:
      type: object
      properties:
        error:
          type: string
          enum:
            - gateway_error
        provider:
          type: string
          enum:
            - abacate_pay
            - asaas
            - pagarme
          description: Gateway envolvido no erro.
      required:
        - error
        - provider
      description: O gateway retornou erro 4xx/5xx ou timeout. Retentar com backoff é seguro (idempotência por externalId).
    ErrorNoRoutingRule:
      type: object
      properties:
        error:
          type: string
          enum:
            - no_routing_rule
        message:
          type: string
      required:
        - error
        - message
      description: Nenhum gateway configurado em **Roteamento** para esse método no ambiente da API key.
    ErrorProviderNotConfigured:
      type: object
      properties:
        error:
          type: string
          enum:
            - provider_not_configured
        provider:
          type: string
          enum:
            - abacate_pay
            - asaas
            - pagarme
          description: Gateway envolvido no erro.
      required:
        - error
        - provider
      description: A regra de roteamento aponta para um gateway sem credenciais cadastradas neste ambiente.
    ErrorProviderDisabled:
      type: object
      properties:
        error:
          type: string
          enum:
            - provider_disabled
        provider:
          type: string
          enum:
            - abacate_pay
            - asaas
            - pagarme
          description: Gateway envolvido no erro.
      required:
        - error
        - provider
      description: O gateway alvo está desativado no painel (**Gateways → editar**).
    ErrorMethodNotSupported:
      type: object
      properties:
        error:
          type: string
          enum:
            - method_not_supported
        provider:
          type: string
          enum:
            - abacate_pay
            - asaas
            - pagarme
          description: Gateway envolvido no erro.
        method:
          type: string
          enum:
            - pix
            - card
      required:
        - error
        - provider
        - method
      description: O gateway resolvido pelo roteamento não suporta esse método de pagamento.
    ErrorBillingInactive:
      type: object
      properties:
        error:
          type: string
          description: Motivo do bloqueio retornado pelo módulo de billing.
        message:
          type: string
      required:
        - error
        - message
      description: Assinatura da plataforma inativa ou em past_due. Regularize o billing da organização.
    ErrorBillingMonthlyTxLimit:
      type: object
      properties:
        error:
          type: string
          enum:
            - billing_monthly_tx_limit_reached
        message:
          type: string
        limit:
          type: integer
        used:
          type: integer
      required:
        - error
        - message
        - limit
        - used
      description: Cota mensal de transações do plano atingida.
    ErrorMissingGatewayRef:
      type: object
      properties:
        error:
          type: string
          enum:
            - missing_gateway_ref
      required:
        - error
      description: Recurso não tem referência ao gateway, então não há o que consultar/cancelar/sincronizar.
    ErrorNotImplemented:
      type: object
      properties:
        error:
          type: string
          enum:
            - not_implemented
        action:
          type: string
        provider:
          type: string
          enum:
            - abacate_pay
            - asaas
            - pagarme
          description: Gateway envolvido no erro.
      required:
        - error
        - action
        - provider
      description: O adapter do gateway ainda não implementa essa ação (cancel/sync/etc.).
    ErrorActionNotImplemented:
      type: object
      properties:
        error:
          type: string
          enum:
            - action_not_implemented
        action:
          type: string
        provider:
          type: string
          enum:
            - abacate_pay
            - asaas
            - pagarme
          description: Gateway envolvido no erro.
      required:
        - error
        - action
        - provider
      description: Variante de `not_implemented` em assinaturas — ação opcional não suportada pelo gateway.
    ErrorAlreadyCanceled:
      type: object
      properties:
        error:
          type: string
          enum:
            - already_canceled
        status:
          type: string
      required:
        - error
        - status
      description: O recurso já estava cancelado quando o cancel foi chamado.
    ErrorCannotCancelPaid:
      type: object
      properties:
        error:
          type: string
          enum:
            - cannot_cancel_paid
      required:
        - error
      description: Pagamento já está pago. Cancel não é refund — use o painel do gateway para estornar.
    ErrorCannotCancelPix:
      type: object
      properties:
        error:
          type: string
          enum:
            - cannot_cancel_pix
      required:
        - error
      description: Pix expira automaticamente; não há cancel manual.
    ErrorCannotCancelStatus:
      type: object
      properties:
        error:
          type: string
          enum:
            - cannot_cancel_status
        status:
          type: string
      required:
        - error
        - status
      description: 'O status atual do pagamento não permite cancel (ex.: `expired`, `failed`).'
    ErrorMissingQuery:
      type: object
      properties:
        error:
          type: string
          enum:
            - missing_query
        message:
          type: string
      required:
        - error
        - message
      description: Query string obrigatória ausente.
    ErrorInvalidId:
      type: object
      properties:
        error:
          type: string
          enum:
            - invalid_id
      required:
        - error
      description: Parâmetro `:id` da URL está vazio ou malformado.
    ErrorInternal:
      type: object
      properties:
        error:
          type: string
          enum:
            - internal_error
      required:
        - error
      description: Falha inesperada no servidor. Logs detalhados ficam internos; entre em contato se persistir.
    Payment:
      type: object
      properties:
        id:
          type: string
          description: ID público com prefixo `pay_`.
        status:
          type: string
          enum:
            - created
            - pending
            - processing
            - paid
            - failed
            - canceled
            - expired
          description: Status normalizado. Veja a referência de status para o ciclo completo.
        method:
          type: string
          enum:
            - pix
            - card
        gateway:
          type: string
          enum:
            - abacate_pay
            - asaas
            - pagarme
          description: Gateway que atendeu a chamada, definido pelo roteamento do ambiente.
        amount:
          type: integer
          description: Valor em centavos.
        currency:
          type: string
          description: Moeda. Hoje só `BRL`.
        externalId:
          type:
            - string
            - 'null'
          description: Identificador idempotente do cliente; obrigatório no momento da criação.
        gatewayRef:
          type:
            - string
            - 'null'
          description: ID do recurso no gateway (`pay_*` na Allya, `cha_*` no Abacate, etc.).
        customer:
          type:
            - object
            - 'null'
          properties:
            name:
              type:
                - string
                - 'null'
              description: Nome do cliente enviado na criação.
            email:
              type:
                - string
                - 'null'
              description: E-mail do cliente enviado na criação.
            documentLast4:
              type:
                - string
                - 'null'
              description: Últimos 4 dígitos do CPF/CNPJ. O documento completo nunca é retornado nem persistido em plaintext.
          required:
            - name
            - email
            - documentLast4
        checkoutUrl:
          type:
            - string
            - 'null'
          description: URL hospedada pelo gateway quando `method=card`; `null` para Pix.
        pix:
          type:
            - object
            - 'null'
          properties:
            qrCode:
              type: string
              description: Imagem (data URL/base64) ou URL do QR Code, quando o gateway retorna.
            qrCodeText:
              type: string
              description: Código Pix copia e cola (começa com `00020101...`), quando o gateway retorna.
        card:
          type:
            - object
            - 'null'
          properties:
            brand:
              type: string
              description: Bandeira do cartão (`visa`, `mastercard`, etc.).
            last4:
              type: string
              description: Últimos 4 dígitos do cartão.
      required:
        - id
        - status
        - method
        - gateway
        - amount
        - currency
        - externalId
        - gatewayRef
        - customer
        - checkoutUrl
        - pix
        - card
      description: Representação normalizada de um pagamento avulso. Mesma estrutura para POST, GET, sync e cancel.
    Subscription:
      type: object
      properties:
        id:
          type: string
          description: ID público com prefixo `sub_`.
        status:
          type: string
          enum:
            - trialing
            - active
            - past_due
            - canceled
          description: Estado normalizado. Veja referência de status de assinatura para o ciclo completo.
        method:
          type: string
          enum:
            - pix
            - card
        gateway:
          type: string
          enum:
            - abacate_pay
            - asaas
            - pagarme
        amount:
          type: integer
          description: Valor recorrente em centavos.
        currency:
          type: string
        interval:
          type: string
          enum:
            - monthly
            - yearly
        trialDays:
          type: integer
          description: Dias de trial configurados na criação.
        trialEndsAt:
          type:
            - string
            - 'null'
          description: ISO timestamp do fim do trial; `null` quando não há trial.
        nextBillingAt:
          type:
            - string
            - 'null'
          description: ISO timestamp da próxima cobrança recorrente prevista.
        cancelAtPeriodEnd:
          type: boolean
          description: Quando `true`, cancel já foi solicitado e tem efeito ao fim do ciclo corrente.
        canceledAt:
          type:
            - string
            - 'null'
          description: ISO timestamp do momento em que o cancel foi efetivado.
        externalId:
          type:
            - string
            - 'null'
        gatewayRef:
          type:
            - string
            - 'null'
          description: ID do recurso no gateway. No Pagar.me, vira `sub_*` após o cliente concluir o checkout (antes é `pl_*`).
        checkoutUrl:
          type:
            - string
            - 'null'
          description: URL hospedada para o cliente cadastrar o cartão.
        customer:
          type:
            - object
            - 'null'
          properties:
            name:
              type:
                - string
                - 'null'
            email:
              type:
                - string
                - 'null'
            documentLast4:
              type:
                - string
                - 'null'
          required:
            - name
            - email
            - documentLast4
        createdAt:
          type: string
          description: ISO timestamp de criação na Allya.
      required:
        - id
        - status
        - method
        - gateway
        - amount
        - currency
        - interval
        - trialDays
        - trialEndsAt
        - nextBillingAt
        - cancelAtPeriodEnd
        - canceledAt
        - externalId
        - gatewayRef
        - checkoutUrl
        - customer
        - createdAt
      description: Representação normalizada de uma assinatura recorrente. Mesma estrutura para POST, GET e cancel.
    AuthTest:
      type: object
      properties:
        ok:
          type: boolean
          enum:
            - true
        organization:
          type: object
          properties:
            id:
              type: string
              description: ID com prefixo `org_`.
          required:
            - id
        project:
          type: object
          properties:
            id:
              type: string
              description: ID com prefixo `prj_`.
          required:
            - id
        environment:
          type: object
          properties:
            id:
              type: string
              description: ID com prefixo `env_`.
            kind:
              type: string
              enum:
                - sandbox
                - production
              description: Ambiente resolvido a partir da API key (`sk_test_` ou `sk_live_`).
          required:
            - id
            - kind
        apiKey:
          type: object
          properties:
            id:
              type: string
              description: ID com prefixo `key_`.
          required:
            - id
      required:
        - ok
        - organization
        - project
        - environment
        - apiKey
      description: Confirma que a API key é válida e expõe os IDs da hierarquia organização → projeto → ambiente.
    Health:
      type: object
      properties:
        ok:
          type: boolean
          enum:
            - true
        service:
          type: string
          enum:
            - allya-payments
      required:
        - ok
        - service
      description: Liveness check público (sem autenticação).
  parameters: {}
paths:
  /v1/health:
    get:
      summary: Liveness check
      description: Endpoint público sem autenticação. Útil para uptime monitors. Não consulta banco nem gateway.
      tags:
        - Health
      security: []
      responses:
        '200':
          description: Serviço respondendo.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Health'
  /v1/auth/test:
    get:
      summary: Validar API key
      description: >-
        Devolve a hierarquia organização → projeto → ambiente atrelada à API key recebida. Bom para confirmar `sk_live_`
        antes de liberar tráfego real.
      tags:
        - Auth
      responses:
        '200':
          description: API key válida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthTest'
        '401':
          description: API key ausente, malformada ou revogada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorUnauthorized'
  /v1/payments:
    post:
      summary: Criar pagamento
      description: >-
        Cria uma cobrança Pix ou cartão. **Idempotente por `externalId`** dentro do ambiente: retentar com o mesmo valor
        devolve a cobrança já existente sem criar nova no gateway. Cartão usa checkout hospedado — a Allya nunca recebe
        número/CVV.
      tags:
        - Payments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: integer
                  exclusiveMinimum: 0
                  description: Valor em centavos. `1990` representa R$ 19,90.
                  example: 4990
                currency:
                  type: string
                  enum:
                    - BRL
                  default: BRL
                method:
                  type: string
                  description: Método de pagamento. Aceita também `PIX`/`CARD` em uppercase.
                  enum:
                    - pix
                    - card
                  example: pix
                customer:
                  type: object
                  properties:
                    name:
                      type: string
                      minLength: 1
                      maxLength: 255
                      description: Nome completo do cliente.
                      example: Cliente Teste
                    email:
                      type: string
                      format: email
                      description: E-mail do cliente.
                      example: cliente@example.com
                    document:
                      type: string
                      minLength: 8
                      maxLength: 32
                      description: >-
                        CPF (11 dígitos) ou CNPJ (14 dígitos). Só dígitos ou formato livre — a Allya remove pontuação
                        antes de enviar ao gateway.
                      example: '00000000000'
                    phone:
                      type: string
                      maxLength: 32
                      description: >-
                        Telefone com DDD + número (mín. 10 dígitos). **Obrigatório quando method=card e o gateway
                        resolvido é Pagar.me** — sem isso, o Pagar.me rejeita o paymentlink com 422.
                      example: '11999999999'
                  required:
                    - name
                    - email
                    - document
                externalId:
                  type: string
                  minLength: 1
                  maxLength: 255
                  description: >-
                    Identificador único do pedido no seu sistema. Funciona como chave de idempotência: reenviar com o
                    mesmo valor retorna o pagamento já criado.
                  example: pedido_42
                metadata:
                  type: object
                  additionalProperties: {}
                  description: >-
                    Dados livres para correlação interna (até 4 KiB serializados, profundidade máx. 4). Aceita apenas
                    JSON. Evite enviar PII ou segredos.
                  example:
                    orderId: pedido_42
                    source: checkout
                card:
                  type: object
                  properties:
                    installments:
                      type: integer
                      minimum: 1
                      maximum: 24
                      default: 1
                      description: >-
                        Número de parcelas para checkout hospedado de cartão. Limite real depende do gateway resolvido
                        (Abacate Pay: 1–12; Asaas/Pagar.me: 1–24). Ignorado em assinatura.
                      example: 1
              required:
                - amount
                - method
                - customer
                - externalId
            example:
              amount: 4990
              currency: BRL
              method: pix
              externalId: pedido_42
              customer:
                name: Cliente Teste
                email: cliente@example.com
                document: '00000000000'
                phone: '11999999999'
              metadata:
                orderId: pedido_42
                source: checkout
      responses:
        '201':
          description: Pagamento criado (ou já existente quando `externalId` é repetido).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '400':
          description: Body inválido — `invalid_json` ou `invalid_input`.
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/ErrorInvalidJson'
                  - $ref: '#/components/schemas/ErrorInvalidInput'
        '401':
          description: API key inválida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorUnauthorized'
        '402':
          description: Billing da plataforma bloqueia a chamada.
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/ErrorBillingInactive'
                  - $ref: '#/components/schemas/ErrorBillingMonthlyTxLimit'
        '409':
          description: >-
            Sem regra de roteamento, gateway desativado, sem credenciais, ou método não suportado pelo gateway
            resolvido.
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/ErrorNoRoutingRule'
                  - $ref: '#/components/schemas/ErrorProviderNotConfigured'
                  - $ref: '#/components/schemas/ErrorProviderDisabled'
                  - $ref: '#/components/schemas/ErrorMethodNotSupported'
        '429':
          description: Limite por API key excedido — consulte `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRateLimit'
        '500':
          description: Erro inesperado da Allya.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternal'
        '502':
          description: Gateway retornou erro ou timeout. Seguro retentar (idempotência por `externalId`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorGateway'
    get:
      summary: Buscar pagamento por externalId
      description: >-
        Consulta idempotente: retorna o pagamento cadastrado com o `externalId` informado, sem chamar o gateway. Use
        para conferir antes de fazer um `POST` retry.
      tags:
        - Payments
      parameters:
        - schema:
            type: string
            minLength: 1
            description: Identificador idempotente enviado na criação.
          required: true
          description: Identificador idempotente enviado na criação.
          name: externalId
          in: query
      responses:
        '200':
          description: Pagamento encontrado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '400':
          description: Query `externalId` ausente.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMissingQuery'
        '401':
          description: API key inválida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorUnauthorized'
        '404':
          description: Nenhum pagamento com esse `externalId` no ambiente.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorNotFound'
  /v1/payments/{id}:
    get:
      summary: Consultar pagamento
      description: >-
        Lê o pagamento direto do banco da Allya — **não consulta o gateway**. Para forçar reconciliação com o gateway,
        use `POST /v1/payments/{id}/sync`.
      tags:
        - Payments
      parameters:
        - schema:
            type: string
            description: ID público com prefixo `pay_`.
          required: true
          description: ID público com prefixo `pay_`.
          name: id
          in: path
      responses:
        '200':
          description: Pagamento encontrado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '400':
          description: Parâmetro `id` vazio.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInvalidId'
        '401':
          description: API key inválida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorUnauthorized'
        '404':
          description: ID não existe no ambiente.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorNotFound'
  /v1/payments/{id}/cancel:
    post:
      summary: Cancelar pagamento
      description: >-
        Cancela uma cobrança de cartão ainda não paga. **Não é refund**: pagamentos pagos retornam `409
        cannot_cancel_paid`. Pix expira sozinho — `cannot_cancel_pix` é retornado para tentativas em Pix.
      tags:
        - Payments
      parameters:
        - schema:
            type: string
            description: ID público com prefixo `pay_`.
          required: true
          description: ID público com prefixo `pay_`.
          name: id
          in: path
      responses:
        '200':
          description: 'Cancelamento confirmado. Resposta é o pagamento com `status: canceled`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '400':
          description: '`id` vazio ou método `cannot_cancel_pix`.'
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/ErrorInvalidId'
                  - $ref: '#/components/schemas/ErrorCannotCancelPix'
        '401':
          description: API key inválida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorUnauthorized'
        '404':
          description: Pagamento não existe.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorNotFound'
        '409':
          description: Conflito de estado — já pago, já cancelado, status incompatível, ou faltam dados para cancelar.
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/ErrorCannotCancelPaid'
                  - $ref: '#/components/schemas/ErrorAlreadyCanceled'
                  - $ref: '#/components/schemas/ErrorCannotCancelStatus'
                  - $ref: '#/components/schemas/ErrorMissingGatewayRef'
                  - $ref: '#/components/schemas/ErrorProviderNotConfigured'
        '429':
          description: Limite por API key excedido — consulte `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRateLimit'
        '500':
          description: Erro inesperado da Allya.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternal'
        '501':
          description: Adapter do gateway não implementa cancel.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorNotImplemented'
        '502':
          description: Gateway retornou erro ou timeout.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorGateway'
  /v1/payments/{id}/sync:
    post:
      summary: Reconciliar pagamento com o gateway
      description: >-
        Consulta o gateway na hora, atualiza o status local e dispara webhook outbound se houve mudança. Use quando
        suspeitar que um webhook foi perdido ou para recuperar o QR Pix do Asaas após a 2ª chamada falhar.
      tags:
        - Payments
      parameters:
        - schema:
            type: string
            description: ID público com prefixo `pay_`.
          required: true
          description: ID público com prefixo `pay_`.
          name: id
          in: path
      responses:
        '200':
          description: Pagamento sincronizado — resposta no mesmo formato de `GET /v1/payments/{id}`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '400':
          description: '`id` vazio.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInvalidId'
        '401':
          description: API key inválida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorUnauthorized'
        '404':
          description: Pagamento não existe no ambiente.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorNotFound'
        '409':
          description: Pagamento sem `gatewayRef` ou gateway sem credenciais.
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/ErrorMissingGatewayRef'
                  - $ref: '#/components/schemas/ErrorProviderNotConfigured'
        '429':
          description: Limite por API key excedido — consulte `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRateLimit'
        '500':
          description: Erro inesperado da Allya.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternal'
        '501':
          description: Adapter do gateway ainda não implementa sync.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorNotImplemented'
        '502':
          description: Gateway retornou erro ou timeout.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorGateway'
  /v1/subscriptions:
    post:
      summary: Criar assinatura recorrente
      description: >-
        Cria uma assinatura cobrada via cartão. **Idempotente por `externalId`** dentro do ambiente. No Pagar.me, o
        campo `gateway.pagarme.planId` é **obrigatório** (Plan deve existir antes na API do Pagar.me).
      tags:
        - Subscriptions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: integer
                  exclusiveMinimum: 0
                  description: Valor recorrente em centavos.
                  example: 4990
                currency:
                  type: string
                  enum:
                    - BRL
                  default: BRL
                interval:
                  type: string
                  description: Periodicidade da cobrança. Aceita também `MONTHLY`/`YEARLY`.
                  enum:
                    - monthly
                    - yearly
                  example: monthly
                trialDays:
                  type:
                    - integer
                    - 'null'
                  minimum: 0
                  maximum: 365
                  default: 0
                  description: >-
                    Dias de trial antes da primeira cobrança real (0–365). No Pagar.me, o trial real é definido no Plan;
                    este campo só mantém o status `trialing` local consistente.
                  example: 7
                customer:
                  type: object
                  properties:
                    name:
                      type: string
                      minLength: 1
                      maxLength: 255
                      description: Nome completo do cliente.
                      example: Cliente Teste
                    email:
                      type: string
                      format: email
                      description: E-mail do cliente.
                      example: cliente@example.com
                    document:
                      type: string
                      minLength: 8
                      maxLength: 32
                      description: >-
                        CPF (11 dígitos) ou CNPJ (14 dígitos). Só dígitos ou formato livre — a Allya remove pontuação
                        antes de enviar ao gateway.
                      example: '00000000000'
                    phone:
                      type: string
                      maxLength: 32
                      description: >-
                        Telefone com DDD + número (mín. 10 dígitos). **Obrigatório quando o roteamento de SUBSCRIPTION
                        resolver para Pagar.me** — sem isso, o Pagar.me rejeita o paymentlink com 422.
                      example: '11999999999'
                  required:
                    - name
                    - email
                    - document
                externalId:
                  type: string
                  minLength: 1
                  maxLength: 255
                  description: Identificador único da assinatura no seu sistema. Idempotente por ambiente.
                  example: assinatura_cliente_42_plano_pro_mensal
                metadata:
                  type: object
                  additionalProperties: {}
                  description: Dados livres para correlação interna. Evite enviar PII ou segredos.
                  example:
                    orderId: assinatura_cliente_42
                    plan: pro_mensal
                card:
                  type: object
                  properties:
                    installments:
                      type: integer
                      minimum: 1
                      maximum: 24
                      description: Ignorado em assinatura — recorrência não parcela.
                      example: 1
                gateway:
                  type: object
                  properties:
                    pagarme:
                      type: object
                      properties:
                        planId:
                          type: string
                          minLength: 1
                          description: >-
                            ID do Plan pré-criado na API do Pagar.me (`POST /core/v5/plans`). Obrigatório quando o
                            roteamento resolve para Pagar.me; ignorado nos demais gateways.
                          example: plan_XnB8eYvR7K1aZ4Qm
                      required:
                        - planId
              required:
                - amount
                - interval
                - customer
                - externalId
            example:
              amount: 4990
              currency: BRL
              interval: monthly
              trialDays: 7
              externalId: assinatura_cliente_42_plano_pro_mensal
              customer:
                name: Cliente Teste
                email: cliente@example.com
                document: '00000000000'
                phone: '11999999999'
              metadata:
                orderId: assinatura_cliente_42
                plan: pro_mensal
              gateway:
                pagarme:
                  planId: plan_XnB8eYvR7K1aZ4Qm
      responses:
        '201':
          description: Assinatura criada (ou já existente quando `externalId` é repetido).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '400':
          description: Body inválido.
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/ErrorInvalidJson'
                  - $ref: '#/components/schemas/ErrorInvalidInput'
        '401':
          description: API key inválida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorUnauthorized'
        '402':
          description: Billing da plataforma bloqueia a chamada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBillingInactive'
        '409':
          description: Sem roteamento, gateway sem credenciais, método não suportado ou ação ausente no adapter.
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/ErrorNoRoutingRule'
                  - $ref: '#/components/schemas/ErrorProviderNotConfigured'
                  - $ref: '#/components/schemas/ErrorProviderDisabled'
                  - $ref: '#/components/schemas/ErrorMethodNotSupported'
                  - $ref: '#/components/schemas/ErrorActionNotImplemented'
        '429':
          description: Limite por API key excedido — consulte `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRateLimit'
        '500':
          description: Erro inesperado da Allya.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternal'
        '502':
          description: Gateway retornou erro ou timeout.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorGateway'
    get:
      summary: Buscar assinatura por externalId
      description: Consulta idempotente por `externalId` — não chama o gateway.
      tags:
        - Subscriptions
      parameters:
        - schema:
            type: string
            minLength: 1
          required: true
          name: externalId
          in: query
      responses:
        '200':
          description: Assinatura encontrada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '400':
          description: Query `externalId` ausente.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMissingQuery'
        '401':
          description: API key inválida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorUnauthorized'
        '404':
          description: Nenhuma assinatura com esse `externalId` no ambiente.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorNotFound'
  /v1/subscriptions/{id}:
    get:
      summary: Consultar assinatura
      description: Lê a assinatura direto do banco da Allya. Não há `sync` para assinaturas hoje.
      tags:
        - Subscriptions
      parameters:
        - schema:
            type: string
            description: ID público com prefixo `sub_`.
          required: true
          description: ID público com prefixo `sub_`.
          name: id
          in: path
      responses:
        '200':
          description: Assinatura encontrada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '401':
          description: API key inválida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorUnauthorized'
        '404':
          description: Assinatura não existe.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorNotFound'
        '500':
          description: Erro inesperado da Allya.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternal'
  /v1/subscriptions/{id}/cancel:
    post:
      summary: Cancelar assinatura
      description: >-
        Cancela imediatamente (`atPeriodEnd=false`, default) ou ao fim do ciclo corrente (`atPeriodEnd=true`).
        Restrições por gateway: Abacate Pay e Pagar.me não suportam `atPeriodEnd=true`.
      tags:
        - Subscriptions
      parameters:
        - schema:
            type: string
            description: ID público com prefixo `sub_`.
          required: true
          description: ID público com prefixo `sub_`.
          name: id
          in: path
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                atPeriodEnd:
                  type:
                    - boolean
                    - 'null'
                  default: false
                  description: >-
                    Quando `true`, cancela ao fim do ciclo corrente (não suportado em Abacate Pay e Pagar.me). Default
                    `false` = cancela imediato.
                  example: false
      responses:
        '200':
          description: Cancelamento confirmado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '400':
          description: Body inválido.
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/ErrorInvalidJson'
                  - $ref: '#/components/schemas/ErrorInvalidInput'
        '401':
          description: API key inválida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorUnauthorized'
        '404':
          description: Assinatura não existe.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorNotFound'
        '409':
          description: Já cancelada, sem `gatewayRef`, gateway sem credenciais, ou ação não suportada pelo gateway.
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/ErrorAlreadyCanceled'
                  - $ref: '#/components/schemas/ErrorMissingGatewayRef'
                  - $ref: '#/components/schemas/ErrorProviderNotConfigured'
                  - $ref: '#/components/schemas/ErrorActionNotImplemented'
        '500':
          description: Erro inesperado da Allya.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternal'
        '502':
          description: Gateway retornou erro ou timeout.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorGateway'
webhooks: {}