Toku Consulta de consentimientos API

openapi: 3.2.0
info:
  title: Recursos secundarios Consulta de consentimientos API
  version: 1.0.0
  description: 'API server-to-server con la que la organización consulta qué consintió una persona, para decidir qué pedirle antes de anunciar. Se autentica igual que los intents: la llama su backend con la api-key de Toku, el gateway le entrega al servicio la organización en el header `organization-consumer`, y una request sin él responde `403`. Cada organización ve sólo lo que ella registró.'
servers:
- description: Production
  url: https://api.trytoku.com
security:
- ApiKeyAuth: []
tags:
- description: 'API server-to-server con la que la organización consulta qué consintió una persona, para decidir qué pedirle antes de anunciar. Se autentica igual que los intents: la llama su backend con la api-key de Toku, el gateway le entrega al servicio la organización en el header `organization-consumer`, y una request sin él responde `403`. Cada organización ve sólo lo que ella registró.'
  name: Consulta de consentimientos
paths:
  /consent/consents:
    get:
      description: 'Devuelve, por cada uso de datos del que la persona tiene registro, qué versión aceptó, cuál está vigente y en qué estado queda la combinación. La organización lo llama **desde su servidor**, antes de anunciar un consentimiento, para no volver a pedir lo que ya está `active` o pedir sólo lo que quedó `outdated`.


        **Una persona sin registros responde `200` con una lista vacía**, no un `404`: que no haya consentido nada es una respuesta. La lista no se pagina, porque una persona tiene a lo sumo una fila por uso de datos.


        **Editar el enunciado de un uso de datos no desactualiza nada**: sólo una versión nueva lo hace, así que quien aceptó la frase anterior sigue saliendo `active`.


        **`external_id` tiene que ser opaco.** Viaja en la URL, así que queda en los logs de las requests por debajo de cualquier filtro: no uses ahí un correo, un RUT ni ningún otro dato de la persona. Por la misma razón esta ruta no recibe un documento de identidad.


        **Límite de tasa:** 20 solicitudes por segundo. Al superarlo, la API responde `429`. Ver Límites de tasa.'
      operationId: list_subject_consents
      parameters:
      - description: 'Identificador de la persona en los sistemas de la organización, el mismo con el que la anunció. Tiene que ser opaco: nunca un correo ni un RUT.'
        in: query
        name: external_id
        required: true
        schema:
          description: 'Identificador de la persona en los sistemas de la organización, el mismo con el que la anunció. Tiene que ser opaco: nunca un correo ni un RUT.'
          examples:
          - cliente-4471
          pattern: \S
          title: External Id
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/SubjectConsentResponse'
                title: Response List Subject Consents
                type: array
          description: Successful Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentService_ErrorResponse'
          description: Faltan las credenciales o son inválidas.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentService_ErrorResponse'
          description: La request no declara una organización en `organization-consumer`.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentService_ErrorResponse'
          description: El recurso solicitado no existe.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentService_ErrorResponse'
          description: Falta `external_id` o está en blanco.
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentService_ErrorResponse'
          description: Se superó el límite de peticiones permitidas.
      summary: Consultar qué consintió una persona
      tags:
      - Consulta de consentimientos
