API do Contravo

Crie contratos a partir do seu CRM, leve os dados para o ERP ou faturamento e mantenha os clientes sincronizados, sem digitar nada duas vezes.

A documentação é aberta. O acesso à API (chave de integração) faz parte dos planos pagos.

Começando

A API usa JSON e HTTPS. Todos os endereços começam com:

https://api.contravo.com.br/v1

Tudo que se faz nas telas também se faz pela API, e com as mesmas regras: o que a pessoa não pode fazer na tela, a chave também não pode. Cada empresa só enxerga os próprios dados.

Autenticação

O administrador da sua empresa gera uma chave de integração e escolhe o que ela pode fazer (por exemplo: só ler contratos, ou criar clientes e contratos). Envie a chave em todas as chamadas:

Authorization: Bearer pk_live_1a2b3c4d_SEU_SEGREDO

• A chave aparece uma única vez, quando é criada. Guardamos apenas uma assinatura dela, nunca a chave em si.
• Uma chave pode ser revogada a qualquer momento, sem afetar as outras.
• Tudo o que a chave faz fica no histórico com o nome dela (ex.: “API: Integração ERP”).
• Nunca coloque a chave em código que roda no navegador ou no celular do cliente.

Formato dos dados

• Datas: AAAA-MM-DD, por exemplo 2026-12-01.
• Valores em dinheiro: texto com ponto decimal, por exemplo "12500.00" (evita erro de arredondamento).
• CPF e CNPJ: com ou sem pontuação; os dígitos verificadores são conferidos.
• Chaves dos dados: cada informação do contrato tem uma chave fixa da sua empresa, como valor_contrato ou data_inicio. A lista completa está em GET /fields.
• Seu próprio id: clientes e contratos aceitam um externalId, o código deles no seu sistema, para você nunca precisar guardar os ids do Contravo.

Paginação

As listas vêm em páginas. Use page (começa em 1) e pageSize (20, 50 ou 100; padrão 20). A resposta traz o total para você saber quantas páginas existem:

{ "data": [ ... ], "page": 1, "pageSize": 20, "total": 137 }

Clientes

{
  "type": "PJ",
  "name": "Construtora Vale Verde Ltda",
  "document": "32.188.842/0001-05",
  "email": "contratos@valeverde.com.br",
  "contacts": [
    { "name": "Eduardo Rocha", "email": "eduardo@valeverde.com.br",
      "cpf": "602.572.505-57", "defaultRoles": ["SIGNER"] }
  ]
}

Templates e campos

Contratos

{
  "templateId": "cm3x8k2p00001",
  "clientId": "cm3x8j9a00007",
  "externalId": "PED-2026-1187",
  "values": {
    "data_inicio": "2026-12-01",
    "prazo_meses": 12,
    "indice_reajuste": "IPCA",
    "equipamentos_locados": [
      { "identificador": "AND-8513", "descricao": "Andaime tubular",
        "quantidade": 109, "valor_unitario_mensal": "35.00" }
    ]
  }
}

Ler e alterar dados

{
  "number": 1042,
  "externalId": "PED-2026-1187",
  "status": "IN_WORKFLOW",
  "summary": { "value": "3815.00", "startDate": "2026-12-01", "endDate": "2027-11-30" },
  "variables": {
    "indice_reajuste": { "label": "Índice de reajuste", "type": "SELECT", "value": "IPCA" },
    "equipamentos_locados": {
      "type": "LIST",
      "value": [ { "identificador": "AND-8513", "quantidade": 109, "valor_unitario_mensal": "35.00" } ],
      "totals": { "total": "3815.00", "groups": [] }
    }
  }
}

Buscar itens

Erros

Os erros vêm com uma mensagem em português, pronta para mostrar a quem usa o seu sistema. Quando o problema é em dados específicos, cada chave vem com o seu motivo:

{ "statusCode": 400,
  "message": "Valores inválidos: data_inicio (data inválida)",
  "errors": { "data_inicio": "data inválida" } }

• 401 chave ausente, errada ou revogada · 403 a chave não tem permissão para isso
• 404 não encontrado (ou de outra empresa) · 409 já existe (ex.: CPF/CNPJ repetido)
• 429 limite de chamadas atingido (veja Limites de uso)

Limites de uso

Para manter a API rápida para todos, cada empresa tem dois limites, conforme o plano. Só as chamadas de integração contam; o uso pelas telas do sistema não conta.

• Por minuto (rate limit): protege contra rajadas e laços infinitos. Picos curtos de até o dobro são aceitos, desde que a média do minuto fique dentro do limite.
• Por mês (cota): o total de chamadas no mês do calendário. Recomeça todo dia 1º.

Toda resposta informa quanto ainda resta no minuto atual:

X-RateLimit-Limit: 60        ← chamadas permitidas por minuto
X-RateLimit-Remaining: 57    ← quantas ainda restam neste minuto
X-RateLimit-Reset: 1764590460 ← quando o contador recomeça (segundos desde 1970)

Ao passar do limite, a resposta é 429 com o cabeçalho Retry-After, que diz em quantos segundos tentar de novo:

Retry-After: 12

{ "statusCode": 429, "message": "Limite de chamadas por minuto atingido. Tente de novo em 12 segundos." }

Precisa de mais? Os limites de uma empresa podem ser ampliados sem trocar de plano. Fale com a gente.

Boas práticas

• Use o seu código (externalId). PUT /clients/external/… cria ou atualiza numa chamada só, em vez de buscar e depois criar.
• Envie só o que mudou. PUT /contracts/…/variables aceita apenas os campos alterados.
• Ao receber 429, espere o Retry-After. Para erros 5xx, tente de novo aos poucos (1s, 2s, 4s…), no máximo algumas vezes.
• Guarde o que muda pouco. Templates e o dicionário de campos raramente mudam: consulte uma vez por dia, não a cada contrato.
• Uma chave por integração. Assim o histórico mostra de onde veio cada mudança, e dá para revogar uma sem parar as outras.

Versões

O endereço tem a versão (/v1). Novidades que não quebram integrações (campos e endereços novos) entram na mesma versão. Mudanças que quebrariam uma integração só acontecem numa versão nova (/v2), com aviso antecipado; a anterior continua funcionando por um período de transição.

Webhooks em breve

Seu sistema será avisado quando algo acontecer: contrato aprovado, assinado, vencendo, reajustado. Sem precisar consultar a API de tempos em tempos.

Referência completa

Todos os endereços, campos e respostas, gerados direto do código (sempre atualizados):