📚 Documentación API REST

🚀 Introducción

La API REST de MiFirma te permite integrar firma electrónica en tus aplicaciones de forma programática. Ideal para:

• Sistemas ERP y CRM
• Plataformas de gestión documental
• Aplicaciones empresariales
• Flujos de trabajo automatizados

🔐 Autenticación

La API utiliza tokens Bearer para autenticación. Todos los requests deben incluir el header:

Authorization: Bearer YOUR_API_KEY

Obtener API Key

1. Contratar plan Corporativo
2. Acceder al Dashboard → API Keys
3. Crear nueva API Key
4. Copiar y guardar de forma segura (solo se muestra una vez)

⚠️ Códigos de Error

Formato de Error

{
  "success": false,
  "error": {
    "code": "INVALID_CERTIFICATE",
    "message": "El certificado digital es inválido o está vencido",
    "details": {
      "expiry_date": "2025-12-31"
    }
  }
}

⏱️ Rate Limits

Los headers de respuesta incluyen información del rate limit:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 115
X-RateLimit-Reset: 1704207600

Firma un documento PDF con un certificado digital.

Parámetros

Ejemplo de Request (cURL)

curl -X POST https://api.MiFirma.com/v1/documents/sign \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "pdf_file=@/path/to/document.pdf" \
  -F "certificate_file=@/path/to/certificate.p12" \
  -F "certificate_password=mypassword" \
  -F "reason=Firma de contrato" \
  -F "location=Quito, Ecuador" \
  -F "cargo=Gerente General" \
  -F 'signature_config={"x":100,"y":200,"page":1,"showQr":true}'

Ejemplo de Request (JavaScript)

const formData = new FormData();
formData.append('pdf_file', pdfFile);
formData.append('certificate_file', certificateFile);
formData.append('certificate_password', 'mypassword');
formData.append('reason', 'Firma de contrato');
formData.append('location', 'Quito, Ecuador');
formData.append('cargo', 'Gerente General');
formData.append('signature_config', JSON.stringify({
  x: 100,
  y: 200,
  page: 1,
  showQr: true,
  borderColor: '#1a4d7a',
  textColor: '#000000'
}));

const response = await fetch('https://api.MiFirma.com/v1/documents/sign', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: formData
});

const result = await response.json();

Respuesta Exitosa (200)

{
  "success": true,
  "data": {
    "document_id": "doc_1234567890",
    "filename": "contrato_firmado.pdf",
    "download_url": "https://api.MiFirma.com/v1/documents/doc_1234567890/download",
    "signed_at": "2026-01-02T15:30:00Z",
    "signer": {
      "name": "Juan Pérez García",
      "certificate_issuer": "BCE"
    },
    "file_size": 524288,
    "pages": 5
  }
}

Firma múltiples documentos PDF con el mismo certificado.

Parámetros

Ejemplo de Request

{
  "documents": [
    {
      "pdf_file": "base64_encoded_pdf_1",
      "filename": "contrato_1.pdf",
      "signature_config": {"x": 100, "y": 200, "page": 1}
    },
    {
      "pdf_file": "base64_encoded_pdf_2",
      "filename": "contrato_2.pdf",
      "signature_config": {"x": 150, "y": 250, "page": 2}
    }
  ],
  "certificate_file": "base64_encoded_certificate",
  "certificate_password": "mypassword"
}

Respuesta Exitosa (201)

{
  "success": true,
  "data": {
    "batch_id": "batch_abc123",
    "status": "processing",
    "total_documents": 2,
    "estimated_completion": "2026-01-02T15:35:00Z"
  }
}

Obtiene información de un documento firmado.

Respuesta Exitosa (200)

{
  "success": true,
  "data": {
    "document_id": "doc_1234567890",
    "filename": "contrato.pdf",
    "status": "signed",
    "signed_at": "2026-01-02T15:30:00Z",
    "signer": {
      "name": "Juan Pérez García",
      "certificate_issuer": "BCE",
      "certificate_valid_until": "2027-12-31"
    },
    "download_url": "https://api.MiFirma.com/v1/documents/doc_1234567890/download",
    "verification_url": "https://MiFirma.com/verificar?id=doc_1234567890"
  }
}

Lista todos los documentos firmados.

Query Parameters

Ejemplo

curl -X GET "https://api.MiFirma.com/v1/documents?page=1&per_page=20&status=signed" \
  -H "Authorization: Bearer YOUR_API_KEY"

Verifica la autenticidad de un documento firmado.

Parámetros

Respuesta Exitosa (200)

{
  "success": true,
  "data": {
    "is_valid": true,
    "signatures": [
      {
        "signer_name": "Juan Pérez García",
        "signed_at": "2026-01-02T15:30:00Z",
        "certificate": {
          "issuer": "BCE",
          "serial_number": "ABC123456",
          "valid_from": "2025-01-01",
          "valid_until": "2027-12-31",
          "is_valid": true
        },
        "document_integrity": "intact"
      }
    ],
    "total_signatures": 1
  }
}

🔔 Webhooks

Recibe notificaciones en tiempo real cuando ocurren eventos en tu cuenta.

Eventos Disponibles

• document.signed - Documento firmado exitosamente
• document.failed - Error al firmar documento
• batch.completed - Lote de firmas completado
• certificate.expiring - Certificado por vencer (30 días)

Formato del Payload

{
  "event": "document.signed",
  "timestamp": "2026-01-02T15:30:00Z",
  "data": {
    "document_id": "doc_1234567890",
    "filename": "contrato.pdf",
    "signer_name": "Juan Pérez García",
    "download_url": "https://api.MiFirma.com/v1/documents/doc_1234567890/download"
  }
}

Configuración

1. Accede a Dashboard → Webhooks
2. Agrega tu URL de endpoint
3. Selecciona los eventos que deseas recibir
4. Copia el secret para verificar firmas

📦 SDKs y Librerías

npm install MiFirma-sdk

composer require MiFirma/php-sdk

pip install MiFirma