Generar PDF de Beneficiario Controlador

Tabla de Contenidos

1. Descripción General
2. Especificaciones del Endpoint
3. Autenticación y Permisos
4. Ejemplos de Código
5. Respuestas y Manejo de Errores
6. Datos Incluidos en el PDF
7. Mejores Prácticas
8. Testing y Ambientes
9. Cumplimiento Legal
10. Soporte y Recursos
11. Historial de Versiones

1. Descripción General

Este endpoint permite descargar el Formato de Identificación de Beneficiario Controlador del SAT (Anexo 3 - Personas Físicas) completado automáticamente con los datos capturados durante el proceso KYC.

Casos de Uso

• Cumplimiento regulatorio SAT
• Onboarding de clientes bancarios y fintech
• Archivo de expedientes digitales
• Reportes de prevención de lavado de dinero

Características Principales

• Generación automática: El PDF se completa con datos extraídos del KYC
• Cumplimiento normativo: Formato oficial del SAT
• Descarga instantánea: Archivo PDF listo para usar
• Personalizable: Incluye logo de tu empresa si está configurado

2. Especificaciones del Endpoint

URL del Endpoint

GET https://api.jaak.ai/api/v1/kyc/session/{sessionId}/beneficiary-controller-pdf

Parámetros

3. Autenticación y Permisos

Métodos de Autenticación

Puedes usar cualquiera de estos dos métodos:

Opción 1: API Key (Recomendado)

Authorization: YOUR_API_KEY

Ideal para: Integraciones server-to-server y automatizaciones

Opción 2: Bearer Token

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Ideal para: Aplicaciones web con usuarios autenticados

Roles Permitidos

• God - Acceso completo
• Administrator - Gestión total
• Manager - Gestión operativa
• Viewer - Solo lectura

4. Ejemplos de Código

cURL

curl -X GET \
  "https://api.jaak.ai/api/v1/kyc/session/SESSION_ID/beneficiary-controller-pdf" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Language: es" \
  -o beneficiario_controlador.pdf

JavaScript / Node.js

const fetch = require('node-fetch');
const fs = require('fs');

async function downloadBeneficiaryPDF(sessionId) {
  const response = await fetch(
    `https://api.jaak.ai/api/v1/kyc/session/${sessionId}/beneficiary-controller-pdf`,
    {
      method: 'GET',
      headers: {
        'Authorization': 'YOUR_API_KEY',
        'Language': 'es'
      }
    }
  );

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

  const buffer = await response.buffer();
  fs.writeFileSync('beneficiario_controlador.pdf', buffer);
  console.log('✅ PDF descargado exitosamente');
}

// Uso
downloadBeneficiaryPDF('06722190-9de7-4d1b-a9ad-1559a5ab8cb9');

Python

import requests

def download_beneficiary_pdf(session_id):
    url = f"https://api.jaak.ai/api/v1/kyc/session/{session_id}/beneficiary-controller-pdf"
    
    headers = {
        "Authorization": "YOUR_API_KEY",
        "Language": "es"
    }
    
    response = requests.get(url, headers=headers)
    
    if response.status_code == 200:
        with open("beneficiario_controlador.pdf", "wb") as f:
            f.write(response.content)
        print("✅ PDF descargado exitosamente")
    else:
        error = response.json()
        print(f"❌ Error: {error['error']['message']}")

# Uso
download_beneficiary_pdf("06722190-9de7-4d1b-a9ad-1559a5ab8cb9")

PHP

<?php

function downloadBeneficiaryPDF($sessionId) {
    $url = "https://api.jaak.ai/api/v1/kyc/session/{$sessionId}/beneficiary-controller-pdf";
    
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: YOUR_API_KEY',
        'Language: es'
    ]);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    if ($httpCode === 200) {
        file_put_contents('beneficiario_controlador.pdf', $response);
        echo "✅ PDF descargado exitosamente\n";
    } else {
        $error = json_decode($response, true);
        echo "❌ Error: " . $error['error']['message'] . "\n";
    }
}

// Uso
downloadBeneficiaryPDF('06722190-9de7-4d1b-a9ad-1559a5ab8cb9');

?>

Java

import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;

public class BeneficiaryPDFDownloader {
    
