Constaia
SDKs

SDK de PHP

Referencia de constaia/constaia-php para PHP 8.1+: instalación con Composer, entradas, opciones, métodos, paginación, excepciones, reintentos y webhooks.

constaia/constaia-php es el SDK oficial para PHP. Requiere PHP ≥ 8.1 con ext-curl y ext-json; no usa Guzzle ni otras dependencias. Incluye integración con Laravel (se autodescubre). Versión actual: 0.2.0.

composer require constaia/constaia-php

La clave vive en el servidor

Nunca imprimas la clave en una página ni la pases a JavaScript. En el navegador usa el widget apuntando a una ruta de tu backend.

Configuración

bootstrap.php
<?php
require __DIR__ . '/vendor/autoload.php';

$constaia = new \Constaia\Client(null, [ // null → lee CONSTAIA_API_KEY
    'base_url' => 'https://api.constaia.com', // o CONSTAIA_BASE_URL
    'timeout' => 60,                          // segundos por intento
    'max_retries' => 2,                       // en 408, 409, 429, 5xx y errores de red
    'max_concurrency' => 4,                   // peticiones en paralelo en analyzeMany()
    'headers' => [],                          // cabeceras extra en todas las peticiones
]);

Si no hay clave (ni argumento ni CONSTAIA_API_KEY), el constructor lanza AuthenticationException con el código missing_api_key.

Qué ficheros acepta

