Contratos como serviço, na sua plataforma

Autenticação

Toda chamada leva Authorization: Bearer cnsc_sk_…. Cada chave pertence a um tenant, carrega escopos (contracts:read/write, templates:read/write, sign:write, account:read/write e, para os contratos de nível 2 e 3, contracts:operate e contracts:intervene) e tem rate-limit por minuto. O antigo sign:request continua aceito como sinônimo de sign:write. Chaves são exibidas uma única vez; guarde com segurança. A chave pessoal (cnsc_uk_, da página de integrações) só tem contracts:read/write e account:read, e pedir assinatura com ela vira uma proposta que uma pessoa confirma. A chave de empresa (também cnsc_uk_, gerada em Minha conta, Identidades, por quem responde por uma empresa verificada) é a do sistema da empresa: o que ela cria nasce na carteira da empresa, e o pedido de assinatura sai na hora, para as partes do contrato, dentro do plano de quem gerou a chave. Ela para de valer se essa pessoa deixar de responder pela empresa. Pela chave pessoal você alcança o que alcança na tela, inclusive a restrição por área da empresa; a chave da empresa alcança a carteira inteira. O limite por minuto (GET /v1/usage, campo rate_limit) é 120 na chave pessoal e na de empresa, 60, 120 ou 300 conforme o plano do intermediador e até 30 na chave de teste do intermediador.

curl https://api.contratocombinado.com/v1/usage -H "Authorization: Bearer cnsc_sk_SUACHAVE"

Quickstart: do template ao PDF em 3 chamadas

1. Crie um template com cláusulas, {{placeholders}} tipados e regras:

curl -X POST https://api.contratocombinado.com/v1/templates \
  -H "Authorization: Bearer cnsc_sk_SUACHAVE" -H "Content-Type: application/json" \
  -d '{
    "name": "Campanha com modelo",
    "contract_type": "Contrato de campanha publicitária",
    "body": {"clauses": [
      {"number": 1, "title": "Partes", "text": "AGENCIA: {{agencia}}. MODELO: {{modelo}}."},
      {"number": 2, "title": "Cache", "text": "Cache de {{cache}}, pago em até 15 dias."},
      {"number": 3, "title": "Direito de imagem", "text": "Uso limitado à campanha por {{prazo_imagem}}."}
    ]},
    "variables": [
      {"key": "agencia", "required": true}, {"key": "modelo", "required": true},
      {"key": "cache", "required": true}, {"key": "prazo_imagem", "required": false}
    ],
    "min_clauses": ["Direito de imagem"],
    "question_policy": {"ask": ["prazo_imagem"]}
  }'

2. Gere o contrato. Com dados completos, mode=fill responde na hora (201, sem IA):

curl -X POST https://api.contratocombinado.com/v1/contracts \
  -H "Authorization: Bearer cnsc_sk_SUACHAVE" -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-123" \
  -d '{
    "template_id": "TEMPLATE_ID", "mode": "fill",
    "variables": {"agencia": "Sua Agência LTDA", "modelo": "Ana Souza", "cache": "R$ 3.000,00", "prazo_imagem": "12 meses"},
    "parties": [
      {"role": "agencia", "name": "Sua Agência LTDA", "kind": "PJ"},
      {"role": "modelo", "name": "Ana Souza", "kind": "PF"}
    ]
  }'

3. Baixe os artefatos:

curl https://api.contratocombinado.com/v1/contracts/CASE_ID/outputs/draft.pdf -H "Authorization: Bearer cnsc_sk_SUACHAVE" -o contrato.pdf
curl https://api.contratocombinado.com/v1/contracts/CASE_ID/outputs/summary.json -H "Authorization: Bearer cnsc_sk_SUACHAVE"

O que cada parte pode negociar. Em cada cláusula do template, negociacao define o modo: fixa (a parte aceita ou recusa, o texto não muda), faixa (a parte escolhe o valor de uma variável entre min e max), catalogo (a parte escolhe uma das opcoes redigidas por você) ou livre. Com "obrigatoria": true, a cláusula não pode ser removida. Se o template declara negociacao em alguma cláusula, as demais ficam fixa, e o contrato precisa ser criado com mode=fill. Uma proposta fora disso é recusada pelo servidor, inclusive a que nasce da sugestão da IA.

