> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base39.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Protestos

> Retorna os protestos, valores informados e cartórios. Ausência de registros não equivale a aprovação de crédito.



## OpenAPI

````yaml /api-reference/openapi.json post /v3/queries/list_protests
openapi: 3.1.2
info:
  title: API Base39
  version: 3.0.0
  description: >-
    Contratos canônicos Base39 compartilhados entre API e MCP. Campos de negócio
    em snake_case. Valores financeiros em centavos de BRL; montantes de dados
    consultados são textos decimais que preservam a precisão informada. Datas
    cadastrais usam YYYY-MM-DD. As consultas podem debitar o saldo; a repetição
    equivalente na organização é gratuita até meia-noite de São Paulo. O extrato
    informa o consumo. Campos ausentes não significam zero nem aprovação de
    crédito.
servers:
  - url: https://mcp.base39.com.br
    description: API pública Base39, independente do caminho do protocolo MCP.
security:
  - bearer_auth: []
tags:
  - name: Consultas
    description: Consultas canônicas de dados.
  - name: Modelos de relatórios
    description: Modelos de relatório e seus recursos na organização autenticada.
  - name: Saldo e pagamentos
    description: Saldo e extrato da organização autenticada.
paths:
  /v3/queries/list_protests:
    post:
      tags:
        - Consultas
      summary: Protestos
      description: >-
        Retorna os protestos, valores informados e cartórios. Ausência de
        registros não equivale a aprovação de crédito.
      operationId: list_protests
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/list_protests_request'
            examples:
              requisicao:
                summary: Parâmetros da consulta.
                value:
                  document: '00000000000191'
      responses:
        '200':
          description: >-
            Objeto ou coleção Base39; coleções integrais não possuem
            next_cursor.
          headers:
            Request-Id:
              description: Identificador da requisição para suporte e rastreamento.
              schema:
                type: string
              example: req_example
            Cache-Control:
              description: >-
                As respostas autenticadas não devem ser armazenadas por serviços
                HTTP compartilhados.
              schema:
                type: string
                const: no-store
              example: no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list_protests_response'
              examples:
                resposta:
                  summary: Exemplo de resposta Base39.
                  value:
                    object: list
                    data:
                      - id: protest_ef3df8c186edf6473f5aa975
                        object: protest
                        document: '00000000000191'
                        date: '2024-10-24'
                        amount: '14699.44'
                        city: São Paulo
                        city_code: '3550308'
                        state: SP
                      - id: protest_511c12270c45635a8338fe4b
                        object: protest
                        document: '00000000000191'
                        date: '2024-09-27'
                        amount: '29708.44'
                        city: São Paulo
                        city_code: '3550308'
                        state: SP
                      - id: protest_e3db0e286f82c445b04bf18b
                        object: protest
                        document: '00000000000191'
                        date: '2023-11-10'
                        amount: '4679.83'
                        city: São Paulo
                        city_code: '3550308'
                        state: SP
                    has_records: true
                    total_amount: '82557.76'
        '400':
          $ref: '#/components/responses/error_400'
        '401':
          $ref: '#/components/responses/error_401'
        '402':
          $ref: '#/components/responses/error_402'
        '403':
          $ref: '#/components/responses/error_403'
        '404':
          $ref: '#/components/responses/error_404'
        '405':
          $ref: '#/components/responses/error_405'
        '409':
          $ref: '#/components/responses/error_409'
        '413':
          $ref: '#/components/responses/error_413'
        '415':
          $ref: '#/components/responses/error_415'
        '422':
          $ref: '#/components/responses/error_422'
        '425':
          $ref: '#/components/responses/error_425'
        '502':
          $ref: '#/components/responses/error_502'
        '503':
          $ref: '#/components/responses/error_503'
        '504':
          $ref: '#/components/responses/error_504'