components:
  schemas:
    SubjectConsentResponse:
      properties:
        document:
          allOf:
          - $ref: '#/components/schemas/SubjectConsentDocumentResponse'
          description: Uso de datos sobre el que rige, con la versión aceptada y la vigente.
          examples:
          - current_version: 2
            name: Términos y condiciones para el flujo de pago
            uuid: 8f14e45f-ceea-467a-9f39-1c4b2f7a0d31
            version: 1
        granted_at:
          description: Momento de la aceptación que rige, en UTC.
          examples:
          - '2026-04-23T09:42:02Z'
          format: date-time
          title: Granted At
          type: string
        revoked_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          description: Momento del retiro, si lo hubo, en UTC.
          examples:
          - null
          title: Revoked At
        status:
          allOf:
          - $ref: '#/components/schemas/ConsentState'
          description: 'Estado **calculado al leer**. `active`: lo aceptado sigue siendo lo vigente. `outdated`: se publicó una versión nueva de ese uso de datos, así que hay que volver a preguntarle. `revoked`: la organización retiró el consentimiento. Editar el enunciado no cambia el estado: sólo una versión nueva lo desactualiza.'
          examples:
          - outdated
      required:
      - document
      - status
      - granted_at
      title: SubjectConsentResponse
      type: object
    ConsentService_ErrorResponse:
      description: Cuerpo de error canónico de la API, con el detalle anidado bajo `error`.
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
      required:
      - error
      title: ConsentService_ErrorResponse
      type: object
    ErrorDetail:
      description: 'Detalle de un error de la API: mensaje legible y código interno estable.'
      properties:
        code:
          description: Código de error interno de Toku (formato `TKxxxxx`), estable. El listado completo está en [Códigos de API](/reference/codigos-de-api).
          title: Code
          type: string
        message:
          description: Descripción legible de qué salió mal.
          title: Message
          type: string
      required:
      - message
      - code
      title: ErrorDetail
      type: object
    SubjectConsentDocumentResponse:
      properties:
        current_version:
          description: Versión vigente hoy.
          examples:
          - 2
          title: Current Version
          type: integer
        name:
          description: Nombre que el uso de datos tenía cuando se aceptó.
          examples:
          - Términos y condiciones para el flujo de pago
          title: Name
          type: string
        uuid:
          description: uuid del uso de datos.
          examples:
          - 8f14e45f-ceea-467a-9f39-1c4b2f7a0d31
          title: Uuid
          type: string
        version:
          description: Versión que la persona aceptó.
          examples:
          - 1
          title: Version
          type: integer
      required:
      - uuid
      - name
      - version
      - current_version
      title: SubjectConsentDocumentResponse
      type: object
    ConsentState:
      description: What the API answers and filters by. `outdated` is never stored — it is a comparison against the version in force, made when the row is read.
      enum:
      - active
      - outdated
      - revoked
      title: ConsentState
      type: string
  securitySchemes:
    ApiKeyAuth:
      description: Toku public API key. Send it in the x-api-key header on every request.
      in: header
      name: x-api-key
      type: apiKey
x-toku-api-version: '2026-10-08'
x-toku-dto-versions:
  DTOAccountPaymentInstrument: DTOAccountPaymentInstrumentV1
  DTOAggregatedPaymentMethod: DTOAggregatedPaymentMethodV2
  DTOAggregatedTransaction: DTOAggregatedTransactionV2
  DTOBankAccountPaymentMethod: DTOBankAccountPaymentMethodV1
  DTOBoletoPaymentInstrument: DTOBoletoPaymentInstrumentV2
  DTOBrPaymentInstrument: DTOBrPaymentInstrumentV2
  DTOCardPaymentInstrument: DTOCardPaymentInstrumentV1
  DTOCardPaymentMethod: DTOCardPaymentMethodV1
  DTOCashClPaymentInstrument: DTOCashClPaymentInstrumentV1
  DTOCashMxPaymentInstrument: DTOCashMxPaymentInstrumentV1
  DTOClPaymentInstrument: DTOClPaymentInstrumentV2
  DTOCustomer: DTOCustomerV2
  DTOInvoice: DTOInvoiceV4
  DTOMxPaymentInstrument: DTOMxPaymentInstrumentV3
  DTOPacManagementPaymentInstrument: DTOPacManagementPaymentInstrumentV1
  DTOPatpassPaymentInstrument: DTOPatpassPaymentInstrumentV1
  DTOPaymentIntent: DTOPaymentIntentV5
  DTOPaymentMethod: DTOPaymentMethodV7
  DTOPixPaymentInstrument: DTOPixPaymentInstrumentV1
  DTOPixPaymentMethod: DTOPixPaymentMethodV1
  DTOReferencedPaymentMXInstrument: DTOReferencedPaymentMXInstrumentV1
  DTOTransaction: DTOTransactionV10
  DTOTransferClPaymentInstrument: DTOTransferClPaymentInstrumentV2
  DTOTransferMxPaymentInstrument: DTOTransferMxPaymentInstrumentV1
  DTOUpdatedFields: DTOUpdatedFieldsV1
  DTOWalletMovement: DTOWalletMovementV1
  DTOWalletPaymentInstrument: DTOWalletPaymentInstrumentV2