EntradaSe envía como
Ruta local '/tmp/dni.jpg'multipart (file + options en JSON)
Stream abierto (fopen(…), php://memory)multipart
SplFileInfo, incluido UploadedFile de Laravel o Symfony (usa el nombre y el tipo originales)multipart
URL 'https://…'JSON file_url
['base64' => '…', 'filename' => 'dni.jpg']JSON file_base64 + filename
['file_url' => 'https://…']JSON file_url

Usa la opción filename para forzar el nombre (útil con streams y, en modo test, para elegir el escenario).

Opciones

Las opciones usan los mismos nombres snake_case que la API. Además, cada método acepta opciones de petición que no se envían a la API: filename, idempotency_key, timeout, max_retries y headers.

verify.php
$analysis = $constaia->analyze($path, [
    'expect' => ['es_dni', 'es_nie', 'passport'], // sin expect, veredicto contra el tipo detectado
    'extract' => true,                            // o tu propio JSON Schema
    'checks' => [
        'not_expired' => true,
        'min_age_years' => 18,
        'holder' => ['full_name' => 'María García López', 'document_number' => '12345678Z'],
    ],
    'storage' => 'none',                          // none | temporary | persistent
    'ttl_hours' => 24,                            // con storage=temporary
    'keep_results' => true,
    'async' => false,                             // true → 202 y webhook
    'export' => ['xlsx'],                         // URLs firmadas en $analysis->exports
    'metadata' => ['registration_id' => '123'],
    'language' => 'es',                           // es | en | pt | fr

    // Opciones de petición (no van a la API)
    'filename' => 'dni_valid.jpg',
    'idempotency_key' => 'registration-123-dni',
    'timeout' => 90,
]);

Cada opción se explica en POST /v1/analyze y Comprobaciones.

Leer el resultado

analyze() devuelve un Constaia\Analysis. Los objetos se leen como propiedades o como arrays; una clave que no existe devuelve null sin avisos.

$analysis->verdict->status;            // "valid" | "invalid" | "review"
$analysis['verdict']['status'];        // igual, como array
$analysis->fields->document_number->value;

$analysis->verdictStatus();            // null si no hay veredicto (p. ej. documento generic sin expect)
$analysis->isValid();
$analysis->isInvalid();
$analysis->needsReview();
$analysis->isCompleted();              // false si la API respondió 202
$analysis->field('birth_date');        // atajo de fields.birth_date.value

foreach ($analysis->verdict->reasons as $reason) {
    echo $reason->code, ' (', $reason->severity, '): ', $reason->message, PHP_EOL;
}

$analysis->toArray();
json_encode($analysis);                // JsonSerializable

$constaia->lastResponse->status;       // HTTP de la última llamada
$constaia->lastResponse->requestId;    // X-Request-Id: inclúyelo si escribes a soporte

Métodos

// Clasificar (0,2 créditos)
$c = $constaia->classify($input, ['expect' => 'invoice']);
$c->document->type;
$c->candidates[0]->confidence;

// Análisis guardados
$constaia->analyses->get('an_01J…');
$page = $constaia->analyses->list([
    'limit' => 50,
    'status' => 'completed',
    'type' => 'es_dni',
    'metadata' => ['registration_id' => '123'],
]);
$constaia->analyses->delete('an_01J…');                          // { id, object, deleted: true }
$bytes = $constaia->analyses->export('an_01J…', 'xlsx');         // bytes
$constaia->analyses->export('an_01J…', 'csv', '/tmp/an.csv');    // guarda en disco y devuelve la ruta

// Revisión humana (solo clave secreta)
$pending = $constaia->reviews->list(['status' => 'pending']);      // más antiguos primero; autoPagingIterator()
$bytes = $constaia->analyses->file('an_01J…');                      // el original; 404 file_not_stored si ya no está
$constaia->analyses->review('an_01J…', ['decision' => 'approve', 'reason' => 'Datos correctos'],
    ['idempotency_key' => 'review-an_01J…']);                       // devuelve el análisis actualizado

// Lotes (hasta 100 documentos, siempre asíncronos)
$batch = $constaia->batches->create([
    'items' => [
        ['file_url' => 'https://example.com/a.pdf'],
        ['file_url' => 'https://example.com/b.pdf', 'options' => ['checks' => ['expected_amount' => 45]]],
    ],
    'options' => ['expect' => 'payment_receipt', 'export' => ['xlsx']],
]);
$batch = $constaia->batches->create([
    'files' => ['/tmp/a.pdf', '/tmp/b.pdf'],                      // multipart files[]
    'options' => ['expect' => 'invoice'],
]);
$constaia->batches->get($batch->id);

// Catálogo
$constaia->documentTypes->list(['language' => 'es']);
$constaia->documentTypes->get('es_dni');

// Endpoints de webhook (el secreto solo se devuelve al crear)
$endpoint = $constaia->webhookEndpoints->create([
    'url' => 'https://example.com/webhooks/constaia',
    'events' => ['analysis.completed', 'analysis.review_required', 'batch.completed'],
]);
$endpoint->secret; // whsec_…
$constaia->webhookEndpoints->list();
$constaia->webhookEndpoints->get('we_01J…');
$constaia->webhookEndpoints->delete('we_01J…');

// Saldo y uso
$constaia->balance();
$constaia->usage(['from' => '2026-09-01', 'to' => '2026-09-30']);

Varios documentos en paralelo

analyzeMany() analiza varios documentos a la vez con curl_multi, con como máximo max_concurrency peticiones en vuelo (por defecto 4). Conserva las claves del array y, en lugar de lanzar, devuelve la excepción en la posición del documento que falló.

use Constaia\Exception\ConstaiaException;

$results = $constaia->analyzeMany(
    ['ana' => '/tmp/dni_ana.jpg', 'luis' => '/tmp/dni_luis.jpg'],
    ['expect' => 'es_dni', 'checks' => ['not_expired' => true]],
);

foreach ($results as $who => $result) {
    if ($result instanceof ConstaiaException) {
        echo "$who: error {$result->getErrorCode()}", PHP_EOL;
        continue;
    }
    echo "$who: ", $result->verdictStatus(), PHP_EOL;
}

Para más de unos pocos documentos, o si no necesitas la respuesta al momento, usa lotes.

Paginación

analyses->list() devuelve un Constaia\Collection con la primera página. foreach recorre solo esa página; autoPagingIterator() (o all()) recorre todas pidiendo las siguientes con starting_after.

$page = $constaia->analyses->list(['limit' => 100, 'type' => 'es_dni']);

$page->data();     // array de la página actual
$page->hasMore();
$next = $page->nextPage(); // null si no hay más

foreach ($page->autoPagingIterator() as $analysis) {
    echo $analysis->id, ' ', $analysis->verdictStatus(), PHP_EOL;
}

Más en Paginación.

Webhooks

Constaia\Webhook::verify() comprueba la firma Standard Webhooks con el cuerpo sin procesar y devuelve el evento como array asociativo. Acepta las cabeceras de getallheaders() o el array $_SERVER (HTTP_WEBHOOK_ID…). Tolerancia por defecto: 300 segundos (cuarto argumento).

webhook.php
<?php
require __DIR__ . '/vendor/autoload.php';

use Constaia\Exception\SignatureVerificationException;
use Constaia\Webhook;

$payload = file_get_contents('php://input');

try {
    $event = Webhook::verify($payload, $_SERVER, getenv('CONSTAIA_WEBHOOK_SECRET'));
} catch (SignatureVerificationException $e) {
    http_response_code(400);
    exit;
}

switch ($event['type']) {
    case 'analysis.completed':
    case 'analysis.review_required':
        // $event['data'] es el análisis
        break;
    case 'analysis.failed':
    case 'batch.completed':
    case 'credits.low':
        break;
}

http_response_code(204);

Para tus tests, Webhook::headers($payload, $secret) genera cabeceras firmadas como las de Constaia y Webhook::sign($id, $timestamp, $payload, $secret) solo la firma. Más en Webhooks.

Excepciones

Todas heredan de Constaia\Exception\ConstaiaException y exponen getType(), getErrorCode(), getParam(), getRequestId() y getHttpStatus() (también como propiedades type, errorCode, param, requestId, httpStatus).

ExcepciónCuándo
InvalidRequestException400, 409, 413, 415 y 422 (fichero u opción no válidos, tamaño, tipo, idempotencia). También en local si el fichero no se puede leer.
AuthenticationException401, o no hay clave configurada.
InsufficientCreditsException402.
PermissionException403.
NotFoundException404.
RateLimitException429 tras agotar los reintentos; getRetryAfter() con los segundos de Retry-After.
ApiException5xx tras agotar los reintentos (por ejemplo 503 live_mode_unavailable).
ConnectionExceptionError de red o tiempo agotado.
SignatureVerificationExceptionFirma de webhook no válida.
use Constaia\Exception;

try {
    $analysis = $constaia->analyze($path, ['expect' => 'es_dni']);
} catch (Exception\InsufficientCreditsException $e) {
    // Avisa a quien gestiona la cuenta y reintenta más tarde
} catch (Exception\RateLimitException $e) {
    sleep($e->getRetryAfter() ?? 1);
} catch (Exception\InvalidRequestException $e) {
    echo $e->getErrorCode(), ' ', $e->getParam(), ': ', $e->getMessage();
} catch (Exception\ConstaiaException $e) {
    error_log(sprintf('Constaia %s %s (%s)', $e->getHttpStatus(), $e->getErrorCode(), $e->getRequestId()));
}

Todos los códigos, en Errores.

Reintentos e idempotencia

  • Reintenta 408, 409 idempotency_in_progress, 429, 5xx (nunca 501) y errores de red hasta max_retries veces (0 los desactiva), con backoff exponencial y jitter, respetando Retry-After.
  • $constaia->lastRateLimit (Constaia\RateLimit: limit, remaining, reset, policy, retryAfter) guarda las cabeceras de límite de la última respuesta.
  • Cada POST lleva una Idempotency-Key (UUID v4) que se mantiene en los reintentos: un reintento nunca cobra dos veces. Pasa la tuya con idempotency_key para deduplicar entre procesos. Ver Idempotencia.

Laravel y WordPress

  • Laravel: el paquete registra Constaia\Client como singleton y la facade Constaia. Configura CONSTAIA_API_KEY y CONSTAIA_WEBHOOK_SECRET en .env y, si quieres, publica la configuración con php artisan vendor:publish --tag=constaia-config. Guía completa en Laravel.
  • WordPress: el repositorio del SDK incluye un plugin de ejemplo con shortcode y ruta REST. Ver WordPress.

Plantillas, expedientes, sesiones y privacidad

El SDK también cubre $constaia->templates, $constaia->dossiers, $constaia->sessions, $constaia->analytics() y $constaia->analyses->deleteByMetadata() / exportByMetadata(). Los campos y ejemplos están en Plantillas, Expedientes, Sesiones y claves publicables, Analítica y Privacidad avanzada.

Siguientes pasos

En esta página