SDK de PHP

composer require constaia/constaia-php

$constaia = new \Constaia\Client(); // lee CONSTAIA_API_KEY del entorno

// o con opciones explícitas
$constaia = new \Constaia\Client(getenv('CONSTAIA_API_KEY'), [
    'timeout' => 60,     // segundos por intento (por defecto 60)
    'max_retries' => 2,  // reintentos en 429, 5xx y errores de red (por defecto 2)
]);

$analysis = $constaia->analyze('dni_valid.jpg', [
    'expect' => 'es_dni',
    'checks' => [
        'not_expired' => true,
        'holder' => ['full_name' => 'María García López'],
    ],
    'storage' => 'none',
    'language' => 'es',
]);

$analysis->verdictStatus();          // "valid" | "invalid" | "review" | null
$analysis->isValid();                // true
$analysis->isInvalid();              // false
$analysis->needsReview();            // false
$analysis->field('document_number'); // "12345678Z"
$analysis->warnings;                 // []

$analysis->document->type;          // "es_dni"
$analysis['verdict']['reasons'];    // lista de motivos
$analysis->toArray();               // array PHP
$analysis->toJson();                // JSON
$constaia->lastResponse->requestId; // req_… de la última petición

$result = $constaia->classify('passport.jpg', ['expect' => ['es_dni', 'passport']]);
$result->document->type;   // "passport"
$result->candidates;       // [{ type, confidence }, …]
$result->verdict->status;  // solo si pasas expect

$analysis = $constaia->analyses->get('an_01J…');

// Una página
$page = $constaia->analyses->list(['limit' => 20, 'status' => 'completed', 'type' => 'es_dni']);
foreach ($page as $item) { /* … */ }
$page->hasMore();

// Todas las páginas
foreach ($constaia->analyses->list(['metadata' => ['registration_id' => '123']])->autoPagingIterator() as $item) {
    echo $item->id, PHP_EOL;
}

$constaia->analyses->delete('an_01J…');

$bytes = $constaia->analyses->export('an_01J…', 'csv');                  // devuelve los bytes
$constaia->analyses->export('an_01J…', 'xlsx', storage_path('a.xlsx')); // o guarda en disco

$batch = $constaia->batches->create([
    'files' => ['dni_valid.jpg', 'nie.jpg'],   // rutas, streams o UploadedFile
    'options' => ['expect' => ['es_dni', 'es_nie'], 'export' => ['xlsx']],
]);

// o con URLs
$batch = $constaia->batches->create([
    'items' => [['file_url' => 'https://example.com/1.jpg', 'options' => ['expect' => 'es_dni']]],
]);

$constaia->batches->get($batch->id);

$types = $constaia->documentTypes->list();
$dni = $constaia->documentTypes->get('es_dni');

$balance = $constaia->balance();   // credits_available, credits_reserved, …
$usage = $constaia->usage(['from' => '2026-09-01', 'to' => '2026-09-30']);

$endpoint = $constaia->webhookEndpoints->create([
    'url' => 'https://tuapp.example/webhooks/constaia',
    'events' => ['analysis.completed', 'analysis.failed'],
]);
$endpoint->secret; // whsec_… (solo en la creación)

// En tu handler: cuerpo crudo + cabeceras + secreto
$event = \Constaia\Webhook::verify(file_get_contents('php://input'), getallheaders(), getenv('CONSTAIA_WEBHOOK_SECRET'));

$constaia->analyze($path, [
    'expect' => 'es_dni',
    'idempotency_key' => 'registration-123-dni',
    'timeout' => 90,
    'max_retries' => 0,
]);

$constaia->analyses->get('an_01J…', ['timeout' => 10]);

use Constaia\Exception\InsufficientCreditsException;
use Constaia\Exception\InvalidRequestException;

try {
    $analysis = $constaia->analyze($path, ['expect' => 'es_dni']);
} catch (InsufficientCreditsException $e) {
    // avisa al administrador
} catch (InvalidRequestException $e) {
    error_log($e->getErrorCode() . ' ' . $e->getRequestId());
}

CONSTAIA_API_KEY=ck_test_…
CONSTAIA_WEBHOOK_SECRET=whsec_…
# opcionales
CONSTAIA_TIMEOUT=60
CONSTAIA_MAX_RETRIES=2

php artisan vendor:publish --tag=constaia-config

namespace App\Http\Controllers;

use Constaia;
use Illuminate\Http\Request;

class RegistrationDocumentController
{
    public function store(Request $request)
    {
        $request->validate([
            'dni' => ['required', 'file', 'mimes:jpg,jpeg,png,webp,pdf', 'max:20480'],
        ]);

        $analysis = Constaia::analyze($request->file('dni'), [
            'expect' => ['es_dni', 'es_nie'],
            'checks' => [
                'not_expired' => true,
                'holder' => ['full_name' => $request->user()->name],
            ],
            'metadata' => ['user_id' => (string) $request->user()->id],
        ]);

        return match ($analysis->verdictStatus()) {
            'valid' => back()->with('status', 'Documento verificado.'),
            'invalid' => back()->withErrors(['dni' => $analysis->verdict->reasons[0]->message ?? 'Documento no válido.']),
            default => back()->with('status', 'Lo revisaremos manualmente.'),
        };
    }
}