x-toku-schema-names:
  ApiPaymentMethod_AssociatePaymentMethodResponse: AssociatePaymentMethodResponse
  ApiPaymentMethod_DTOPaymentMethodV7: PaymentMethod
  ApiPaymentTransaction_DTOTransactionV10: Transaction
  ApiPaymentTransaction_TransactionStatus: TransactionStatus
  ApiRenditionFile_BusinessDaysBeforeFilter: BusinessDaysBeforeFilter
  ApiRenditionFile_DaysBeforeFilter: DaysBeforeFilter
  ApiRenditionFile_DueDatesDaysFutureFilter: DueDatesDaysFutureFilter
  ApiRenditionFile_EntityRestrictions: EntityRestrictions
  ApiRenditionFile_NewestNInvoicesFilter: NewestNInvoicesFilter
  ApiRenditionFile_OldestNInvoicesFilter: OldestNInvoicesFilter
  CheckoutApi_AccountDetailsResponse: AccountDetailsResponse
  CheckoutApi_CheckoutSessionResponse: CheckoutSession
  ClientPaymentPortalBackend_CheckoutSessionResponse: CheckoutSessionResponse
  CollectionStrategist_InstitutionId: InstitutionId
  CollectionStrategist_SubTreeConfiguration: SubTreeConfiguration
  DTOAccountPaymentInstrumentV1: AccountPaymentInstrument
  DTOAggregatedTransactionV2: AggregatedTransaction
  DTOAppliedAdjustmentDocumentV1: AppliedAdjustmentDocument
  DTOBoletoPaymentInstrumentV2: BoletoPaymentInstrument
  DTOBrPaymentInstrumentV2: BrPaymentInstrument
  DTOCardPaymentInstrumentV1: CardPaymentInstrument
  DTOCardPaymentMethodV1: CardPaymentMethod
  DTOCashClPaymentInstrumentV1: CashClPaymentInstrument
  DTOCashMxPaymentInstrumentV1: CashMxPaymentInstrument
  DTOClPaymentInstrumentV2: ClPaymentInstrument
  DTOInvoiceV4: Invoice
  DTOMxPaymentInstrumentV3: MxPaymentInstrument
  DTOPacManagementPaymentInstrumentV1: PacManagementPaymentInstrument
  DTOPatpassPaymentInstrumentV1: PatpassPaymentInstrument
  DTOPaymentIntentV5: PaymentIntent
  DTOPixPaymentInstrumentV1: PixPaymentInstrument
  DTOPixPaymentMethodV1: PixPaymentMethod
  DTOReferencedPaymentMXInstrumentV1: ReferencedPaymentMXInstrument
  DTOTransferClPaymentInstrumentV2: TransferClPaymentInstrument
  DTOTransferMxPaymentInstrumentV1: TransferMxPaymentInstrument
  DTOUpdatedFieldsV1: UpdatedFields
  DTOWalletMovementV1: WalletMovement
  DTOWalletPaymentInstrumentV2: WalletPaymentInstrument
  GetCustomerResponse: Customer
  GetSubscriptionResponse: Subscription
  PayoutsBeneficiaryService_ApprovalFlowsStatus: ApprovalFlowsStatus
  PayoutsBeneficiaryService_Beneficiary: Beneficiary
  PayoutsBeneficiaryService_BeneficiaryAccount: BeneficiaryAccount
  PayoutsBeneficiaryService_BeneficiaryAccountVerification: BeneficiaryAccountVerification
  PayoutsBeneficiaryService_IdentityDocument: IdentityDocument
  PayoutsBeneficiaryService_VerificationStatus: VerificationStatus
  PayoutsDataIngestionService_DisbursementType: DisbursementType
  WebhookEndpointResponse: WebhookEndpoint
