API Pública / Guia, segurança e versões

Guia, segurança e versões

Um fluxo completo de exemplo, as regras de segurança e como a API evolui.

Exemplo: atendimento de chatbot

Um atendimento típico de segunda via, desbloqueio e suporte pelo WhatsApp:

  1. O assinante informa o CPF → GET /clientes?cpf_cnpj=....
  2. Se houver mais de um contrato, pergunte qual. A situacao e a conexao de cada um ajudam a orientar.
  3. Pediu o boleto → GET /faturas?contrato_id=...&situacao=aberta e envie a pagina_pix, o link_pagamento ou o pix_copia_cola.
  4. Contrato bloqueado e o cliente promete pagar → POST /contratos/{id}/desbloqueio-confianca. Em caso de recusa, a mensagem já explica o motivo.
  5. Sem internet → GET /contratos/{id}/conexao mostra se está online e quantas vezes caiu. Se precisar de visita, consulte GET /chamados?cliente_id=...&situacao=em_aberto e, não havendo chamado sobre o mesmo assunto, POST /chamados.
  6. Quer contratar → GET /planos e, escolhido o plano, POST /pre-cadastros/convites para enviar o link do formulário.
  7. Assine fatura.paga nos webhooks para confirmar o pagamento ao assinante assim que ele cair.

Especificação OpenAPI

A API está descrita no padrão OpenAPI 3: openapi.json. Importe no Postman ou no Insomnia para ter todas as rotas prontas, ou use um gerador de código para criar o cliente na sua linguagem. Depois de importar, ajuste o servidor para o endereço do provedor.

Segurança e LGPD

  • Guarde a chave e o segredo do webhook como senhas. Nunca os coloque em código de navegador, aplicativo de celular, repositório público ou URL.
  • Uma chave por sistema. Assim o provedor revoga só o que precisa, e a auditoria mostra quem fez cada ação.
  • Permissões mínimas e, sempre que possível, restrição de IP ao servidor da integração.
  • Valide a assinatura de todo webhook antes de confiar nele.
  • Toda ação que altera dados (desbloqueio, chamado, link de pré-cadastro) aparece na Auditoria de Usuários do provedor, com o nome da chave e o IP de origem.
  • A API devolve dados pessoais de assinantes. Quem integra é responsável por tratá-los conforme a LGPD, só para a finalidade combinada com o provedor, e por apagá-los quando a integração terminar.

Versões e mudanças

A versão faz parte do endereço (/api/v1). Dentro da v1, nenhum campo existente muda de nome ou de tipo, e nenhum é removido. Podem entrar campos, rotas e eventos novos, então ignore o que o seu sistema não conhece. Mudanças incompatíveis, se um dia forem necessárias, virão numa /api/v2, com a v1 mantida por um período de transição.

DataMudança
13/10/2026Webhooks; atualização e histórico de chamados; conexão e quedas do contrato; link de pré-cadastro; especificação OpenAPI.
13/10/2026Lançamento da v1: clientes, contratos, faturas e segunda via, desbloqueio de confiança, chamados e planos.

Suporte

Dúvidas técnicas sobre a integração podem ser enviadas pelos nossos canais. Para pedir acesso a um provedor específico, fale diretamente com ele: as chaves e os webhooks são criados e controlados pelo próprio provedor.