Todo documento nace privado. Publicarlo sirve para compartir un enlace que cualquiera puede abrir. Esta página cubre cómo publicar y despublicar, cómo lee el documento quien lo recibe y las dos formas de entregarlo.
Antes de entregar, el documento tiene que estar anchored: ver Estados y revocación.
Publicar o despublicar
Una llamada sin body: el valor (public o private) va en la URL.
# publicarlo
curl -s -X PUT -H "Authorization: Bearer $SOVRA_API_KEY" \
"$BASE_URL/api/v1/issuer/documents/$DOCUMENT_ID/visibility/public"
# y volverlo privado
curl -s -X PUT -H "Authorization: Bearer $SOVRA_API_KEY" \
"$BASE_URL/api/v1/issuer/documents/$DOCUMENT_ID/visibility/private"Responde 200 OK con el mismo objeto que la emisión, con visibility actualizada. Nada más cambia: el documento no se reemite. En la referencia: make-document-public y make-document-private.
Qué restringe la visibilidad, y qué no
La visibilidad restringe el enlace, no el documento.
public: tener elido el enlace alcanza para leerlo.private: el enlace solo no alcanza; hace falta sesión del dashboard.
La visibilidad tampoco forma parte del documento: no está cubierta por la firma. Y si construís un buscador o índice que consultan terceros, incluí solo documentos public: servir un privado por búsqueda anula la decisión del emisor.
Leer un documento: la zona pública
Quien recibe el documento lo lee con GET /api/v1/documents/{id}: sin /issuer y sin API key (referencia).
curl -s "$BASE_URL/api/v1/documents/$DOCUMENT_ID"- Si es público, tener el
idalcanza. - Si es privado, responde
401 authentication_required, incluso con una API key. Tu integración lee sus propios documentos con el listado. - Responde con
Access-Control-Allow-Origin: *, así que se puede llamar directo desde el navegador.
La respuesta trae lo necesario para mostrar y verificar el documento:
| Campo | Qué es |
|---|---|
credential |
El documento en sí. Lo único verificable de toda la respuesta. |
layout |
Cómo dibujar la hoja. Ver Renderizado. |
anchor |
status, tx_hash y anchored_at del anclaje. |
issuer |
name, did y address del emisor. El nombre es solo informativo. |
schema |
El nombre del esquema y la definición de cada campo. |
La respuesta completa, campo por campo
200 OK (objeto PublicDocument):
{
"id": "63813a91-6986-46bf-9f23-128a6598cd82",
"issuer": {
"name": "Lotería de San Juan",
"address": "0xb516d2f945db504198d726bda2a01d19ecd3cc23",
"did": "did:sovra:0xb516d2f945db504198d726bda2a01d19ecd3cc23"
},
"schema": {
"name": "Document Example",
"claims": [
{
"disclosable": true,
"key": "date",
"label": "Date",
"required": true,
"type": "date"
},
{
"disclosable": true,
"key": "idDocument",
"label": "ID Document",
"required": true,
"type": "number"
},
{
"disclosable": true,
"key": "content",
"label": "Content",
"required": true,
"type": "string"
},
{
"disclosable": true,
"key": "isConfidential",
"label": "Confidencial",
"required": true,
"type": "boolean"
}
]
},
"layout": {
"elements": [
{
"bold": true,
"color": "#111827",
"id": "title",
"size": 26,
"type": "text",
"value": "Document Example",
"x": 283,
"y": 56
},
{
"bold": true,
"color": "#111827",
"id": "emt2553os0",
"size": 14,
"type": "text",
"value": "Date",
"x": 600,
"y": 128
},
{
"bind": "date",
"color": "#111827",
"id": "emt25542s1",
"size": 14,
"type": "field",
"x": 648,
"y": 128
},
{
"bold": true,
"color": "#111827",
"id": "emt2555sp2",
"size": 14,
"type": "text",
"value": "Content",
"x": 48,
"y": 208
},
{
"bold": true,
"color": "#111827",
"id": "emt25578k3",
"size": 14,
"type": "text",
"value": "Confidencial",
"x": 48,
"y": 872
},
{
"bind": "isConfidential",
"color": "#111827",
"id": "emt2558k94",
"size": 14,
"type": "field",
"x": 152,
"y": 872
},
{
"bind": "content",
"color": "#111827",
"id": "emt255ha05",
"size": 14,
"type": "field",
"x": 48,
"y": 240
},
{
"bold": true,
"color": "#111827",
"id": "emt255sub6",
"size": 14,
"type": "text",
"value": "ID Document",
"x": 48,
"y": 128
},
{
"bind": "idDocument",
"color": "#111827",
"id": "emt255xr77",
"size": 14,
"type": "field",
"x": 152,
"y": 128
}
],
"page": {
"height": 1123,
"width": 794
}
},
"anchor": {
"status": "anchored",
"tx_hash": "0x9c93c1eec04ae7e4566b4ee394ac518b33c36b0ffd324276289e998eed72f8ca",
"anchored_at": "2026-08-21T14:12:43Z"
},
"credential": "eyJhbGciOiJFUzI1NiIsInR5cCI6InZjK3NkLWp3dCJ9.eyJjb250ZW50IjoiQ29udGVuaWRvIGRlIFBydWViYSIsImRhdGUiOiIyMC0wOC0yMDI2IiwiZXhwIjoxODE4ODU3NTU0LCJpYXQiOjE3ODczMjE1NTQsImlkRG9jdW1lbnQiOjEyMzQ1NjcsImlzQ29uZmlkZW50aWFsIjpmYWxzZSwiaXNzIjoiaHR0cHM6Ly90ZXN0LWFwaS1zb3ZyYS5mbGFnb25zYS5jb20vZGlkOnNvdnJhOjB4YjUxNmQyZjk0NWRiNTA0MTk4ZDcyNmJkYTJhMDFkMTllY2QzY2MyMyIsImp0aSI6IjYzODEzYTkxLTY5ODYtNDZiZi05ZjIzLTEyOGE2NTk4Y2Q4MiIsInZjdCI6IkRvY3VtZW50In0.FEArm9ydMriuvLaIij1i6f02ZxrFkvOC3YXDfL8RWsAfiuS-l1VfxaJPjqBqVeNnwjSds48ZhVbRpO4UBeyGHQ~"
}El orden de las claves del JSON no es estable, pero el orden de layout.elements[] sí importa: es el orden de pintado, y no coincide con el orden visual de la hoja.
| Campo | Qué es | Firmado |
|---|---|---|
id |
El identificador del documento, el mismo de la URL. | Sí (como jti) |
credential |
El documento en sí. | Es la firma |
issuer.did |
El DID del emisor; 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. Solo informativo. | No |
schema.name |
Nombre del esquema. Acá no vienen el UUID ni el credential_type. |
No |
schema.claims[] |
Definición de cada campo: key, label, type, required, disclosable. |
No |
layout |
Instrucciones para dibujar la hoja. | No |
anchor.status |
anchored = la firma quedó registrada on-chain. |
No |
anchor.tx_hash |
Hash de la transacción del anclaje. | No |
anchor.anchored_at |
Cuándo quedó anclada. | No |
Comparada con la respuesta de emisión, esta trae layout y agrupa los datos del anclaje en anchor, pero no trae claims decodificados, visibility, signed_at, revoked_at, digest, ni schema.id, schema.schema_id o schema.credential_type. La emisión le responde al emisor; la lectura pública, a quien necesita dibujar el documento.
Los caminos de entrega
Hay dos formas de hacerle llegar el documento a alguien, y las dos terminan en el mismo credential:
| Camino | Qué mandás | Cuándo conviene |
|---|---|---|
| El string | El credential completo: por correo, en un archivo, en un QR impreso, dentro de un PDF. |
Cuando querés que el documento sobreviva a la API. No hace falta que sea público ni que Sovra esté en línea. |
| El enlace | $BASE_URL/api/v1/documents/{id} |
Cuando querés una URL para compartir. Requiere visibility: "public", y quien la abre tiene que renderizar el JSON. |
- El QR de una hoja impresa debería llevar el
credential, no un link. Así quien lo escanea verifica contra la cadena aunque el servicio ya no exista. - Publicar no es autorizar. El
ides un UUID v4 y no se adivina, pero si se filtra, el documento se lee.
Errores de visibilidad y lectura pública
| Respuesta | Dónde | Causa |
|---|---|---|
401 invalid_api_key |
PUT …/visibility/… |
Key inválida, o el header no decía literalmente Bearer. |
422 invalid_visibility |
PUT …/visibility/… |
El último segmento del path no es public ni private. |
401 authentication_required |
GET /api/v1/documents/{id} |
El documento es privado y no hay sesión del dashboard (la cookie document_session o Authorization: Bearer con el token de sesión). Pasa incluso con una API key en el header. No es una falla de tu integración: es la respuesta correcta. |
404 document_not_found |
Los dos | Id inexistente, malformado o de otro workspace. No distingue entre los tres casos, a propósito. |
La tabla completa está en Errores de documentos.