O tipo_contrato que o GET devolve é derivado do template, nunca escolhido: essencial (tudo fixa e "analise_por_lado": false), negociado (alguma cláusula negociável ou análise por lado ligada) ou mediado (nível 3). Enquanto houver tópico aberto na mesa do contrato, o pedido de assinatura responde 409. Em qualquer nível, impasse_status diz se o contrato está em impasse, de que tipo ( divergencia: tópico aberto na mesa; sem_resposta: proposta há mais de 3 dias sem decisão) e desde quando, sem o conteúdo. Cada parte traz requirements: currently_due (o que ela deve agora, inclusive marco.<chave> que o papel dela confirma), past_due (o que já venceu), eventually_due (o que ainda vai ser pedido, como a assinatura), blocked_reason e current_deadline.

Marcos. Em body.marcos o template declara o que acontece depois da assinatura: cada marco tem chave, rotulo, tipo (entrega, evento, pagamento ou data), prazo ({"data": "2026-12-01"}, {"dias_da_assinatura": 30} ou {"variavel": "data_entrega"}), quem_confirma (o papel de uma parte, qualquer_parte ou intermediador, este só com nível 2) e, se quiser, aceite_tacito_dias. Variável pode ter tipo (texto, numero, moeda, data, opcao com opcoes, pessoa); fora do tipo, 422 variable_invalid. O GET devolve em marcos o estado de cada um: pendente, confirmado, contestado, vencido ou aceito_tacitamente (passou o prazo e mais esses dias sem contestação). O motivo de uma contestação fica entre as partes.

Prazo de resposta. Proposta de mudança sem resposta não vira aceite: ela expira. body.prazo_de_resposta_dias (de 7 a 30; sem o campo, 15) define o prazo, copiado para o contrato na criação. Três dias antes, quem precisa decidir recebe um lembrete por e-mail. No prazo, a proposta fica expirada e, se era aditivo ou distrato, sai aditivo.recusado ou distrato.recusado com "motivo": "expirada". Pedido de assinatura vencido fica expirada e sai contrato.expirado.

Aditivo fora do modelo. Depois de assinado, o contrato é das partes: nos níveis 0 a 2 um aditivo pode mudar cláusula fixa, sem veto do intermediador. O aditivo.proposto traz fora_do_modelo com o que saiu da trava (fixa:cl_3, removida:cl_5, clausula_nova), e o GET do contrato traz fora_do_modelo (e, a partir do nível 1, clausulas_fora_do_modelo) depois do aceite. No nível 3 o mesmo aditivo espera a sua decisão de exceção, como a contraproposta. Regra do seu negócio (taxa, pagamento pela plataforma) mora nos seus termos de uso com cada parte, não no contrato entre elas.

Troca de signatário. Uma parte que é empresa escolhe quem assina por ela: o responsável pela empresa (ou quem assina hoje) troca para outro membro da empresa com CPF na conta, antes de essa pessoa assinar. As outras partes recebem aviso, sem novo aceite, e você recebe signatario.trocado com o party_id. O intermediador não troca: antes do vínculo, corrija o e-mail pelo PATCH da parte. Pessoa física não troca (seria trocar a parte).

{"number": 2, "title": "Prazo", "text": "Entrega em {{prazo}} dias.",
 "negociacao": {"modo": "faixa", "variavel": "prazo", "min": 10, "max": 30, "unidade": "dias"}}
{"number": 3, "title": "Foro", "text": "Foro de São Paulo.",
 "negociacao": {"modo": "catalogo", "opcoes": [{"id": "rj", "texto": "Foro do Rio de Janeiro."}]}}

Começar com a chave de empresa

Para o sistema da sua empresa enviar documentos para assinar, sem intermediário. Quase tudo abaixo também existe na tela e no conector MCP. O conector não baixa o PDF assinado nem configura o webhook: isso se faz pela API ou pela tela.

1. Cadastre e verifique a empresa. Em Minha conta, Identidades, informe o CNPJ e envie o contrato social (ou documento equivalente). A decisão chega por e-mail; se recusada, vem com o motivo e você envia outro.
2. Gere a chave na mesma tela (só quem responde pela empresa). Ela aparece uma vez. Na mesma tela, ligue o webhook para receber os eventos da carteira da empresa.
3. Envie um PDF para assinar. O arquivo fica intacto; o PDF assinado é ele com o certificado ao fim.

