Versionado y changelog
Cómo versiona Constaia su API (v1 en la ruta) y sus SDK, qué cambios compatibles pueden llegar sin aviso y cómo escribir código que no se rompa con ellos.
Versión de la API
La versión va en la ruta: todas las llamadas son https://api.constaia.com/v1/…. La especificación OpenAPI
(https://api.constaia.com/openapi.json) declara info.version 1.0.0.
Dentro de v1 mantenemos la compatibilidad hacia atrás: el código que funciona hoy contra v1 debe seguir
funcionando.
Cambios compatibles (pueden llegar sin aviso)
Dentro de v1 podemos publicar en cualquier momento cambios que no rompen integraciones bien escritas:
- Campos nuevos en las respuestas (por ejemplo, un objeto nuevo en el análisis).
- Códigos nuevos de motivo (
verdict.reasons[].code), de comprobación (checks[].code), de aviso (warnings) y de error (error.code). - Tipos de documento nuevos en el catálogo y campos nuevos en los tipos existentes.
- Parámetros opcionales nuevos en las peticiones y opciones nuevas en
optionsooptions.checks. - Eventos de webhook nuevos (solo los recibes si te suscribes a ellos o usas
*). - Cambios en la redacción de los
message.
Tu código debe estar preparado:
| Haz | No hagas |
|---|---|
| Ignora los campos que no conoces. | Validar las respuestas con un esquema estricto que rechace campos extra. |
Trata un código de motivo desconocido según su severity. | Fallar con un switch sin caso por defecto. |
Trata un código de error desconocido según el estado HTTP y type. | Suponer que la lista de códigos es cerrada. |
| Trata un aviso desconocido como una señal más para revisión. | Rechazar un documento por un aviso que no conoces. |
Programa contra code, nunca contra message. | Comparar textos de message. |
| Ignora los eventos de webhook que no manejas y responde 2xx. | Responder error a un tipo de evento desconocido (se reintentaría durante días). |
import type { Analysis } from "@constaia/sdk";
export function decide(analysis: Analysis): "accept" | "reject" | "review" {
const reasons = analysis.verdict?.reasons ?? [];
if (reasons.some((r) => r.severity === "error")) return "reject";
if (reasons.some((r) => r.severity === "warning")) return "review";
return "accept"; // también cubre códigos que aún no conocemos
}Opciones estrictas
Las opciones que envías son estrictas: una clave que no existe devuelve 422 invalid_parameter. Así un error
tipográfico nunca se ignora en silencio. Por eso, si usas una opción nueva, asegúrate de que ya está disponible (el
changelog lo indica).
Cambios incompatibles
Nuestra política: un cambio que rompa integraciones existentes (quitar o renombrar un campo, cambiar su tipo o su
significado, hacer obligatorio un parámetro opcional) no se publica dentro de v1. Llegaría como una nueva versión
en la ruta (/v2), anunciada con antelación en el changelog, y v1
seguiría funcionando durante un periodo de transición.
SDK
Los SDK siguen versionado semántico: los cambios incompatibles solo llegan en una nueva
versión mayor. Mientras estén en 0.x, una versión menor (0.1 → 0.2) puede incluir cambios incompatibles; fija
la versión menor en tu gestor de dependencias y revisa el changelog antes de actualizar.
| Paquete | Registro | Versión actual |
|---|---|---|
@constaia/sdk (JavaScript / TypeScript) | npm | 0.2.0 |
constaia/constaia-php | Packagist | 0.2.0 |
constaia (Python) | PyPI | 0.2.0 |
@constaia/widget | npm | 0.1.0 |
@constaia/mcp | npm | 0.1.0 |
npm i @constaia/sdk@~0.2.0
composer require constaia/constaia-php:~0.2.0
pip install "constaia~=0.2.0"Guías: JavaScript, PHP, Python, widget y MCP.
Changelog
Todos los cambios de la API, el catálogo y los SDK se publican en el changelog.
Siguientes pasos
Créditos y facturación
Cómo se calculan los créditos por página, qué no se cobra, plan gratis de 150 créditos al mes, packs en EUR y USD, caducidad, saldo, alertas y error 402.
Seguridad
Seguridad con Constaia, cómo guardar y rotar claves de API, verificar webhooks, proteger tu endpoint de subida y no fiarte de veredictos del navegador.