x-provenance:
  method: searched
  source: https://docs.trytoku.com/reference
  harvested: '2026-10-29'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://docs.trytoku.com/reference/associate_subscription.md
  - https://docs.trytoku.com/reference/associate_subscription_bulk.md
  - https://docs.trytoku.com/reference/bulk_inscriptions_public.md
  - https://docs.trytoku.com/reference/cancel_billing_document.md
  - https://docs.trytoku.com/reference/cancel_preauth_endpoint.md
  - https://docs.trytoku.com/reference/capture_preauth_endpoint.md
  - https://docs.trytoku.com/reference/change_subscription_status.md
  - https://docs.trytoku.com/reference/create_adjustment_document.md
  - https://docs.trytoku.com/reference/create_beneficiaries.md
  - https://docs.trytoku.com/reference/create_bulk_automatic_debit_payment_methods.md
  - https://docs.trytoku.com/reference/create_credit_note.md
  - https://docs.trytoku.com/reference/create_customer.md
  - https://docs.trytoku.com/reference/create_customer_billing_data.md
  - https://docs.trytoku.com/reference/create_customer_billing_data_bulk.md
  - https://docs.trytoku.com/reference/create_document.md
  - https://docs.trytoku.com/reference/create_external_transaction.md
  - https://docs.trytoku.com/reference/create_external_transactions.md
  - https://docs.trytoku.com/reference/create_handler.md
  - https://docs.trytoku.com/reference/create_intent.md
  - https://docs.trytoku.com/reference/create_invoice_billing_data.md
  - https://docs.trytoku.com/reference/create_m2m_access_token.md
  - https://docs.trytoku.com/reference/create_or_update_invoice.md
  - https://docs.trytoku.com/reference/create_or_update_subscription.md
  - https://docs.trytoku.com/reference/create_pacs.md
  - https://docs.trytoku.com/reference/create_pix_automatic_configuration.md
  - https://docs.trytoku.com/reference/create_ppd_billing_document.md
  - https://docs.trytoku.com/reference/create_ppd_complement_billing_document.md
  - https://docs.trytoku.com/reference/create_ppd_complement_from_wallet_movement_billing_document.md
  - https://docs.trytoku.com/reference/create_public_validator_execution.md
  - https://docs.trytoku.com/reference/create_pue_billing_document.md
  - https://docs.trytoku.com/reference/create_receipt.md
  - https://docs.trytoku.com/reference/create_referenced_payment_mx_reference_endpoint.md
  - https://docs.trytoku.com/reference/create_terminal.md
  - https://docs.trytoku.com/reference/create_transfer_clabe_account.md
  - https://docs.trytoku.com/reference/create_webhook_endpoint.md
  - https://docs.trytoku.com/reference/delete_customer.md
  - https://docs.trytoku.com/reference/delete_customer_collection_account_endpoint.md
  - https://docs.trytoku.com/reference/delete_external_transaction.md
  - https://docs.trytoku.com/reference/delete_external_transactions.md
  - https://docs.trytoku.com/reference/delete_invoice.md
  - https://docs.trytoku.com/reference/delete_pacs.md
  - https://docs.trytoku.com/reference/delete_payment_method.md
  - https://docs.trytoku.com/reference/delete_subscription.md
  - https://docs.trytoku.com/reference/delete_terminal.md
  - https://docs.trytoku.com/reference/download_pdf_for_transaction.md
  - https://docs.trytoku.com/reference/edit_customer.md
  - https://docs.trytoku.com/reference/edit_invoice.md
  - https://docs.trytoku.com/reference/edit_invoice_billing_data.md
  - https://docs.trytoku.com/reference/edit_subscription.md
  - https://docs.trytoku.com/reference/edit_webhook_endpoint.md
  - https://docs.trytoku.com/reference/enroll_carteira_boleto.md
  - https://docs.trytoku.com/reference/expire_checkout_session_endpoint.md
  - https://docs.trytoku.com/reference/expire_handler.md
  - https://docs.trytoku.com/reference/expire_webhook_sender_organization_configuration_endpoint.md
  - https://docs.trytoku.com/reference/external_boleto_initialize.md
  - https://docs.trytoku.com/reference/external_onetime_initialize.md
  - https://docs.trytoku.com/reference/generate_report.md
  - https://docs.trytoku.com/reference/get_account_verifications_by_batch.md
  - https://docs.trytoku.com/reference/get_adjustment_document.md
  - https://docs.trytoku.com/reference/get_bank_account_verification_by_id.md
  - https://docs.trytoku.com/reference/get_bank_account_verifications.md
  - https://docs.trytoku.com/reference/get_beneficiary_accounts.md
  - https://docs.trytoku.com/reference/get_billing_document.md
  - https://docs.trytoku.com/reference/get_checkout_session_endpoint_v2.md
  - https://docs.trytoku.com/reference/get_customer.md
  - https://docs.trytoku.com/reference/get_customer_billing_data.md
  - https://docs.trytoku.com/reference/get_customer_collection_account_endpoint.md
  - https://docs.trytoku.com/reference/get_customers.md
  - https://docs.trytoku.com/reference/get_handler.md
  - https://docs.trytoku.com/reference/get_invoice.md
  - https://docs.trytoku.com/reference/get_invoice_billing_data.md
  - https://docs.trytoku.com/reference/get_paginated_chargeable_invoices.md
  - https://docs.trytoku.com/reference/get_payment_method.md
  - https://docs.trytoku.com/reference/get_payment_method_by_id.md
  - https://docs.trytoku.com/reference/get_payment_methods.md
  - https://docs.trytoku.com/reference/get_pix_automatic_configuration.md
  - https://docs.trytoku.com/reference/get_public_transactions.md
  - https://docs.trytoku.com/reference/get_receipt.md
  - https://docs.trytoku.com/reference/get_report_columns.md
  - https://docs.trytoku.com/reference/get_signed_document_url.md
  - https://docs.trytoku.com/reference/get_subscription.md
  - https://docs.trytoku.com/reference/get_subscriptions.md
  - https://docs.trytoku.com/reference/get_terminal.md
  - https://docs.trytoku.com/reference/get_transaction.md
  - https://docs.trytoku.com/reference/get_transaction_data_for_refund.md
  - https://docs.trytoku.com/reference/get_transaction_fees_public.md
  - https://docs.trytoku.com/reference/get_transfer_clabe_account.md
  - https://docs.trytoku.com/reference/get_webhook_endpoint.md
  - https://docs.trytoku.com/reference/get_webhook_endpoints.md
  - https://docs.trytoku.com/reference/get_webhook_sender_organization_configuration_endpoint.md
  - https://docs.trytoku.com/reference/ingest_payout_request_input.md
  - https://docs.trytoku.com/reference/initialize_enrollment_pix.md
  - https://docs.trytoku.com/reference/initialize_push_notification_enrollment.md
  - https://docs.trytoku.com/reference/list_adjustment_documents.md
  - https://docs.trytoku.com/reference/list_customer_invoices.md
  - https://docs.trytoku.com/reference/list_invoices.md
  - https://docs.trytoku.com/reference/list_invoices_by_customer.md
  - https://docs.trytoku.com/reference/list_payout_request_items.md
  - https://docs.trytoku.com/reference/list_payouts.md
  - https://docs.trytoku.com/reference/list_subject_consents.md
  - https://docs.trytoku.com/reference/list_terminals.md
  - https://docs.trytoku.com/reference/lookup_customer.md
  - https://docs.trytoku.com/reference/lookup_invoice.md
  - https://docs.trytoku.com/reference/lookup_subscription.md
  - https://docs.trytoku.com/reference/open_checkout_session_endpoint.md
  - https://docs.trytoku.com/reference/patch_beneficiary_account_data.md
  - https://docs.trytoku.com/reference/patch_beneficiary_account_external_id.md
  - https://docs.trytoku.com/reference/patch_beneficiary_metadata.md
  - https://docs.trytoku.com/reference/patch_webhook_sender_organization_configuration_endpoint.md
  - https://docs.trytoku.com/reference/pos_charge_endpoint.md
  - https://docs.trytoku.com/reference/post_customer_collection_account_endpoint.md
  - https://docs.trytoku.com/reference/post_webhook_sender_organization_configuration_endpoint.md
  - https://docs.trytoku.com/reference/public_available_institutions.md
  - https://docs.trytoku.com/reference/public_start_create_cash_mx_reference.md
  - https://docs.trytoku.com/reference/public_update_checkout_session_endpoint.md
  - https://docs.trytoku.com/reference/refund_invoice_public.md
  - https://docs.trytoku.com/reference/refund_transaction_public.md
  - https://docs.trytoku.com/reference/soft_delete_pix_automatic_configuration.md
  - https://docs.trytoku.com/reference/subscriptions_by_customer.md
  - https://docs.trytoku.com/reference/undo_debt_reconciliation_by_invoice_endpoint.md
  - https://docs.trytoku.com/reference/update_adjustment_document.md
  - https://docs.trytoku.com/reference/update_customer_billing_data.md
  - https://docs.trytoku.com/reference/update_external_transaction.md
  - https://docs.trytoku.com/reference/update_external_transactions.md
  - https://docs.trytoku.com/reference/update_pix_automatic_configuration.md
  - https://docs.trytoku.com/reference/update_terminal.md
  - https://docs.trytoku.com/reference/upload_external_pdf.md
  - https://docs.trytoku.com/reference/validate_handler.md
  - https://docs.trytoku.com/reference/verify_bank_account.md
  - https://docs.trytoku.com/reference/verify_public_bulk_bank_accounts.md
  - https://docs.trytoku.com/reference/void_invoice.md
  merge:
    pages: 131
    deduped: 757
    conflicts_kept_first: 0