API CNF — Consulta de Óbitos | Documentação Completa e Teste

I

Seção 1

Autenticação

Todas as requisições devem incluir a chave de API no cabeçalho personalizado CNF-API-Authorization.

Formato do Cabeçalho

CNF-API-Authorization: cnf_CCfw.....

Importante: A chave de API é de uso exclusivo do cliente e não deve ser compartilhada.

II

Seção 2

Endpoint

GET /v1/consulta

Retorna uma lista de registros de falecidos filtrados conforme os parâmetros enviados.

URL Base (Produção)

https://api.falecidosdobrasil.com.br/v1/consulta

                    curl -X GET \
                    "https://api.falecidosdobrasil.com.br/v1/consulta?cpf=12345678909" \
                    -H "CNF-API-Authorization: cnf_CCfw..."
                

III

Seção 3

Parâmetros de Consulta

Parâmetro	Tipo	Obrigatório	Descrição
`nomefal`	string	Não	Nome do falecido (aceita letras, espaços e hífen). Busca case-insensitive e insensível a acentos.
`cpf`	string	Não	CPF do falecido (apenas números, 11 dígitos).
`data_exata`	string	Não	Data exata do óbito no formato `YYYY-MM-DD`.
`data_ini`	string	Não	Data inicial do período de óbito (`YYYY-MM-DD`).
`data_fim`	string	Não	Data final do período de óbito (`YYYY-MM-DD`).
`estadofal`	integer	Não	ID do estado (UF) onde ocorreu o óbito. Consulte a tabela de referência.
`cidadefal`	integer	Não	ID da cidade onde ocorreu o óbito. Consulte a tabela de referência.
`page`	integer	Não	Número da página de resultados (padrão: 1, mínimo 1).
`limit`	integer	Não	Quantidade de registros por página (padrão: 50, mínimo 1, máximo 100).

Observações:

Se data_exata for informado, data_ini e data_fim são ignorados.
estadofal e cidadefal podem ser usados separadamente ou em conjunto.
O parâmetro cpf deve conter exatamente 11 dígitos.
A busca por nomefal utiliza LIKE '%nome%' e SOUNDEX para nomes com 4+ caracteres.

IV

Seção 4

Formato de Respostas

Estrutura Padrão

{
                        "success": true,
                        "data": [],
                        "meta": {},
                        "error": null
                        }
                    

Campos da Resposta

Campo	Descrição
`success`	Booleano indicando se a requisição foi processada com sucesso.
`data`	Array contendo os registros encontrados.
`meta`	Objeto com informações sobre paginação, filtros e tempo de resposta.
`error`	Presente apenas em caso de erro, com `code`, `message` e opcionalmente `fields`.

Sucesso (200 OK)

{
                            "success": true,
                            "data": [{
                            "U_ID": 123456,
                            "Cpf": "12345678909",
                            "NomeFalecido": "JOAO DA SILVA",
                            "DataFalecimento": "2023-08-15",
                            "cidade_resolvida": "SAO PAULO",
                            "uf_resolvida": "SP"
                            }],
                            "meta": {
                            "page": 1,
                            "limit": 10,
                            "count": 1,
                            "has_more": false,
                            "response_time_ms": 42.56
                            },
                            "error": null
                            }
                        

Erro (401)

{
                            "success": false,
                            "data": [],
                            "meta": [],
                            "error": {
                            "code": "AUTH_REQUIRED",
                            "message": "API Key não informada."
                            }
                            }
                        

Erro de Validação (422)

{
                            "success": false,
                            "error": {
                            "code": "VALIDATION_ERROR",
                            "fields": {
                            "cpf": "CPF deve conter 11 dígitos."
                            }
                            }
                            }
                        

V

Seção 5

Códigos de Status HTTP

Código	Descrição
200	Sucesso – a consulta foi processada.
401	Não autenticado – API Key ausente ou inválida.
403	Proibido – cliente bloqueado, plano inativo ou feature não permitida.
405	Método não permitido – apenas GET é aceito.
422	Erro de validação nos parâmetros.
429	Limite de requisições excedido.
500	Erro interno do servidor.