curl -X POST https://api.contratocombinado.com/v1/contracts/documents \
  -H "Authorization: Bearer cnsc_uk_SUACHAVE" \
  -F "file=@contrato.pdf" \
  -F 'meta={"title": "Contrato de prestação de serviços", "send": true,
            "signers": [{"name": "Ana Souza", "email": "ana@cliente.com.br", "cpf": "12345678909"}],
            "authentication": ["cpf"], "expires_in_days": 15}'

Acompanhe. GET /v1/contracts/CASE_ID/signature traz cada pessoa e, quando todos assinam, sealed. O PDF assinado sai em GET /v1/contracts/CASE_ID/signed-pdf (os anexos com ?attachment=N). Com o webhook ligado, você recebe contrato.assinado sem perguntar. Para cancelar o pedido: POST /v1/contracts/CASE_ID/signature-request/cancel; para reenviar o convite a quem não assinou: POST …/signature-request/resend com {"email"}.

O mesmo documento para muitas pessoas: um contrato e um convite para cada uma, em segundo plano.

curl -X POST https://api.contratocombinado.com/v1/contracts/documents/batch \
  -H "Authorization: Bearer cnsc_uk_SUACHAVE" \
  -F "file=@termo.pdf" \
  -F 'meta={"operation_id": "UM-UUID-SEU", "title": "Termo de adesão",
            "signers": [{"name": "Quem assina pela empresa", "email": "rh@suaempresa.com.br"}],
            "recipients": [{"name": "Ana Souza", "email": "ana@x.com"}, {"name": "Bruno Lima", "email": "bruno@x.com"}]}'
curl https://api.contratocombinado.com/v1/contracts/documents/batch/BATCH_ID -H "Authorization: Bearer cnsc_uk_SUACHAVE"

Modelos. Guarde o PDF com quem assina sempre, as posições e as opções em POST /v1/document-templates, e envie só com template_id (sem file), no envio único ou no lote. Com variables, cada contrato sai com o nome, o e-mail, o CPF de quem recebe ou a data escritos no PDF.

Limites

Chave de teste

Gere a chave de teste em Minha conta, Identidades, logo abaixo da chave da empresa. Ela usa as mesmas rotas (documento, lote, modelos, status) e nada sai para fora: os contratos ficam fora da carteira real, não contam no plano, e as pessoas usam e-mail @teste.contratocombinado.com, em que o nome decide o que acontece: aceita@ assina e recusa@ recusa (para várias, aceita+1@, aceita+2@). A assinatura é simulada na hora, sem e-mail, selo nem PDF assinado, então não há pedido para cancelar nem convite para reenviar. O webhook do teste é só dele: ligue com PUT /v1/webhook usando a chave de teste. Criar ou analisar contrato com IA não existe na chave de teste (403 sandbox_unsupported).

Os três modos

Perguntas pendentes chegam de duas formas: webhook case.needs_input (você renderiza na sua UI e responde via POST /v1/contracts/{id}/answers) ou o embed abaixo.

Embed: o fluxo dentro da sua plataforma

curl -X POST https://api.contratocombinado.com/v1/embed-sessions \
  -H "Authorization: Bearer cnsc_sk_SUACHAVE" -H "Content-Type: application/json" \
  -d '{"contract_id": "CASE_ID", "surface": "complete"}'
# → { "url": "https://contratocombinado.com/#/embed/<token>", "expires_at": ... }

