Colômbia — Cédula nacional premium (CC)

Finalidade: validar uma Cédula de Ciudadanía (CC) perante fontes oficiais e retornar um registro de identidade estruturado para KYC e conformidade, e não apenas um sim/não sobre o número. A resposta consolida nome conforme o cadastro, data de nascimento, local e data de expedição e, quando houver, gênero e sinal de vida, com bloco de certificação assinada. Apenas o número é informado; a data de expedição é resolvida no servidor (sem tipo de documento ou data na requisição). Nível de detalhe equivalente à cédula extra. O custo de créditos é maior que o do endpoint básico devido à cadeia de resolução.

Referência da API

Endpoint

GET https://api.verifik.co/v2/co/cedula/premium

Resposta: retorna data (atributos de identidade retornados para o número informado), signature (metadados de certificação do payload) e id (identificador da requisição). HTTP 404 indica que não foi possível montar um registro completo para o número neste fluxo. HTTP 409 indica falha de validação de entrada (p. ex. comprimento de documentNumber) antes do processamento. Custo de créditos por requisição superior ao de /v2/co/cedula básico, pela cadeia de resolução.

Cabeçalhos

Nome	Valor
Accept	application/json
Authorization	Bearer <token>

Parâmetros

Nome	Tipo	Obrigatório	Descrição
documentNumber	string	Sim	Número da Cédula de Ciudadanía (CC). O servidor normaliza para somente dígitos; o comprimento deve ficar entre 5 e 10 caracteres (validação de API).

Preço dinâmico

O endpoint padrão GET/POST /v2/co/cedula (cédula básica) participa da arquitetura de Consulta Dinâmica da Verifik. Na maioria dos casos você paga a tarifa padrão. Quando os caminhos de verificação padrão não retornam correspondência, um caminho de verificação estendido pode ser executado automaticamente. Se esse caminho retornar HTTP 200, aplica-se preço dinâmico e os créditos são deduzidos no nível premium dessa família de endpoints.

Expectativa de preço: da tarifa padrão da sua conta · até a tarifa premium (consulte seu plano ou Postman).

Passe includeCost=true em /v2/co/cedula para receber um objeto billing quando o preço dinâmico se aplicar. Consulte o SLA — Preço dinâmico (faturamento).

Premium direto vs preço dinâmico

Esta página documenta o endpoint premium explícito (/v2/co/cedula/premium). Chamá-lo diretamente sempre usa precificação premium.

O preço dinâmico descreve a escalada automática a partir de /v2/co/cedula; em caso de sucesso (HTTP 200), o mesmo nível premium desta rota é cobrado.

Solicitação

GET

import axios from "axios";

const { data } = await axios.get("https://api.verifik.co/v2/co/cedula/premium", {
	params: { documentNumber: "1234567890" },
	headers: {
		Accept: "application/json",
		Authorization: `Bearer ${process.env.VERIFIK_TOKEN}`,
	},
});
console.log(data);

POST

import axios from "axios";

const { data } = await axios.post(
	"https://api.verifik.co/v2/co/cedula/premium",
	{ documentNumber: "1234567890" },
	{
		headers: {
			Accept: "application/json",
			Authorization: `Bearer ${process.env.VERIFIK_TOKEN}`,
		},
	}
);
console.log(data);

Resposta

200

Forma ilustrativa (valores de exemplo, não pessoas reais):

{
	"data": {
		"arrayName": ["GIVEN", "MIDDLE", "PATERNAL", "MATERNAL"],
		"dateOfBirth": "1990-05-20",
		"documentNumber": "1234567890",
		"documentType": "CC",
		"expeditionDate": "2015-08-12",
		"expeditionPlace": {
			"municipio": "Município de exemplo",
			"departamento": "Departamento de exemplo"
		},
		"firstName": "GIVEN MIDDLE",
		"fullName": "GIVEN MIDDLE PATERNAL MATERNAL",
		"gender": "HOMBRE",
		"isAlive": true,
		"lastName": "PATERNAL MATERNAL"
	},
	"signature": {
		"dateTime": "April 21, 2026 9:34 PM",
		"message": "Certified by Verifik.co"
	},
	"id": "XXXXX"
}

Os nomes de campos e sua presença podem variar conforme as fontes oficiais.

404

{
	"code": "NotFound",
	"message": "Record not found."
}

Retornado quando as fontes acima não trazem correspondência ou dados necessários (por exemplo, falha na resolução da data de expedição).

409

{
	"code": "MissingParameter",
	"message": "documentNumber maximum length: 10\n"
}

A validação exige 5 a 10 caracteres em documentNumber; outras mensagens do Joi podem aparecer para entradas ausentes ou inválidas.

Relacionados

• Cédula colombiana (básica) — GET/POST /v2/co/cedula (CC / PPT).
• Referência oficial em inglês: Colombian cédula premium.