El certificado de firma
Cómo subes tu .p12 y por qué, una vez guardado, ni nuestra API puede abrirlo.
Todo comprobante electrónico va firmado con el certificado de firma electrónica del emisor: el archivo .p12 (o .pfx) que te entregó una entidad de certificación, con su clave. En Sandbox firmamos con un certificado de práctica; para Pruebas y Producción necesitas el tuyo.
Subirlo
Es un formulario multipart, como subir cualquier archivo:
read -s CERTIFICATE_PASSWORD
curl -X POST https://api.fiscalbase.io/v1/ec/entities/$ENTITY_ID/certificates \
-H "Authorization: Bearer $FISCALBASE_API_KEY" \
-F "file=@firma.p12" \
-F "password=$CERTIFICATE_PASSWORD"read -s pide la clave sin mostrarla ni guardarla en el historial de tu terminal.
Antes de guardarlo verificamos que:
- la clave abre el archivo;
- el certificado es de ese emisor: su RUC, o la cédula de la persona natural titular del RUC;
- está vigente hoy.
Si algo falla, respondemos 422 en certificate, diciendo qué: por ejemplo, El certificado es de 1712345678, no del RUC 1790012345001.
La respuesta, y el certificate de la entidad, muestran lo que necesitas saber del certificado, nunca el certificado:
{
"holder": "MARIA JOSE ROBLES VERA",
"holder_identification": "1712345678",
"holder_identification_type": "cedula",
"kind": "natural_person",
"issuer_name": "Security Data",
"subject": "CN=MARIA JOSE ROBLES VERA, serialNumber=1712345678-200224172048, O=SECURITY DATA S.A. 2, C=EC",
"issuer": "CN=AUTORIDAD DE CERTIFICACION SUBCA-2 SECURITY DATA, O=SECURITY DATA S.A. 2, C=EC",
"serial_number": "5c2d…",
"valid_from": "2026-01-15T00:00:00Z",
"valid_until": "2028-01-15T00:00:00Z"
}Para mostrarlo a una persona usa los campos en claro:
| Campo | Qué es |
|---|---|
holder | El nombre del titular, como la entidad de certificación lo escribe (CN). |
holder_identification y holder_identification_type | Su cédula (cedula, 10 dígitos) o, si el certificado no la trae, su RUC (ruc, 13). La leemos de la extensión propia de la entidad de certificación (Security Data, Banco Central, ANF, Uanataca y las demás acreditadas) o, si no, del serialNumber del titular (1712345678-…). |
kind | natural_person si firma por sí mismo, legal_representative si representa a una empresa (el certificado trae un RUC que no es su cédula más 001). Es null si no se sabe. |
issuer_name | La entidad de certificación como se la conoce: «Security Data», sin la forma legal. |
valid_from y valid_until | La vigencia. |
subject y issuer son los nombres distinguidos completos (RFC 4514, con las comas de los valores escapadas). Están por completitud: para mostrar, usa los campos de arriba. Los certificados subidos antes de que existieran estos campos tienen holder, holder_identification e issuer_name leídos de esos nombres, y kind en null hasta que subas el certificado de nuevo.
Cómo lo protegemos
Tu certificado firma en tu nombre, así que lo tratamos como lo que es:
- Al recibirlo, lo sellamos junto con su clave usando una llave pública. La API solo tiene esa llave pública: una vez sellado, ni la API puede abrirlo.
- Solo el proceso que firma comprobantes tiene la llave privada, y abre el certificado únicamente para firmar.
- Nunca lo devolvemos, ni el archivo ni la clave, por ningún endpoint.
Renovarlo
Sube el nuevo cuando lo recibas, sin esperar a que venza el anterior: el cambio no interrumpe tu emisión. Firmamos siempre con el más reciente que subiste, mientras siga vigente. Subir uno reemplaza al anterior, que ya no vuelve a firmar aunque siga vigente, porque quizá lo cambiaste por haberlo revocado o por un cambio de representante legal.
Los certificados anteriores se conservan, no se sobrescriben. GET /v1/ec/entities/$ENTITY_ID/certificates los lista del más reciente al más antiguo, con su vigencia, titular, emisor y número de serie, current en el que firma y replaced_at, el momento en que subiste el siguiente. Como todo lo que devolvemos de un certificado, solo es lo que el certificado dice: nunca el archivo ni la clave.
Si el más reciente vence, emitir, corregir o renumerar en Pruebas o Producción responde 409 hasta que subas uno vigente, aunque uno anterior siga vigente: preferimos no aceptar un comprobante que no podríamos firmar.