components:
  schemas:
    list_protests_request:
      $schema: https://json-schema.org/draft/2020-12/schema
      type: object
      properties:
        document:
          description: CPF ou CNPJ completo, com ou sem pontuação.
          title: CPF ou CNPJ
          type: string
          pattern: >-
            ^(?:\d{11}|\d{3}\.\d{3}\.\d{3}-\d{2}|[0-9A-Za-z]{12}\d{2}|[0-9A-Za-z]{2}\.[0-9A-Za-z]{3}\.[0-9A-Za-z]{3}\/[0-9A-Za-z]{4}-\d{2})$
      required:
        - document
      additionalProperties: false
    list_protests_response:
      $schema: https://json-schema.org/draft/2020-12/schema
      type: object
      properties:
        object:
          type: string
          const: list
          description: Coleção de objetos Base39.
        data:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                minLength: 1
                description: Identificador opaco e estável do objeto Base39.
              object:
                type: string
                const: protest
                description: 'Tipo do objeto: protesto.'
              document:
                type: string
                minLength: 1
                description: CPF ou CNPJ informado pela fonte; pode estar mascarado.
              date:
                type: string
                format: date
                pattern: >-
                  ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
                description: Data do protesto, em YYYY-MM-DD.
              amount:
                type: string
                pattern: ^-?\d+(?:\.\d+)?$
                description: >-
                  Valor protestado em reais, como texto decimal, preservando a
                  precisão informada.
              city:
                type: string
                description: Município do cartório.
              city_code:
                type: string
                description: Código do município informado pela fonte.
              state:
                type: string
                description: Unidade federativa do cartório.
            required:
              - id
              - object
            additionalProperties: false
          description: Objetos da coleção.
        next_cursor:
          description: Cursor opaco da próxima página; ausente ao final.
          type: string
        has_records:
          type: boolean
          description: Indicação explícita de protestos na fonte.
        total_amount:
          type: string
          pattern: ^-?\d+(?:\.\d+)?$
          description: >-
            Total protestado em reais, como texto decimal, preservando a
            precisão informada.
      required:
        - object
        - data
        - has_records
      additionalProperties: false
    error:
      $schema: https://json-schema.org/draft/2020-12/schema
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
                - invalid_request_error
                - authentication_error
                - permission_error
                - balance_error
                - api_error
              description: Categoria estável da falha.
            code:
              type: string
              pattern: ^[a-z][a-z0-9_]*$
              description: Código estável da falha para tratamento pela aplicação.
            message:
              type: string
              description: Descrição da falha em português brasileiro.
            param:
              description: Parâmetro relacionado à falha, quando aplicável.
              type: string
          required:
            - type
            - code
            - message
          additionalProperties: false
          description: Falha que impediu a operação.
      required:
        - error
      additionalProperties: false
  responses:
    error_400:
      description: Parâmetros inválidos.
      headers:
        Request-Id:
          description: Identificador da requisição para suporte e rastreamento.
          schema:
            type: string
          example: req_example
        Cache-Control:
          description: >-
            As respostas autenticadas não devem ser armazenadas por serviços
            HTTP compartilhados.
          schema:
            type: string
            const: no-store
          example: no-store
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          examples:
            erro:
              summary: Parâmetros inválidos.
              value:
                error:
                  type: invalid_request_error
                  code: invalid_request
                  message: Revise os parâmetros da requisição.
    error_401:
      description: Autenticação ausente ou inválida.
      headers:
        Request-Id:
          description: Identificador da requisição para suporte e rastreamento.
          schema:
            type: string
          example: req_example
        Cache-Control:
          description: >-
            As respostas autenticadas não devem ser armazenadas por serviços
            HTTP compartilhados.
          schema:
            type: string
            const: no-store
          example: no-store
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          examples:
            erro:
              summary: Autenticação ausente ou inválida.
              value:
                error:
                  type: authentication_error
                  code: unauthorized
                  message: Autenticação necessária.
    error_402:
      description: Saldo insuficiente para a consulta.
      headers:
        Request-Id:
          description: Identificador da requisição para suporte e rastreamento.
          schema:
            type: string
          example: req_example
        Cache-Control:
          description: >-
            As respostas autenticadas não devem ser armazenadas por serviços
            HTTP compartilhados.
          schema:
            type: string
            const: no-store
          example: no-store
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          examples:
            erro:
              summary: Saldo insuficiente para a consulta.
              value:
                error:
                  type: balance_error
                  code: insufficient_balance
                  message: Saldo insuficiente para realizar a consulta.
    error_403:
      description: Acesso não permitido.
      headers:
        Request-Id:
          description: Identificador da requisição para suporte e rastreamento.
          schema:
            type: string
          example: req_example
        Cache-Control:
          description: >-
            As respostas autenticadas não devem ser armazenadas por serviços
            HTTP compartilhados.
          schema:
            type: string
            const: no-store
          example: no-store
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          examples:
            erro:
              summary: Acesso não permitido.
              value:
                error:
                  type: permission_error
                  code: forbidden
                  message: Acesso não permitido.
    error_404:
      description: Operação ou resultado não encontrado.
      headers:
        Request-Id:
          description: Identificador da requisição para suporte e rastreamento.
          schema:
            type: string
          example: req_example
        Cache-Control:
          description: >-
            As respostas autenticadas não devem ser armazenadas por serviços
            HTTP compartilhados.
          schema:
            type: string
            const: no-store
          example: no-store
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          examples:
            erro:
              summary: Operação ou resultado não encontrado.
              value:
                error:
                  type: invalid_request_error
                  code: resource_not_found
                  message: Nenhum registro encontrado.
    error_405:
      description: Método HTTP não permitido.
      headers:
        Request-Id:
          description: Identificador da requisição para suporte e rastreamento.
          schema:
            type: string
          example: req_example
        Cache-Control:
          description: >-
            As respostas autenticadas não devem ser armazenadas por serviços
            HTTP compartilhados.
          schema:
            type: string
            const: no-store
          example: no-store
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          examples:
            erro:
              summary: Método HTTP não permitido.
              value:
                error:
                  type: invalid_request_error
                  code: method_not_allowed
                  message: Método HTTP não permitido para esta operação.
    error_409:
      description: Consulta equivalente em andamento.
      headers:
        Request-Id:
          description: Identificador da requisição para suporte e rastreamento.
          schema:
            type: string
          example: req_example
        Cache-Control:
          description: >-
            As respostas autenticadas não devem ser armazenadas por serviços
            HTTP compartilhados.
          schema:
            type: string
            const: no-store
          example: no-store
        Retry-After:
          description: Tempo em segundos antes de uma nova tentativa.
          schema:
            type: integer
            minimum: 1
          example: 2
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          examples:
            erro:
              summary: Consulta equivalente em andamento.
              value:
                error:
                  type: invalid_request_error
                  code: query_in_progress
                  message: Uma consulta equivalente está em andamento.
    error_413:
      description: Corpo da requisição acima do limite permitido para a operação.
      headers:
        Request-Id:
          description: Identificador da requisição para suporte e rastreamento.
          schema:
            type: string
          example: req_example
        Cache-Control:
          description: >-
            As respostas autenticadas não devem ser armazenadas por serviços
            HTTP compartilhados.
          schema:
            type: string
            const: no-store
          example: no-store
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          examples:
            erro:
              summary: Corpo da requisição acima do limite permitido para a operação.
              value:
                error:
                  type: invalid_request_error
                  code: request_too_large
                  message: A requisição excedeu o limite permitido.
    error_415:
      description: O corpo deve usar application/json.
      headers:
        Request-Id:
          description: Identificador da requisição para suporte e rastreamento.
          schema:
            type: string
          example: req_example
        Cache-Control:
          description: >-
            As respostas autenticadas não devem ser armazenadas por serviços
            HTTP compartilhados.
          schema:
            type: string
            const: no-store
          example: no-store
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          examples:
            erro:
              summary: O corpo deve usar application/json.
              value:
                error:
                  type: invalid_request_error
                  code: unsupported_media_type
                  message: Envie o corpo como application/json.
    error_422:
      description: Integração ou parâmetros específicos indisponíveis.
      headers:
        Request-Id:
          description: Identificador da requisição para suporte e rastreamento.
          schema:
            type: string
          example: req_example
        Cache-Control:
          description: >-
            As respostas autenticadas não devem ser armazenadas por serviços
            HTTP compartilhados.
          schema:
            type: string
            const: no-store
          example: no-store
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          examples:
            erro:
              summary: Integração ou parâmetros específicos indisponíveis.
              value:
                error:
                  type: invalid_request_error
                  code: integration_not_configured
                  message: A integração necessária não está configurada na organização.
    error_425:
      description: Resultado temporariamente indisponível para leitura.
      headers:
        Request-Id:
          description: Identificador da requisição para suporte e rastreamento.
          schema:
            type: string
          example: req_example
        Cache-Control:
          description: >-
            As respostas autenticadas não devem ser armazenadas por serviços
            HTTP compartilhados.
          schema:
            type: string
            const: no-store
          example: no-store
        Retry-After:
          description: Tempo em segundos antes de uma nova tentativa.
          schema:
            type: integer
            minimum: 1
          example: 2
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          examples:
            erro:
              summary: Resultado temporariamente indisponível para leitura.
              value:
                error:
                  type: invalid_request_error
                  code: cache_propagating
                  message: O resultado está sendo disponibilizado. Tente novamente.
    error_502:
      description: Resposta inválida ao executar a consulta.
      headers:
        Request-Id:
          description: Identificador da requisição para suporte e rastreamento.
          schema:
            type: string
          example: req_example
        Cache-Control:
          description: >-
            As respostas autenticadas não devem ser armazenadas por serviços
            HTTP compartilhados.
          schema:
            type: string
            const: no-store
          example: no-store
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          examples:
            erro:
              summary: Resposta inválida ao executar a consulta.
              value:
                error:
                  type: api_error
                  code: query_unavailable
                  message: Não foi possível concluir a consulta.
    error_503:
      description: Serviço temporariamente indisponível.
      headers:
        Request-Id:
          description: Identificador da requisição para suporte e rastreamento.
          schema:
            type: string
          example: req_example
        Cache-Control:
          description: >-
            As respostas autenticadas não devem ser armazenadas por serviços
            HTTP compartilhados.
          schema:
            type: string
            const: no-store
          example: no-store
        Retry-After:
          description: Tempo em segundos antes de uma nova tentativa.
          schema:
            type: integer
            minimum: 1
          example: 2
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          examples:
            erro:
              summary: Serviço temporariamente indisponível.
              value:
                error:
                  type: api_error
                  code: query_unavailable
                  message: Não foi possível concluir a consulta.
    error_504:
      description: Prazo de execução excedido.
      headers:
        Request-Id:
          description: Identificador da requisição para suporte e rastreamento.
          schema:
            type: string
          example: req_example
        Cache-Control:
          description: >-
            As respostas autenticadas não devem ser armazenadas por serviços
            HTTP compartilhados.
          schema:
            type: string
            const: no-store
          example: no-store
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          examples:
            erro:
              summary: Prazo de execução excedido.
              value:
                error:
                  type: api_error
                  code: query_timeout
                  message: A consulta excedeu o prazo de execução.
  securitySchemes:
    bearer_auth:
      type: http
      scheme: bearer
      description: >-
        Credencial OAuth da Base39 com os escopos profile e user:org:read, ou
        chave de API pertencente à organização. A organização e o autor são
        obtidos da autenticação.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.