    public static void downloadPDF(String sessionId) throws IOException {
        String urlString = "https://api.jaak.ai/api/v1/kyc/session/" 
                         + sessionId + "/beneficiary-controller-pdf";
        
        URL url = new URL(urlString);
        HttpURLConnection conn = (HttpURLConnection) url.openConnection();
        conn.setRequestMethod("GET");
        conn.setRequestProperty("Authorization", "YOUR_API_KEY");
        conn.setRequestProperty("Language", "es");
        
        int responseCode = conn.getResponseCode();
        
        if (responseCode == 200) {
            try (InputStream in = conn.getInputStream();
                 FileOutputStream out = new FileOutputStream("beneficiario_controlador.pdf")) {
                byte[] buffer = new byte[4096];
                int bytesRead;
                while ((bytesRead = in.read(buffer)) != -1) {
                    out.write(buffer, 0, bytesRead);
                }
            }
            System.out.println("✅ PDF descargado exitosamente");
        } else {
            System.out.println("❌ Error: " + responseCode);
        }
    }
    
    public static void main(String[] args) throws IOException {
        downloadPDF("06722190-9de7-4d1b-a9ad-1559a5ab8cb9");
    }
}

5. Respuestas y Manejo de Errores

Respuesta Exitosa

HTTP Status: 200 OK

Headers:

Content-Type: application/pdf
Content-Disposition: attachment; filename=beneficiario_controlador_{sessionId}.pdf

Body: Archivo PDF binario

Códigos de Error

Ejemplo de Respuesta de Error

{
  "error": {
    "code": "KYC19",
    "message": "Session not found"
  }
}

Manejo de Errores en tu Código

// JavaScript
try {
  const response = await fetch(url, options);
  
  if (!response.ok) {
    const error = await response.json();
    
    switch (response.status) {
      case 404:
        console.error('Sesión no encontrada');
        break;
      case 401:
        console.error('Autenticación inválida');
        break;
      case 500:
        console.error('Error del servidor, intenta más tarde');
        break;
      default:
        console.error(`Error: ${error.error.message}`);
    }
  }
} catch (err) {
  console.error('Error de conexión:', err);
}

6. Datos Incluidos en el PDF

El PDF se genera automáticamente con todos los datos capturados durante el proceso KYC:

✅ Información Personal

• Nombre completo (nombres, apellido paterno, apellido materno)
• Fecha y lugar de nacimiento
• Nacionalidad y género
• CURP y RFC

✅ Documentos de Identificación

• Tipo de documento (INE/Pasaporte/Licencia)
• Número de documento
• Autoridad emisora

✅ Domicilio Completo

• Calle, número exterior e interior
• Colonia, municipio, estado
• Código postal y país

✅ Contacto Verificado

• Teléfono (de verificación WhatsApp/SMS)
• Email (de verificación de correo)

✅ Elementos Visuales

• Fotografía del rostro
• Logo de tu empresa (si está configurado)
• Fecha de generación

7. Mejores Prácticas

✅ DO (Recomendado)

1. Verificar estado del KYC: Asegúrate de que el proceso KYC esté completado (status: "completed") antes de solicitar el PDF
2. Descarga inmediata: Descarga el PDF tan pronto como el KYC esté completo
3. Nomenclatura descriptiva: Guarda el archivo con un nombre único que incluya el sessionId o datos del cliente
4. Validación de Content-Type: Verifica que el Content-Type sea application/pdf antes de guardar
5. Implementar reintentos: Configura reintentos automáticos para errores 500
6. Logs de auditoría: Registra todas las descargas para cumplimiento y trazabilidad

❌ DON'T (Evitar)

• No hagas múltiples requests simultáneos del mismo PDF
• No asumas que el PDF estará disponible sin verificar el status del KYC
• No ignores los errores 404 (pueden indicar IDs incorrectos)
• No guardes PDFs sin validar que la descarga fue exitosa

🔄 Flujo de Integración Recomendado

1. Iniciar sesión KYC y obtener sessionId
2. Usuario completa el proceso de verificación
3. Verificar que el status de la sesión sea "completed"
4. Llamar al endpoint para descargar el PDF
5. Guardar el PDF en tu sistema de almacenamiento
6. Asociar el PDF al expediente del cliente

8. Testing y Ambientes

Ambiente Sandbox

URL Base: https://api.sandbox.jaak.ai

