Empresas

Vincular certificado digital

Envía el certificado digital A1 (.pfx / .p12) y la contraseña de la empresa; acepta JSON + Base64 o multipart.

POST/openapi/v1/empresas/{empresaId}/certificadoDigital

Requiere las cabeceras de firma token, timestamp y sign, vea Autenticación.

La misma ruta acepta dos formas de solicitud, seleccionadas por Content-Type: use JSON + Base64 (esta página) cuando solo tenga los bytes del certificado, por ejemplo leídos de su propio almacenamiento, lo que evita montar multipart y sus salvedades de firma; use multipart (sección más abajo) cuando tenga el certificado como archivo. La validación y el resultado son idénticos en ambas formas. Un envío exitoso reemplaza el certificado anterior de la empresa.

Parámetros

Cabeceras

Content-Typestringobligatorio
application/json para la forma JSON + Base64; multipart/form-data para la forma multipart.

Parámetros de ruta

empresaIdstringobligatorio
Identificador devuelto por Registrar empresa.
Ejemplo: 1934811222334455

Cuerpo de la petición

senhastringobligatorio
Contraseña del certificado.
Ejemplo: certpass123
arquivoBase64stringobligatorio
Base64 del contenido del archivo .pfx / .p12; se toleran saltos de línea y el prefijo data:...;base64,; como máximo 1MB tras decodificar. Base64 inválido o tamaño excedido devuelve 10003035.
Ejemplo: MIIKXQIBAzCCCicGCSqGSIb3DQEHAaCCChgEggoU...

Respuestas

200

Certificado validado y vinculado; sin cuerpo de respuesta. Se reemplaza el certificado anterior de la empresa.

Sin cuerpo de respuesta

Errores

Código	HTTP
10003000	404	`empresaId` no existe o no pertenece a esta aplicación.
10003035	400	Base64 inválido o archivo mayor de 1MB tras decodificar (solo forma JSON).
CER0005	400	La contraseña del certificado no coincide. Verifique la contraseña.
10003010	400	El CNPJ del certificado no corresponde a la empresa. Use el certificado correcto.
10003011	400	Certificado expirado. Use un certificado válido.
10003012	400	Certificado idéntico al actualmente activo en la empresa.

Firma de la forma JSON

En la forma JSON el cuerpo forma parte de la firma (cuerpo bruto con CR/LF eliminados, como en todo endpoint JSON). Genere Base64 estándar sin saltos de línea para que el cuerpo firmado y el cuerpo enviado nunca difieran.

bash

APP_SECRET="sk_live_9f8e7d6c5b4a"
P="/openapi/v1/empresas/1934811222334455/certificadoDigital"
TS=$(date +%s)
BODY=$(printf '{"senha":"certpass123","arquivoBase64":"%s"}' "$(base64 -w0 uploaded-cert.pfx)")
SIGN=$(printf '%s' "${APP_SECRET}${P}${BODY}${TS}" | md5sum | cut -d' ' -f1)

curl -X POST "https://api.v2.tffiscal.com${P}" \
  -H "token: ${APP_SECRET}" -H "timestamp: ${TS}" -H "sign: ${SIGN}" \
  -H "Content-Type: application/json" --data-binary "${BODY}"

Forma alternativa: carga multipart

Envíe Content-Type: multipart/form-data con los campos de formulario siguientes.

Campo del formulario	Tipo	Obligatorio	Descripción
`senha`	text	sí	Contraseña del certificado
`arquivo`	file	sí	Archivo del certificado digital A1 (.pfx / .p12), hasta 1MB

Nota de firma: en solicitudes multipart el cuerpo es la cadena vacía (sign = MD5(token + path + timestamp)).

bash

APP_SECRET="sk_live_9f8e7d6c5b4a"
P="/openapi/v1/empresas/1934811222334455/certificadoDigital"
TS=$(date +%s)
SIGN=$(printf '%s' "${APP_SECRET}${P}${TS}" | md5sum | cut -d' ' -f1)

curl -X POST "https://api.v2.tffiscal.com${P}" \
  -H "token: ${APP_SECRET}" -H "timestamp: ${TS}" -H "sign: ${SIGN}" \
  -F "senha=certpass123" -F "arquivo=@uploaded-cert.pfx"

Validación y resultado (ambas formas)

La plataforma verifica: validez del Base64 (solo forma JSON, 10003035), contraseña correcta (CER0005 en caso contrario), certificado no expirado (10003011), CNPJ del certificado igual al de la empresa (10003010), no idéntico al certificado actualmente activo (10003012). El éxito es HTTP 200 sin cuerpo. Un envío exitoso reemplaza el certificado anterior de la empresa. El contenido del certificado se almacena cifrado en la plataforma; ningún endpoint devuelve el contenido del certificado ni la contraseña.

La empresa solo pasa a emitir cuando, además del certificado, la aprobación de operaciones esté completa; vea el ciclo de vida en Empresas.