CallMint

Documentação técnica

CDR, RADIUS, Real Time e SBC

Integrações CallMint

Guia para conectar softswitches, SBCs e collectors à CallMint com ingestão de CDRs, accounting RADIUS, contratos de eventos em tempo real e mapeamento canônico para billing.

Começar por CDR REST Ver RADIUS Abrir no app
01 SBC / Softswitch

OpenSIPS, Kamailio, FreeSWITCH, Asterisk, Khomp e SBCs comerciais.

02 Collector / Adapter

Normaliza CDR, RADIUS, syslog, webhook ou exportação vendor-specific.

03 CallMint API

Valida API key, aplica idempotência, mapeia cliente/trunk e aciona o rating.

04 Billing e Live Ops

Registra ledger, saldos, CDRs, KPIs, alertas e relatórios operacionais.

Disponível agora

CDR REST/Webhook

Ingestão HTTP de CDRs com API key, headers de origem, normalização e rating.

Disponível agora

RADIUS Accounting

Bridge HTTP para Start, Interim-Update e Stop vindos de FreeRADIUS ou collector dedicado.

Contrato técnico

Real-time traffic

Eventos de chamada, trunk status e fraude para alimentar dashboard live e automações.

Extensível

Adapters nativos

Mapeamento por origem para manter a CallMint independente do fornecedor de rede.

Visão geral

Arquitetura de integração

A CallMint separa origem de rede, adapter, ingestão e billing. Esse desenho permite receber eventos de múltiplos fornecedores sem acoplar o rating ou o ledger a um formato proprietário.

SBC / Softswitch Adapter Ingestion API Rating Engine Ledger / Reports
Para engenharia, a versão-fonte desta documentação também fica no repositório em docs/integration-guide.md.

CDR REST/Webhook

Ingestão de CDRs

Use o endpoint REST quando o SBC, softswitch ou collector consegue emitir CDR finalizado por HTTP. O evento deve ser enviado preferencialmente no encerramento da chamada.

POST https://app.callmint.com.br/api/v1/cdrs
Header Obrigatório Uso
x-api-key Sim API key da integração SBC/collector.
x-account-id Recomendado Cliente comercial quando o payload não informa account_id.
x-trunk-id Recomendado Trunk lógico para auditoria, relatório e live traffic.
x-source-type Não generic, opensips, kamailio, freeswitch, asterisk, khomp ou vendor SBC.
x-source-node Recomendado Hostname, IP ou identificador do nó de rede. 
curl -X POST https://app.callmint.com.br/api/v1/cdrs \
  -H "Content-Type: application/json" \
  -H "x-api-key: $CALLMINT_SBC_API_KEY" \
  -H "x-account-id: acct-001" \
  -H "x-trunk-id: sbc-mia-02" \
  -H "x-source-type: generic" \
  -d '{
    "call_id": "call-20260519-0001",
    "caller": "+12025550100",
    "callee": "+5511987654321",
    "start_time": "2026-05-19T12:00:00Z",
    "duration_seconds": 120,
    "billable_seconds": 120
  }'

RADIUS Accounting

Start, Interim-Update e Stop

Para RADIUS nativo, o modelo recomendado é usar um receiver/sidecar na porta UDP 1813. Esse componente valida o shared secret, converte atributos RADIUS em JSON e publica no endpoint HTTP da CallMint.

POST https://app.callmint.com.br/api/v1/radius/accounting 
{
  "Acct-Status-Type": "Stop",
  "Acct-Session-Id": "radius-session-001",
  "User-Name": "acct-001",
  "Calling-Station-Id": "+12025550100",
  "Called-Station-Id": "+5511987654321",
  "NAS-IP-Address": "10.0.0.10",
  "Acct-Session-Time": 119,
  "Event-Timestamp": "2026-05-19T12:02:00Z"
}
Eventos Start abrem a tentativa de chamada, Interim-Update atualiza duração/estado para live traffic, e Stop fecha CDR, rating e débito.

Real Time

Contrato de eventos live

O portal operacional já exibe visão de tráfego em /traffic. A evolução real-time usa eventos canônicos para alimentar WebSocket, alertas de fraude, CPS e status de trunk. 

{
  "event_type": "call.started",
  "event_id": "evt-20260519-0001",
  "occurred_at": "2026-05-19T12:00:00Z",
  "call_id": "call-20260519-0001",
  "account_id": "acct-001",
  "trunk_id": "sbc-mia-02",
  "caller": "+12025550100",
  "callee": "+5511987654321",
  "codec": "G.711u",
  "route": "BR-Mobile-LCR",
  "sip_state": "early"
}
call.started call.answered call.updated call.ended trunk.status.changed fraud.alert.created

Softswitches e SBCs

Caminhos de conexão nativa

Plataforma Caminho recomendado
OpenSIPS acc/dialog para CDR, HTTP async e x-source-type: opensips.
Kamailio acc_json, collector externo ou HTTP async com x-source-type: kamailio.
FreeSWITCH mod_json_cdr, mod_cdr_csv com forwarder, ou Event Socket collector.
Asterisk CDR/CEL via AMI, ODBC export ou script HTTP pós-processamento.
Khomp SBC Exportação de CDR ou webhook usando adapter khomp.
Ribbon, AudioCodes, Oracle ACME, Cisco CUBE RADIUS Accounting, CDR export ou syslog collector com adapter vendor-specific.

Segurança operacional

Autenticação, idempotência e retries

API key por origem: gere uma chave por SBC, collector ou trunk lógico para facilitar revogação e auditoria.

Idempotência: preserve call_id ou Acct-Session-Id; reenvios não devem gerar cobrança duplicada.

Retries: em erro 5xx, use backoff exponencial. Em 401/403, pare e revise credenciais.

Transporte: envie eventos sempre por HTTPS; em RADIUS UDP, mantenha receiver em rede privada e shared secret forte.

Checklist

Go-live de integração

  1. Criar trunk lógico na CallMint.
  2. Criar ou validar customer/account comercial.
  3. Gerar API key dedicada para o SBC ou collector.
  4. Configurar envio de CDR Stop em ambiente de teste.
  5. Validar prefixo tarifado, custo, ledger e saldo.
  6. Reenviar o mesmo call_id para testar idempotência.
  7. Ativar RADIUS Interim ou evento real-time quando aplicável.
  8. Monitorar Traffic, CDR, Invoices e alertas de fraude.