Consulte informações de óbitos diretamente pelo seu sistema

1. Visão geral

A API expõe um endpoint de consulta de falecidos via HTTP GET. Os parâmetros são enviados na query string. A resposta segue um envelope JSON consistente com os campos success, data, meta e error.

A API utiliza o header proprietário CNF-API-Authorization para autenticação. A chave de API deve ser enviada diretamente nesse header, sem prefixos adicionais.

CNF-API-Authorization: SUA_API_KEY

3. Fluxo da requisição

5. Estrutura da resposta JSON

O envelope é padronizado. O campo data carrega o registro de maior similaridade; meta traz os filtros aplicados; error fica preenchido nas respostas de erro.

{
  "success": true,
  "data": {
    "indice": 0,
    "registro": {
      "U_ID": 1,
      "ID": 44940177,
      "Cpf": 0,
      "NomeFalecido": "LUIZ ALBERTO DA SILVA",
      "DataNascimento": "-",
      "NomeMae": "LUIZA CERBIA DA SILVA",
      "NomePai": "-",
      "DataFalecimento": "2018-12-28",
      "Cartorio_OrigemFonte": "202",
      "Cartorio_Codigo": 0,
      "Livro": "-",
      "Folha": "-",
      "Termo": "-",
      "DataLavramento": "-",
      "Cidade": "Porto Ferreira",
      "UF": "SP",
      "cidade_id_cod": null,
      "nome_cidade_cod": null,
      "estado_id_cod": null,
      "uf_cod": null,
      "cidade_id_nome": null,
      "nome_cidade_nome": null,
      "estado_id_nome": null,
      "uf_nome": null,
      "cidade_resolvida": "Porto Ferreira",
      "uf_resolvida": "SP"
    },
    "similaridade": 0.775,
    "percentual": 77.5
  },
  "meta": {
    "page": 1,
    "limit": 10,
    "count": 3,
    "has_more": false,
    "next_page": null,
    "response_time_ms": 1.07,
    "filters": {
      "nomefal": "LUIZ ALBERTO DA SILVA",
      "cpf": null,
      "data_exata": null,
      "data_ini": null,
      "data_fim": null,
      "estadofal": null,
      "cidadefal": null
    }
  },
  "error": null
}

{
  "success": false,
  "data": null,
  "meta": [],
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API Key inválida."
  }
}

6. Rate limit e headers

A API contabiliza requisições por minuto, dia, mês e total, conforme o plano do cliente. Quando os limites estão definidos, a resposta de sucesso também pode trazer headers de consumo.

7. Códigos HTTP e erros

8. Exemplos de integração

const API_URL = "https://api.falecidosdobrasil.com.br/v1/obitos";
const API_KEY = "SUA_API_KEY";

const params = new URLSearchParams({
  nomefal: "NOME DA PESSOA",
  estadofal: "25",   // Código do estado (ex: 25 = São Paulo)
  cidadefal: "3550308" // Código da cidade
});

const response = await fetch(`${API_URL}?${params}`, {
  method: "GET",
  headers: {
    "CNF-API-Authorization": API_KEY,
    "Accept": "application/json"
  }
});

const result = await response.json();

if (!response.ok) {
  console.error("Erro:", result.error);
  throw new Error(result.error?.message || "Falha na API");
}

// result.data contém o registro de maior similaridade
console.log(result.data);

           $url = "https://api.falecidosdobrasil.com.br/v1/obitos?" . http_build_query([
    "nomefal" => "NOME DA PESSOA",
    "estadofal" => 25,
    "cidadefal" => 3550308
]);

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "CNF-API-Authorization: SUA_API_KEY",
        "Accept: application/json",
    ],
]);

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$result = json_decode($body, true);

if ($status < 200 || $status >= 300) {
    throw new Exception($result["error"]["message"] ?? "Falha na API");
}

// $result["data"] contém o registro de maior similaridade
print_r($result["data"]);

            curl --request GET \
  --url 'https://api.falecidosdobrasil.com.br/v1/obitos?nomefal=NOME%20DA%20PESSOA&estadofal=25&cidadefal=3550308' \
  --header 'Accept: application/json' \
  --header 'CNF-API-Authorization: SUA_API_KEY'

9. Webhook e busca manual

Quando a consulta não encontra nenhum registro na base imediata, o sistema automaticamente registra a solicitação para uma busca manual em diversos cartórios e outras fontes disponíveis. Se o registro for localizado dentro do prazo, um webhook é disparado para o endpoint cadastrado pelo cliente.

{
  "event": "registro_localizado",
  "consulta_id": "a3f8c2e1-9b4d-4e7f-8a1c-5d6e7f8a9b0c",
  "data": {
    "NomeFalecido": "MARIA DA SILVA",
    "Cpf": "12345678901",
    "DataFalecimento": "2024-08-10",
    "DataNascimento": "1955-01-14",
    "NomeMae": "JOANA DA SILVA",
    "NomePai": "JOAO DA SILVA",
    "cidade_resolvida": "SAO PAULO",
    "uf_resolvida": "SP",
    "similaridade": 0.987
  },
  "timestamp": "2024-09-15T14:30:00Z"
}

11. Checklist para o desenvolvedor