Uso: Para pruebas y desarrollo

Ambiente Producción

URL Base: https://api.jaak.ai

Uso: Para operaciones en producción

Casos de Prueba Recomendados

1. Test exitoso: Descargar PDF con sesión válida y completada
2. Test de autenticación: Intentar descargar sin Authorization header (debe retornar 401)
3. Test de sesión inválida: Usar un sessionId inexistente (debe retornar 404)
4. Test de permisos: Usar credenciales sin permisos adecuados (debe retornar 403)
5. Test de integridad: Verificar que el PDF descargado sea válido y contenga todos los datos esperados

Ejemplo de Test Unitario

describe('Beneficiary PDF Download', () => {
  it('should download PDF successfully', async () => {
    const sessionId = 'valid-test-session-id';
    const response = await downloadBeneficiaryPDF(sessionId);
    
    expect(response.status).toBe(200);
    expect(response.headers['content-type']).toBe('application/pdf');
    expect(response.data).toBeInstanceOf(Buffer);
  });
  
  it('should handle invalid session ID', async () => {
    const sessionId = 'invalid-id';
    
    try {
      await downloadBeneficiaryPDF(sessionId);
    } catch (error) {
      expect(error.response.status).toBe(404);
      expect(error.response.data.error.code).toBe('KYC19');
    }
  });
});

9. Cumplimiento Legal

Este endpoint genera documentos que cumplen con:

• ✅ Anexo 3 - Formato de Identificación de Beneficiario Controlador (SAT)
• ✅ Normativa de Prevención de Lavado de Dinero (México)
• ✅ Requisitos de identificación oficial vigentes
• ✅ Ley Federal para la Prevención e Identificación de Operaciones con Recursos de Procedencia Ilícita

⚠️ Nota Importante

Es responsabilidad del cliente validar que el uso del documento cumpla con sus requisitos regulatorios específicos y con las normativas aplicables a su industria.

10. Soporte y Recursos

📞 Contacto

📚 Recursos Adicionales

• API Reference: Documentación completa de todos los endpoints
• SDKs: Librerías oficiales para Node.js, Python, PHP, Java
• Changelog: Historial de cambios y actualizaciones de la API
• Status Page: Monitoreo en tiempo real del estado de los servicios

🕐 Horario de Soporte

• Lunes a Viernes: 9:00 AM - 6:00 PM (Hora del Centro, México)
• Sábados: 10:00 AM - 2:00 PM (Hora del Centro, México)

Nota: Para emergencias críticas, contáctanos en cualquier momento a través de [email protected]

11. Historial de Versiones

🎯 Quick Start

# 1. Obtener tu API Key desde el portal
https://app.jaak.ai/settings/api-keys

# 2. Descargar PDF de una sesión completada
curl -X GET \
  "https://api.jaak.ai/api/v1/kyc/session/{sessionId}/beneficiary-controller-pdf" \
  -H "Authorization: YOUR_API_KEY" \
  -o beneficiario_controlador.pdf

# 3. Verificar el archivo
file beneficiario_controlador.pdf
# Output: beneficiario_controlador.pdf: PDF document, version 1.4

📊 Diagrama de Flujo

┌─────────────┐
│ Tu Sistema  │
└──────┬──────┘
       │
       │ 1. Iniciar sesión KYC
       ▼
┌─────────────┐
│  API JAAK   │
└──────┬──────┘
       │
       │ 2. sessionId
       ▼
┌─────────────┐
│ Usuario KYC │
└──────┬──────┘
       │
       │ 3. Completar proceso
       ▼
┌─────────────┐
│  API JAAK   │
└──────┬──────┘
       │
       │ 4. GET /beneficiary-controller-pdf
       ▼
┌─────────────┐
│ PDF Generado│
└──────┬──────┘
       │
       │ 5. Descargar PDF
       ▼
┌─────────────┐
│ Tu Sistema  │
└─────────────┘

💡 Tips Pro

• Caché: No necesitas cachear el PDF, se genera bajo demanda
• Reintentos: Implementa exponential backoff para errores 500
• Webhooks: Combina con webhooks para automatizar la descarga cuando el KYC se completa
• Logs: Guarda el sessionId, timestamp y resultado de cada descarga
• Validación: Verifica que el PDF sea mayor a 10KB antes de guardarlo