# Alojar o remover e.firma (FIEL)

Servicios para administrar la e.firma (Firma Electrónica Avanzada) del contribuyente en FactuDesk. La e.firma es utilizada para autenticación ante el SAT y descarga de CFDIs.

**A diferencia de los certificados de sello digital (CSD), solo puede existir una e.firma por RFC.**

---

## Alojar o actualizar e.firma

Almacena o actualiza los archivos de la e.firma del contribuyente.

### Punto final

```
POST https://factudesk.api.induxsoft.net/efirma/administrar/
```

### Encabezados

```
Authorization: Bearer {ids}
Content-Type: application/json
```

### Parámetros (JSON body)

| Parámetro | Tipo | Requerido | Descripción |
|-----------|------|-----------|-------------|
| `rfc` | string | Sí | RFC del contribuyente propietario de la e.firma |
| `cer` | string | Sí | Archivo de certificado (.cer) codificado en base64 |
| `key` | string | Sí | Archivo de clave privada (.key) codificado en base64 |
| `password` | string | Sí | Contraseña de la clave privada |

### Validaciones

El servicio realiza las siguientes validaciones antes de almacenar la e.firma:

1. **Validación de contraseña:** Verifica que la contraseña proporcionada sea válida para descifrar la clave privada (.key)
2. **Validación de RFC:** Verifica que el RFC especificado en el parámetro `rfc` coincida con el RFC para el cual fue expedido el certificado (.cer)

Si alguna validación falla, se retorna un error y los archivos no se almacenan.

### Respuesta

**Éxito (200 OK):**

```json
{
  "success": true,
  "rfc": "AAA010101AAA",
  "message": "e.firma almacenada correctamente",
  "vigencia": {
    "desde": "2023-01-15",
    "hasta": "2027-01-14"
  }
}
```

**Error - Contraseña inválida (400 Bad Request):**

```json
{
  "success": false,
  "error": "invalid_password",
  "message": "La contraseña proporcionada no es válida para la clave privada"
}
```

**Error - RFC no coincide (400 Bad Request):**

```json
{
  "success": false,
  "error": "rfc_mismatch",
  "message": "El RFC especificado no coincide con el RFC del certificado"
}
```

**Error - Archivos inválidos (400 Bad Request):**

```json
{
  "success": false,
  "error": "invalid_files",
  "message": "Los archivos proporcionados no son válidos"
}
```

### Ejemplo con cURL

```bash
curl -X POST https://factudesk.api.induxsoft.net/efirma/administrar/ \
  -H "Authorization: Bearer {ids}" \
  -H "Content-Type: application/json" \
  -d '{
    "rfc": "AAA010101AAA",
    "cer": "MIIFuzCCA6OgAwIBAgIUMjAwMDEwMDAwMDAzMDAwMjI4MTUw...",
    "key": "MIIFDjBABgkqhkiG9w0BBQ0wMzAbBgkqhkiG9w0BBQwwDgQI...",
    "password": "mi_contraseña_segura"
  }'
```

**Nota:** Los archivos `.cer` y `.key` deben enviarse codificados en base64. Los valores mostrados arriba están truncados por brevedad.

---

## Verificar existencia de e.firma

Verifica si existe una e.firma almacenada para el RFC especificado.

### Punto final

```
GET https://factudesk.api.induxsoft.net/efirma/administrar/{rfc}
```

### Encabezados

```
Authorization: Bearer {ids}
```

### Parámetros de ruta

| Parámetro | Tipo | Descripción |
|-----------|------|-------------|
| `rfc` | string | RFC del contribuyente |

### Respuesta

**e.firma existe (200 OK):**

```json
{
  "success": true,
  "rfc": "AAA010101AAA",
  "exists": true,
  "vigencia": {
    "desde": "2023-01-15",
    "hasta": "2027-01-14"
  },
  "dias_restantes": 365
}
```

**e.firma no existe (200 OK):**

```json
{
  "success": true,
  "rfc": "AAA010101AAA",
  "exists": false
}
```

### Ejemplo con cURL

```bash
curl -X GET https://factudesk.api.induxsoft.net/efirma/administrar/AAA010101AAA \
  -H "Authorization: Bearer {ids}"
```

---

## Verificar si e.firma está cargada

Verifica si existe una e.firma almacenada para el RFC especificado y retorna sus datos básicos.

### Punto final

```
GET https://factudesk.api.induxsoft.net/efirma/verificar/{rfc}
```

### Encabezados

```
Authorization: Bearer {ids}
```

### Parámetros de ruta

| Parámetro | Tipo | Descripción |
|-----------|------|-------------|
| `rfc` | string | RFC del contribuyente |

### Respuesta

**e.firma existe (200 OK):**

```json
{
  "success": true,
  "data": {
    "rfc": "AAA010101AAA",
    "no_certificado": "20001000000300022815",
    "fecha_emision": "2023-01-15",
    "fecha_expiracion": "2027-01-14"
  }
}
```

**e.firma no existe (200 OK):**

```json
{
  "success": false,
  "message": "eFirma no configurada"
}
```

### Ejemplo con cURL

```bash
curl -X GET https://factudesk.api.induxsoft.net/efirma/verificar/AAA010101AAA \
  -H "Authorization: Bearer {ids}"
```

---

## Remover e.firma

Elimina los archivos de e.firma almacenados para el RFC especificado.

### Punto final

```
DELETE https://factudesk.api.induxsoft.net/efirma/administrar/{rfc}
```

### Encabezados

```
Authorization: Bearer {ids}
```

### Parámetros de ruta

| Parámetro | Tipo | Descripción |
|-----------|------|-------------|
| `rfc` | string | RFC del contribuyente |

### Respuesta

**Éxito (200 OK):**

```json
{
  "success": true,
  "rfc": "AAA010101AAA",
  "message": "e.firma removida correctamente"
}
```

**e.firma no existe (404 Not Found):**

```json
{
  "success": false,
  "error": "not_found",
  "message": "No existe e.firma almacenada para el RFC especificado"
}
```

### Ejemplo con cURL

```bash
curl -X DELETE https://factudesk.api.induxsoft.net/efirma/administrar/AAA010101AAA \
  -H "Authorization: Bearer {ids}"
```

---

## Notas de seguridad

- La contraseña de la clave privada se almacena cifrada usando el RFC en minúsculas como clave de cifrado
- Los archivos de e.firma se almacenan en una estructura protegida accesible únicamente por el sistema
- Solo el propietario autenticado del RFC (validado mediante `ids`) puede administrar su e.firma
- La e.firma es requerida para la funcionalidad de sincronización automática de CFDIs desde el SAT

---

## Consideraciones

- **Una e.firma por RFC:** A diferencia de los certificados de sello digital (CSD), donde puede haber múltiples certificados vigentes, solo puede existir una e.firma por RFC
- **Actualización:** Si ya existe una e.firma para el RFC y se envía una nueva mediante POST, la e.firma anterior se sobrescribe
- **Vigencia:** Es responsabilidad del usuario mantener su e.firma vigente. FactuDesk notificará cuando la e.firma esté próxima a vencer