A cadeia do registro de imóveis, por API

A cadeia

As três APIs funcionam isoladas, mas foram desenhadas para encadear. A Pesquisa Prévia devolve exatamente os quatro campos que as outras duas exigem como entrada — matrícula, cartório, município e UF.

A prévia responde indício, não titularidade. Ela diz que o documento aparece na matrícula — pode ser proprietário atual, ex-proprietário, cônjuge que deu anuência, credor hipotecário ou herdeiro. Quem confirma quem é dono hoje é a matrícula ou a certidão.

Antes de começar

Autenticação

Todo endpoint pede o token no cabeçalho padrão:

Authorization: Bearer od_SEU_TOKEN_AQUI

Confira as credenciais antes de escrever qualquer integração — essa chamada é grátis e não toca em nenhuma origem:

# Quem sou eu, o que posso, até quando
curl https://api.oficialdata.com.br/v1/token \
  -H "Authorization: Bearer od_SEU_TOKEN"

Resposta:

{
  "code": 200,
  "header": { "billable": false, "price": 0.0, "api_version": "v1",
               "request_id": "9f2c…" },
  "data": [{
    "conta": "Parceiro Integrador LTDA",
    "escopos": ["consultas:pesquisa-previa-bens", …],
    "expira_em": "2027-09-01T00:00:00-03:00"
  }]
}

Localizar a serventia antes de pedir documento de imóvel

A outra rota que não cobra. As consultas do registro de imóveis são endereçadas à serventia, e errar o cartório não é retrabalho: o emolumento é do cartório e não estorna. Use GET /v1/cartorios para achar a serventia e copiar os campos do pedido — ela lê só o nosso catálogo medido, sem falar com o cartório.

# Por cidade (uf obrigatório), por CNS, por CNM ou por parte do nome
curl "https://api.oficialdata.com.br/v1/cartorios?uf=RJ&municipio=niteroi" \
  -H "Authorization: Bearer od_SEU_TOKEN"

Resposta:

{
  "code": 200,
  "header": { "billable": false, "price": 0.0, "api_version": "v1" },
  "data": [{
    "medido_em": "2026-10-29",
    "cartorios": [{
      "nome": "2º Registro de Imóveis de Niterói",
      "cns": "062661",
      "params_pedido": {
        "imovel_cartorio": "2",
        "imovel_municipio": "NITERÓI - 2º REGISTRO DE IMÓVEIS DA 1º CIRCUNSCRIÇÃO",
        "imovel_uf": "RJ"
      }
    }, …]
  }]
}

O fluxo, passo a passo

Toda consulta paga segue o mesmo desenho: orçar, pedir, acompanhar, baixar. Os passos 1 e 4 não cobram.

curl -X POST https://api.oficialdata.com.br/v1/orcamento/pesquisa-previa-bens \
  -H "Authorization: Bearer od_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "cpf_cnpj": "19131243000197", "uf": "SP" }'

{
  "code": 200,
  "header": { "billable": false, "price": 0.0 },
  "data": [{
    "disponivel": true,
    "motivo": null,
    "campos_faltando": [],
    "preco": {
      "total": 17.52,
      "moeda": "BRL",
      "estimado": true,
      "desconto_plano_percentual": 0,
      "motivo": "emolumentos_e_servico",
      "justificativa": "O valor inclui os emolumentos do cartório e a cobrança pelo serviço. O plano não possui cota para esta consulta. O orçamento não reserva cota; preço e disponibilidade serão revalidados na execução.",
      "piso_minimo_aplicado": false
    },
    "cota": {
      "status": "plano_sem_cota",
      "eixo": "consultas",
      "limite": 0,
      "restante": 0,
      "unidades_necessarias": 1,
      "unidades_previstas": 0,
      "origem": "plano",
      "reservada": false
    },
    "limites": { "latencia_p50_s": 72, "teto_hora": 50 }
  }]
}

{
  "code": 202,
  "header": { "billable": true, "price": 17.52 },
  "data": [{
    "protocolo": "4713",
    "estado": "processando",
    "consultar_em": "/v1/consultas/4713",
    "intervalo_consulta_segundos": 72,
    "escada_polling_s": [72, 30, 60, 120]
  }]
}

