openapi: 3.0.3
info:
  title: sinnu API
  version: 1.0.0
  description: API pública da sinnu para links, clientes e transações. Autentique com Bearer e a chave da empresa. Links usam amountCents em centavos; a API de transações usa centavos; webhooks e transações de um link usam reais. Consulte a unidade de cada recurso.
  x-source-sha256: 153c3fdb10dbb3d93407364e1d121b9565747a56c1b8db9ace49edcb2ef48d8a
paths:
  /api/payment-links:
    get:
      operationId: paymentLinks_list
      description: Lista os links de pagamento da empresa autenticada no envelope paginado do sinnu `{ data, total, page, pageSize }`.
      parameters:
        - in: query
          name: createdAt__gte
          schema:
            type: string
            format: date
          description: Criados a partir desta data (YYYY-MM-DD, inclusive).
        - in: query
          name: createdAt__lte
          schema:
            type: string
            format: date
          description: Criados até esta data (YYYY-MM-DD, inclusive).
        - in: query
          name: methods
          schema:
            type: string
          description: "Filtra por método aceito (CSV): pix | credit_card | applepay | googlepay."
        - in: query
          name: ordering
          schema:
            type: string
          description: 'Ordenação (default -createdAt): title | status | priceMode | amountCents | createdAt | updatedAt, com "-" para descendente.'
        - in: query
          name: page
          schema:
            type: integer
        - in: query
          name: pageSize
          schema:
            type: integer
        - in: query
          name: priceMode
          schema:
            type: string
          description: "Filtra por modo de preço (CSV): fixed | customer_chooses."
        - in: query
          name: search
          schema:
            type: string
          description: Busca por título, slug ou descrição do link.
        - in: query
          name: status
          schema:
            type: string
          description: "Filtra por status (CSV): active | paused | archived. OMITIDO = catálogo (exclui os arquivados); peça `archived` para vê-los."
      tags:
        - payment-links
      security:
        - bearerAuth: []
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedPaymentLink"
          description: ""
        "403": &a1
          description: Sua chave de API não tem permissão para consultar este recurso.
      summary: Listar links de pagamento
      x-codeSamples:
        - lang: bash
          label: cURL
          source: |-
            curl --fail-with-body --request GET \
              'https://api.sinnu.com.br/api/payment-links' \
              --header "Authorization: Bearer $SINNU_API_KEY"
        - lang: javascript
          label: JavaScript · servidor
          source: |-
            const apiKey = process.env.SINNU_API_KEY;
            if (!apiKey) throw new Error("Configure SINNU_API_KEY no servidor.");
            const response = await fetch("https://api.sinnu.com.br/api/payment-links", {
              method: "GET",
              headers: {
                Authorization: `Bearer ${apiKey}`,
              },
            });
            if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
            console.log(response.status === 204 ? null : await response.json());
    post:
      operationId: paymentLinks_create
      description: Cria um link de pagamento para a empresa autenticada. Use este recurso para gerar cobranças compartilháveis com suporte a Pix e cartão de crédito.
      tags:
        - payment-links
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PaymentLinkWrite"
            example:
              title: Consultoria inicial
              priceMode: fixed
              amountCents: 9900
              methods: &a4
                - pix
                - credit_card
              maxInstallments: 1
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/PaymentLinkWrite"
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/PaymentLinkWrite"
        required: true
      security:
        - bearerAuth: []
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaymentLinkRead"
          description: ""
        "403": &a2
          description: Sua chave de API não tem permissão para criar ou alterar links de pagamento.
      summary: Criar link de pagamento
      x-codeSamples:
        - lang: bash
          label: cURL
          source: |-
            curl --fail-with-body --request POST \
              'https://api.sinnu.com.br/api/payment-links' \
              --header "Authorization: Bearer $SINNU_API_KEY" \
              --header 'Content-Type: application/json' \
              --data '{
              "title": "Consultoria inicial",
              "priceMode": "fixed",
              "amountCents": 9900,
              "methods": [
                "pix",
                "credit_card"
              ],
              "maxInstallments": 1
            }'
        - lang: javascript
          label: JavaScript · servidor
          source: |-
            const apiKey = process.env.SINNU_API_KEY;
            if (!apiKey) throw new Error("Configure SINNU_API_KEY no servidor.");
            const response = await fetch("https://api.sinnu.com.br/api/payment-links", {
              method: "POST",
              headers: {
                Authorization: `Bearer ${apiKey}`,
                "Content-Type": "application/json",
              },
              body: JSON.stringify({
              "title": "Consultoria inicial",
              "priceMode": "fixed",
              "amountCents": 9900,
              "methods": [
                "pix",
                "credit_card"
              ],
              "maxInstallments": 1
            }),
            });
            if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
            console.log(response.status === 204 ? null : await response.json());
  /api/payment-links/{id}:
    get:
      operationId: paymentLinks_retrieve
      description: Retorna os detalhes de um link de pagamento da empresa autenticada.
      parameters:
        - in: path
          name: id
          schema:
            type: string
            format: uuid
          required: true
          example: 00000000-0000-4000-8000-000000000003
      tags:
        - payment-links
      security:
        - bearerAuth: []
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaymentLinkRead"
          description: ""
        "403": *a1
      summary: Consultar link de pagamento
      x-codeSamples:
        - lang: bash
          label: cURL
          source: |-
            curl --fail-with-body --request GET \
              'https://api.sinnu.com.br/api/payment-links/ID_DO_RECURSO' \
              --header "Authorization: Bearer $SINNU_API_KEY"
        - lang: javascript
          label: JavaScript · servidor
          source: |-
            const apiKey = process.env.SINNU_API_KEY;
            if (!apiKey) throw new Error("Configure SINNU_API_KEY no servidor.");
            const response = await fetch("https://api.sinnu.com.br/api/payment-links/ID_DO_RECURSO", {
              method: "GET",
              headers: {
                Authorization: `Bearer ${apiKey}`,
              },
            });
            if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
            console.log(response.status === 204 ? null : await response.json());
    patch:
      operationId: paymentLinks_partialUpdate
      description: Atualiza um link de pagamento da empresa autenticada.
      parameters:
        - in: path
          name: id
          schema:
            type: string
            format: uuid
          required: true
          example: 00000000-0000-4000-8000-000000000003
      tags:
        - payment-links
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PatchedPaymentLinkWrite"
            example:
              title: Consultoria individual
              amountCents: 12900
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/PatchedPaymentLinkWrite"
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/PatchedPaymentLinkWrite"
      security:
        - bearerAuth: []
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaymentLinkRead"
          description: ""
        "403": *a2
      summary: Atualizar link de pagamento
      x-codeSamples:
        - lang: bash
          label: cURL
          source: |-
            curl --fail-with-body --request PATCH \
              'https://api.sinnu.com.br/api/payment-links/ID_DO_RECURSO' \
              --header "Authorization: Bearer $SINNU_API_KEY" \
              --header 'Content-Type: application/json' \
              --data '{
              "title": "Consultoria individual",
              "amountCents": 12900
            }'
        - lang: javascript
          label: JavaScript · servidor
          source: |-
            const apiKey = process.env.SINNU_API_KEY;
            if (!apiKey) throw new Error("Configure SINNU_API_KEY no servidor.");
            const response = await fetch("https://api.sinnu.com.br/api/payment-links/ID_DO_RECURSO", {
              method: "PATCH",
              headers: {
                Authorization: `Bearer ${apiKey}`,
                "Content-Type": "application/json",
              },
              body: JSON.stringify({
              "title": "Consultoria individual",
              "amountCents": 12900
            }),
            });
            if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
            console.log(response.status === 204 ? null : await response.json());
    delete:
      operationId: paymentLinks_destroy
      description: Arquiva um link de pagamento da empresa autenticada.
      summary: Arquivar link de pagamento
      parameters:
        - in: path
          name: id
          schema:
            type: string
            format: uuid
          required: true
          example: 00000000-0000-4000-8000-000000000003
      tags:
        - payment-links
      security:
        - bearerAuth: []
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaymentLinkArchiveResult"
          description: ""
        "403": *a2
      x-codeSamples:
        - lang: bash
          label: cURL
          source: |-
            curl --fail-with-body --request DELETE \
              'https://api.sinnu.com.br/api/payment-links/ID_DO_RECURSO' \
              --header "Authorization: Bearer $SINNU_API_KEY"
        - lang: javascript
          label: JavaScript · servidor
          source: |-
            const apiKey = process.env.SINNU_API_KEY;
            if (!apiKey) throw new Error("Configure SINNU_API_KEY no servidor.");
            const response = await fetch("https://api.sinnu.com.br/api/payment-links/ID_DO_RECURSO", {
              method: "DELETE",
              headers: {
                Authorization: `Bearer ${apiKey}`,
              },
            });
            if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
            console.log(response.status === 204 ? null : await response.json());
  /api/payment-links/{id}/transactions:
    get:
      operationId: paymentLinks_transactions
      description: Lista as transações originadas por um link de pagamento da empresa autenticada.
      parameters:
        - in: path
          name: id
          schema:
            type: string
            format: uuid
          required: true
          example: 00000000-0000-4000-8000-000000000003
        - in: query
          name: page
          schema:
            type: integer
        - in: query
          name: pageSize
          schema:
            type: integer
      tags:
        - payment-links
      security:
        - bearerAuth: []
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedPaymentLinkTransaction"
          description: ""
        "403": *a1
      summary: Listar transações do link
      x-codeSamples:
        - lang: bash
          label: cURL
          source: |-
            curl --fail-with-body --request GET \
              'https://api.sinnu.com.br/api/payment-links/ID_DO_RECURSO/transactions' \
              --header "Authorization: Bearer $SINNU_API_KEY"
        - lang: javascript
          label: JavaScript · servidor
          source: |-
            const apiKey = process.env.SINNU_API_KEY;
            if (!apiKey) throw new Error("Configure SINNU_API_KEY no servidor.");
            const response = await fetch("https://api.sinnu.com.br/api/payment-links/ID_DO_RECURSO/transactions", {
              method: "GET",
              headers: {
                Authorization: `Bearer ${apiKey}`,
              },
            });
            if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
            console.log(response.status === 204 ? null : await response.json());
  /api/transactions/:
    get:
      operationId: transactions_list
      description: Lista transações da empresa autenticada no envelope paginado `{ data, total, page, pageSize }`. Use `status`, `customer` e `search` para filtrar.
      parameters:
        - in: query
          name: campaign
          schema:
            type: string
          description: Filtra por trecho de `utm_campaign` (sem diferenciar maiúsculas). Mesma condição de `origin`.
        - in: query
          name: customer
          schema:
            type: string
            format: uuid
          description: Filtra as transações por ID do cliente (Customer.id, UUID).
        - in: query
          name: origin
          schema:
            type: string
          description: "Filtra pelo canal de origem da venda (`origin.channel`): meta | tiktok | whatsapp | instagram | google | direct | other. Só casa na sessão do painel de uma empresa com os pixels de rastreamento abertos."
        - in: query
          name: page
          schema:
            type: integer
          description: Número da página (1-based, default 1).
        - in: query
          name: pageSize
          schema:
            type: integer
          description: Itens por página (default 20, máx. 100).
        - in: query
          name: salesperson
          schema:
            type: integer
          description: Filtra pelo vendedor responsável (`salesperson.id`).
        - in: query
          name: search
          schema:
            type: string
          description: Busca por nome/e-mail do cliente ou descrição.
        - in: query
          name: status
          schema:
            type: string
          description: "Filtra pelo status do painel: approved | pending | refused | refunded | chargeback."
      tags:
        - transactions
      security:
        - bearerAuth: []
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedSinnuTransactionList"
          description: ""
        "403": &a3
          description: Sua chave de API não tem permissão para consultar transações.
      summary: Listar transações
      x-codeSamples:
        - lang: bash
          label: cURL
          source: |-
            curl --fail-with-body --request GET \
              'https://api.sinnu.com.br/api/transactions/' \
              --header "Authorization: Bearer $SINNU_API_KEY"
        - lang: javascript
          label: JavaScript · servidor
          source: |-
            const apiKey = process.env.SINNU_API_KEY;
            if (!apiKey) throw new Error("Configure SINNU_API_KEY no servidor.");
            const response = await fetch("https://api.sinnu.com.br/api/transactions/", {
              method: "GET",
              headers: {
                Authorization: `Bearer ${apiKey}`,
              },
            });
            if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
            console.log(response.status === 204 ? null : await response.json());
  /api/transactions/{id}/:
    get:
      operationId: transactions_retrieve
      description: Retorna uma transação da empresa autenticada em formato flat.
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          example: 00000000-0000-4000-8000-000000000001
      tags:
        - transactions
      security:
        - bearerAuth: []
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SinnuTransactionDetail"
          description: ""
        "403": *a3
      summary: Consultar transação
      x-codeSamples:
        - lang: bash
          label: cURL
          source: |-
            curl --fail-with-body --request GET \
              'https://api.sinnu.com.br/api/transactions/ID_DO_RECURSO/' \
              --header "Authorization: Bearer $SINNU_API_KEY"
        - lang: javascript
          label: JavaScript · servidor
          source: |-
            const apiKey = process.env.SINNU_API_KEY;
            if (!apiKey) throw new Error("Configure SINNU_API_KEY no servidor.");
            const response = await fetch("https://api.sinnu.com.br/api/transactions/ID_DO_RECURSO/", {
              method: "GET",
              headers: {
                Authorization: `Bearer ${apiKey}`,
              },
            });
            if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
            console.log(response.status === 204 ? null : await response.json());
  /api/transactions/{id}/refund/:
    post:
      operationId: transactions_refund
      description: Solicita o estorno total de uma transação paga. `reason` e `note` são opcionais e servem para registro interno. Reenvios podem usar `Idempotency-Key`.
      parameters:
        - in: header
          name: Idempotency-Key
          schema:
            type: string
          description: "Chave de idempotência: reenvios com a mesma chave numa transação já estornada retornam a transação atual sem reexecutar o estorno."
        - in: path
          name: id
          schema:
            type: string
          required: true
          example: 00000000-0000-4000-8000-000000000001
      tags:
        - transactions
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SinnuRefundRequest"
            example:
              reason: Solicitação do comprador
              note: Cancelamento do pedido de exemplo
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/SinnuRefundRequest"
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/SinnuRefundRequest"
      security:
        - bearerAuth: []
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SinnuTransaction"
          description: ""
        "403":
          description: Sua chave de API não tem permissão para solicitar estorno.
      summary: Estornar transação
      x-codeSamples:
        - lang: bash
          label: cURL
          source: |-
            curl --fail-with-body --request POST \
              'https://api.sinnu.com.br/api/transactions/ID_DO_RECURSO/refund/' \
              --header "Authorization: Bearer $SINNU_API_KEY" \
              --header 'Content-Type: application/json' \
              --data '{
              "reason": "Solicitação do comprador",
              "note": "Cancelamento do pedido de exemplo"
            }'
        - lang: javascript
          label: JavaScript · servidor
          source: |-
            const apiKey = process.env.SINNU_API_KEY;
            if (!apiKey) throw new Error("Configure SINNU_API_KEY no servidor.");
            const response = await fetch("https://api.sinnu.com.br/api/transactions/ID_DO_RECURSO/refund/", {
              method: "POST",
              headers: {
                Authorization: `Bearer ${apiKey}`,
                "Content-Type": "application/json",
              },
              body: JSON.stringify({
              "reason": "Solicitação do comprador",
              "note": "Cancelamento do pedido de exemplo"
            }),
            });
            if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
            console.log(response.status === 204 ? null : await response.json());
  /api/customers/:
    get:
      operationId: customers_list
      description: Lista os clientes da empresa autenticada no envelope paginado `{ data, total, page, pageSize }`.
      parameters:
        - name: ordering
          required: false
          in: query
          description: Which field to use when ordering the results.
          schema:
            type: string
        - in: query
          name: page
          schema:
            type: integer
          description: Número da página (1-based; default 1).
        - in: query
          name: pageSize
          schema:
            type: integer
          description: Tamanho da página (default 20, máx. 100).
        - in: query
          name: search
          schema:
            type: string
          description: Busca por nome, e-mail, telefone ou documento.
      tags:
        - customers
      security:
        - bearerAuth: []
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedSinnuCustomerList"
          description: ""
      summary: Listar clientes
      x-codeSamples:
        - lang: bash
          label: cURL
          source: |-
            curl --fail-with-body --request GET \
              'https://api.sinnu.com.br/api/customers/' \
              --header "Authorization: Bearer $SINNU_API_KEY"
        - lang: javascript
          label: JavaScript · servidor
          source: |-
            const apiKey = process.env.SINNU_API_KEY;
            if (!apiKey) throw new Error("Configure SINNU_API_KEY no servidor.");
            const response = await fetch("https://api.sinnu.com.br/api/customers/", {
              method: "GET",
              headers: {
                Authorization: `Bearer ${apiKey}`,
              },
            });
            if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
            console.log(response.status === 204 ? null : await response.json());
    post:
      operationId: customers_create
      description: Cadastra um cliente na empresa autenticada. O CPF ou CNPJ é único por empresa.
      tags:
        - customers
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SinnuCustomer"
            example:
              name: Cliente de exemplo
              email: cliente@example.com
              phone: "11999999999"
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/SinnuCustomer"
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/SinnuCustomer"
        required: true
      security:
        - bearerAuth: []
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SinnuCustomer"
          description: ""
      summary: Cadastrar cliente
      x-codeSamples:
        - lang: bash
          label: cURL
          source: |-
            curl --fail-with-body --request POST \
              'https://api.sinnu.com.br/api/customers/' \
              --header "Authorization: Bearer $SINNU_API_KEY" \
              --header 'Content-Type: application/json' \
              --data '{
              "name": "Cliente de exemplo",
              "email": "cliente@example.com",
              "phone": "11999999999"
            }'
        - lang: javascript
          label: JavaScript · servidor
          source: |-
            const apiKey = process.env.SINNU_API_KEY;
            if (!apiKey) throw new Error("Configure SINNU_API_KEY no servidor.");
            const response = await fetch("https://api.sinnu.com.br/api/customers/", {
              method: "POST",
              headers: {
                Authorization: `Bearer ${apiKey}`,
                "Content-Type": "application/json",
              },
              body: JSON.stringify({
              "name": "Cliente de exemplo",
              "email": "cliente@example.com",
              "phone": "11999999999"
            }),
            });
            if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
            console.log(response.status === 204 ? null : await response.json());
  /api/customers/{id}/:
    get:
      operationId: customers_retrieve
      description: Retorna um cliente da empresa autenticada.
      parameters:
        - in: path
          name: id
          schema:
            type: string
            format: uuid
          required: true
          example: 00000000-0000-4000-8000-000000000002
      tags:
        - customers
      security:
        - bearerAuth: []
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SinnuCustomer"
          description: ""
      summary: Consultar cliente
      x-codeSamples:
        - lang: bash
          label: cURL
          source: |-
            curl --fail-with-body --request GET \
              'https://api.sinnu.com.br/api/customers/ID_DO_RECURSO/' \
              --header "Authorization: Bearer $SINNU_API_KEY"
        - lang: javascript
          label: JavaScript · servidor
          source: |-
            const apiKey = process.env.SINNU_API_KEY;
            if (!apiKey) throw new Error("Configure SINNU_API_KEY no servidor.");
            const response = await fetch("https://api.sinnu.com.br/api/customers/ID_DO_RECURSO/", {
              method: "GET",
              headers: {
                Authorization: `Bearer ${apiKey}`,
              },
            });
            if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
            console.log(response.status === 204 ? null : await response.json());
    patch:
      operationId: customers_partial_update
      description: Atualiza parcialmente um cliente da empresa autenticada.
      parameters:
        - in: path
          name: id
          schema:
            type: string
            format: uuid
          required: true
          example: 00000000-0000-4000-8000-000000000002
      tags:
        - customers
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PatchedSinnuCustomer"
            example:
              name: Cliente de exemplo atualizado
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/PatchedSinnuCustomer"
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/PatchedSinnuCustomer"
      security:
        - bearerAuth: []
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SinnuCustomer"
          description: ""
      summary: Atualizar cliente
      x-codeSamples:
        - lang: bash
          label: cURL
          source: |-
            curl --fail-with-body --request PATCH \
              'https://api.sinnu.com.br/api/customers/ID_DO_RECURSO/' \
              --header "Authorization: Bearer $SINNU_API_KEY" \
              --header 'Content-Type: application/json' \
              --data '{
              "name": "Cliente de exemplo atualizado"
            }'
        - lang: javascript
          label: JavaScript · servidor
          source: |-
            const apiKey = process.env.SINNU_API_KEY;
            if (!apiKey) throw new Error("Configure SINNU_API_KEY no servidor.");
            const response = await fetch("https://api.sinnu.com.br/api/customers/ID_DO_RECURSO/", {
              method: "PATCH",
              headers: {
                Authorization: `Bearer ${apiKey}`,
                "Content-Type": "application/json",
              },
              body: JSON.stringify({
              "name": "Cliente de exemplo atualizado"
            }),
            });
            if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
            console.log(response.status === 204 ? null : await response.json());
