Conexão mTLS
Como estabelecer a conexão mTLS exigida nos endpoints transacionais (emissão de VCN)
🚧 Em breve — a conexão mTLS ainda não está disponível em Sandbox nem Produção. Esta página descreve como vai funcionar para você se preparar; avisaremos no changelog quando habilitarmos.
Visão geral
Os endpoints transacionais da API — como a emissão de VCN (POST /credit-cards/v1/vcns) — exigem mTLS (Mutual TLS) além da autenticação por credencial.
São duas camadas independentes e complementares:
| Camada | O que é | Para que serve |
|---|---|---|
| mTLS | Certificado de cliente apresentado no handshake TLS | Autentica o canal (transporte) — só conexões com certificado confiável chegam à API |
| Credencial | API Key + Secret → token Bearer (OAuth 2.0) | Identifica o cliente e autoriza a operação |
O mTLS é exigido apenas nos endpoints transacionais (emissão de VCN). Consultas de leitura continuam usando somente a autenticação por credencial. Quem tem só a chave não opera sem o certificado.
Endpoint mTLS
As chamadas transacionais usam um host dedicado, separado do host padrão da API:
| Ambiente | Host mTLS |
|---|---|
| Sandbox | mtls-sandbox.contasimples.com |
| Produção | mtls.contasimples.com |
Os hosts acima são provisórios — o host e a porta definitivos são confirmados pela Conta Simples no onboarding. Não faça hardcode até a confirmação. O restante do contrato (paths, payloads) é idêntico ao publicado na referência da API.
Obtendo seu certificado de cliente
O certificado de cliente é provisionado durante o onboarding, coordenado pelo time de segurança da Conta Simples.
Solicitação no onboarding
Ao iniciar a integração, a Conta Simples inicia o processo de emissão do seu certificado de cliente.
Geração e assinatura
Você gera o par de chaves e o CSR no seu ambiente — a chave privada nunca sai dele. Você envia apenas o CSR; a Conta Simples assina e registra a sua CA na trust store da API.
Instalação
Você instala o certificado de cliente e a chave privada no cliente HTTP que fará as chamadas (servidor de integração da sua plataforma).
Validação
Faça uma chamada de teste no Sandbox e confirme que o handshake mTLS é aceito.
A chave privada do certificado é uma credencial sensível. Armazene em um cofre (AWS Secrets Manager, Vault) e nunca a comite em repositório ou exponha em logs.
Fazendo uma chamada com mTLS
Apresente o certificado de cliente e a chave privada no cliente HTTP, mantendo a credencial OAuth no header Authorization. Obtenha o {TOKEN} via OAuth (API key/secret) — veja Autenticação.
cURL
curl -X POST https://mtls-sandbox.contasimples.com/credit-cards/v1/vcns \
--cert ./client-cert.pem \
--key ./client-key.pem \
-H "Authorization: Bearer {TOKEN}" \
-H "Idempotency-Key: {bookingId}" \
-H "Content-Type: application/json" \
-d '{
"type": "AIR",
"bookingId": "ACME-AIR-554433",
"amount": { "rate": 100.0, "taxes": 1.0, "currency": "BRL" },
"flightBooking": { "departureDate": "2026-06-10", "passengers": 1 }
}'
Node.js
import https from "node:https";
import fs from "node:fs";
const agent = new https.Agent({
cert: fs.readFileSync("./client-cert.pem"),
key: fs.readFileSync("./client-key.pem"), // a chave privada fica só no seu ambiente
});
const res = await fetch("https://mtls-sandbox.contasimples.com/credit-cards/v1/vcns", {
method: "POST",
agent,
headers: {
Authorization: `Bearer ${token}`,
"Idempotency-Key": bookingId,
"Content-Type": "application/json",
},
body: JSON.stringify(payload),
});
Python
import requests
res = requests.post(
"https://mtls-sandbox.contasimples.com/credit-cards/v1/vcns",
cert=("./client-cert.pem", "./client-key.pem"), # a chave privada fica só no seu ambiente
headers={
"Authorization": f"Bearer {token}",
"Idempotency-Key": booking_id,
"Content-Type": "application/json",
},
json=payload,
)
Resposta (201)
{
"vcnId": "21624502",
"bookingId": "ACME-AIR-554433",
"type": "AIR",
"card": { "pan": "465635******6026", "cvv": "***", "expirationDate": "06/31" },
"status": "ACTIVE"
}
A resposta real traz PAN e CVV em claro (mascarados acima) — trate como dado sensível: use apenas em memória, nunca registre em log nem exponha no client-side.
Se o certificado de cliente não for apresentado (ou não for confiável), o handshake falha antes de chegar à aplicação — você recebe um erro de TLS, não um JSON:
curl: (56) OpenSSL SSL_read: error:0A000412:SSL routines::sslv3 alert certificate required
Requisitos técnicos
| Item | Requisito |
|---|---|
| Versão TLS | TLS 1.2 (mínimo) |
| Cifras | Suporte a cifras modernas (ex.: ECDHE-RSA-AES256-GCM-SHA384) |
| Chave | RSA 2048 bits, SHA-256 |
| Certificado | Cliente, emitido/registrado no onboarding |
Renovação
Certificados têm validade. A Conta Simples comunica a janela de renovação com antecedência. Planeje a troca do certificado antes do vencimento para evitar interrupção das emissões — a renovação de mTLS não é automática.
Troubleshooting
Causas comuns:
- Certificado de cliente ausente ou não apresentado (
--cert/--key) - Certificado não registrado na trust store (ainda em onboarding)
- Host incorreto (use o host mTLS dedicado, não o host padrão)
Solução: confirme o certificado, o host e que o onboarding foi concluído.
Causas comuns:
- Certificado expirado ou emissor inesperado
- Credencial (Bearer) ausente ou inválida
Solução: verifique a validade do certificado e a credencial OAuth.