Skip to content

Visibilidad y entrega

Cómo publicar o despublicar un documento firmado, qué cambia (y qué no) al hacerlo, y las dos formas de hacérselo llegar a alguien.

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 el id o 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 id alcanza.
  • 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 id es 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.

Type to search…

↑↓ navigate↵ selectEsc close