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 guarda dentro de ese mismo blob cifrado, nunca en claro, y se descifra en memoria cada vez que hay que usarlo.

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

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.

curl -X POST https://app.notta.cl/api/v1/certificates \
  -H "Authorization: Bearer $NOTTA_API_KEY" \
  -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:

GET /certificates

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

curl https://app.notta.cl/api/v1/certificates \
  -H "Authorization: Bearer $NOTTA_API_KEY"

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:

POST /certificates/:id/activate

Fija cuál de tus certificados firma por defecto. Es el que Notta usa cuando emites sin mandar X-Cert-Id. Sirve para rotar el certificado sin tocar tu código: subes el nuevo, lo activas, y las emisiones siguientes salen firmadas con él.

curl -X POST https://app.notta.cl/api/v1/certificates/01977f00-0000-7000-8000-000000000abc/activate \
  -H "Authorization: Bearer $NOTTA_API_KEY"

Respuesta 200 OK:

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

Un certificado vencido no puede quedar como predeterminado: responde 409 cert.expired. Un certificado de otra organización responde 404, no 403: no se filtra si existe.

Errores posibles:

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 \
  -H "Authorization: Bearer $NOTTA_API_KEY"

Respuesta 200 OK:

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

No se puede borrar el ÚNICO certificado de la organización: sin ninguno cargado, Notta no puede timbrar, emitir ni enviar documentos al SII, y el dashboard devuelve al asistente de puesta en marcha. Ese intento responde 409 cert.last_remaining.

Para rotar el certificado, el orden es al revés del que uno suele intentar: sube primero el reemplazo con POST /certificates y recién después elimina el anterior. Entre los dos pasos la organización nunca se queda sin firma, y con más de un certificado vigente eliges cuál firma con POST /certificates/:id/activate.

Errores posibles:

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.