curl https://api.oficialdata.com.br/v1/consultas/4713 \
  -H "Authorization: Bearer od_SEU_TOKEN"

{
  "code": 200,
  "header": { "billable": true, "price": 97.36 },
  "data": [{
    "status_consulta": "SUCESSO",
    "status": "Emitida",
    "identificadores": { "numero_pedido": "CT030158741" },
    "certidao_codigo": "1234-5678-9012",
    "documento_url": "https://api.oficialdata.com.br/v1/consultas/4713/documento",
    "mensagem": "Certidão emitida com fé pública…"
  }],
  "site_receipts": ["https://origem/…"]
}

curl -L https://api.oficialdata.com.br/v1/consultas/4713/documento \
  -H "Authorization: Bearer od_SEU_TOKEN" \
  -o certidao.pdf

Nova consulta e acompanhamento

Todas as consultas: basta enviar o token e os dados. Cada POST inicia uma nova consulta, mesmo com dados iguais, com protocolo e cobrança próprios. Não há reaproveitamento automático por CPF/CNPJ ou imóvel.

O protocolo identifica o pedido aceito. As travas internas protegem seu processamento. Use GET para acompanhar esse pedido sem iniciar outra consulta.

Exemplo: o ERP envia um POST, recebe o protocolo e acompanha por GET. Se precisar consultar novamente o mesmo alvo, envia outro POST e recebe outro protocolo.

Guarde o protocolo no seu sistema. O token fica somente no backend; estes exemplos não são para rodar no navegador.

// 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":"12345678000190","uf":"SP","nome":"EMPRESA EXEMPLO LTDA","imovel_finalidade":2}) {
  const corpo = await enviar(token, "https://api.oficialdata.com.br/v1/consultas/pesquisa-previa-bens", 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;
}

<?php

// Salve como oficialdata.php no backend Laravel. Configure o token no servidor.
// $consultar = require base_path('oficialdata.php');
// $pedido = $consultar(config('services.oficialdata.token'), $dados);
// Guarde $pedido['protocolo']; acompanhe com $consultar($token, null, $protocolo).
// Cada POST inicia uma nova consulta, mesmo com dados iguais.
// Resposta perdida: confira o histórico antes de reenviar; outro POST é outro pedido.
use Illuminate\Support\Facades\Http;

return function (string $token, ?array $dados = null, ?string $protocolo = null): array {
    if ($token === '') {
        throw new RuntimeException('Informe o token de acesso.');
    }
    $http = Http::withToken($token)->acceptJson()->timeout(30);
    if ($protocolo !== null) {
        if (! ctype_digit($protocolo)) {
            throw new RuntimeException('Informe o protocolo recebido.');
        }
        $resposta = $http->get("https://api.oficialdata.com.br".'/v1/consultas/'.rawurlencode($protocolo));
    } else {
        $dados ??= json_decode('{"cpf_cnpj":"12345678000190","uf":"SP","nome":"EMPRESA EXEMPLO LTDA","imovel_finalidade":2}', true, flags: JSON_THROW_ON_ERROR);
        $resposta = $http->post("https://api.oficialdata.com.br/v1/consultas/pesquisa-previa-bens", $dados);
    }
    // Não repita POST automaticamente após timeout: o pedido pode ter sido aceito.
    $resposta->throw();
    $corpo = $resposta->json();
    if ($protocolo === null) {
        $protocolo = $corpo['data'][0]['protocolo'] ?? null;
        if (($corpo['code'] ?? null) !== 202 || ! $protocolo) {
            throw new RuntimeException(json_encode($corpo, JSON_THROW_ON_ERROR));
        }
    }

    // code 202: aguarde intervalo_consulta_segundos e faça GET; code 200/6xx: leia o resultado.
    return ['protocolo' => (string) $protocolo, 'resposta' => $corpo];
};

• POST → nova consulta, mesmo com dados iguais, sujeita a nova cobrança.
• GET com protocolo → acompanha o pedido existente, sem nova consulta ou cobrança.
• Se a resposta do POST se perder, confira o histórico antes de reenviar.

Preços

