Empresas

Vincular certificado digital

Envia o certificado digital A1 (.pfx / .p12) e a senha da empresa; aceita JSON + Base64 ou multipart.

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

Requer os cabeçalhos de assinatura token, timestamp e sign, veja Autenticação.

O mesmo caminho aceita duas formas de requisição, selecionadas pelo Content-Type: use JSON + Base64 (esta página) quando você só tem os bytes do certificado, por exemplo lidos do seu próprio armazenamento, o que evita montar multipart e suas ressalvas de assinatura; use multipart (seção abaixo) quando tem o certificado como arquivo. Validação e resultado são idênticos nas duas formas. Um envio bem-sucedido substitui o certificado anterior da empresa.

Parâmetros

Cabeçalhos

Content-Typestringobrigatório
application/json para a forma JSON + Base64; multipart/form-data para a forma multipart.

Parâmetros de caminho

empresaIdstringobrigatório
Identificador devolvido por Registrar empresa.
Exemplo: 1934811222334455

Corpo da requisição

senhastringobrigatório
Senha do certificado.
Exemplo: certpass123
arquivoBase64stringobrigatório
Base64 do conteúdo do arquivo .pfx / .p12; quebras de linha e o prefixo data:...;base64, são tolerados; no máximo 1MB após decodificar. Base64 inválido ou tamanho excedido devolve 10003035.
Exemplo: MIIKXQIBAzCCCicGCSqGSIb3DQEHAaCCChgEggoU...

Respostas

200

Certificado validado e vinculado; sem corpo de resposta. O certificado anterior da empresa é substituído.

Sem corpo de resposta

Erros

Código	HTTP
10003000	404	`empresaId` não existe ou não pertence a esta aplicação.
10003035	400	Base64 inválido ou arquivo acima de 1MB após decodificar (somente forma JSON).
CER0005	400	Senha do certificado não confere. Verifique a senha.
10003010	400	CNPJ do certificado não corresponde ao da empresa. Use o certificado correto.
10003011	400	Certificado expirado. Use um certificado válido.
10003012	400	Certificado idêntico ao atualmente ativo na empresa.

Assinatura da forma JSON

Na forma JSON o corpo participa da assinatura (corpo bruto com CR/LF removidos, como em todo endpoint JSON). Gere Base64 padrão sem quebras de linha para que o corpo assinado e o corpo enviado nunca divirjam.

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: upload multipart

Envie Content-Type: multipart/form-data com os campos abaixo.

Campo do formulário	Tipo	Obrigatório	Descrição
`senha`	text	sim	Senha do certificado
`arquivo`	file	sim	Arquivo do certificado digital A1 (.pfx / .p12), até 1MB

Nota de assinatura: em requisições multipart o corpo é a string vazia (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"

Validação e resultado (ambas as formas)

A plataforma verifica: validade do Base64 (só a forma JSON, 10003035), senha correta (CER0005 caso contrário), certificado não expirado (10003011), CNPJ do certificado igual ao da empresa (10003010), não idêntico ao certificado atualmente ativo (10003012). Sucesso é HTTP 200 sem corpo. Um envio bem-sucedido substitui o certificado anterior da empresa. O conteúdo do certificado é armazenado criptografado na plataforma; nenhum endpoint devolve o conteúdo do certificado nem a senha.

A empresa só passa a emitir quando, além do certificado, a aprovação da operação estiver concluída; veja o ciclo de vida em Empresas.