---
title: "Visibilidad y entrega"
description: "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."
---

> Documentation Index
> Fetch the complete documentation index at: https://sovra-id-docs-1044960690985.us-central1.run.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Visibilidad y entrega

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](https://sovra-id-docs-1044960690985.us-central1.run.app/documentos/estados-y-revocacion/).

## Publicar o despublicar

Una llamada sin body: el valor (`public` o `private`) va en la URL.

```bash
# 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](https://sovra-id-docs-1044960690985.us-central1.run.app/documentos/emitir/#la-respuesta), con `visibility` actualizada. Nada más cambia: el documento no se reemite. En la referencia: [`make-document-public`](https://sovra-id-docs-1044960690985.us-central1.run.app/api/make-document-public/) y [`make-document-private`](https://sovra-id-docs-1044960690985.us-central1.run.app/api/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.

> **Volver a privado no recupera nada**
>
> Un `credential` ya entregado sigue legible y verificable por quien lo tenga, para siempre. Privado significa "el enlace por sí solo no basta", nunca "los bytes son secretos". Para invalidar un documento existe la [revocación](https://sovra-id-docs-1044960690985.us-central1.run.app/documentos/estados-y-revocacion/#revocación).

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](https://sovra-id-docs-1044960690985.us-central1.run.app/api/documents/retrieve/)).

```bash
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](https://sovra-id-docs-1044960690985.us-central1.run.app/documentos/emitir/#listar-los-documentos-del-workspace).
- 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](https://sovra-id-docs-1044960690985.us-central1.run.app/documentos/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. |

> **Los valores no vienen sueltos**
>
> `schema.claims[]` trae solo las definiciones de los campos. Los valores (el `1234567`, el `"Contenido de Prueba"`) están dentro del `credential`. Ver [Renderizado](https://sovra-id-docs-1044960690985.us-central1.run.app/documentos/renderizado/#las-tres-cosas-que-el-json-no-trae).

**`200 OK`** (objeto **PublicDocument**):

```json
{
  "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](https://sovra-id-docs-1044960690985.us-central1.run.app/documentos/renderizado/) 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.

| 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](https://sovra-id-docs-1044960690985.us-central1.run.app/errores/documentos/).

Source: https://sovra-id-docs-1044960690985.us-central1.run.app/documentos/visibilidad-y-entrega/index.mdx
