API de dados

Começando

1. No Metricaas, adicione uma fonte do tipo Dados customizados e responda às três perguntas (se você vai informar pagamentos, se cada assinatura tem plano, se vai cadastrar clientes).
2. Em Configurações > API, gere uma chave. Ela aparece uma única vez.
3. Mande as suas assinaturas. O painel se move em até um minuto.

Autenticação

Toda chamada leva a sua chave no cabeçalho. A chave pertence à sua empresa e diz em qual fonte ela escreve.

Authorization: Bearer mtc_live_...

Endereço base: https://api.metricaas.ai/v1

Guardamos apenas um resumo criptográfico da chave, então nem nós conseguimos mostrá-la de novo. Perdeu, gere outra e revogue a antiga.

A primeira chamada

Criar e atualizar são a mesma chamada: o id é seu, e mandar o mesmo id de novo atualiza em vez de duplicar.

curl -X POST https://api.metricaas.ai/v1/subscriptions \
  -H "Authorization: Bearer mtc_live_..." \
  -H "Content-Type: application/json" \
  -d '{"id":"sub_001","customer":"cli_001","plan":"Pro","currency":"BRL","cycle":"monthly","started_at":"2024-01-10","amounts":[{"from":"2024-01-10","cents":9990},{"from":"2025-03-01","cents":12990}]}'

Mande em LOTE (um array no corpo, até 1000 objetos). Ou tudo entra, ou nada entra: um lote meio-aplicado deixaria você sem saber o que entrou.

O valor é uma HISTÓRIA, não um número

Num gateway, a história do preço mora nas faturas: cada uma é um período cobrado, com o preço daquele dia. Aqui não há faturas, então a história mora dentro da assinatura, no campo `amounts`.

Cada faixa diz quanto ela passou a valer, e desde quando. A primeira começa no início da assinatura. É isso que faz o MRR de março continuar sendo o de março depois que você reajusta o preço em abril.

{
  "amounts": [
    {
      "from": "2024-01-10",
      "cents": 9990
    },
    {
      "from": "2025-03-01",
      "cents": 12990
    }
  ]
}

Por isso, um envio que ENCURTE ou ALTERE uma faixa já declarada é recusado com 409: ele reescreveria o MRR de meses que já fecharam. Se foi um reajuste, acrescente uma faixa nova. Se foi erro de digitação, confirme que você quer mesmo reescrever:

POST https://api.metricaas.ai/v1/subscriptions?correct_history=true

Cancelar não é apagar

Cancelar é um fato do seu negócio: o cliente saiu, a assinatura fica no histórico e vira churn na data declarada. Apagar é uma errata: aquilo nunca existiu, e o MRR passado se refaz sem ele. Confundir os dois corrompe o seu churn nas duas direções.

# o cliente saiu (vira churn)
PUT https://api.metricaas.ai/v1/subscriptions/sub_001   { "canceled_at": "2026-03-01", ... }

# eu digitei errado (some da historia)
DELETE https://api.metricaas.ai/v1/subscriptions/sub_001

/v1/customers

Opcional. Só é preciso se um mesmo cliente tiver mais de uma assinatura. O único campo obrigatório é o id, então dá para agrupar sem nos contar quem eles são.

{
  "id": "cli_001",
  "name": "Empresa Exemplo",
  "email": "contato@exemplo.com"
}

/v1/subscriptions

O coração da fonte. É daqui que sai o seu MRR.

{
  "id": "sub_001",
  "customer": "cli_001",
  "plan": "Pro",
  "currency": "BRL",
  "cycle": "monthly",
  "started_at": "2024-01-10",
  "amounts": [
    {
      "from": "2024-01-10",
      "cents": 9990
    },
    {
      "from": "2025-03-01",
      "cents": 12990
    }
  ]
}

/v1/payments

Opcional. Se você declarar os pagamentos, ganha inadimplência, receita recebida, taxas e estornos. Se não, o MRR continua inteiro e a inadimplência simplesmente não existe na sua conta.

{
  "id": "pay_001",
  "customer": "cli_001",
  "subscription": "sub_001",
  "amount_cents": 9990,
  "paid_at": "2024-02-10",
  "fee_cents": 349
}

Erros

A recusa lista TODOS os problemas de uma vez, com o campo (e, na planilha, a linha). Você não vai consertar um por requisição.

{
  "error": {
    "code": "invalid_request",
    "message": "a declaracao tem 2 problema(s)",
    "details": [
      {
        "field": "subscription.cycle (sub_002)",
        "line": 4,
        "reason": "invalid option"
      },
      {
        "field": "subscription.amounts (sub_007)",
        "line": 9,
        "reason": "..."
      }
    ]
  }
}

• 202 — aceito. O seu painel se move em até um minuto.
• 400 — a declaração tem problemas. Nada foi gravado.
• 401 — chave inválida, revogada, ou sem permissão para esta operação.
• 409 — isto reescreveria o histórico de valor já declarado. Veja a seção acima.
• 429 — muitas requisições. Mande em lote.

Conferindo o que você declarou

O GET devolve o que está no seu cofre, paginado por cursor. Esta mesma chave vai ler as suas métricas quando a API de leitura existir.

GET https://api.metricaas.ai/v1/subscriptions?limit=100&cursor=sub_050