---
title: "API: Certificados"
description: Subida, listado y eliminación del certificado digital .p12 con el que Notta firma tus DTE, cifrado con envelope encryption por organización
url: https://notta.cl/docs/api/certificates
related:
  - https://notta.cl/docs/onboarding-cert
  - https://notta.cl/docs/api/caf
  - https://notta.cl/docs/authentication
---

> Documentación de Notta en markdown. Índice completo: https://notta.cl/llms.txt — corpus entero: https://notta.cl/llms-full.txt

# "API: Certificados"

El recurso `/certificates` administra los certificados digitales `.p12` de tu organización. El `.p12` se cifra con envelope encryption (DEK por org, KEK maestra) antes de persistirse; el password se usa en memoria al firmar y nunca se guarda en claro.

Base URL: `https://app.notta.cl/api/v1`.

> **Estado actual: autenticación por sesión:**
Estos endpoints se autentican con la sesión del dashboard (cookie de Supabase Auth en `app.notta.cl`), no con API key Bearer. Sin sesión válida o sin organización responden `412 org.required`. El camino práctico hoy es subir el certificado desde el dashboard; los curl de abajo muestran el contrato exacto del endpoint.

## Endpoints

### `POST /certificates`

Sube un certificado `.p12` (multipart/form-data): lo cifra, calcula su fingerprint SHA-256 y devuelve el `id` que después va en el header `X-Cert-Id` al emitir.

| Campo (form) | Tipo | Requerido | Descripción |
|---|---|---|---|
| `file` | archivo | sí | El `.p12` emitido por tu PSC (Acepta, eCertChile, etc.). |
| `password` | string | sí | Password del `.p12`; se usa solo en memoria al firmar. |
| `label` | string | sí | Nombre legible, p. ej. "Producción". |
| `rut_owner` | string | no | RUT del titular del certificado. |
| `subject_cn` | string | no | CN del subject; default: el `label`. |
| `issuer_cn` | string | no | CN del emisor del certificado. |

```bash
curl -X POST https://app.notta.cl/api/v1/certificates \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "file=@mi-cert.p12" \
  -F "password=********" \
  -F "label=Producción" \
  -F "rut_owner=76123456-0"
```

Respuesta `201 Created`:

```json
{
  "data": {
    "id": "01977f00-0000-7000-8000-000000000abc",
    "label": "Producción",
    "not_after": "2027-06-09T18:00:00.000Z"
  }
}
```

La deduplicación es por contenido: el mismo `.p12` subido dos veces para la misma org responde `409 cert.duplicate`.

Errores posibles:

| Código | HTTP | `next_action` |
|---|---|---|
| `cert.invalid_request` (falta `file`, `password` o `label`) | 400 | — |
| `cert.duplicate` | 409 | — |
| `org.required` | 412 | — |
| `cert.insert_failed` | 500 | — |
| `db.unavailable` · `cert.kms_unavailable` | 503 | — |

### `GET /certificates`

Lista los certificados vigentes (no eliminados) de tu organización.

```bash
curl https://app.notta.cl/api/v1/certificates
```

Respuesta `200 OK`:

```json
{
  "data": [
    {
      "id": "01977f00-0000-7000-8000-000000000abc",
      "label": "Producción",
      "rut_owner": "76123456-0",
      "subject_cn": "Producción",
      "not_before": "2026-06-09T18:00:00.000Z",
      "not_after": "2027-06-09T18:00:00.000Z",
      "created_at": "2026-06-09T18:00:01.000Z"
    }
  ]
}
```

Errores posibles:

| Código | HTTP | `next_action` |
|---|---|---|
| `org.required` | 412 | — |
| `db.unavailable` | 503 | — |

### `DELETE /certificates/:id`

Elimina (soft delete) un certificado de tu organización; deja de aparecer en el listado y de servir para firmar.

```bash
curl -X DELETE https://app.notta.cl/api/v1/certificates/01977f00-0000-7000-8000-000000000abc
```

Respuesta `200 OK`:

```json
{ "data": { "id": "01977f00-0000-7000-8000-000000000abc", "deleted": true } }
```

Errores posibles:

| Código | HTTP | `next_action` |
|---|---|---|
| `cert.not_found` | 404 | — |
| `org.required` | 412 | — |
| `db.unavailable` | 503 | — |

## Próximos pasos

- **[Onboarding y certificación SII](/docs/onboarding-cert)** — de dónde sale el `.p12` y cómo encaja en el camino a producción.
- [API: Folios (CAF)](/docs/api/caf) — el siguiente upload: los folios autorizados por el SII.
- [Autenticación](/docs/authentication) — API keys, scopes y entornos para el resto de la API.