API: Certificados

Subida, listado y eliminación del certificado digital .p12 con el que Notta firma tus DTE, cifrado con envelope encryption por organización

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.

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:

{
  "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.

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

Respuesta 200 OK:

{
  "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.

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

Respuesta 200 OK:

{ "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 — de dónde sale el .p12 y cómo encaja en el camino a producción.
API: Folios (CAF) — el siguiente upload: los folios autorizados por el SII.
Autenticación — API keys, scopes y entornos para el resto de la API.

API: Certificados

Endpoints

POST /certificates

GET /certificates

DELETE /certificates/:id

Próximos pasos

En esta página

`POST /certificates`

`GET /certificates`

`DELETE /certificates/:id`