Overview
SUNAT requires a digital certificate to sign electronic documents before sending them to their web services. The certificate authenticates your company and ensures document integrity.Certificate Requirements
SUNAT-Approved Certificates
You must obtain a digital certificate from a SUNAT-approved Certificate Authority (CA):- eCert (formerly ePeru)
- Certicámara
- **AC Camerfirma
- Llama Sign
For Beta/Testing environment, SUNAT provides a test certificate that can be used during development.
Certificate Format
SUNAT certificates typically come in.pfx (PKCS#12) format, which contains:
- Private Key (encrypted)
- Public Certificate
- Certificate Chain (optional)
.pem format for use with the Greenter library.
Certificate Conversion
Convert .pfx to .pem
Use OpenSSL to convert your.pfx certificate to .pem format:
Extract Private Key
.pfx password.The
-nodes flag creates an unencrypted private key. Store this file securely!Alternative: RSA PRIVATE KEY Format
Some certificates use RSA PRIVATE KEY format:Convert PKCS#8 to RSA Format
Convert PKCS#8 to RSA Format
If you have a PKCS#8 private key, convert it to RSA format:
Certificate Storage
The API stores certificates in the filesystem and references them in the database.Storage Location
Location:storage/app/public/certificado/certificado.pem
Database Storage (Optional)
Companies can store certificate content in thecertificado_pem field:
app/Models/Company.php
Certificate Loading
The GreenterService loads the certificate from the filesystem: Location:app/Services/GreenterService.php:60
app/Services/GreenterService.php
Certificate Validation
The API includes commands to validate certificates:Validate Certificate
Command:app/Console/Commands/ValidateCertificate.php
- Certificate file exists
- Certificate is readable
- Private key is valid
- Certificate is not expired
- Certificate subject matches expected format
Clean Certificate
Command:app/Console/Commands/CleanCertificate.php
- Removes Bag Attributes from .pem files
- Normalizes line endings
- Validates PEM structure
- Creates a clean version of the certificate
Certificate Troubleshooting
Error: Certificate file not found
Error: Certificate file not found
Cause: Certificate file doesn’t exist at the expected location.Solution:
Error: Invalid certificate format
Error: Invalid certificate format
Cause: Certificate file is corrupted or has incorrect structure.Solution:Should contain both
- Verify PEM structure:
BEGIN PRIVATE KEY and BEGIN CERTIFICATE blocks.- Clean certificate:
- Re-convert from .pfx:
Error: Certificate expired
Error: Certificate expired
Cause: Certificate validity period has ended.Solution:
- Check expiration date:
- Renew certificate with your CA
- Replace expired certificate:
Error: SUNAT rejects signature
Error: SUNAT rejects signature
Cause: Certificate CN doesn’t match company RUC or certificate chain is incomplete.Solution:Subject should contain:
- Verify certificate subject:
CN = RUC-[YourRUC] or similar.- Ensure certificate is from SUNAT-approved CA
- Include full certificate chain if required:
Error: Permission denied reading certificate
Error: Permission denied reading certificate
Cause: Web server doesn’t have permission to read certificate file.Solution:
Certificate Structure
The GreenterService includes methods to validate and clean certificate structure: Location:app/Services/GreenterService.php:674
app/Services/GreenterService.php
Remove Bag Attributes
Some .pfx exports include “Bag Attributes” that can interfere with OpenSSL:app/Services/GreenterService.php:753
Test Certificate (Beta Environment)
For testing in Beta environment, you can use SUNAT’s test certificate:Security Best Practices
Never Commit Certificates
Add certificate files to
.gitignore:Restrict File Permissions
Only the web server should read certificates:
Encrypt at Rest
Consider encrypting certificate storage:
Monitor Expiration
Set up alerts for certificate expiration:
Certificate Renewal
SUNAT certificates typically expire after 1-2 years. Plan for renewal:Request Renewal from CA
Contact your Certificate Authority (eCert, Certicámara, etc.) at least 30 days before expiration.
Test New Certificate in Beta
Before using in production, test the new certificate in Beta environment.
Multi-Company Certificates
Each company can have its own certificate:Common Certificate Issues
| Issue | Symptom | Solution |
|---|---|---|
| Wrong Format | ”Invalid certificate” error | Convert .pfx to .pem with OpenSSL |
| Missing Private Key | ”Could not sign document” | Ensure .pem contains both private key and certificate |
| Expired Certificate | SUNAT rejects with “Certificate expired” | Renew certificate with CA |
| Wrong RUC | SUNAT rejects signature | Certificate CN must match company RUC |
| File Permissions | ”Permission denied” reading certificate | Set correct ownership and permissions (600) |
| Bag Attributes | OpenSSL parsing errors | Run php artisan certificate:clean |
Next Steps
Environments
Configure Beta and Production SUNAT endpoints
Create Invoice
Start sending documents to SUNAT
