Integre assinaturas
ao seu ERP.

Comece pelo fluxo de envelopes.

Um envelope reúne um PDF, seus destinatários e o registro dos aceites. Para uma jornada com clientes assinando na página da CLP, use /v1/envelopes.

1. Após habilitação da conta, entre no portal, configure a marca e o remetente e gere sua chave de API. A verificação do remetente é assistida pela CLP.
2. Escolha proteção pelo certificado da plataforma, quando disponível, ou importe o certificado próprio da empresa.
3. Configure o webhook HTTPS e persista seu segredo no servidor.
4. Envie o envelope com uma chave de idempotência estável para a operação do ERP.
5. Aguarde envelope.completed, baixe os três arquivos e confirme os hashes antes de registrar o arquivamento.

curl --fail-with-body "https://api.clpsistemas.com.br/v1/envelopes/$ENVELOPE_ID/signing-links" \
  -H "Authorization: Bearer $CLP_API_KEY"

A resposta contém envelope_id, expires_at e recipients, com recipient_id, name, email e signing_url. Só aparecem destinatários que ainda não aceitaram nem recusaram, em envelopes abertos e dentro do prazo. Links são privados: preserve o fragmento #, não registre a resposta em logs ou ferramentas de análise e entregue cada URL apenas à pessoa correspondente. A confirmação de acesso por e-mail continua obrigatória para visualizar o PDF.

Marca, logo, geração/revogação de chaves e cancelamento da mensalidade são geridos no portal. As rotas de sessão do portal não fazem parte do contrato público de autenticação por chave de API.

Autenticação entre servidores.

Endereço base: https://api.clpsistemas.com.br. Envie Authorization: Bearer SUA_CHAVE_CLP em todas as rotas /v1 desta referência. GET /public/plans é público.

curl --fail-with-body 'https://api.clpsistemas.com.br/v1/account/subscription' \
  -H "Authorization: Bearer $CLP_API_KEY"

Carregue CLP_API_KEY do cofre ou configuração protegida do seu servidor. Não coloque chaves em páginas web, aplicativos distribuídos, URLs, repositórios ou logs. A chave da empresa é diferente da credencial Asaas da CLP.

As respostas JSON usam snake_case. Campos opcionais sem valor podem estar ausentes. Datas são UTC em formato ISO 8601; identificadores de recursos usam UUID. A chave só acessa os recursos da própria empresa.

O limite padrão é de 60 requisições por minuto por chave. Em 429, aplique espera progressiva com variação aleatória. O cabeçalho Retry-After não é garantido.

Envie o PDF e os destinatários.

POST /v1/envelopes

Corpo multipart/form-data. Não defina manualmente o Content-Type ao usar FormData ou cURL; a biblioteca precisa incluir o delimitador.

curl --fail-with-body 'https://api.clpsistemas.com.br/v1/envelopes' \
  -H "Authorization: Bearer $CLP_API_KEY" \
  -H 'Idempotency-Key: erp-pedido-1042-v1' \
  -F '[email protected];type=application/pdf' \
  --form-string 'title=Contrato de prestação de serviços' \
  --form-string 'external_id=PEDIDO-1042' \
  --form-string 'protection_mode=platform' \
  --form-string 'recipients=[{"name":"Ana Exemplo","email":"[email protected]"},{"name":"Bruno Exemplo","email":"[email protected]"}]'

import { readFile } from 'node:fs/promises';

const form = new FormData();
form.set('pdf', new Blob([await readFile('./contrato.pdf')],
  { type: 'application/pdf' }), 'contrato.pdf');
form.set('title', 'Contrato de prestação de serviços');
form.set('external_id', 'PEDIDO-1042');
form.set('protection_mode', 'platform');
form.set('recipients', JSON.stringify([
  { name: 'Ana Exemplo', email: '[email protected]' },
  { name: 'Bruno Exemplo', email: '[email protected]' }
]));

