scorecod/sdk

SDK oficial de ScoreCod para PHP

dev-main 2026-06-25 10:04 UTC

Requires

• php: >=7.4
• guzzlehttp/guzzle: ^7.0

Suggests

• ext-json: Requerido para decodificar las respuestas JSON de la API

MIT

• ScoreCod Team

Published on Packagist.org on 2026-07-09 14:43 UTC

README

El SDK oficial de ScoreCod para PHP te permite integrar rápidamente el Motor de Confiabilidad Operativa en cualquier aplicación de backend o plugin de e-commerce (como WooCommerce).

Permite consultar la reputación del comprador de forma preventiva antes de procesar o enviar un pedido a contra entrega (Delivery).

🔒 Consideraciones de Seguridad (Importante)

[!WARNING] Nunca expongas tus credenciales secretas (sk_live_... o sk_test_...) en código del lado del cliente (frontend/navegador). Llama siempre a este SDK desde el servidor backend.

🛠️ Instalación

Instala el paquete a través de Composer:

composer require scorecod/sdk

🚀 Inicialización y Configuración

<?php

use ScoreCod\ScoreCod;

require_once 'vendor/autoload.php';

$scoreCod = new ScoreCod([
    'apiKey' => 'sk_test_tu_api_key_secreta', // Requerido
    // 'baseUrl' => 'https://tu-url-custom.com' // Opcional, por defecto usa la de producción
]);

Configuración por variable de entorno

También puedes omitir la propiedad baseUrl y configurar la variable de entorno SCORECOD_BASE_URL para que el SDK la detecte automáticamente.

📚 Métodos Disponibles

1. Evaluar Cliente (evaluate)

Consulta el historial global de comportamiento de un cliente en la red colaborativa a través de su número de teléfono o ID.

try {
    $result = $scoreCod->evaluate('51948710503');
    
    echo "ID Cliente: " . $result['customer_id'] . "\n";
    echo "Score: " . $result['score'] . "\n"; // Ej: 92
    echo "Riesgo: " . $result['status'] . "\n"; // LOW_RISK, MEDIUM_RISK, HIGH_RISK
    echo "Recomendación: " . $result['recommendation'] . "\n";
} catch (Exception $e) {
    echo "Error: " . $e->getMessage();
}

2. Reportar Evento (reportEvent)

Registra el resultado final de un pedido para actualizar la reputación colaborativa del cliente en la red.

try {
    // Eventos válidos: 'DELIVERED', 'REJECTED', 'NO_RESPONSE'
    $response = $scoreCod->reportEvent('51948710503', 'DELIVERED');
    echo $response['message']; // "Evento registrado"
} catch (Exception $e) {
    echo "Error: " . $e->getMessage();
}

🛡️ Manejo de Errores

El SDK arroja excepciones de PHP estándar (Exception) cuando ocurren errores de red o errores devueltos por la API de ScoreCod:

• Errores HTTP de la API (ej: 401 Unauthorized, 404 Not Found): Contendrán el código de estado HTTP y el mensaje descriptivo devuelto por el servidor.
• Errores de Red: Si el servidor API está caído o hay fallas de conexión.