Fora da cota, a taxa é fixa por pedido: R$ 9,90 na Pesquisa Prévia, R$ 14,90 na Visualização e R$ 19,90 no Inteiro Teor. Some o emolumento e o custo de execução aplicável. Pedidos de cartório não consomem a cota do plano: com assinatura, paga-se o emolumento mais a taxa do seu plano, sem custo de execução — R$ 6, R$ 8 e R$ 10 no Essencial, R$ 4, R$ 5 e R$ 7 no Profissional e R$ 2,90, R$ 3,90 e R$ 4,90 do Escritório em diante (pesquisa prévia, visualização e inteiro teor). Não há faixas de volume. Acordos vigentes podem alterar o orçamento da conta. Orçamento e acompanhamento não cobram novamente. O emolumento é fixado por lei estadual, e é por isso que a mesma consulta custa 16× mais no Rio de Janeiro que em São Paulo.

Documentos do imóvel

Valores medidos no 1º RI de Taquaritinga/SP. Cada serventia tem a sua tabela — sempre orce antes.

Pesquisa Prévia, por estado

Códigos e dinheiro

O status HTTP fala de transporte. O desfecho do negócio vive em code, no corpo — inclusive quando a resposta HTTP é 200. Assim 404 de rota errada nunca se confunde com "nada consta".

Transporte

Resultado da consulta

Chegam com HTTP 200. A coluna que importa para a sua conciliação é a última.

Todo desfecho declara header.billable e header.price, inclusive as falhas. Concilie por esses dois campos, nunca pelo status HTTP.

Webhook — Em breve

O webhook ainda não está disponível. Acompanhe a conclusão pelo protocolo em GET /v1/consultas/{protocolo}, respeitando o intervalo indicado na resposta.

Limites

Armadilhas

Erros de leitura que custam caro, em ordem de quanto já custaram.

Tratar em_emissao como desfecho

É o mais caro da lista. A certidão fecha o pedido em 202 · em_emissao e entrega horas depois. Pare de acompanhar aí e você pagou ~R$ 85 por um documento que não buscou.

Guardar a URL de site_receipts

Expira em ~7 dias. A entrega é documento_url, que não expira.

Ler matricula: null como "não tem imóvel"

Na Pesquisa Prévia, um item de imoveis[] com matricula: null significa que o cartório devolveu "matrícula não informada". O imóvel existe e o documento consta nele — o que falta é o número.

Ler "nada consta" sem olhar a cobertura

A resposta traz um bloco cobertura com quantos cartórios responderam, quantos estavam fora do ar e se a busca fechou. nada_consta só vem true quando a busca fechou sem achado. Com cobertura.retries_pendentes: true ou cobertura.leitura_parcial: true, um "não achamos" não cobre o estado inteiro — e não sustenta laudo.

Confiar em nome_digitado_manualmente como prova de identidade

A origem repete no resultado o nome que foi enviado no pedido, sem conferi-lo contra o documento. A única chave da busca é o CPF/CNPJ. Compare pesquisado_documento programaticamente antes de arquivar: divergência de um dígito invalida a busca inteira.

Esperar registros anteriores a 1976

A busca alcança registros a partir de 01/01/1976. O que é anterior está em livro de transcrição, fora da base indexada, e não aparece por nenhum parâmetro.

Mandar o município do imóvel

imovel_municipio é o do cartório. Um imóvel em Fernando Prestes pode estar registrado em Taquaritinga — e é Taquaritinga que vai no campo. Se você não sabe qual é, a Pesquisa Prévia devolve exatamente esse dado.

Checklist antes de ir para produção

• GET /v1/token responde 200 com os escopos que você espera.
• Retry automático desligado nos POST /v1/consultas/*.
• Em caso de timeout do POST, conferir histórico antes de reenviar; depois do protocolo, acompanhamento por GET.
• Você orça antes de pedir, e mostra o preço a quem decide.
• O acompanhamento continua enquanto code for 202 — incluindo em_emissao.
• numero_pedido gravado do seu lado assim que aparece.
• Você guarda documento_url, não site_receipts.
• Conciliação por header.billable e header.price, não por status HTTP.
• 612 tratado como resposta válida, com comprovante.
• request_id no seu log, em toda chamada.
• Alerta interno para 402: saldo acabando interrompe a operação inteira.