Credenciales

Cada tenant necesita dos credenciales para poder emitir DTEs:

API Key de Simple API — para conectarse al servicio de facturación del SII
Certificado digital (.pfx) — para firmar los documentos electrónicos

Opción 1: Link de activación (recomendado)

La forma más simple es generar un link de activación y enviarlo a tu cliente. Ellos configuran sus credenciales en una página hosted por nosotros, sin tocar tu código.

curl -X POST https://api.example.com/api/v1/tenants/{tenantId}/activation-link \
  -H "Authorization: Bearer sk_live_..."

Respuesta:

{
  "token": "act_...",
  "url": "https://app.example.com/activate/act_...",
  "expiresAt": "2024-04-01T00:00:00Z"
}

Envía url a tu cliente por email o muéstralo in-app. Ver Link de activación para más detalles.

Opción 2: Vía API

Si prefieres manejar la UI de configuración tú mismo:

Guardar API key de Simple API

curl -X POST https://api.example.com/api/v1/tenants/{tenantId}/credentials/api-key \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"apiKey": "simple-api-key-aqui"}'

Subir certificado digital

curl -X POST https://api.example.com/api/v1/tenants/{tenantId}/credentials/certificate \
  -H "Authorization: Bearer sk_live_..." \
  -F "file=@certificado.pfx" \
  -F "password=password-del-pfx" \
  -F "rutCertificado=12.345.678-9" \
  -F "nombreTitular=Juan Pérez" \
  -F "fechaVencimiento=2026-12-31" \
  -F "esPrincipal=true"

Respuesta:

{
  "id": "uuid-del-certificado",
  "diasParaVencer": 730
}

Tiene que ser el certificado personal de la persona autorizada ante el SII, con su RUT personal — no el de la empresa. El SII lo exige así, y con el certificado de la empresa rechaza todos los envíos.

Qué se valida al subir

La API abre el archivo antes de guardar nada. Los tres campos de texto son de confirmación: lo que se persiste sale siempre del propio certificado.

Se valida	Si falla
El password abre el archivo	`400 CERT_PASSWORD_INVALIDO`
Es un PKCS#12 válido	`400 CERT_ILEGIBLE`
Declara el RUT del titular en su `subjectAltName`	`400 CERT_SIN_RUT`
No está vencido	`400 CERT_VENCIDO`, con la fecha en el mensaje
Los 3 campos coinciden con el archivo	`400 CERT_DATOS_NO_COINCIDEN`

Cuando la validación falla, no se escribe nada: ni el archivo en S3, ni la contraseña en Secrets Manager, ni la fila en la base. CERT_DATOS_NO_COINCIDEN trae en details.desajustes qué campo difiere y qué dice el certificado, para poder marcar el input exacto:

{
  "error": {
    "code": "CERT_DATOS_NO_COINCIDEN",
    "message": "Los datos declarados no coinciden con el certificado: rutCertificado",
    "details": {
      "desajustes": [
        { "campo": "rutCertificado", "declarado": "11.111.111-1", "enElArchivo": "19532105-1" }
      ]
    }
  }
}

El RUT se compara normalizado, así que 19.532.105-1 y 19532105-1 son el mismo valor. Lo que se guarda es la forma canónica del certificado, sin puntos: de ahí sale el RutEnvia que se le declara al SII en cada envío.

Renovar un certificado

Subir uno nuevo con esPrincipal=true degrada al anterior en la misma operación. Un tenant tiene un solo certificado principal, garantizado por la base: los anteriores quedan registrados pero dejan de usarse para firmar.

Consultar estado

curl https://api.example.com/api/v1/tenants/{tenantId}/credentials/status \
  -H "Authorization: Bearer sk_live_..."

Respuesta:

{
  "apiKey": {
    "configured": true,
    "lastVerified": "2024-03-15T14:00:00Z"
  },
  "certificates": [
    {
      "id": "uuid",
      "rutCertificado": "12.345.678-9",
      "nombreTitular": "Juan Pérez",
      "fechaVencimiento": "2026-12-31",
      "esPrincipal": true
    }
  ]
}

El certificado se almacena cifrado con AWS KMS. La contraseña se guarda en AWS Secrets Manager. Nunca almacenamos credenciales en texto plano.

Empezar

Flujos principales

Referencia

Opción 1: Link de activación (recomendado)

Opción 2: Vía API

Guardar API key de Simple API

Subir certificado digital

Qué se valida al subir

Renovar un certificado

Consultar estado

​Opción 1: Link de activación (recomendado)

​Opción 2: Vía API

​Guardar API key de Simple API

​Subir certificado digital

​Qué se valida al subir

​Renovar un certificado

​Consultar estado

Opción 1: Link de activación (recomendado)

Opción 2: Vía API

Guardar API key de Simple API

Subir certificado digital

Qué se valida al subir

Renovar un certificado

Consultar estado