Emitir es una sola llamada: Sovra valida los datos contra el esquema, los firma con tu llave y responde al instante. El anclaje on-chain (el registro de la firma en la cadena) corre después, en segundo plano. Hasta que termine, el documento todavía no se puede entregar.
Necesitás un esquema de kind document en estado registered (Crear un esquema) y una API key (Primeros pasos).
La llamada
curl -s -X POST "$BASE_URL/api/v1/issuer/documents" \
-H "Authorization: Bearer $SOVRA_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"schema_id": "document_example",
"claims": {
"date": "20-08-2026",
"idDocument": 1234567,
"content": "Contenido de Prueba",
"isConfidential": false
}
}'schema_id(obligatorio): el identificador legible del esquema, no su UUID. Se usa su última versión.claims: un objeto con un valor por cada campo del esquema. Losrequiredno pueden faltar. Los valores se firman tal cual:"42"y42son documentos distintos.visibility:"private"(el default) o"public". Ver Visibilidad y entrega.valid_until: una fecha ISO 8601 a futuro, si querés pisar la vigencia del esquema. No mandesnull: omitilo.
Todos los detalles del request están en la referencia de API.
La respuesta
Responde 201 Created con el documento. Estos son los campos que vas a usar:
| Campo | Qué es |
|---|---|
credential |
El documento en sí: un string firmado que cualquiera puede verificar. |
id |
El identificador del documento, para el enlace público y para cambiar la visibilidad. |
status |
En la emisión es siempre signed. Después pasa a anchored o failed. |
tx_hash |
La transacción del anclaje. null hasta que el anclaje confirme. |
{
"id": "63813a91-6986-46bf-9f23-128a6598cd82",
"status": "signed",
"visibility": "private",
"credential": "eyJhbGciOiJFUzI1NiIsInR5cCI6InZjK3Nk…eyJjb250ZW50…~",
"tx_hash": null,
"…": "…"
}La respuesta completa, campo por campo
{
"id": "63813a91-6986-46bf-9f23-128a6598cd82",
"status": "signed",
"visibility": "private",
"credential": "eyJhbGciOiJFUzI1NiIsInR5cCI6InZjK3Nk…eyJjb250ZW50…~",
"claims": {
"date": "20-08-2026",
"idDocument": 1234567,
"content": "Contenido de Prueba",
"isConfidential": false
},
"digest": "1043…",
"tx_hash": null,
"signed_at": "2026-08-21T14:12:34Z",
"anchored_at": null,
"revoked_at": null,
"issuer": {
"did": "did:sovra:0xb516d2f945db504198d726bda2a01d19ecd3cc23",
"name": "Lotería de San Juan",
"address": "0xb516d2f945db504198d726bda2a01d19ecd3cc23"
},
"schema": {
"id": "3f2b…",
"schema_id": "document_example",
"credential_type": "Document",
"name": "Document Example",
"version": 1,
"claims": [ /* … */ ]
}
}Este objeto (Document) es el mismo que devuelven el cambio de visibilidad y cada entrada del listado. La columna Firmado dice si el dato está cubierto por la firma (vive dentro del credential) o si es una afirmación del servicio. Ver las dos capas de confianza.
| Campo | Qué es | Firmado |
|---|---|---|
id |
Identificador del documento. Coincide con el claim jti del credential, así que una credencial no puede servirse bajo otro id. |
Sí (como jti) |
status |
signed, anchored, failed o revoked. Ver Estados y revocación. |
No |
visibility |
public o private. |
No |
credential |
El documento: un SD-JWT VC en base64url, autocontenido. | Es la firma |
claims |
Los mismos claims decodificados, por conveniencia. No prueba nada. | Sí, adentro del credential |
digest |
SHA-256 (hex) de los bytes que se firmaron. Es la clave bajo la cual la firma queda anclada; la verificación lo recalcula. | No (se recalcula) |
tx_hash |
Hash de la transacción del anclaje. null hasta que confirme. |
No |
signed_at |
Cuándo se firmó. | Sí (como iat) |
anchored_at |
Cuándo quedó anclada la firma. null hasta que confirme. |
No |
revoked_at |
null = vigente. Con fecha, revocado. |
No |
issuer.did |
El DID del emisor (did:sovra:0x…); con él se resuelve su clave pública on-chain. |
Sí (como iss) |
issuer.address |
La dirección del emisor en la cadena. | Sí, se deriva de iss |
issuer.name |
Nombre visible del emisor. Un verificador no debería usarlo para decidir. | No |
schema.credential_type |
Viaja como vct en el documento; contra él se comprueba on-chain si el emisor está autorizado. |
Sí (como vct) |
schema.id, schema_id, name, version, claims[] |
El molde usado: UUID, identificador legible, nombre, versión y definición de cada campo. | No |
Esperá el anclaje antes de entregar
El 201 llega con status: "signed" y tx_hash: null: la firma existe, pero todavía no está en la cadena. Cuando el anclaje termina, Sovra te manda el webhook document.status-changed con el estado final:
anchored: listo para entregar. Traetx_hashyanchored_at.failed: el anclaje no confirmó después de 5 intentos. No se puede reintentar: hay que volver a emitirlo.
Si no podés recibir webhooks, consultá el listado hasta ver anchored. El ciclo completo está en Estados y revocación.
Qué guardar
Guardá el credential. Es el documento; todo lo demás se puede volver a pedir. Conviene guardar también el id (para el enlace y la visibilidad) y el tx_hash cuando llegue por webhook (para enlazar al explorer de la cadena).
Listar los documentos del workspace
GET /api/v1/issuer/documents devuelve todos tus documentos, en todos los estados, del más nuevo al más viejo. Cada entrada trae el credential completo, así que con una llamada recuperás todo lo emitido.
curl -s "$BASE_URL/api/v1/issuer/documents" \
-H "Authorization: Bearer $SOVRA_API_KEY"No tiene paginación ni filtros: si necesitás buscar, indexá de tu lado a partir de este listado. Y si ese índice lo pueden consultar terceros, incluí solo los documentos public: servir un privado por búsqueda anula la decisión del emisor.
Límites y lo que no existe
Límites
| Recurso | Límite |
|---|---|
| Cuerpo de un request | 8 MB |
| Intentos de anclaje de un documento | 5 |
| Throughput del anclaje | Del orden de 5 documentos por bloque y por nodo |
| Layout de un documento | 3 MB |
Techo de un QR con el credential (nivel L) |
~2953 bytes |
| Tamaño de cada entrada del listado | Un SD-JWT completo (~520 bytes en el ejemplo de esta documentación) |
Lo que no existe, a propósito
| No hay | Qué usar en cambio |
|---|---|
| Endpoint de verificación | La verificación corre del lado de quien verifica, contra la cadena. Ver Verificación. |
| Endpoints de layout | El layout se diseña en el dashboard. Ver Crear un esquema. |
| Búsqueda, filtros o paginación | ?digest=, /by-digest/, /search, ?page y ?limit no existen; los query params se ignoran. Indexá a partir del listado. |
| Endpoint de revocación | La baja se gestiona desde el dashboard. Ver Estados y revocación. |
GET de un documento propio por la zona emisor |
El listado; para uno solo, la zona pública. |
| Reintento del anclaje | Un failed se vuelve a emitir. |
Errores comunes al emitir
| Respuesta | Causa | Qué revisar |
|---|---|---|
401 invalid_api_key |
Key desconocida, malformada o revocada, o el header no decía literalmente Bearer. |
Que diga Bearer con B mayúscula. |
404 schema_not_found |
No hay esquema con ese schema_id en este workspace. |
El slug. |
409 workspace_not_provisioned |
El workspace todavía no tiene DID ni claves. | Aprovisionarlo desde el dashboard y esperar el DID. |
409 schema_registration_pending |
El esquema se sigue registrando on-chain. | Esperar unos segundos y reintentar. |
409 schema_registration_failed |
El esquema no pudo registrarse. | Crearlo de nuevo, o pedir ayuda al equipo de Sovra. |
422 wrong_schema_kind |
El esquema es de kind credential. |
Usar un esquema de documentos. |
422 missing_claims |
Falta un claim requerido. La respuesta lista cuáles. | Los required del esquema. |
422 invalid_visibility |
visibility no es public ni private. |
El body. |
422 invalid_valid_until |
valid_until es null, está malformado o en el pasado. |
El body, o omitilo. |
422 validation_error |
El documento no pudo guardarse. details nombra el campo. |
La respuesta. |
500 |
Falta schema_id, o claims no es un objeto. |
El body. |
503 chain_not_configured |
No hay registro de firmas configurado: el servicio se niega a firmar algo que no podría anclar. | Contactá al equipo de Sovra. |
El sobre de error es siempre el mismo:
{ "error": "missing_claims", "details": ["content", "idDocument"] }La tabla completa está en Errores de documentos.
Colección de Postman
La colección de Postman trae los requests de emitir, cambiar la visibilidad, listar y leer un documento. Configurá base_url (sin slash final), api_key y schema_id; el document_id se completa solo al emitir, así que el orden natural es emitir → cambiar visibilidad → leer.
Qué trae la colección
| Variable | Valor |
|---|---|
base_url |
URL base de la API, sin slash final. |
api_key |
La key del workspace. Solo la usan los requests de /issuer. Vaciala antes de exportar o compartir la colección. |
schema_id |
Id del esquema de kind document. |
document_id |
Se autocompleta al emitir. |
| Request | Llamada | Qué testea |
|---|---|---|
| Emitir documento | POST {{base_url}}/api/v1/issuer/documents |
201 y que credential sea un string. |
| Visibilidad → public / private | PUT …/issuer/documents/{{document_id}}/visibility/public o /private |
200 y el valor nuevo de visibility. |
| Listar documentos | GET {{base_url}}/api/v1/issuer/documents |
200 y que documents sea un array. |
| Obtener documento (sin API key) | GET {{base_url}}/api/v1/documents/{{document_id}} |
200 o 401, según si está publicado. |
Un 401 en el último request no es una falla: es la respuesta correcta para un documento privado. Y el test de emisión no comprueba que el documento esté anclado: recién emitido va a estar signed.
La colección todavía no incluye los endpoints de esquemas: para crear el esquema por API, usá el curl de Crear un esquema.