Coloque a url num iframe. Surfaces: complete (o usuário responde as perguntas, em formulário ou conversa), review (cláusulas com tradução leiga) e status. O iframe emite postMessage para a sua página ({source:"cnsc", type}): cnsc:ready, cnsc:status, cnsc:resized (altura) e cnsc:completed, só se a origem da sua página estiver em embed_origins (PUT /v1/branding, até 10 origens https://host[:porta]). Sem lista, nenhuma mensagem sai; o webhook continua sendo a fonte de verdade. A mesma lista decide onde a página aparece: num iframe de origem fora dela, o embed e o sign_url não mostram o contrato, só um link para abrir numa aba própria. O resto do site não abre em iframe nenhum. Ponha referrerpolicy="origin" no seu <iframe>: alguns navegadores só sabem a origem da sua página por aí, e sem ela o iframe recusa. Seu logo (só https, host público), cor (#RRGGBB) e rodapé vão no mesmo PUT /v1/branding.

Assinatura com validade jurídica

curl -X POST https://api.contratocombinado.com/v1/contracts/CASE_ID/signature-requests \
  -H "Authorization: Bearer cnsc_sk_SUACHAVE" -H "Content-Type: application/json" \
  -d '{"signers": [
    {"name": "Sua Agência LTDA", "email": "contratos@suaagencia.com", "role": "agencia"},
    {"name": "Ana Souza", "email": "ana@email.com", "role": "modelo"}
  ]}'
# → { "request_id": ..., "signers": [{ "name", "email", "sign_url" }] }

Cada signatário recebe convite por e-mail (com o seu branding) e você recebe o sign_url de cada um. Embede no seu fluxo (o iframe emite cnsc:signed para as origens de embed_origins). Assinatura eletrônica (MP 2.200-2/2001, art. 10, § 2º): consentimento + código por e-mail + trilha de auditoria (IP, horário) + selagem imutável com manifesto assinado pela plataforma (Ed25519) e âncora pública OpenTimestamps. Acompanhe em GET /v1/contracts/{id}/signature.

Webhooks

Ligue o webhook com PUT /v1/webhook e body {"url": "https://..."} (escopo account:write). O webhook existe para a chave do intermediador, para a chave de empresa e para a chave pessoal do advogado (quem responde por uma identidade no plano de advogado): ele recebe os eventos dos contratos dos clientes que representa e lê esses contratos em GET /v1/contracts/{id} (título, situação, partes e texto; sem escrever). A chave pessoal de quem não é advogado recebe 403. Na primeira vez a resposta traz o secret, uma única vez; trocar só a url mantém o secret, e "rotate": true gera um novo. Na rotação, o secret anterior continua assinando por 24 horas, para você trocar sem perder evento. Eventos: contrato.assinado (o contrato foi selado), case.completed, case.needs_input (com as questions[]), case.blocked e case.failed (o processamento falhou; traz code, estável, como job_failed, ai_unavailable, job_timeout ou job_interrupted, e message, em português). Os case.* trazem, além dos campos de sempre (event, case_id, status...), o mesmo cabeçalho dos demais: id, type, created_at e contract_id. O id é o mesmo em toda retentativa.

Contrato criado com parties também emite parte.convidada, parte.convite_reenviado, parte.entrou, assinatura.parte_assinou, contrato.assinado, contrato.cancelado, contrato.encerrado e, quando uma parte ou você mexe num marco, marco.confirmado, marco.contestado e marco.reaberto, e quando o prazo passa, marco.vencido e marco.aceito_tacitamente (com milestone, a chave do marco), e contrato.pronto_para_assinar quando todas as partes entraram, sem mesa aberta nem proposta pendente (com version_id; qualquer parte pode pedir a assinatura, ou você pela API). Também contrato.criado, contrato.recusado, contrato.expirado (pedido de assinatura vencido), pendencia.vencendo e pendencia.vencida (convite da parte), prazo.proximo (marco em até 3 dias), impasse.aberto/impasse.resolvido, signatario.trocado (a empresa trocou quem assina por ela), rodada.aberta (pedido de ajustes com round_id) e proposta.recebida (com proposta_id e kind; o texto se lê pela API). Aditivo e distrato emitem aditivo.proposto, aditivo.aceito, aditivo.recusado, aditivo.assinado, distrato.proposto, distrato.aceito, distrato.recusado e distrato.assinado; o teste de configuração emite webhook.teste. O corpo traz id (para deduplicar), type, created_at, contract_id, party_id quando houver, a sua metadata e, em data, o contrato exatamente como GET /v1/contracts/{id} devolve em intermediador. Não há garantia de ordem: o GET é a fonte da verdade.

Com a chave de empresa, o webhook (ligado pela API ou em Minha conta, Identidades) recebe os eventos da carteira da empresa, criados pela API ou pela tela: assinatura.parte_assinou, contrato.assinado, contrato.cancelado, contrato.encerrado, os de aditivo e os de distrato, além de rodada.aberta, proposta.recebida, signatario.trocado e contrato.aprovado (aprovação interna completa, com version_id; só nasce em contrato de empresa). Aí data traz title, status, created_at e parties (com name, role, side e signed).

