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-phpLa 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
<?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
| Entrada | Se 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.
$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 soporteMé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).
<?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ón | Cuándo |
|---|---|
InvalidRequestException | 400, 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. |
AuthenticationException | 401, o no hay clave configurada. |
InsufficientCreditsException | 402. |
PermissionException | 403. |
NotFoundException | 404. |
RateLimitException | 429 tras agotar los reintentos; getRetryAfter() con los segundos de Retry-After. |
ApiException | 5xx tras agotar los reintentos (por ejemplo 503 live_mode_unavailable). |
ConnectionException | Error de red o tiempo agotado. |
SignatureVerificationException | Firma 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 hastamax_retriesveces (0los desactiva), con backoff exponencial y jitter, respetandoRetry-After. $constaia->lastRateLimit(Constaia\RateLimit:limit,remaining,reset,policy,retryAfter) guarda las cabeceras de límite de la última respuesta.- Cada
POSTlleva unaIdempotency-Key(UUID v4) que se mantiene en los reintentos: un reintento nunca cobra dos veces. Pasa la tuya conidempotency_keypara deduplicar entre procesos. Ver Idempotencia.
Laravel y WordPress
- Laravel: el paquete registra
Constaia\Clientcomo singleton y la facadeConstaia. ConfiguraCONSTAIA_API_KEYyCONSTAIA_WEBHOOK_SECRETen.envy, si quieres, publica la configuración conphp 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
SDK de JavaScript y TypeScript
Referencia de @constaia/sdk para Node.js, Bun, Deno y runtimes edge. Instalación, opciones, métodos, errores, reintentos y verificación de webhooks.
SDK de Python
Referencia del SDK oficial constaia para Python 3.9+: clientes síncrono y asíncrono, entradas, opciones, paginación, errores, concurrencia y webhooks.