API de consulta de personas

El entorno local devuelve exclusivamente datos sintéticos. Una coincidencia no acredita por sí sola identidad ni situación tributaria o legal.

AutenticaciónCopiar enlace

Cada organización administra sus credenciales desde el panel. La clave completa se muestra una sola vez y puede enviarse en X-API-Key o como token Bearer.

POST /api/v1/person-search
Content-Type: application/json
X-API-Key: rsl_test_...
Idempotency-Key: cliente-operacion-0001

Consulta por cédula o RUCCopiar enlace

{
	"type": "cedula",
	"value": "4567890",
	"purpose": "due_diligence"
}

Para buscar un contribuyente utiliza "type": "ruc" con un valor como "80012345-6"; la consulta puede corresponder a una persona o empresa. Para consulta exploratoria por nombre, utiliza "type": "name". purpose admite legal_review, due_diligence, credit_risk, fraud_prevention y other; si se omite, se registra legal_review. La cédula se normaliza a dígitos, el RUC a número-dígito verificador y el nombre para búsqueda. El valor completo nunca se guarda en el ledger.

RespuestaCopiar enlace

{
	"requestId": "cm...",
	"query": {
		"type": "cedula",
		"preview": "••••890",
		"matchMode": "exact",
		"purpose": "due_diligence"
	},
	"resultCount": 3,
	"billableUnits": 1,
	"source": "synthetic",
	"disclaimer": "Datos sintéticos para validar la integración...",
	"results": [
		{
			"id": "synthetic-resolution-1",
			"documentType": "Resolución judicial",
			"documentCategory": "judicial",
			"decisionStatus": "closed",
			"subjectRole": "Demandado",
			"outcome": "Demanda rechazada; sin efecto económico adverso vigente",
			"title": "Resolución de cierre — ejemplo sintético",
			"sourceName": "Corpus Resillia — simulación",
			"sourceUrl": null,
			"publishedAt": "2024-05-15",
			"matchType": "exact",
			"matchReasons": ["Cédula coincidente en el documento"],
			"snippet": "Texto sintético sin información personal real.",
			"synthetic": true,
			"intelligence": {
				"caseReference": "EXP-SINT-001/2025",
				"legalArea": "civil",
				"caseStatus": "closed",
				"participationRole": "defendant",
				"currentEffect": "no_adverse_effect",
				"summary": "La pretensión fue rechazada y el expediente quedó cerrado.",
				"economicEffects": [],
				"evidence": [
					{
						"sourceVersionId": "synthetic-resolution-1",
						"locator": "p. 3, resolutivo",
						"excerpt": "rechazar la demanda y disponer el cierre del expediente",
						"supports": ["case_status", "current_effect", "summary"]
					}
				],
				"confidenceBasisPoints": 9900,
				"reviewStatus": "approved",
				"extractionVersion": "legal-intelligence-v1",
				"modelAssisted": false
			}
		}
	]
}

source vale synthetic durante la validación local y legaltax_corpus cuando el proveedor de solo lectura esté habilitado. documentCategory separa actuaciones judiciales, sanciones administrativas, insolvencia, estado regulatorio y contexto tributario. decisionStatus, subjectRole y outcome evitan presentar una mención como si acreditara una sanción vigente. matchReasons explica por qué se clasificó cada coincidencia; una coincidencia por nombre o una mención literal de cédula o RUC continúa requiriendo verificación humana y no acredita identidad ni situación tributaria o legal.

intelligence es opcional y solo aparece cuando el documento fue procesado por una versión identificable del extractor. Separa expediente, materia, estado, participación, efecto actual y hechos económicos; cada afirmación debe estar respaldada por evidence. reviewStatus=required impide presentar el dato como revisado. El bloque no constituye un puntaje ni una recomendación crediticia y puede omitirse aunque exista una mención documental.

ErroresCopiar enlace

Todas las respuestas incluyen X-Request-Id y los errores incluyen el mismo valor en el cuerpo para correlación. Las reservas mensual y por minuto son atómicas: solicitudes simultáneas no pueden superar los límites configurados. Un 429 por ráfaga incluye Retry-After.

Envía una Idempotency-Key distinta por operación lógica y reutiliza esa misma clave únicamente al reintentar la misma consulta. Durante 24 horas, una repetición completada devuelve la respuesta original con Idempotency-Replayed: true sin crear otra unidad facturable. No reutilices la clave para otro cuerpo.

Cada respuesta exitosa crea una unidad facturable y una entrada de auditoría. El registro conserva el propósito, una vista enmascarada y una huella HMAC, no la cédula, el RUC o el nombre completos. El contrato OpenAPI legible por herramientas está disponible en GET /api/v1/openapi.json.

JavaScriptCopiar enlace

const response = await fetch("https://api.resillia.com.py/api/v1/person-search", {
	method: "POST",
	headers: {
		"Content-Type": "application/json",
		"X-API-Key": process.env.RESILLIA_API_KEY,
		"Idempotency-Key": crypto.randomUUID(),
	},
	body: JSON.stringify({
		type: "cedula",
		value: "4567890",
		purpose: "due_diligence",
	}),
});

const result = await response.json();
if (!response.ok) throw new Error(`${result.error}: ${result.requestId}`);

PythonCopiar enlace

import os
import requests

response = requests.post(
    "https://api.resillia.com.py/api/v1/person-search",
    headers={
        "X-API-Key": os.environ["RESILLIA_API_KEY"],
        "Idempotency-Key": "operacion-interna-0001",
    },
    json={"type": "cedula", "value": "4567890", "purpose": "due_diligence"},
    timeout=15,
)
response.raise_for_status()
result = response.json()

Hasta disponer de DNS, sustituye el origen por http://localhost:3000 mediante el túnel SSH documentado para DEV.

La colección Postman versionada se encuentra en artifacts/integration/resillia-person-search.postman_collection.json dentro del repositorio.