# Generar sello de tiempo

Fuente: /timestamping/create-time-stamp/

Este endpoint emite un **sello de tiempo RFC 3161** sobre una huella SHA-256. El sello lo firma un
Prestador de Servicios de Certificación (PSC) autorizado y prueba que esa huella existía en la fecha
del sello.

#### **Descripción**

- Su uso principal es **incrustarlo dentro de una firma electrónica** (PAdES para PDF, CAdES), normalmente
  uno por firmante. También puedes usarlo como evidencia independiente de que un archivo existía en
  cierta fecha.
- La respuesta es **síncrona**: el sello llega en Base64 en el campo `sello`.
- Consume **5 tokens**, solo si el sello se emite y corresponde a la huella enviada.

> **¿Qué huella debo enviar?**
>
> Si vas a incrustar el sello en una firma, envía la huella que te pida tu software de firma
> (normalmente la del valor de la firma, no la del PDF completo). Si solo quieres demostrar que un
> archivo existía en cierta fecha, envía la huella del archivo; en ese caso quizá te convenga una
> [constancia NOM-151](/timestamping/create-nom151-constancy/).

**Método:**   POST

#### **Endpoint**

```
https://api.verificamex.com/identity/v1/miscellaneous/sello-tiempo
```

> **Nota**
>
> Recuerda que debes tener un token válido para realizar la solicitud.
> Puedes obtener un token siguiendo los pasos descritos en la sección [Generar tokens](/authentication/generate-tokens/).

### **Encabezados de la Solicitud**

| Encabezado | Valor | Descripción |
| - | - | - |
| Accept | `application/json` | Tipo de contenido de la solicitud. |
| Content-Type | `application/json` | Formato del cuerpo de la solicitud. |
| Authorization | `Bearer {tu_token}` | Token generado para autenticar al usuario. |

### **Cuerpo de la Solicitud**

| Parámetro | Tipo | Descripción |
| - | - | - |
| hash | `String` | **Requerido.** Huella SHA-256 a sellar: 64 caracteres en hexadecimal o 44 en Base64. |
| referencia | `String` | *Opcional.* Referencia propia para identificar el sello, por ejemplo el firmante o el documento. Máximo 255 caracteres. |

### **Ejemplo de Solicitud**

**JSON**

```json
{
    "hash": "de57da9462866cfe28619e9eb9567e6e825c71deacfd84fa0ef33929607db7ef",
    "referencia": "Firma 1 del contrato 2026-118"
}
```

**cURL**

```bash
curl -X POST https://api.verificamex.com/identity/v1/miscellaneous/sello-tiempo \
  -H "Authorization: Bearer {TU_TOKEN}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "hash": "de57da9462866cfe28619e9eb9567e6e825c71deacfd84fa0ef33929607db7ef",
    "referencia": "Firma 1 del contrato 2026-118"
  }' > respuesta.json

# Guarda el sello como archivo .tst
jq -r .sello respuesta.json | base64 -d > sello.tst
```

**PowerShell**

```powershell
$body = @{
    hash = "de57da9462866cfe28619e9eb9567e6e825c71deacfd84fa0ef33929607db7ef"
    referencia = "Firma 1 del contrato 2026-118"
} | ConvertTo-Json

$r = Invoke-RestMethod -Method Post `
    -Uri "https://api.verificamex.com/identity/v1/miscellaneous/sello-tiempo" `
    -Headers @{ Authorization = "Bearer {TU_TOKEN}"; Accept = "application/json" } `
    -ContentType "application/json" -Body $body

[IO.File]::WriteAllBytes("$PWD\sello.tst", [Convert]::FromBase64String($r.sello))
```

### Respuesta del Endpoint

**status 201**

```json
    {
        "uuid": "0c6d3a44-5f1e-4b8a-9d2c-7e1f0a9b3c21",
        "status": "OK",
        "referencia": "Firma 1 del contrato 2026-118",
        "hash": "de57da9462866cfe28619e9eb9567e6e825c71deacfd84fa0ef33929607db7ef",
        "fecha_sello": "2026-10-22T18:04:11+00:00",
        "psc": {
            "nombre": "Autoridad de Sellos digitales de tiempo de PSC WORLD",
            "serie": "11e"
        },
        "politica": "2.16.484.101.10.316.100.2.1.3.1.1",
        "sello": "MIIJ...",
        "created_at": "2026-10-22T12:04:10-06:00"
    }
```

**status 422**

```json
    {
        "message": "El hash debe ser un SHA-256: 64 caracteres en hexadecimal o 44 en Base64.",
        "errors": {
            "hash": ["El hash debe ser un SHA-256: 64 caracteres en hexadecimal o 44 en Base64."]
        }
    }
```

**status 503**

```json
    {
        "uuid": "0c6d3a44-5f1e-4b8a-9d2c-7e1f0a9b3c21",
        "status": "ERROR",
        "message": "PSC World respondió HTTP 500 al pedir el sello de tiempo."
    }
```

**status 417**

```json
    {
        "message": "No tokens available",
        "errors": []
    }
```

**status 403**

```json
    {
        "message": "Las transacciones del usuario se han terminado"
    }
```

**status 401**

```json
    {
        "message": "Unauthorized"
    }
```

El cuerpo de la respuesta exitosa contiene los siguientes campos:

| Campo | Tipo | Descripción |
| - | - | - |
| uuid | `String` | Identificador del sello. Guárdalo para [consultarlo después](/timestamping/show-time-stamp/). |
| status | `String` | `OK` cuando el sello se emitió. |
| referencia | `String` | La referencia que enviaste, o `null`. |
| hash | `String` | La huella sellada, siempre en hexadecimal en minúsculas (aunque la hayas enviado en Base64). |
| `fecha_sello` | `String` | Fecha oficial del sello asignada por el PSC, en UTC (ISO-8601). |
| `psc.nombre` | `String` | Nombre del PSC que emitió el sello, tomado de su certificado. |
| `psc.serie` | `String` | Número de serie del certificado del PSC, en hexadecimal. Puede variar entre solicitudes, porque el PSC opera con más de un certificado vigente. |
| politica | `String` | Identificador (OID) de la política del PSC con la que se emitió. |
| sello | `String` | El sello en Base64. Decodificado es un `TimeStampToken` (CMS, DER), la estructura que se incrusta en una firma PAdES/CAdES. |
| `created_at` | `String` | Fecha en que se registró la solicitud (ISO-8601). |

| Código | Cuándo ocurre | ¿Se cobra? |
| - | - | - |
| `201` | El sello se emitió. | Sí, 5 tokens. |
| `422` | La huella no es un SHA-256 válido. | No. |
| `503` | El PSC no respondió o no emitió un sello válido. Puedes reintentar. | No. |
| `417` | Tienes saldo, pero menos de los 5 tokens que cuesta. | No. |
| `403` | Ya no tienes tokens disponibles. | No. |
| `401` | Falta el token de autenticación o no es válido. | No. |

> **Revisa el sello**
>
> Ejecuta `openssl cms -verify -inform DER -in sello.tst -noverify -binary -out tstinfo.der` y después
> `openssl asn1parse -inform DER -in tstinfo.der`. El `OCTET STRING` debe ser la huella que enviaste y
> el `GENERALIZEDTIME` la misma fecha que `fecha_sello`. Ver
> [Guarda y verifica el archivo](/timestamping/introduction/#3-guarda-y-verifica-el-archivo).