VI

Seção 6

Limites de Requisições (Rate Limit)

A API impõe limites de acordo com o plano contratado:

Por minuto: Número máximo de requisições em 60 segundos.
Por dia: Número máximo de requisições em um dia.
Por mês: Número máximo de requisições no mês corrente.
Total: Número total acumulado de requisições permitidas.

Quando um limite é excedido, a API retorna 429 com o código correspondente (RATE_LIMIT_EXCEEDED, DAILY_QUOTA_EXCEEDED, MONTHLY_QUOTA_EXCEEDED ou QUOTA_EXCEEDED).

Headers Informativos

X-RateLimit-Limit-Minute: 60
                        X-RateLimit-Remaining-Minute: 45
                        X-RateLimit-Limit-Day: 1000
                        X-RateLimit-Remaining-Day: 823

VII

Seção 7

Ambiente de Teste

Consultar por CPF

Digite um CPF fictício com 11 dígitos para ver o formato de resposta da API. Nenhuma consulta real é realizada nesta demonstração.

CPF

Nota: esta é uma simulação. A resposta abaixo é exibida em formato JSON fictício.

Aguardando consulta…

VIII

Seção 8

Proteção de Dados (LGPD)

Os dados disponibilizados pela API CNF referem-se a pessoas falecidas e são considerados dados pessoais nos termos da Lei Geral de Proteção de Dados (Lei nº 13.709/2018). Embora o titular dos dados não possa mais exercer pessoalmente os direitos previstos na lei, familiares, herdeiros ou sucessores podem, em situações específicas, atuar em nome do falecido.

O tratamento desses dados deve observar:

Finalidade legítima e específica — ex.: verificação de óbito para fins de compliance, crédito, seguros;
Necessidade — somente os dados estritamente necessários;
Transparência — informar claramente a origem e a finalidade;
Segurança — medidas técnicas e administrativas de proteção;
Responsabilização — prestação de contas sobre o tratamento.

O uso da API CNF para fins ilícitos, discriminatórios ou que violem a dignidade da pessoa falecida ou de seus familiares é estritamente proibido.

IX

Seção 9

Tabelas de Referência

Estados (UF)

ID	UF	Nome
1	AC	Acre
2	AL	Alagoas
3	AP	Amapá
4	AM	Amazonas
5	BA	Bahia
6	CE	Ceará
7	DF	Distrito Federal
8	ES	Espírito Santo
9	GO	Goiás
10	MA	Maranhão
11	MT	Mato Grosso
12	MS	Mato Grosso do Sul
13	MG	Minas Gerais
14	PA	Pará
15	PB	Paraíba
16	PR	Paraná
17	PE	Pernambuco
18	PI	Piauí
19	RJ	Rio de Janeiro
20	RN	Rio Grande do Norte
21	RS	Rio Grande do Sul
22	RO	Rondônia
23	RR	Roraima
24	SC	Santa Catarina
25	SP	São Paulo
26	SE	Sergipe
27	TO	Tocantins

Cidades (parcial — 1 a 300)

ID	Cidade
1	Acrelândia
2	Assis Brasil
3	Brasiléia
4	Bujari
5	Capixaba
6	Cruzeiro do Sul
7	Epitaciolândia
8	Feijó
9	Jordão
10	Mâncio Lima
11	Manoel Urbano
12	Marechal Thaumaturgo
13	Plácido de Castro
14	Porto Acre
15	Porto Walter
16	Rio Branco
17	Rodrigues Alves
18	Santa Rosa do Purus
19	Sena Madureira
20	Senador Guiomard
21	Tarauacá
22	Xapuri
23	Água Branca (AL)
24	Anadia
25	Arapiraca
26	Atalaia
27	Barra de Santo Antônio
28	Barra de São Miguel
29	Batalha
30	Belém (AL)
... (lista completa disponível sob solicitação)

Para obter a lista completa de cidades, entre em contato com o suporte.