# Consulta de Protesto SP — CENPROT por CPF/CNPJ (`paulovitor18/protesto-sp-consulta`) Actor

Consulte protesto de títulos por CPF ou CNPJ na base oficial do CENPROT SP (IEPTB). Retorna se constam protestos, cartórios, comarcas e quantidade. Para análise de crédito, inadimplência, risco e KYB. Pague por resultado.

- **URL**: https://apify.com/paulovitor18/protesto-sp-consulta.md
- **Developed by:** [MoreLock](https://apify.com/paulovitor18) (community)
- **Categories:** Lead generation, Business, Developer tools
- **Stats:** 3 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$400.00 / 1,000 consulta de protesto entregues

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Consulta de Protesto SP — CENPROT por CPF/CNPJ

Consulte protestos de títulos por **CPF ou CNPJ** direto na base oficial do **CENPROT SP** (Cartórios de Protesto do Estado de São Paulo). Descubra se **constam protestos**, em quais **cartórios** e **comarcas**, e a **quantidade** — em JSON estruturado, pronto para análise de risco de crédito, cobrança e KYB (verificação de fornecedores).

### Visão geral

Este Actor automatiza a consulta gratuita e anônima do [protestosp.com.br](https://www.protestosp.com.br/consulta-de-protesto). Você informa uma lista de documentos; o Actor detecta CPF ou CNPJ automaticamente, consulta cada um na base do IEPTB-SP e devolve **um item por documento** no dataset, com a situação de protesto e o detalhamento por cartório.

Ideal para **análise de crédito** e **due diligence**: checar a saúde financeira e a inadimplência de clientes, fornecedores e parceiros antes de conceder crédito, prazo ou fechar contrato — sem abrir o site manualmente, documento por documento. O protesto é um dos sinais mais diretos de inadimplência de uma pessoa ou empresa.

### Funcionalidades

- **Detecção automática** de CPF (11 dígitos) e CNPJ (14 dígitos) — com ou sem pontuação
- **Dois resultados cobráveis:** positivo (constam protestos) e negativo (nada consta) — ambos entram no dataset. Documento inválido ou consulta que falha fica só no log, com motivo honesto, e não é cobrado (nunca inventa dado)
- **Tabela paginada de cartórios lida por completo** (estado, comarca, cartório, quantidade) — percorre todas as páginas do resultado
- **Protocolo oficial** da consulta e **abrangência** da base em SP
- **Proxy residencial BR** embutido (a origem bloqueia data center) e IP novo por consulta
- Saída em JSON limpo, pronta pra planilha, CRM ou fluxo de dados

### Exemplo de entrada

```json
{
  "documentos": ["47960950000121", "11.222.333/0001-81", "390.533.447-05"],
  "maxItems": 100
}
```

### Exemplo de saída

```json
{
  "documento": "47960950000121",
  "tipo": "CNPJ",
  "temProtesto": true,
  "qtdeTotal": 115,
  "valorTotal": null,
  "cartorios": [
    { "estado": "SP", "comarca": "BARUERI", "cartorio": "1 TABELIAO DE NOTAS E DE PROTESTO DE LETRAS E TITULOS", "qtde": 4, "valor": null },
    { "estado": "SP", "comarca": "FRANCA", "cartorio": "2 TABELIAO DE NOTAS E DE PROTESTO DE LETRAS E TITULOS", "qtde": 14, "valor": null }
  ],
  "protocolo": "0147603092",
  "abrangencia": "100%",
  "paginasLidas": 5,
  "resultadoUrl": "https://protestosp.com.br/consulta-de-protesto/Positivo",
  "status": "sucesso",
  "motivo": null,
  "dataConsulta": "2026-07-05T08:30:58.168Z"
}
```

Documento limpo retorna `temProtesto: false`, `qtdeTotal: 0` e `resultadoUrl` terminando em `/Negativo`.

### Tabela de parâmetros

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `documentos` | Lista de textos | Sim | CPF/CNPJ, um por linha. Com ou sem pontuação. |
| `maxItems` | Número | Não | Limite de documentos por execução (controle de custo). Padrão 100. |
| `useApifyProxy` | Sim/Não | Não | Proxy residencial BR. Obrigatório — data center é bloqueado na origem. Padrão `true`. |
| `proxyCountry` | Texto | Não | País do proxy residencial. Manter `BR`. |

#### Campos do resultado

| Campo | Descrição |
|---|---|
| `documento` / `tipo` | Documento consultado (só dígitos) e tipo detectado (CPF/CNPJ/INVALIDO). |
| `temProtesto` | `true` (constam protestos) ou `false` (nada consta). Todo item do dataset é um desses dois resultados. |
| `qtdeTotal` | Soma das quantidades de protesto em todos os cartórios. |
| `valorTotal` | Valor total quando exposto (a consulta gratuita traz só quantidade → normalmente `null`). |
| `cartorios[]` | Estado, comarca, cartório e quantidade de protestos por cartório. |
| `protocolo` | Número de protocolo oficial da consulta no CENPROT. |
| `abrangencia` | Percentual de abrangência da base em SP (ex.: `100%`). |
| `status` / `motivo` | Itens do dataset trazem sempre `status: "sucesso"` (resultado entregue). Documentos inválidos (`invalido`) e falhas (`erro`) não entram no dataset — só no log da execução, com o `motivo`. |

### Dicas

- Envie os documentos em **lote** — um por linha no campo `documentos`. O Actor consulta cada um com IP e sessão limpos, evitando o bloqueio por consultas repetidas do CENPROT.
- **Com ou sem máscara funciona:** `47.960.950/0001-21` e `47960950000121` dão o mesmo resultado.
- Use `maxItems` para **teto de custo** em bases grandes.
- Todo item do dataset é um resultado entregue (`status: "sucesso"`), positivo ou negativo. Documentos inválidos e consultas que falham ficam só no log da execução, com o `motivo` — sem entrar no dataset e sem cobrança.
- A consulta cobre **os últimos 5 anos no estado de SP**. Não substitui a certidão oficial de protesto.

### Casos de uso

- **Análise de risco de crédito** — cheque protestos antes de conceder crédito, prazo ou limite a um cliente PJ/PF.
- **KYB e entrada de fornecedores** — due diligence de CNPJ na etapa de cadastro, cruzando protesto com outros sinais.
- **Cobrança e recuperação** — priorize a carteira por situação de protesto; foque nos casos com mais títulos protestados.
- **Antifraude e prevenção** — combine protesto com dados cadastrais para pontuar o risco de um documento.
- **Monitoramento periódico** — reconsulte uma base de clientes de tempos em tempos e detecte novos protestos.
- **Pesquisa e compliance** — levante a situação de protesto de uma lista de empresas para relatórios internos.

### FAQ

**Como leio o resultado de cada documento?**
Olhe o campo `temProtesto`: `true` constam protestos (confira `qtdeTotal` e `cartorios[]`), `false` nada consta. Os dois resultados — positivo e negativo — vêm sempre no mesmo formato no dataset e nunca quebram a execução. Documentos inválidos ou consultas que falham não entram no dataset; aparecem só no log da execução, com o motivo.

**A consulta é oficial?**
Os dados vêm da base do IEPTB-SP (Instituto de Estudos de Protesto de Títulos do Brasil — Seção São Paulo), a mesma da consulta gratuita pública. É informativa e **não substitui a certidão oficial** de protesto.

**Cobre o Brasil inteiro?**
Não. Cobre **protestos registrados no estado de São Paulo** (CENPROT-SP), abrangência dos últimos 5 anos. O campo `abrangencia` indica a cobertura da base.

**A consulta traz o valor de cada protesto?**
A consulta gratuita do CENPROT expõe a **quantidade** de protestos por cartório, não o valor individual. Por isso `valor`/`valorTotal` costumam vir `null`. O Actor não inventa valor.

**Funciona para CPF e CNPJ?**
Sim. O tipo é detectado automaticamente pelo comprimento (11 = CPF, 14 = CNPJ). Documento fora desses formatos é marcado como `invalido` e registrado no log da execução com o motivo — não entra no dataset e não é cobrado, sem quebrar a execução.

**Por que precisa de proxy residencial?**
A origem bloqueia IPs de data center e detecta automação. O Actor usa proxy **residencial brasileiro** e um IP/sessão novos a cada documento para que cada consulta pareça um acesso legítimo.

**Quanto custa por consulta?**
Você paga por documento com resultado entregue — `positivo` (constam protestos) ou `negativo` (nada consta) — a US$ 0,40 cada (Pay per result). Veja a seção Preço abaixo. Documentos inválidos ou consultas que falham NÃO entram no dataset e NÃO são cobrados: aparecem só no log da execução, com o motivo.

### Preço

**Pague por resultado (Pay per result).** Você paga por documento com resultado entregue — protesto encontrado (`positivo`) ou nada consta (`negativo`), US$ 0,40 cada. Documentos inválidos (`invalido`) ou consultas que falham (`erro`) NÃO entram no dataset e NÃO são cobrados — aparecem apenas no log. Sem assinatura, sem mínimo mensal.

Os custos de plataforma (computação + proxy residencial) já entram no valor de US$ 0,40 por resultado entregue.

### Actors relacionados

Da mesma suíte de dados brasileiros (100% PT-native):

- **[Consulta CNPJ em Lote — Dados da Receita Federal](https://apify.com/paulovitor18/cnpj-bulk-lookup)** — razão social, sócios, CNAE, endereço e situação cadastral por CNPJ.
- **[Reclame Aqui Scraper — Reputação de Empresas BR](https://apify.com/paulovitor18/reclameaqui-scraper)** — nota, reclamações e % de resolução no Reclame Aqui.
- **[Brazil Due Diligence — CNPJ + Reclame Aqui](https://apify.com/paulovitor18/brazil-company-due-diligence)** — cadastro da Receita + reputação do consumidor num só item, casado por CNPJ.

Combine este Actor de protesto com o de CNPJ para um dossiê de risco completo por documento.

### Changelog

- **0.1** (2026-07) — Versão inicial. Consulta CPF/CNPJ no CENPROT SP, ramos positivo/negativo/inválido, tabela de cartórios paginada, proxy residencial BR com IP por consulta.

### Contato e problemas

Encontrou um bug ou quer um campo novo? Abra uma **Issue** na página do Actor. Retorno rápido.

# Actor input Schema

## `documentos` (type: `array`):

Um documento por linha. CPF (11 dígitos) e CNPJ (14 dígitos) são detectados automaticamente. Com ou sem pontuação, os dois funcionam.

## `maxItems` (type: `integer`):

Para após consultar esta quantidade de documentos (controle de custo — a consulta usa proxy residencial).

## `useApifyProxy` (type: `boolean`):

A origem bloqueia IP de datacenter — o proxy residencial BR é obrigatório para a consulta funcionar. Deixe ligado.

## `proxyCountry` (type: `string`):

Código do país do proxy residencial. A origem é brasileira; mantenha BR.

## Actor input object example

```json
{
  "documentos": [
    "47960950000121"
  ],
  "maxItems": 100,
  "useApifyProxy": true,
  "proxyCountry": "BR"
}
```

# Actor output Schema

## `resultados` (type: `string`):

Itens gerados por esta execucao, no dataset default do run.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "documentos": [
        "47960950000121"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("paulovitor18/protesto-sp-consulta").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "documentos": ["47960950000121"] }

# Run the Actor and wait for it to finish
run = client.actor("paulovitor18/protesto-sp-consulta").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "documentos": [
    "47960950000121"
  ]
}' |
apify call paulovitor18/protesto-sp-consulta --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=paulovitor18/protesto-sp-consulta",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/SHBY1ULWAOOyrbj3n/builds/gtR2XSqVHRx3XV8vZ/openapi.json