const response = await fetch('https://api.clpsistemas.com.br/v1/envelopes', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CLP_API_KEY}`,
    'Idempotency-Key': 'erp-pedido-1042-v1'
  },
  body: form,
  signal: AbortSignal.timeout(60000)
});
if (!response.ok) throw new Error(`CLP retornou HTTP ${response.status}`);
const envelope = await response.json();
// Persista envelope.id junto à operação do ERP, sem registrar credenciais.
// Timeout: consulte/reenvie com a mesma chave, nunca com uma chave nova automática.

Resposta 201: envelope criado

Exemplo parcial. Um 201 confirma a criação e o enfileiramento dos convites, não o recebimento do e-mail nem a conclusão da assinatura.

{
  "id": "11111111-1111-4111-8111-111111111111",
  "title": "Contrato de prestação de serviços",
  "external_id": "PEDIDO-1042",
  "status": "sent",
  "sequence": 1,
  "protection_mode": "platform",
  "created_at": "2026-09-28T15:00:00Z",
  "expires_at": "2026-10-05T15:00:00Z"
}

Repetição: os mesmos dados e bytes, com a mesma chave, retornam o envelope existente com 200. Conteúdo diferente retorna 409 idempotency_conflict. Após timeout, repita com a mesma chave; não gere outra automaticamente. Uma alteração legítima no documento é um novo envio.

Consultar andamento

curl --fail-with-body "https://api.clpsistemas.com.br/v1/envelopes/$ENVELOPE_ID" \
  -H "Authorization: Bearer $CLP_API_KEY"

A consulta individual retorna {"envelope": {...}, "recipients": [...]}. Cada destinatário informa id, name, email e, quando existentes, viewed_at, accepted_at e declined_at. A criação retorna diretamente o objeto do envelope, sem esse agrupamento.

GET /v1/envelopes?page=1 retorna um array de até 100 envelopes, do mais recente para o mais antigo. Não há total nem cursor nessa resposta. Incremente a página até receber menos de 100 itens; deduplique por ID se novos envios ocorrerem durante a paginação.

Os convites são enviados aos participantes em paralelo. A ordem no array não cria uma sequência de assinaturas. Todos precisam aceitar para iniciar a finalização.

Duas modalidades de proteção.

GET /v1/envelopes/protection informa enabled, available, legal_name e, quando presentes, document e expires_at. Confira available antes de integrar a modalidade platform.

• platform: a CLP seleciona o certificado do prestador. Não envie certificate_id. Sem certificado utilizável, a criação retorna 503 platform_seal_unavailable.
• customer: use o A1 da empresa da conta. Envie seu certificate_id e mantenha a validade e a autorização atualizadas.

Os signatários registram seus próprios aceites eletrônicos. A proteção final do PDF por certificado do prestador ou da empresa não representa a vontade das partes nem converte esses aceites em assinaturas pessoais ICP-Brasil.

Importar o A1 da empresa

POST /v1/certificates, multipart: arquivo pfx de até 256 KB, campo password com a senha do arquivo e accept_authorization=true para registrar a autorização de uso. Em produção, use multipart; o envio JSON não contempla a confirmação exigida.

O certificado deve ter chave privada utilizável, estar válido e, em produção, ser ICP-Brasil e pertencer ao CPF/CNPJ da conta. A senha abre o arquivo durante a importação; a aplicação não a persiste para cada assinatura. O retorno 201 traz metadados, incluindo id, document, not_after, status e icp_brasil.

GET /v1/certificates lista os certificados; GET /v1/certificates/{id} consulta um deles. DELETE /v1/certificates/{id} bloqueia seu uso e retorna 204. Antes de excluir, confira envelopes ainda pendentes que dependam do certificado.

Receba eventos. Valide a origem.

Configuração da empresa

curl --fail-with-body -X PUT 'https://api.clpsistemas.com.br/v1/account/webhook' \
  -H "Authorization: Bearer $CLP_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"url":"https://erp.example.com/webhooks/clp","rotate_secret":false}'

A resposta contém url e secret. Guarde o segredo no servidor. Enviar rotate_secret=true troca o segredo usado nas próximas tentativas; coordene a alteração com o receptor. A URL deve ser HTTPS, porta 443, pública e sem redirecionamentos ou endereços internos.

POST /v1/account/webhook/test enfileira webhook.test e retorna 202 com delivery_id. Consulte GET /v1/account/webhook/deliveries para as últimas 50 entregas, tentativas e erros. DELETE /v1/account/webhook remove a configuração. Reenvio manual de uma entrega fica disponível no portal.

Eventos de documentos

Não há evento individual de cada aceite, leitura, recusa ou cancelamento nesta versão. Consulte o envelope para esses estados. Os eventos signature.completed e signature.failed pertencem à assinatura direta, não ao fluxo de aceites.

{
  "id": "22222222-2222-4222-8222-222222222222",
  "event": "envelope.completed",
  "created_at": "2026-09-28T15:30:00Z",
  "account_id": "33333333-3333-4333-8333-333333333333",
  "data": {
    "envelope": {
      "id": "11111111-1111-4111-8111-111111111111",
      "external_id": "PEDIDO-1042",
      "status": "completed",
      "sequence": 4
    },
    "files": [
      "original",
      "final",
      "evidence"
    ],
    "download_endpoint": "/v1/envelopes/11111111-1111-4111-8111-111111111111/files/{kind}"
  }
}

O exemplo acima é parcial. O webhook não inclui o PDF nem uma URL pública permanente. Construa o download no endereço base da API com o ID validado e um kind permitido.

Autenticação HMAC-SHA256

Cabeçalhos: X-Clp-Delivery-Id, X-Clp-Event, X-Clp-Timestamp (Unix, em segundos) e X-Clp-Signature. Calcule sha256= + HMAC hexadecimal de timestamp + ponto + corpo bruto UTF-8, usando o segredo como chave.

import { createHmac, timingSafeEqual } from 'node:crypto';

// Supply the original request bytes, before any JSON parser or body transformation.
// Resolve the secret from the receiver's account configuration, never from the body.
export function verifyClpWebhook({ rawBody, timestamp, signature, secret, nowMs = Date.now() }) {
  if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || secret.length === 0) return false;
  if (typeof timestamp !== 'string' || !/^\d{1,12}$/.test(timestamp)) return false;
  if (typeof signature !== 'string' || !/^sha256=[0-9a-fA-F]{64}$/.test(signature)) return false;
  if (!Number.isFinite(nowMs) || Math.abs(nowMs / 1000 - Number(timestamp)) > 300) return false;
  const expected = createHmac('sha256', secret).update(timestamp + '.', 'utf8').update(rawBody).digest();
  const supplied = Buffer.from(signature.slice(7), 'hex');
  return supplied.length === expected.length && timingSafeEqual(supplied, expected);
}

// After authentication: validate JSON, match body.id/body.event to delivery headers,
// persist the event with a unique (account, event.id) constraint, then acknowledge 2xx.
// Download files in a durable background job. An HMAC check alone is not deduplication.

Baixar o verificador Node.js completo ↗. Capture os bytes antes do parser JSON. Não reserialize o corpo para verificar. Faça a comparação em tempo constante e aceite apenas relógios dentro da tolerância de cinco minutos. Sincronize o relógio do servidor.

1. Resolva o segredo pela configuração da conta no receptor, não por um account_id ainda não autenticado.
2. Verifique a assinatura e só então interprete o JSON; confira se id e event correspondem aos cabeçalhos.
3. Persista o evento com unicidade por empresa e ID; responda 2xx somente depois. Não confirme sucesso se a gravação falhar.
4. Processe o download em uma fila durável. Repetições válidas já persistidas também podem receber 2xx.

Eventos podem repetir e chegar fora de ordem. As retentativas conservam o ID e usam novo timestamp. A entrega é tentada por até sete dias, respeitando a disponibilidade dos arquivos. HTTP 2xx confirma recebimento do evento, não seu arquivamento. Use sequence quando presente e consulte o estado atual; mantenha também reconciliação periódica pela API.

Baixe, confira e arquive.

Após completed, use GET /v1/envelopes/{id}/files/{kind}, sendo kind original, final ou evidence. Os dois primeiros retornam PDF; evidence retorna JSON como arquivo. A autorização continua sendo a chave da empresa.

curl --fail-with-body \
  "https://api.clpsistemas.com.br/v1/envelopes/$ENVELOPE_ID/files/final" \
  -H "Authorization: Bearer $CLP_API_KEY" \
  --dump-header final.headers --output final.pdf

# Baixe também /files/original e /files/evidence.
# Só arquive como concluído se o HTTP for 200 e os três hashes coincidirem.

Compare o SHA-256 dos bytes com original_sha256, final_sha256 e evidence_sha256 do envelope. Cada download também traz X-Content-Sha256. Grave os três artefatos de forma durável antes do recibo:

{
  "original_sha256": "SUBSTITUA_PELO_SHA256_DO_ORIGINAL",
  "final_sha256": "SUBSTITUA_PELO_SHA256_DO_FINAL",
  "evidence_sha256": "SUBSTITUA_PELO_SHA256_DAS_EVIDENCIAS"
}

O recibo retorna archived_at e, quando aplicável, retain_until. Não antecipa a exclusão, não estende a guarda e não substitui o armazenamento no ERP.

Prazo e links temporários

expires_at é o prazo para coletar os aceites; retain_until é o prazo de disponibilidade dos arquivos. Não confunda o prazo de assinatura com a guarda de um ou dois anos do plano. Consulte o envelope para o prazo vigente, inclusive após renovação ou cancelamento.

A guarda segue o plano: até um ano no Essencial e dois no Profissional, enquanto ativo; Empresarial enquanto a assinatura estiver ativa. Após encerramento, a janela de exportação é de 30 dias, respeitado o limite de idade do documento. retain_until pode estar ausente quando não há uma data determinada. Conserve suas cópias conforme os requisitos da sua atividade.

GET /v1/envelopes/{id}/files/{kind}/link retorna direct, expires_at e, se disponível, url. Com direct=false, utilize o download autenticado normal. Um link direto vale no máximo dois minutos e nunca além do prazo do envelope; não registre ou redistribua a URL. Não envie a chave CLP ao host de armazenamento.

Estados e recuperação.

• POST /v1/envelopes/{id}/resend: reenvia aos pendentes; até três operações por hora, apenas enquanto aberto. Retorno 202.
• POST /v1/envelopes/{id}/cancel: cancela apenas quando status=sent. Retorno 200 com status=canceled.
• POST /v1/envelopes/{id}/retry: retoma sealing_failed; retorna 202. Consulte até a conclusão.
• PUT /v1/envelopes/{id}/certificate: em falha e antes de existir PDF final, envie {"certificate_id":"UUID_DO_NOVO_CERTIFICADO"} para customer ou {} para a plataforma selecionar seu certificado atual. Retorno 202.

Assinatura direta com certificado próprio.

POST /v1/signatures aplica a assinatura do certificado da empresa diretamente ao PDF. Não cria destinatários, convites, página de aceite ou evidências de consentimento. Para obter esses recursos, use envelopes.

Envie multipart com pdf, certificate_id e Idempotency-Key. Os campos reason, location e contact são opcionais. O certificado da plataforma não é permitido nessa rota.

curl --fail-with-body 'https://api.clpsistemas.com.br/v1/signatures' \
  -H "Authorization: Bearer $CLP_API_KEY" \
  -H 'Idempotency-Key: erp-assinatura-direta-1042-v1' \
  -F '[email protected];type=application/pdf' \
  --form-string "certificate_id=$CERTIFICATE_ID" \
  --dump-header assinatura.headers --output assinatura.resposta

# Confira o status e o Content-Type antes de tratar a resposta como PDF.

A resposta normal é PDF com X-Signature-Id e X-Signed-Sha256. Com ?response=json, retorna signature e signed_pdf_base64. Armazene a resposta: o endpoint direto não guarda o PDF para download posterior.

Em repetição já concluída, o servidor retorna JSON com replay=true e o registro, sem os bytes do PDF, mesmo se a primeira resposta foi binária. Confira Content-Type e Idempotent-Replay antes de salvar o resultado como PDF. Não faça nova assinatura automaticamente para tentar recuperar um arquivo perdido.

GET /v1/signatures aceita page (padrão 1), pageSize (1–200, padrão 50), from, to e certificateId; retorna items, page, page_size e total. O filtro to é exclusivo. GET /v1/signatures/{id} retorna o registro de auditoria.

POST /v1/verify recebe o PDF em multipart (campo pdf), ou JSON com pdf_base64. Retorna valid, signature_count, file_size, signatures e warnings. Leia os resultados de integridade e cadeia e os avisos; o relatório técnico não equivale a uma análise jurídica do contrato.

Limites e tratamento de erros.

Franquias: Essencial 500 documentos/mês; Profissional 1.500; Empresarial sem franquia mensal. Até cinco signatários por envelope e cinco certificados ativos por empresa. API e portal compartilham a franquia. Envelope conta uma vez no envio; assinatura direta conta quando concluída. Reenvios e repetições idempotentes não duplicam o consumo.

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Esta chave já foi usada com outro conteúdo.",
    "request_id": "ID_DA_REQUISICAO"
  }
}

Não presuma JSON em toda resposta: limites de infraestrutura, 429 e downloads podem ter outro formato. Confira status e Content-Type. Envie request_id ao suporte sem incluir chave, senha, PDF ou URL temporária.

Conferência com IA: piloto por API.

Seu ERP envia o PDF, recebe os trechos extraídos e compara os campos da operação antes de autorizar os convites. O piloto está ativado para contas habilitadas, com 100 análises por mês por empresa, separadas da franquia de documentos — inclusive no Empresarial. Consulte os limites atuais em GET /v1/ai/capabilities.

1. Envie POST /v1/ai/analyses em multipart com pdf, allow_ai_processing=true e Idempotency-Key. Essa autorização cobre o envio do texto ao Google Gemini. Aceita PDF com texto selecionável, até 10 MB, 50 páginas e 100 mil caracteres; não faz OCR.
2. Leia id e status; se receber 202, consulte GET /v1/ai/analyses/{id}. Rascunhos duram 24 horas. Retentativas devem usar a mesma chave e o mesmo PDF.
3. Quando concluído, envie POST /v1/ai/analyses/{id}/compare com JSON como {"monthly_amount_brl":249.90,"term_months":12}. Também aceita party_documents, até dez CPF/CNPJ válidos. Pelo menos um campo é obrigatório; outros campos são rejeitados. Os dados esperados não são enviados ao modelo.
4. Leia comparison.status: no_difference_detected, needs_review ou inconclusive. Cada conferência contém trechos e páginas. Sempre revise o PDF: ausência de diferença não significa aprovação jurídica.
5. Após revisão, crie o envelope com o mesmo PDF, ai_analysis_id e ai_reviewed=true. Se desejar mostrar trechos revisados aos destinatários, acrescente include_ai_summary=true. Nada é enviado automaticamente pela análise.

DELETE /v1/ai/analyses/{id} descarta o rascunho; não remove um resumo já vinculado a envelope. Alterações no PDF exigem nova análise. Falhas após envio ao provedor podem consumir a franquia; compare não faz nova chamada ao modelo. O envio manual continua disponível sem IA.

Explorar a demonstração fictícia da conferência ↗

Antes de liberar a integração.

Use dados sintéticos e destinatários de teste autorizados na homologação combinada. Os exemplos desta documentação não criam um ambiente sandbox nem autorizam envios a terceiros.