Confira o preço antes de iniciar a pesquisa. Envie POST /v1/orcamento/visualizacao-matricula com os dados que deseja pesquisar. O orçamento informa o valor e a disponibilidade, sem cobrar.
Registro de Imóveis
Visualização de Matrícula
O inteiro conteúdo de uma matrícula de imóvel, direto do registro de imóveis, em minutos.
/v1/consultas/visualizacao-matricula
v1
Tempo típico
não medido
Preço
R$ 24,83
por consulta
Visão geral
Devolve o conteúdo da matrícula do imóvel no registro de imóveis: quem é o titular, os ônus e gravames averbados, penhoras, hipotecas, área, confrontações e a cadeia de atos. É o documento que responde "o que está registrado sobre este imóvel".
Atenção: É fonte de DADO, não certidão. O PDF sai do sistema do cartório, mas NÃO tem fé pública nem validade declarada — não é oponível a terceiros e não serve para instruir processo ou fechar negócio. Serve para due diligence, análise e decisão. Quem tem fé pública é a Certidão de Inteiro Teor, que é outro produto, mais caro e mais lento.
O endereçamento é pelo IMÓVEL, não pela pessoa: matrícula + cartório + município + UF. Se você só tem o CPF/CNPJ do titular e não sabe onde ele tem imóvel, comece pela Pesquisa Prévia de Bens — ela faz a busca reversa e devolve exatamente estes quatro campos.
Antes de começar
Cobrança, idempotência e leitura do resultado. Leia antes da primeira chamada.
Custa dinheiro se você ignorar 5
Não tem fé pública — e a diferença é jurídica, não de formato
A visualização entrega o MESMO conteúdo da certidão de inteiro teor, e é aí que mora o risco: o PDF parece um documento oficial, mas não é assinado digitalmente pelo oficial do registro e não declara validade.
Não use para instruir processo, registrar ato, fechar financiamento ou provar titularidade perante terceiro. Para isso existe a Certidão de Inteiro Teor (/v1/consultas/certidao-inteiro-teor), que é o mesmo conteúdo com assinatura do cartório — e custa cerca de 3,3× mais, porque o emolumento é outro.
Use a visualização para o que ela é boa: due diligence, triagem, decisão interna, conferência antes de pedir a certidão paga.
Cada chamada gasta emolumento de cartório, e não tem desfazer
O preço não é tarifa nossa: é o emolumento que o registro de imóveis cobra, fixado por tabela estadual, mais a nossa margem. Ele sai da nossa conta pré-paga no portal no momento do pedido, e ato registral não estorna.
Basta enviar token e dados. Cada POST inicia uma nova consulta, mesmo para o mesmo imóvel. As travas internas protegem o processamento do pedido aceito. Para acompanhar, use GET no protocolo recebido.
Cuidado com retry automático de biblioteca HTTP: um timeout do SEU lado não significa que o pedido não saiu do nosso — significa que você não viu a resposta. Confira o histórico antes de reenviar; se enviou uma chave opcional, mantenha a MESMA chave.
O preço só se sabe orçando — varia por cartório
Não existe tabela nacional. O emolumento muda por estado e por serventia, então o valor publicado no card é PISO ("a partir de"), nunca o preço do seu pedido.
Use POST /v1/orcamento/visualizacao-matricula com os mesmos quatro campos do imóvel: ele cota na origem, não cobra e devolve preco.total com estimado: true. É o único número que bate com a fatura.
Atenção: Cartório que não cota não é vendido. Município escrito errado, serventia inexistente ou tabela indisponível fazem a consulta responder 602 (indisponível) SEM chamar a origem e SEM cobrar — em vez de protocolar um pedido que ninguém sabe quanto custa.
O bloqueio de pedido repetido é da CONTA, não da sua
O serviço de registro de imóveis recusa um segundo pedido da mesma matrícula, no mesmo cartório, enquanto o anterior estiver vigente. A recusa vem faturada pela origem e não entrega documento nenhum — por isso nós barramos antes, e a resposta é 602 sem cobrança.
Atenção: A plataforma opera com UMA conta no portal para toda a carteira. Isso significa que um pedido feito por outro cliente nosso, do mesmo imóvel, bloqueia o seu enquanto estiver vigente. A janela em uso é de 7 dias, e ela é estimativa: o portal não devolve o prazo real de vigência.
A resposta diz a data a partir da qual o pedido volta a ser aceito. Se o volume do seu produto tornar isso frequente, o caminho é uma credencial dedicada no portal — fale com o suporte antes de escalar.
Finalidade é declaração legal
O campo imovel_finalidade é declarado AO CARTÓRIO em nome de quem pede. Não é filtro de busca nem preferência técnica.
Atenção: O valor 3 afirma que o solicitante É titular de direito real registrado sobre o imóvel. Due diligence de imóvel de terceiro não é titularidade — mandar 3 ali é declaração falsa feita em nome do seu cliente. Por isso o padrão é 2, e o 3 só vai à origem se você o enviar explicitamente.
Vale saber antes de integrar 4
Quatro maneiras de endereçar — e a ambiguidade é recusada, não chutada
O pedido vai a UMA serventia. Diga qual por um destes caminhos, nesta ordem de precedência: imovel_cartorio com imovel_municipio e imovel_uf (o contrato de sempre); imovel_cns, sozinho; um CNM em imovel_matricula, que já carrega o CNS da serventia; ou imovel_municipio + imovel_uf quando o município tem UMA só serventia medida. Nos três últimos, nós preenchemos os campos do cartório e o POST /v1/orcamento enxerga exatamente o mesmo endereço que a consulta vai usar.
Atenção: Quando não dá para decidir — município com várias serventias, CNS que não achamos, serventia sem número de ordem no portal —, a resposta é 602 SEM cobrança e errors[] diz o que fazer: o campo que falta, ou o motivo com os candidatos medidos quando o endereço veio completo e ainda assim não fecha. Não escolhemos por você, porque o emolumento do cartório errado não volta. Para ver as serventias de uma cidade, cada uma com o seu imovel_cartorio e a grafia exata de imovel_municipio para copiar, chame GET /v1/cartorios: é gratuito e não fala com o cartório.
O município é o da SERVENTIA, não o do imóvel, e não alargamos a busca para o vizinho: um imóvel de Fernando Prestes é registrado em Taquaritinga. Se você só tem o imóvel ou o dono, comece pela Pesquisa Prévia de Bens, que devolve o CNS e a matrícula — e com o CNS o endereçamento acaba.
O link da origem morre em 7 dias — use o nosso
A URL do PDF que o cartório devolve é assinada e expira: medido em 2026-08-11, validade de 7 dias. Guardar essa URL e abrir semanas depois entrega link morto de um documento que já custou emolumento.
Nós arquivamos os bytes na entrega. Use documento_url da resposta — ela aponta para o nosso arquivo, autentica com o mesmo Bearer e não expira. site_receipts[] continua trazendo a URL da origem para conferência.
A resposta é 202: o pedido roda na fila
O portal do cartório leva de dezenas de segundos a poucos minutos, e segurar a conexão até lá deixa pedido órfão pago quando o seu HTTP desiste. Por isso o POST responde 202 com data[0].protocolo na hora, e o documento chega depois.
Consulte GET /v1/consultas/{protocolo} para acompanhar. Ele NÃO cobra e não fala com a origem — lê a linha que o motor já escreveu, então pode ser consultado à vontade. Enquanto estiver rodando ele responde 202; quando terminar, 200 com o documento (ou um 6xx dizendo o que houve).
O header.billable já vem true no 202: o valor foi debitado na aceitação. Não some o preço de novo quando o 200 chegar.
Tempos medidos em produção (16/10/2026, 2 pedidos em MG — amostra pequena, não é SLA): o protocolo no cartório sai em cerca de 80 s (formulário ~8 s, desafio anti-robô 13–39 s, envio ~30 s) e o documento chega em cerca de 3 min. A liberação depende do cartório e pode levar mais. Reconsulte o mesmo protocolo após intervalo_consulta_segundos (10 s), inclusive em emissão; isso não faz outro pedido.
Timeout da origem não quer dizer que nada foi protocolado
Quando o portal não responde a tempo (605), a pergunta que fica é de dinheiro: o ato saiu ou não? Nós não chutamos — perguntamos à lista de pedidos da origem antes de decidir.
Achou o protocolo: o valor fica, o documento é entregue e você recebe normalmente. Não achou: o valor é estornado integralmente e a resposta NÃO afirma que nada foi protocolado — a lista da origem pode demorar a mostrar um pedido novo. A reconciliação segue sozinha (a cada 2 min no início, depois a cada 30 min) e, se o pedido aparecer, o documento é entregue no mesmo protocolo sem nova cobrança: o 200 sai com header.billable: false e price: 0.
Atenção: Não reenvie com chave de idempotência nova depois de um timeout. É exatamente o caso em que um segundo ato registral seria protocolado e pago.
Contexto 2
Cópia opcional sem a tarja diagonal
O download padrão entrega o PDF original. Para uma cópia de leitura sem a tarja diagonal de consulta, use GET /v1/consultas/{protocolo}/documento?remover_tarja_consulta=1. É uma opção de download: não envie no POST e não faça outro pedido pago.
A marca ONR e o conteúdo registral são preservados; a linha textual SOLICITADO POR é removida automaticamente da cópia entregue. A cópia continua sendo visualização, sem valor de certidão. O original permanece arquivado.
O tratamento aceita apenas as camadas conhecidas. Se o formato não puder ser tratado com segurança, responde HTTP 422 em JSON; o original continua disponível sem o parâmetro. A resposta PDF tratada tem X-Documento-Versao: copia-leitura.
Quando consultar novamente
Enquanto a resposta for 202, aguarde data[0].intervalo_consulta_segundos (10 segundos) e faça GET /v1/consultas/{protocolo}. A recomendação também vale quando o documento estiver em emissão e no download ainda não disponível.
O GET lê o pedido existente, sem cobrar novamente. Não repita o POST para acompanhar. O intervalo de checagem não é o prazo de emissão do cartório.
Requisição
Autentique com token no cabeçalho. Parâmetro obrigatório ausente é recusado com
422, antes de qualquer cobrança.
cpf_cnpj
string
obrigatório
Atenção: O CONSULENTE, não o dono do imóvel. É a quem a consulta fica associada na sua conta e no seu extrato — o documento sai do imóvel, não deste CPF/CNPJ. Aceita com ou sem máscara.
imovel_matricula
string
obrigatório
Número da matrícula OU o CNM (Código Nacional de Matrícula). Zeros à esquerda são aceitos.
imovel_cns
string(6)
opcional
Atenção: **Alternativa ao trio, não um campo a mais.** Envie **ou** imovel_cns **ou** imovel_cartorio + imovel_municipio + imovel_uf — nunca os dois: se apontarem para serventias diferentes a chamada é recusada sem cobrança, em vez de escolhermos por você. CNS é o código do CNJ da serventia, 6 dígitos (formato 062661), e endereça o pedido sozinho. Vem de GET /v1/cartorios, da Pesquisa Prévia de Bens ou do próprio CNM. Pelo mesmo motivo, não o combine com um CNM de outra serventia em imovel_matricula.
imovel_cartorio
integer
opcional
Atenção: O NÚMERO do registro de imóveis, inteiro: 1 para o 1º RI. Mandar "1º RI - Taquaritinga" é 607 faturado pela origem. Quatro maneiras de endereçar o pedido, nesta ordem de precedência: (1) este campo com imovel_municipio e imovel_uf, que é o contrato de sempre; (2) imovel_cns; (3) um CNM em imovel_matricula, que já carrega a serventia; (4) imovel_municipio + imovel_uf quando o município tem UMA só serventia. Para descobrir o número — e a grafia exata do município —, use GET /v1/cartorios, que é gratuito.
imovel_municipio
string
opcional
Atenção: Município DO CARTÓRIO, não do imóvel. Medido em 2026-08-11: um imóvel de Fernando Prestes está matriculado no RI de Taquaritinga. Errar aqui não protocola nada — a cotação falha e a consulta fica indisponível sem cobrar. **Necessário em dois dos quatro caminhos**: com imovel_cartorio + imovel_uf (o contrato de sempre) e com imovel_uf sozinho, quando o município tem UMA só serventia. Endereçando por imovel_cns ou por CNM, não envie — nós preenchemos com a grafia medida, que é a que a origem aceita. A grafia exata de cada serventia está em GET /v1/cartorios.
imovel_uf
string(2)
opcional
UF do cartório. Mesma regra do imovel_municipio: necessário quando o endereçamento é pelo número do RI ou por município de serventia única, dispensável quando você manda imovel_cns ou um CNM.
imovel_finalidade
integer
opcional
Atenção: Declaração AO CARTÓRIO, não parâmetro técnico. 1 = investigação para avaliação de crédito ou solvência · 2 = investigação jurídica sobre o imóvel e sua titularidade (padrão) · 3 = o solicitante É titular de direito real sobre o imóvel. Ver a nota "Finalidade é declaração legal".
finalidade
string
opcional
Motivo da consulta, em texto livre. **Obrigatória (mínimo 10 caracteres) quando cpf_cnpj é um CPF que ainda não está no seu cadastro**: cadastrar uma pessoa física exige finalidade declarada, e a chamada sem ela é recusada com 422, sem cobrança. Para CNPJ, e para CPF já cadastrado, é opcional. Não confundir com imovel_finalidade, que é a declaração ao cartório.
Envie apenas o token e os dados. Cada POST inicia uma nova consulta, mesmo com dados iguais, com protocolo e cobrança próprios.
Use os exemplos no backend. Guarde o protocolo recebido e acompanhe por GET. Se a resposta do POST se perder, confira o histórico antes de reenviar: outro POST é outro pedido.
// Execute somente no backend (Node.js 22+). Configure o token no servidor.
// const pedido = await consultarOficialData(process.env.OFICIALDATA_TOKEN, dados);
// Guarde pedido.protocolo. Depois use acompanharOficialData(token, pedido.protocolo).
// Cada POST inicia uma nova consulta, mesmo com dados iguais.
// Resposta perdida: confira o histórico antes de reenviar; outro POST é outro pedido.
export async function consultarOficialData(token, dados = {"cpf_cnpj":"19131243000197","imovel_matricula":"21916","imovel_cartorio":1,"imovel_municipio":"Taquaritinga","imovel_uf":"SP","imovel_finalidade":2}) {
const corpo = await enviar(token, "https://api.oficialdata.com.br/v1/consultas/visualizacao-matricula", dados);
const protocolo = corpo.data?.[0]?.protocolo;
if (corpo.code !== 202 || !protocolo) throw new Error(JSON.stringify(corpo));
return { protocolo: String(protocolo), resposta: corpo };
}
export async function acompanharOficialData(token, protocolo) {
if (!/^\d+$/.test(String(protocolo))) throw new Error('Informe o protocolo recebido.');
const corpo = await enviar(token, "https://api.oficialdata.com.br" + '/v1/consultas/' + encodeURIComponent(protocolo));
// code 202: aguarde intervalo_consulta_segundos e consulte novamente por GET.
// code 200/6xx: confira o resultado. Não repita o POST para acompanhar.
return { protocolo: String(protocolo), resposta: corpo };
}
async function enviar(token, url, dados) {
if (!token) throw new Error('Informe o token de acesso.');
const post = dados !== undefined;
const resposta = await fetch(url, {
method: post ? 'POST' : 'GET',
headers: {
Authorization: 'Bearer ' + token, Accept: 'application/json',
...(post && { 'Content-Type': 'application/json' }),
},
...(post && { body: JSON.stringify(dados) }),
signal: AbortSignal.timeout(30000),
});
const corpo = await resposta.json();
// Não repita POST automaticamente após timeout: o pedido pode ter sido aceito.
if (!resposta.ok) throw new Error('HTTP ' + resposta.status + ': ' + JSON.stringify(corpo));
return corpo;
}
A consulta aceita responde HTTP 202 com protocolo.
Acompanhe até a conclusão e confira o campo code do resultado.
Resposta
Dentro de data[]:
11 campos em 3 blocos.
Campo que a origem não informou volta null —
nunca 0 nem string vazia. Trate
null como dado ausente, não como zero.
data[]
object
SUCESSO quando o documento foi entregue. É o estado da CONSULTA, não um veredito sobre o imóvel — a visualização não tem veredito.
Atenção: A ENTREGA. Aponta para o nosso arquivo, autentica com o mesmo Bearer e NÃO expira. Use esta, nunca a de site_receipts[] — aquela é da origem e morre em 7 dias.
Frase pronta para tela, já com o aviso de que a visualização não tem fé pública.
⚠️ URL do PDF NA ORIGEM. Expira em 7 dias — está aqui para conferência e auditoria, não para ser o seu link.
identificadores
object
Atenção: Protocolo do pedido no cartório (ex.: VM030158741). GUARDE: é por ele que se reconcilia um emolumento pago, e é o que o cartório pede no balcão.
Matrícula efetivamente atendida. Quando o cartório devolve o número, ele tem precedência sobre o que você mandou.
dados
object
Texto da matrícula, quando o cartório devolve a camada de texto. Muitas serventias entregam só o PDF — null aqui não significa documento faltando.
Serventia por extenso ("1º RI de Taquaritinga/SP").
Município do cartório.
UF do cartório.
Total cobrado, formatado em reais. O mesmo valor de header.price.
Códigos de erro
O mesmo mapa que o motor usa em produção. Leia as colunas Estorna e Retenta antes de integrar: nem toda falha devolve o dinheiro.
| Classe | Códigos | Significa | Estorna | Retenta |
|---|---|---|---|---|
sucesso |
200 | A origem respondeu e entregou. | — | — |
nao_encontrado |
612 | A origem respondeu: nada consta para este alvo. | Não | Não |
indeterminado |
611 | A origem não conseguiu emitir pela internet. Não é irregularidade. | Não | Não |
erro_participante |
608 619 620 | A origem recusou os DADOS do pedido. | Não | Sim |
retry |
600 605 609 610 613 614 615 618 | Instabilidade momentânea da origem ou do transporte. | Sim | Sim |
fatal |
601 602 603 604 606 607 617 621 622 | Defeito de integração — nosso, não seu. | Sim | Não |
Estorno:
erro_participante é a única
classe que não devolve o dinheiro — nela a origem
respondeu recusando os dados do pedido. Corrija o alvo antes de repetir.
fatal é falha nossa e sempre estorna.
Permanentes: não retente 602 e 603. A fonte sai do ar na hora e a nossa equipe é avisada.
Preço
Preço único por consulta pelo canal API. Confira o orçamento em
POST /v1/orcamento/visualizacao-matricula
antes de disparar em lote.
R$ 24,83
por consulta
Este é o preço da sua conta pelo canal API. Acordos vigentes prevalecem.
Como interpretar o orçamento
Motivo do preço, piso mínimo e situação da cota.
Leia data[0].preco.total para saber o valor previsto da consulta.
header.price é zero porque orçar não cobra.
preco.motivo é um slug estável para sua integração;
preco.justificativa é o texto para exibir ao usuário e pode evoluir.
coberto_pela_cota- A cota cobre a consulta, sem débito de saldo. A execução consumirá as unidades previstas.
fonte_gratuita- A regra de preço aplicada considera a fonte gratuita. Confira se o piso do canal permanece cobrado.
cortesia- Aplica-se uma cortesia comercial. Ela pode continuar sujeita ao piso mínimo da API.
cobranca_avulsa- Aplica-se o preço avulso da consulta no canal API.
preco_negociado- Aplica-se uma condição negociada para a conta.
preco_ao_custo- Aplica-se a condição de preço ao custo da conta, com o piso do canal quando indicado.
somente_emolumentos- A cota cobre o serviço; permanece o emolumento do cartório.
taxa_na_cota- A cota cobre o pedido com a taxa reduzida do plano; soma-se o emolumento do cartório.
taxa_do_plano- Aplica-se a taxa de cartório do plano, com a execução por nossa conta; soma-se o emolumento. O pedido não consome cota.
taxa_integrador- Aplica-se a taxa de cartório do plano Integrador; soma-se o emolumento do cartório.
emolumentos_e_servico- O valor inclui emolumentos do cartório e a cobrança pelo serviço.
Quando preco.piso_minimo_aplicado é true, o mínimo da API
permanece cobrado. Use sempre preco.total: cortesia, custo zero da origem
ou plano Gratuito não garantem uma consulta a R$ 0.
cota.status informa disponivel, esgotada,
insuficiente (restam unidades, mas não bastam para a operação),
fonte_fora_da_cota ou plano_sem_cota.
cota.restante é a quantidade livre agora; unidades_necessarias
é o peso da operação e unidades_previstas é o consumo previsto na execução.
Uma consulta gratuita por outra regra pode ter cota disponível e prever consumo zero.
cota.eixo identifica a franquia e cota.limite o limite do ciclo.
cota.origem distingue plano de trial.
cota.reservada é sempre false: o orçamento não reserva nem
consome unidades. Preço, cota e disponibilidade serão revalidados ao executar.
Se disponivel for false, leia o motivo_codigo
e a mensagem motivo da resposta. Nesse caso, preco.total,
preco.motivo, preco.justificativa e cota vêm
null. Preço desconhecido não significa gratuidade. Disponibilidade e preço
também não dispensam saldo ou os demais requisitos da execução.
Limites e desempenho
Números medidos em produção. "Não medido" é falta de amostra — nenhum valor aqui é estimativa.
Tempo típico
não medido
p95
não medido
Teto por hora
—
Timeout máximo
540s
De onde vem o tempo: cerca de 85% dos ~s típicos é a origem varrendo os cartórios. Dimensione o seu timeout por esse número e não conte com redução.
Sobre o teto: a origem exige sessão única por conta, então os pedidos são serializados. É limite técnico, não cota comercial: acima dele a fila cresce e paralelizar do seu lado não acelera. Para volume maior, combine antes.
Versionamento
O contrato de resposta é v1,
e a versão viaja em header.api_version
em toda resposta.
- Campo novo opcional pode entrar a qualquer momento e não muda a versão. Seu parser precisa ignorar campo que não conhece.
- Remover campo, renomear campo ou mudar tipo é versão nova, publicada em paralelo, com prazo de desligamento anunciado da anterior.
- Nunca alteramos o significado de um campo existente mantendo o nome. Se o significado muda, o nome muda junto.
Vai integrar?
Diga o volume que você espera e em quais UFs. A ordem de liberação segue a demanda.