Cada POST segue o padrão Standard Webhooks: webhook-id (o mesmo nas retentativas), webhook-timestamp e webhook-signature, verificáveis pelas bibliotecas oficiais com o secret como ele foi entregue. Continua indo também x-contracts-signature: sha256=<hex>, o HMAC-SHA256 do corpo cru:

import hmac, hashlib

  def verify(raw_body: bytes, header: str, secret: str) -> bool:
      expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
      return hmac.compare_digest(expected, header)

Só resposta 2xx conta como entregue: 3xx (o redirecionamento não é seguido), 4xx e 5xx são falha. Entrega que falha é re-tentada depois de 30 s, 2 min, 10 min, 30 min, 1 h, 3 h, 6 h e 12 h; depois disso fica como falhou. Se o endereço falhar sem parar por 3 dias, o webhook é desativado e os administradores (na chave de empresa, quem responde pela empresa) recebem um e-mail; cadastrar de novo com PUT religa. Para ver o que saiu e o que falhou, use GET /v1/webhook/deliveries?limit=50: cada entrega vem com event, status (entregue, pendente, retentando ou falhou), attempts, last_error, created_at e delivered_at.

Erros e idempotência

Erros seguem problem+json (RFC 7807): {"title", "detail", "status", "code", "param"}. Trate pelo code, que é estável; param aponta o campo que errou, quando se sabe. Exceção: o 422 de validação do corpo ou de parâmetro fora da faixa sai no formato padrão do FastAPI, {"detail": [...]}, sem code. O plano do tenant tem teto mensal (mês UTC) de contratos criados e de pedidos de assinatura: estourou, a resposta é 402 com type: "credito_insuficiente", antes de qualquer trabalho. Uso e limite em GET /v1/usage (campo limits). Contrato criado com parties consome crédito quando é enviado às partes, uma vez por contrato, pelo tipo: essencial, negociado ou mediado. Sem saldo, o send responde 402 antes de qualquer convite sair. O saldo do mês fica em GET /v1/usage (campo credito); quanto um template vai custar, em POST /v1/contracts/estimate. Em POST /v1/contracts, /contracts/analyze, /contracts/documents, /ask, /answers, /attachments e /risk-refresh, envie o header Idempotency-Key: o retry devolve o MESMO resultado e não cobra duas vezes. Em /ask não há o header: a chave vai no corpo, em idempotency_key. No lote (/contracts/batch) a chave vai em cada item (idempotency_key). As demais rotas de escrita não usam a chave: chamar send de novo só reenvia a quem ainda não entrou, e um segundo signature-requests com pedido ativo responde 409 sem criar outro. Em /contracts/documents, o retry com a mesma chave devolve o MESMO contrato (e o mesmo convite), sem criar outro; sem a chave, cada chamada cria um contrato novo. A mesma chave com outro arquivo ou outro meta responde 409 (idempotency_mismatch); enquanto o primeiro pedido ainda roda, o retry recebe 409 idempotency_in_progress com Retry-After. Casos de outro tenant respondem 404 (indistinguível de inexistente).

Referência de endpoints

Especificação viva: Swagger · openapi.json

Para testar sem escrever código: importe o endereço do openapi.json no Postman ou no Insomnia (Importar, depois Link). Ele monta a coleção com todas as rotas; ponha a chave em Authorization, tipo Bearer.

Chave sandbox

No sandbox, as partes usam e-mail @teste.contratocombinado.com, e o nome antes do arroba define o que a parte faz: aceita@ entra e assina, recusa@ entra e recusa a assinatura, expira@ nunca entra, documento-divergente@ erra o documento. Para várias partes com o mesmo comportamento, use aceita+1@, aceita+2@. Nenhum e-mail sai, ninguém ganha conta e a assinatura é simulada (sem selo nem PDF assinado). A projeção, os webhooks e o crédito funcionam como em produção.

A chave sandbox (engine real, cota reduzida) sai na hora, quando você cria o seu intermediador; o webhook você mesmo liga com PUT /v1/webhook.