components:
  schemas:
    InterestModeEnum:
      enum:
        - absorb
        - pass_to_customer
      type: string
      description: |-
        * `absorb` - Eu absorvo
        * `pass_to_customer` - Cliente paga
    OriginChannelEnum:
      enum:
        - meta
        - tiktok
        - whatsapp
        - instagram
        - google
        - direct
        - other
      type: string
      description: |-
        * `meta` - meta
        * `tiktok` - tiktok
        * `whatsapp` - whatsapp
        * `instagram` - instagram
        * `google` - google
        * `direct` - direct
        * `other` - other
    PaginatedPaymentLink:
      type: object
      properties:
        total:
          type: integer
        page:
          type: integer
        pageSize:
          type: integer
        data:
          type: array
          items:
            $ref: "#/components/schemas/PaymentLinkRead"
        counts:
          $ref: "#/components/schemas/PaymentLinkCounts"
      required:
        - counts
        - data
        - page
        - pageSize
        - total
      example:
        data:
          - &a6
            id: 00000000-0000-4000-8000-000000000003
            slug: Exemplo1
            title: Consultoria inicial
            priceMode: fixed
            amountCents: 9900
            methods: *a4
            maxInstallments: 1
            description: Sessão de consultoria
            imageUrl: null
            minAmountCents: null
            maxAmountCents: null
            maxPayments: null
            interestMode: absorb
            status: active
            threeDsMode: always
            tags: []
            redirectUrl: null
            linkedCustomerId: null
            companyId: null
            companyName: Empresa de exemplo
            sellerEmail: vendedor@example.com
            createdAt: 2026-09-01T12:00:00Z
            updatedAt: 2026-09-01T12:00:00Z
        total: 1
        page: 1
        pageSize: 20
    PaginatedPaymentLinkTransaction:
      type: object
      properties:
        total:
          type: integer
        page:
          type: integer
        pageSize:
          type: integer
        data:
          type: array
          items:
            $ref: "#/components/schemas/PaymentLinkTransactionItem"
      required:
        - data
        - page
        - pageSize
        - total
      example:
        data:
          - &a7
            id: 00000000-0000-4000-8000-000000000001
            amount: 99
            status: paid
            paymentMethod: pix
            installments: 1
            customer: &a5
              id: 00000000-0000-4000-8000-000000000002
              name: Cliente de exemplo
              email: cliente@example.com
            createdAt: 2026-09-01T12:00:00Z
            paidAt: 2026-09-01T12:00:00Z
        total: 1
        page: 1
        pageSize: 20
    PaginatedSinnuCustomerList:
      type: object
      required:
        - data
        - total
        - page
        - pageSize
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/SinnuCustomer"
        total:
          type: integer
          example: 123
        page:
          type: integer
          example: 1
        pageSize:
          type: integer
          example: 20
      example:
        data:
          - &a8
            id: 00000000-0000-4000-8000-000000000002
            name: Cliente de exemplo
            email: cliente@example.com
            phone: "11999999999"
            document: null
            type: pf
            createdAt: 2026-09-01T12:00:00Z
            address: null
            notes: null
        total: 1
        page: 1
        pageSize: 20
    PaginatedSinnuTransactionList:
      type: object
      required:
        - data
        - total
        - page
        - pageSize
        - metrics
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/SinnuTransaction"
        total:
          type: integer
          example: 123
        page:
          type: integer
          example: 1
        pageSize:
          type: integer
          example: 20
        metrics:
          type: object
          required:
            - total
            - net
            - count
            - ticket
          properties:
            total:
              type: integer
              example: 1234500
              description: Soma BRUTA (centavos) de todas as transações do filtro.
            net:
              type: integer
              example: 1180000
              description: Soma LÍQUIDA (centavos) só das aprovadas (status=paid).
            count:
              type: integer
              example: 42
              description: Total de transações do filtro (todas as páginas).
            ticket:
              type: integer
              example: 29000
              description: "Ticket médio bruto (centavos): total / count."
      example:
        data:
          - &a9
            id: 00000000-0000-4000-8000-000000000001
            amount: 9900
            net: 9700
            productAmount: 9900
            interestAmount: 0
            interestMode: absorb
            mdrAmount: 150
            fixedFeeAmount: 50
            otherFeeAmount: 0
            totalFeeAmount: 200
            status: approved
            method: pix
            customer: *a5
            description: Consultoria inicial
            installments: 1
            createdAt: 2026-09-01T12:00:00Z
            paidAt: 2026-09-01T12:00:00Z
        total: 1
        page: 1
        pageSize: 20
    PatchedPaymentLinkWrite:
      type: object
      description: Body para atualizar parcialmente um link de pagamento.
      properties:
        title:
          type: string
          maxLength: 255
          description: Título exibido no checkout hospedado.
        description:
          type: string
          description: Descrição exibida no checkout.
        imageUrl:
          type: string
          format: uri
          nullable: true
          maxLength: 200
        priceMode:
          $ref: "#/components/schemas/PriceModeEnum"
          description: Modo de preço. No contrato público atual, use sempre `fixed`.
        amountCents:
          type: integer
          maximum: 20000000
          minimum: 1000
          nullable: true
          description: "Valor fixo do link em centavos. Obrigatório para `priceMode: fixed`."
        minAmountCents:
          type: integer
          maximum: 2147483647
          minimum: 0
          nullable: true
          description: Reservado para modos de preço futuros. Não use no contrato público atual.
        maxAmountCents:
          type: integer
          maximum: 2147483647
          minimum: 0
          nullable: true
          description: Reservado para modos de preço futuros. Não use no contrato público atual.
        methods:
          type: array
          items:
            type: string
            enum:
              - pix
              - credit_card
          description: Métodos aceitos no checkout. Envie `pix`, `credit_card` ou ambos.
        maxInstallments:
          type: integer
          maximum: 12
          minimum: 1
          description: Número máximo de parcelas para cartão. Use 1 quando o link aceitar apenas Pix.
        interestMode:
          $ref: "#/components/schemas/InterestModeEnum"
          description: "Define quem absorve juros de parcelamento: `absorb` ou `pass_to_customer`."
        acceptsOneTime:
          type: boolean
        status:
          $ref: "#/components/schemas/Status50eEnum"
          description: "Status do link: active, paused ou archived."
        threeDsMode:
          $ref: "#/components/schemas/ThreeDsModeEnum"
          description: "Modo de 3DS para cartão: `always` ou `contingency`."
        tags:
          type: array
          items:
            type: string
          description: Tags livres para organização interna do link.
        redirectUrl:
          type: string
          nullable: true
          maxLength: 200
          description: "Para onde o checkout leva o comprador depois do pagamento confirmado (cartão aprovado ou Pix pago), com `transactionId`, `reference` e `status=approved` na query. Aceita `https://` ou o esquema do seu app (`meuapp://pedido`). O retorno é liberado por empresa: confirme com a Sinnu se já está ativo para a sua. Confirme o pagamento pela API ou pelo webhook: os parâmetros da URL podem ser alterados pelo comprador."
        externalReference:
          type: string
          nullable: true
          maxLength: 255
          description: Código do produto no seu sistema. Volta como `externalRef` do item em cada venda do link.
        linkedCustomer:
          type: string
          format: uuid
          nullable: true
          description: ID (UUID) de um cliente já cadastrado nesta empresa para vincular ao link. Mutuamente exclusivo com `customer`.
        customer:
          allOf:
            - $ref: "#/components/schemas/PaymentLinkCustomerInput"
          writeOnly: true
          nullable: true
          description: Dados do comprador (`name`, `email`, `document?`, `phone?`) para cadastrar ou reutilizar por CPF/CNPJ e vincular ao link em uma única requisição. Mutuamente exclusivo com `linkedCustomer`.
        maxPayments:
          type: integer
          nullable: true
          description: Limite máximo de pagamentos aprovados aceitos pelo link (`null` = ilimitado; `1` = link de uso único que arquiva automaticamente após ser pago).
          minimum: 1
          maximum: 1000000
        salespersonId:
          type: integer
          nullable: true
        trackingPixelIds:
          type: array
          items:
            type: string
            format: uuid
    PatchedSinnuCustomer:
      type: object
      description: Cliente da sua empresa. Expõe apenas os dados principais de cadastro e um único documento principal (CPF ou CNPJ).
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        name:
          type: string
          maxLength: 255
        email:
          type: string
          format: email
          maxLength: 254
        phone:
          type: string
          description: Telefone do cliente com DDD (opcional no cadastro).
          maxLength: 255
        document:
          type: string
          nullable: true
          description: "Documento principal do cliente: CPF ou CNPJ, somente dígitos ou formatado."
        type:
          allOf:
            - $ref: "#/components/schemas/SinnuCustomerTypeEnum"
          description: "Tipo do documento principal: `pf` para CPF ou `pj` para CNPJ."
        createdAt:
          type: string
          format: date-time
          readOnly: true
        address:
          type: string
          nullable: true
          description: Endereço em linha livre, opcional.
        notes:
          type: string
          nullable: true
          description: Observações internas sobre o cliente, opcionais.
          maxLength: 500
        archivedAt:
          type: string
          format: date-time
          readOnly: true
        anonymizedAt:
          type: string
          format: date-time
          readOnly: true
    PaymentLinkArchiveOutcomeEnum:
      enum:
        - archived
        - deleted
      type: string
      description: |-
        * `archived` - Arquivado
        * `deleted` - Excluído
    PaymentLinkArchiveResult:
      type: object
      description: |-
        Desfecho de `DELETE /api/payment-links/{id}` - o que aconteceu, em pt-BR.

        O endpoint deixou de ser um `DELETE` puro (decisão do dono, 10/09/2026): link
        com venda ou plano de assinatura é **arquivado**, e as assinaturas vivas seguem
        sendo cobradas. Só um link sem histórico nenhum é realmente apagado. Como as
        duas coisas atendem o mesmo clique, a resposta precisa dizer QUAL delas
        aconteceu - daí o corpo, no lugar do 204 vazio.

        `message` já vem pronta para a tela: painel e app mostram a MESMA frase, com o
        número real de assinaturas ativas. Nenhum dos dois monta texto por conta.
      properties:
        outcome:
          allOf:
            - $ref: "#/components/schemas/PaymentLinkArchiveOutcomeEnum"
          description: |-
            `archived` = saiu do catálogo e parou de vender; `deleted` = apagado.

            * `archived` - Arquivado
            * `deleted` - Excluído
        status:
          type: string
          nullable: true
          description: Status novo do link (`archived`), ou null quando foi apagado.
        archivedPrices:
          type: integer
          description: Quantos planos de assinatura foram arquivados junto (nunca apagados).
        activeSubscriptions:
          type: integer
          description: Assinaturas que CONTINUAM sendo cobradas (trialing/active/past_due).
        message:
          type: string
          description: Frase pt-BR pronta para exibir ao vendedor, sem jargão de ORM.
      required:
        - activeSubscriptions
        - archivedPrices
        - message
        - outcome
        - status
    PaymentLinkCounts:
      type: object
      description: |-
        Contagem por status do conjunto EM ESCOPO (a empresa inteira).

        Independe da página e dos filtros da tela - é o que alimenta os KPIs
        "Links ativos" / "Total de links" do painel sem que eles contem apenas os
        itens da página carregada.
      properties:
        total:
          type: integer
        active:
          type: integer
        paused:
          type: integer
        archived:
          type: integer
      required:
        - active
        - archived
        - paused
        - total
    PaymentLinkCustomerInput:
      type: object
      description: Dados do comprador para cadastrar ou reutilizar por CPF/CNPJ na empresa e já vincular ao link em uma única requisição.
      properties:
        name:
          type: string
          description: Nome completo ou razão social do comprador.
          maxLength: 255
        email:
          type: string
          format: email
          description: E-mail do comprador para envio da confirmação e recibos.
          maxLength: 254
        document:
          type: string
          nullable: true
          description: CPF (11 dígitos) ou CNPJ (14 dígitos), com ou sem pontuação. No checkout hospedado aparece mascarado (`***.456.789-**`) com opção de alterar.
          maxLength: 32
        phone:
          type: string
          nullable: true
          description: Telefone com DDD, opcional no cadastro do link. Quando informado, também vem pré-preenchido no checkout hospedado.
          maxLength: 32
      required:
        - email
        - name
    PaymentLinkRead:
      type: object
      description: Link de pagamento público da empresa autenticada. Use o `slug` para montar a URL do checkout hospedado.
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        slug:
          type: string
          readOnly: true
        title:
          type: string
          readOnly: true
          description: Título exibido no checkout hospedado.
        description:
          type: string
          readOnly: true
          description: Descrição exibida no checkout.
        imageUrl:
          type: string
          format: uri
          readOnly: true
          nullable: true
        priceMode:
          allOf:
            - $ref: "#/components/schemas/PriceModeEnum"
          readOnly: true
          description: Modo de preço. No contrato público atual, use sempre `fixed`.
        amountCents:
          type: integer
          readOnly: true
          nullable: true
          minimum: 1000
          maximum: 20000000
          description: "Valor fixo do link em centavos. Obrigatório para `priceMode: fixed`."
        minAmountCents:
          type: integer
          readOnly: true
          nullable: true
          description: Reservado para modos de preço futuros. Não use no contrato público atual.
        maxAmountCents:
          type: integer
          readOnly: true
          nullable: true
          description: Reservado para modos de preço futuros. Não use no contrato público atual.
        methods:
          type: array
          items:
            type: string
            enum:
              - pix
              - credit_card
          readOnly: true
          description: Métodos aceitos no checkout. Envie `pix`, `credit_card` ou ambos.
        maxInstallments:
          type: integer
          readOnly: true
          minimum: 1
          maximum: 12
          description: Número máximo de parcelas para cartão. Use 1 quando o link aceitar apenas Pix.
        interestMode:
          allOf:
            - $ref: "#/components/schemas/InterestModeEnum"
          readOnly: true
          description: "Define quem absorve juros de parcelamento: `absorb` ou `pass_to_customer`."
        acceptsOneTime:
          type: boolean
          readOnly: true
        status:
          allOf:
            - $ref: "#/components/schemas/Status50eEnum"
          readOnly: true
          description: "Status do link: active, paused ou archived."
        threeDsMode:
          allOf:
            - $ref: "#/components/schemas/ThreeDsModeEnum"
          readOnly: true
          description: "Modo de 3DS para cartão: `always` ou `contingency`."
        tags:
          readOnly: true
          type: array
          items:
            type: string
          description: Tags livres para organização interna do link.
        redirectUrl:
          type: string
          readOnly: true
          nullable: true
          description: "Para onde o checkout leva o comprador depois do pagamento confirmado (cartão aprovado ou Pix pago), com `transactionId`, `reference` e `status=approved` na query. Aceita `https://` ou o esquema do seu app (`meuapp://pedido`). O retorno é liberado por empresa: confirme com a Sinnu se já está ativo para a sua. Confirme o pagamento pela API ou pelo webhook: os parâmetros da URL podem ser alterados pelo comprador."
        externalReference:
          type: string
          readOnly: true
          nullable: true
          description: Código do produto no seu sistema. Volta como `externalRef` do item em cada venda do link.
        linkedCustomerId:
          type: string
          nullable: true
          readOnly: true
          description: ID do cliente vinculado ao link, quando houver.
        maxPayments:
          type: integer
          readOnly: true
          nullable: true
          description: Limite máximo de pagamentos aprovados aceitos pelo link (`null` = ilimitado; `1` = link de uso único que arquiva automaticamente após ser pago).
          minimum: 1
          maximum: 1000000
        companyId:
          type: integer
          nullable: true
          readOnly: true
        companyName:
          type: string
          nullable: true
          readOnly: true
        sellerEmail:
          type: string
          nullable: true
          readOnly: true
        salesCount:
          type: integer
          description: Nº de vendas pagas do link (Payment status='paid', alinhado a maxPayments).
          readOnly: true
        views:
          type: integer
          description: Visitas ao checkout público (LinkVisit, já deduplicadas na escrita).
          readOnly: true
        conversionRate:
          type: number
          format: double
          description: Fração 0..1 = salesCount/views, com guarda de divisão por zero e teto em 1.0.
          readOnly: true
        activeSubscriptions:
          type: integer
          description: |-
            Assinaturas deste link que CONTINUAM sendo cobradas.

            A cláusula é a de `checkout.services.still_charging_filter` - fonte
            única, para esta contagem e a da mensagem de arquivamento nunca contarem
            coisas diferentes.

            Serve à tela de EDIÇÃO: o aviso de que mudar o preço não repreça quem já
            assinou existia, bem escrito, na tela de CRIAÇÃO - onde ainda não há
            assinante e a frase não significa nada. Com o número, ele passa a
            significar.
          readOnly: true
        salespersonId:
          type: integer
          readOnly: true
          nullable: true
        salesperson:
          allOf:
            - $ref: "#/components/schemas/SaleSalesperson"
          nullable: true
          readOnly: true
        trackingPixelIds:
          type: array
          items:
            type: string
          readOnly: true
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true
      required:
        - acceptsOneTime
        - activeSubscriptions
        - amountCents
        - companyId
        - companyName
        - conversionRate
        - createdAt
        - description
        - externalReference
        - id
        - imageUrl
        - interestMode
        - linkedCustomerId
        - maxAmountCents
        - maxInstallments
        - maxPayments
        - methods
        - minAmountCents
        - priceMode
        - redirectUrl
        - salesCount
        - salesperson
        - salespersonId
        - sellerEmail
        - slug
        - status
        - tags
        - threeDsMode
        - title
        - trackingPixelIds
        - updatedAt
        - views
      example: *a6
    PaymentLinkTransactionCustomer:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
          format: email
      required:
        - email
        - id
        - name
      example: *a5
    PaymentLinkTransactionItem:
      type: object
      properties:
        id:
          type: string
          format: uuid
        amount:
          type: number
          format: double
          maximum: 10000000000
          minimum: -10000000000
          exclusiveMaximum: true
          exclusiveMinimum: true
          description: "Valor em reais (BRL). Ex.: 99.00 representa R$ 99,00. Esta unidade difere de /api/transactions/."
        status:
          type: string
        paymentMethod:
          type: string
        installments:
          type: integer
        customer:
          $ref: "#/components/schemas/PaymentLinkTransactionCustomer"
        createdAt:
          type: string
          format: date-time
        paidAt:
          type: string
          format: date-time
          nullable: true
      required:
        - amount
        - createdAt
        - customer
        - id
        - installments
        - paidAt
        - paymentMethod
        - status
      example: *a7
    PaymentLinkWrite:
      type: object
      description: "Body para criar um link de pagamento. Use `priceMode: fixed` e envie o valor em `amountCents`."
      properties:
        title:
          type: string
          maxLength: 255
          description: Título exibido no checkout hospedado.
        description:
          type: string
          description: Descrição exibida no checkout.
        imageUrl:
          type: string
          format: uri
          nullable: true
          maxLength: 200
        priceMode:
          $ref: "#/components/schemas/PriceModeEnum"
          description: Modo de preço. No contrato público atual, use sempre `fixed`.
        amountCents:
          type: integer
          maximum: 20000000
          minimum: 1000
          nullable: true
          description: "Valor fixo do link em centavos. Obrigatório para `priceMode: fixed`."
        minAmountCents:
          type: integer
          maximum: 2147483647
          minimum: 0
          nullable: true
          description: Reservado para modos de preço futuros. Não use no contrato público atual.
        maxAmountCents:
          type: integer
          maximum: 2147483647
          minimum: 0
          nullable: true
          description: Reservado para modos de preço futuros. Não use no contrato público atual.
        methods:
          type: array
          items:
            type: string
            enum:
              - pix
              - credit_card
          description: Métodos aceitos no checkout. Envie `pix`, `credit_card` ou ambos.
        maxInstallments:
          type: integer
          maximum: 12
          minimum: 1
          description: Número máximo de parcelas para cartão. Use 1 quando o link aceitar apenas Pix.
        interestMode:
          $ref: "#/components/schemas/InterestModeEnum"
          description: "Define quem absorve juros de parcelamento: `absorb` ou `pass_to_customer`."
        acceptsOneTime:
          type: boolean
        status:
          $ref: "#/components/schemas/Status50eEnum"
          description: "Status do link: active, paused ou archived."
        threeDsMode:
          $ref: "#/components/schemas/ThreeDsModeEnum"
          description: "Modo de 3DS para cartão: `always` ou `contingency`."
        tags:
          type: array
          items:
            type: string
          description: Tags livres para organização interna do link.
        redirectUrl:
          type: string
          nullable: true
          maxLength: 200
          description: "Para onde o checkout leva o comprador depois do pagamento confirmado (cartão aprovado ou Pix pago), com `transactionId`, `reference` e `status=approved` na query. Aceita `https://` ou o esquema do seu app (`meuapp://pedido`). O retorno é liberado por empresa: confirme com a Sinnu se já está ativo para a sua. Confirme o pagamento pela API ou pelo webhook: os parâmetros da URL podem ser alterados pelo comprador."
        externalReference:
          type: string
          nullable: true
          maxLength: 255
          description: Código do produto no seu sistema. Volta como `externalRef` do item em cada venda do link.
        linkedCustomer:
          type: string
          format: uuid
          nullable: true
          description: ID (UUID) de um cliente já cadastrado nesta empresa para vincular ao link. Mutuamente exclusivo com `customer`.
        customer:
          allOf:
            - $ref: "#/components/schemas/PaymentLinkCustomerInput"
          writeOnly: true
          nullable: true
          description: Dados do comprador (`name`, `email`, `document?`, `phone?`) para cadastrar ou reutilizar por CPF/CNPJ e vincular ao link em uma única requisição. Mutuamente exclusivo com `linkedCustomer`.
        maxPayments:
          type: integer
          nullable: true
          description: Limite máximo de pagamentos aprovados aceitos pelo link (`null` = ilimitado; `1` = link de uso único que arquiva automaticamente após ser pago).
          minimum: 1
          maximum: 1000000
        salespersonId:
          type: integer
          nullable: true
        trackingPixelIds:
          type: array
          items:
            type: string
            format: uuid
      required:
        - title
    PriceModeEnum:
      enum:
        - fixed
      type: string
      description: "* `fixed` - Fixo"
    SaleItemCents:
      type: object
      properties:
        title:
          type: string
        quantity:
          type: integer
        unitPrice:
          type: integer
          nullable: true
          description: Preço unitário em centavos.
        externalRef:
          type: string
          nullable: true
      required:
        - externalRef
        - quantity
        - title
        - unitPrice
    SaleLink:
      type: object
      properties:
        id:
          type: string
          description: ID do link de pagamento.
        title:
          type: string
          description: Título do link, que é o nome do produto.
      required:
        - id
        - title
    SaleSalesperson:
      type: object
      properties:
        id:
          type: integer
          description: ID do membro da equipe.
        name:
          type: string
        email:
          type: string
          format: email
      required:
        - email
        - id
        - name
    SinnuCustomer:
      type: object
      description: Cliente da sua empresa. Expõe apenas os dados principais de cadastro e um único documento principal (CPF ou CNPJ).
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        name:
          type: string
          maxLength: 255
        email:
          type: string
          format: email
          maxLength: 254
        phone:
          type: string
          description: Telefone do cliente com DDD (opcional no cadastro).
          maxLength: 255
        document:
          type: string
          nullable: true
          description: "Documento principal do cliente: CPF ou CNPJ, somente dígitos ou formatado."
        type:
          allOf:
            - $ref: "#/components/schemas/SinnuCustomerTypeEnum"
          description: "Tipo do documento principal: `pf` para CPF ou `pj` para CNPJ."
        createdAt:
          type: string
          format: date-time
          readOnly: true
        address:
          type: string
          nullable: true
          description: Endereço em linha livre, opcional.
        notes:
          type: string
          nullable: true
          description: Observações internas sobre o cliente, opcionais.
          maxLength: 500
        archivedAt:
          type: string
          format: date-time
          readOnly: true
        anonymizedAt:
          type: string
          format: date-time
          readOnly: true
      required:
        - anonymizedAt
        - archivedAt
        - createdAt
        - email
        - id
        - name
      example: *a8
    SinnuCustomerTypeEnum:
      enum:
        - pf
        - pj
      type: string
      description: |-
        * `pf` - pf
        * `pj` - pj
    SinnuRefundRequest:
      type: object
      description: Pedido de estorno. O estorno é sempre do valor total; não há campo de valor.
      properties:
        reason:
          type: string
          description: Motivo do estorno, opcional.
        note:
          type: string
          description: Observação sobre o estorno, opcional.
          maxLength: 500
    SinnuTransaction:
      type: object
      description: Transação da empresa autenticada. Valores monetários são inteiros em centavos.
      properties:
        id:
          type: string
          readOnly: true
        amount:
          type: integer
          description: Valor bruto cobrado do comprador, em centavos.
          readOnly: true
        net:
          type: integer
          description: Valor líquido do vendedor, em centavos. Os números do exemplo são fictícios e não representam uma proposta de taxas.
          readOnly: true
        productAmount:
          type: integer
          description: Preço do produto, em centavos, antes de juros de parcelamento.
          readOnly: true
        interestAmount:
          type: integer
          description: Juros do parcelamento, em centavos.
          readOnly: true
        interestMode:
          type: string
          nullable: true
          description: "Quem paga os juros do parcelamento: `absorb` ou `pass_to_customer`."
          readOnly: true
        mdrAmount:
          type: integer
          readOnly: true
        fixedFeeAmount:
          type: integer
          readOnly: true
        otherFeeAmount:
          type: integer
          readOnly: true
        totalFeeAmount:
          type: integer
          readOnly: true
        status:
          type: string
          description: "Status da transação: pending, approved, refused, refunded ou chargeback."
          readOnly: true
        method:
          allOf:
            - $ref: "#/components/schemas/SinnuTransactionMethodEnum"
          readOnly: true
          description: "Método de pagamento: pix ou credit_card."
        customer:
          allOf:
            - $ref: "#/components/schemas/SinnuTransactionCustomer"
          readOnly: true
          description: "Pagador da transação: `{ id, name, email }`."
        description:
          type: string
          description: Descrição da venda. Vazia quando não informada.
          readOnly: true
        installments:
          type: integer
          readOnly: true
        createdAt:
          type: string
          format: date-time
          readOnly: true
        paidAt:
          type: string
          format: date-time
          readOnly: true
          nullable: true
        refusal:
          allOf:
            - $ref: "#/components/schemas/SinnuTransactionRefusal"
          nullable: true
          readOnly: true
        splits:
          type: array
          items:
            $ref: "#/components/schemas/SinnuTransactionSplit"
          readOnly: true
        checkoutSlug:
          type: string
          nullable: true
          readOnly: true
          description: "Slug do link de checkout desta venda, e SÓ quando esse link ainda aceita uma compra nova - é com ele que o painel/app monta a URL para o vendedor reenviar ao comprador. `null` quando não há para onde mandar ninguém: venda sem link (cobrança direta por API), link pausado/arquivado, ou link que só vende assinatura. Reabrir o checkout cria uma cobrança NOVA - não quita a pendente, que segue até expirar."
        disputedAt:
          type: string
          format: date-time
          nullable: true
          readOnly: true
          description: Quando a disputa entrou (`Payment.chargedbackAt`). `null` fora de disputa - inclusive numa disputa já revertida, que volta a `approved` e não deve seguir marcada.
        link:
          allOf:
            - $ref: "#/components/schemas/SaleLink"
          nullable: true
          readOnly: true
        reference:
          type: string
          readOnly: true
          nullable: true
          description: "Pedido do seu sistema para esta venda: o `?ref=` com que o checkout foi aberto, ou o `exId` da cobrança criada pela API. `null` quando não informado."
        items:
          type: array
          items:
            $ref: "#/components/schemas/SaleItemCents"
          readOnly: true
        salesperson:
          allOf:
            - $ref: "#/components/schemas/SaleSalesperson"
          nullable: true
          readOnly: true
        origin:
          allOf:
            - $ref: "#/components/schemas/TransactionOrigin"
          nullable: true
          readOnly: true
      required:
        - amount
        - checkoutSlug
        - createdAt
        - customer
        - description
        - disputedAt
        - fixedFeeAmount
        - id
        - installments
        - interestAmount
        - interestMode
        - items
        - link
        - mdrAmount
        - method
        - net
        - origin
        - otherFeeAmount
        - paidAt
        - productAmount
        - reference
        - refusal
        - salesperson
        - splits
        - status
        - totalFeeAmount
      example: *a9
    SinnuTransactionCustomer:
      type: object
      description: "Cliente embutido na transação: `{ id, name, email, phone }`."
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
          format: email
        phone:
          type: string
          nullable: true
      required:
        - email
        - id
        - name
        - phone
    SinnuTransactionDetail:
      type: object
      description: Transação da empresa autenticada. Valores monetários são inteiros em centavos.
      properties:
        id:
          type: string
          readOnly: true
        amount:
          type: integer
          description: Valor bruto cobrado do pagador, em centavos.
          readOnly: true
        net:
          type: integer
          description: Valor líquido da empresa, em centavos.
          readOnly: true
        productAmount:
          type: integer
          description: Preço do produto, em centavos, antes dos juros de parcelamento.
          readOnly: true
        interestAmount:
          type: integer
          description: Juros do parcelamento, em centavos.
          readOnly: true
        interestMode:
          type: string
          nullable: true
          description: "Quem paga os juros do parcelamento: `absorb` ou `pass_to_customer`."
          readOnly: true
        mdrAmount:
          type: integer
          readOnly: true
        fixedFeeAmount:
          type: integer
          readOnly: true
        otherFeeAmount:
          type: integer
          readOnly: true
        totalFeeAmount:
          type: integer
          readOnly: true
        status:
          type: string
          description: "Status da transação: pending, approved, refused, refunded ou chargeback."
          readOnly: true
        method:
          allOf:
            - $ref: "#/components/schemas/SinnuTransactionMethodEnum"
          readOnly: true
          description: "Método de pagamento: pix ou credit_card."
        customer:
          allOf:
            - $ref: "#/components/schemas/SinnuTransactionCustomer"
          readOnly: true
          description: "Pagador da transação: `{ id, name, email }`."
        description:
          type: string
          description: Descrição da venda. Vazia quando não informada.
          readOnly: true
        installments:
          type: integer
          readOnly: true
        createdAt:
          type: string
          format: date-time
          readOnly: true
        paidAt:
          type: string
          format: date-time
          readOnly: true
          nullable: true
        refusal:
          allOf:
            - $ref: "#/components/schemas/SinnuTransactionRefusal"
          nullable: true
          readOnly: true
        splits:
          type: array
          items:
            $ref: "#/components/schemas/SinnuTransactionSplit"
          readOnly: true
        checkoutSlug:
          type: string
          nullable: true
          readOnly: true
          description: "Slug do link de checkout desta venda, e SÓ quando esse link ainda aceita uma compra nova - é com ele que o painel/app monta a URL para o vendedor reenviar ao comprador. `null` quando não há para onde mandar ninguém: venda sem link (cobrança direta por API), link pausado/arquivado, ou link que só vende assinatura. Reabrir o checkout cria uma cobrança NOVA - não quita a pendente, que segue até expirar."
        disputedAt:
          type: string
          format: date-time
          nullable: true
          readOnly: true
          description: Quando a disputa entrou (`Payment.chargedbackAt`). `null` fora de disputa - inclusive numa disputa já revertida, que volta a `approved` e não deve seguir marcada.
        link:
          allOf:
            - $ref: "#/components/schemas/SaleLink"
          nullable: true
          readOnly: true
        reference:
          type: string
          readOnly: true
          nullable: true
          description: "Pedido do seu sistema para esta venda: o `?ref=` com que o checkout foi aberto, ou o `exId` da cobrança criada pela API. `null` quando não informado."
        items:
          type: array
          items:
            $ref: "#/components/schemas/SaleItemCents"
          readOnly: true
        salesperson:
          allOf:
            - $ref: "#/components/schemas/SaleSalesperson"
          nullable: true
          readOnly: true
        origin:
          allOf:
            - $ref: "#/components/schemas/TransactionOrigin"
          nullable: true
          readOnly: true
        attribution:
          allOf:
            - $ref: "#/components/schemas/TransactionAttribution"
          nullable: true
          readOnly: true
        trackingDeliveries:
          type: array
          items:
            $ref: "#/components/schemas/TrackingDeliveryRead"
          readOnly: true
      required:
        - amount
        - attribution
        - checkoutSlug
        - createdAt
        - customer
        - description
        - disputedAt
        - fixedFeeAmount
        - id
        - installments
        - interestAmount
        - interestMode
        - items
        - link
        - mdrAmount
        - method
        - net
        - origin
        - otherFeeAmount
        - paidAt
        - productAmount
        - reference
        - refusal
        - salesperson
        - splits
        - status
        - totalFeeAmount
        - trackingDeliveries
    SinnuTransactionMethodEnum:
      type: string
      enum:
        - pix
        - credit_card
        - threeDs
        - applepay
        - googlepay
    SinnuTransactionRefusal:
      type: object
      description: Motivo detalhado de recusa devolvido pelo emissor do cartão, com orientação para recuperar a venda.
      properties:
        code:
          type: string
          description: "Código ABECS cru devolvido pelo emissor (ex.: `59`, `51`, `03`); vazio quando o emissor não devolveu código. Exibir em fonte mono para repasse ao suporte."
        title:
          type: string
          description: Título curto da causa, voz do seller.
        detail:
          type: string
          description: Explicação da causa (quem recusou e por quê).
        action:
          type: string
          description: Ação sugerida ao seller para recuperar a venda.
        retryable:
          type: boolean
          description: Se vale a pena retentar a MESMA forma de pagamento.
        irreversible:
          type: boolean
          description: 'Coluna "Tipo de código" da tabela ABECS oficial: True quando a recusa é IRREVERSÍVEL (não adianta retentar este cartão - peça outro ou Pix). False também quando o código não está na tabela.'
      required:
        - action
        - code
        - detail
        - irreversible
        - retryable
        - title
    SinnuTransactionSplit:
      type: object
      description: Fatia de divisão do valor líquido da transação entre produtor, coprodutor ou afiliado.
      properties:
        type:
          type: string
          description: "`producer` | `coproducer` | `affiliate` (`payment.SplitType`)."
        recipientName:
          type: string
          description: Nome da empresa que recebe esta fatia. Vazio em split legado sem empresa carimbada. É o ÚNICO dado do parceiro exposto ao vendedor.
        percentage:
          type: number
          format: double
          description: Percentual EFETIVO desta fatia sobre o líquido da venda, como o settle gravou. 0 enquanto a venda não liquidou.
        amountCents:
          type: integer
          description: Parte liberável desta fatia, em centavos.
        reserveCents:
          type: integer
          description: Parte retida em reserva desta fatia, em centavos. O que o recebedor ganha nesta venda é `amountCents + reserveCents`.
      required:
        - amountCents
        - percentage
        - recipientName
        - reserveCents
        - type
    Status50eEnum:
      enum:
        - active
        - paused
        - archived
      type: string
      description: |-
        * `active` - Ativo
        * `paused` - Pausado
        * `archived` - Arquivado
    ThreeDsModeEnum:
      enum:
        - always
        - contingency
      type: string
      description: |-
        * `always` - Sempre
        * `contingency` - Contingência
    TrackingDeliveryPixel:
      type: object
      properties:
        id:
          type: string
          format: uuid
        platform:
          $ref: "#/components/schemas/TrackingPixelPlatformEnum"
        name:
          type: string
      required:
        - id
        - name
        - platform
    TrackingDeliveryRead:
      type: object
      description: Um evento enviado (ou a enviar) a um pixel por esta venda.
      properties:
        id:
          type: integer
        pixel:
          $ref: "#/components/schemas/TrackingDeliveryPixel"
        event:
          type: string
          description: "Nome do evento na plataforma: `Purchase` (também no Google Ads), `PixGerado`, `CompletePayment`, `PlaceAnOrder`."
        kind:
          allOf:
            - $ref: "#/components/schemas/TrackingDeliveryReadKindEnum"
          description: |-
            `purchase` (compra) ou `pix_generated` (Pix gerado, não é conversão).

            * `purchase` - purchase
            * `pix_generated` - pix_generated
        status:
          $ref: "#/components/schemas/TrackingDeliveryStatusEnum"
        attempts:
          type: integer
        sentAt:
          type: string
          format: date-time
          nullable: true
        createdAt:
          type: string
          format: date-time
        error:
          type: string
          description: Resumo do último erro (vazio quando enviado).
        canResend:
          type: boolean
          description: "`true` só em envio que FALHOU e cujo evento ainda cabe na janela de 7 dias da plataforma: é o que `POST /api/tracking/deliveries/{id}/resend` aceita."
      required:
        - attempts
        - canResend
        - createdAt
        - error
        - event
        - id
        - kind
        - pixel
        - sentAt
        - status
    TrackingDeliveryReadKindEnum:
      enum:
        - purchase
        - pix_generated
      type: string
      description: |-
        * `purchase` - purchase
        * `pix_generated` - pix_generated
    TrackingDeliveryStatusEnum:
      enum:
        - pending
        - sent
        - failed
        - skipped
      type: string
      description: |-
        * `pending` - Na fila
        * `sent` - Enviado
        * `failed` - Falhou
        * `skipped` - Não enviado
    TrackingPixelPlatformEnum:
      enum:
        - meta
        - tiktok
        - google_ads
      type: string
      description: |-
        * `meta` - Meta
        * `tiktok` - TikTok
        * `google_ads` - Google Ads
    TransactionAttribution:
      type: object
      description: |-
        ``attribution`` no detalhe da transação: os UTMs e o contexto do clique.

        O que NÃO sai daqui, de propósito: IP, user agent, os cookies dos pixels
        (`fbp`/`fbc`/`ttp`) e os click-ids inteiros - é dado do comprador que só
        serve ao envio. `landingUrl` vai sem a query (é nela que o click-id viaja).
      properties:
        channel:
          $ref: "#/components/schemas/OriginChannelEnum"
        source:
          type: string
        medium:
          type: string
        campaign:
          type: string
        content:
          type: string
          description: "`utm_content`."
        term:
          type: string
          description: "`utm_term`."
        src:
          type: string
        sck:
          type: string
        landingUrl:
          type: string
          description: Página de entrada, SEM a query string.
        referrer:
          type: string
        firstSeenAt:
          type: string
          format: date-time
          description: Quando a atribuição foi gravada (primeiro clique que virou sessão).
        clickIds:
          type: array
          items:
            $ref: "#/components/schemas/TransactionClickId"
      required:
        - campaign
        - channel
        - clickIds
        - content
        - firstSeenAt
        - landingUrl
        - medium
        - referrer
        - sck
        - source
        - src
        - term
    TransactionClickId:
      type: object
      properties:
        param:
          type: string
          description: "`fbclid` | `ttclid` | `gclid` | `gbraid` | `wbraid`."
        masked:
          type: string
          description: "Só o fim do identificador (ex.: `...a9f3`)."
      required:
        - masked
        - param
    TransactionOrigin:
      type: object
      description: "``origin`` de cada linha da lista de transações do painel."
      properties:
        channel:
          allOf:
            - $ref: "#/components/schemas/OriginChannelEnum"
          description: |-
            Canal derivado de `utm_source`: `meta` | `tiktok` | `whatsapp` | `instagram` | `google` | `direct` (sem atribuição) | `other`.

            * `meta` - meta
            * `tiktok` - tiktok
            * `whatsapp` - whatsapp
            * `instagram` - instagram
            * `google` - google
            * `direct` - direct
            * `other` - other
        source:
          type: string
          description: "`utm_source` como veio."
        medium:
          type: string
          description: "`utm_medium` como veio."
        campaign:
          type: string
          description: "`utm_campaign` como veio."
      required:
        - campaign
        - channel
        - medium
        - source
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Chave secreta sk_live_ da empresa. Use somente no servidor.
servers:
  - url: https://api.sinnu.com.br
    description: Produção
security:
  - bearerAuth: []
