account/monitors

Criar um monitor e a primeira linha de base são grátis. Um ciclo de 30 dias é cobrado assim que o monitor fica ativo. O preço depende do intervalo de verificação e cobre todas as verificações que o intervalo agenda dentro de um ciclo.

Um intervalo entre dois degraus custa tanto quanto o próximo degrau mais frequente: a cada quatro dias custa tanto quanto a cada três dias.

Verificações extras acontecem principalmente quando você encurta o intervalo no meio de um ciclo. Cada verificação extra bem-sucedida custa o valor da tabela.

Após 30 dias, o ciclo se renova automaticamente pelo preço vigente. Verificações que falham não custam nada. Quando você pausa, arquiva ou muda o intervalo, não reembolsamos nada.

Cada conta pode ter até 50 monitores ao mesmo tempo, um por empresa. Em 24 horas, você pode criar até 50 monitores; os arquivados também contam.

Você obtém o preço de um intervalo de graça com GET /v1/account/monitoring/pricing, aqui para uma verificação a cada sete dias:

1. Criar. Você indica a empresa, o intervalo de verificação e pelo menos um endpoint de webhook verificado. O monitor começa com o status initializing.
2. Linha de base. Registramos os sinais dos últimos dias como conhecidos. Eles não são entregues, então você só recebe o que for novo depois disso.
3. Ativar. Cobramos o ciclo, o monitor fica active e verifica pela primeira vez na hora.
4. Verificar. Depois disso, ele verifica no intervalo escolhido. Cada novo sinal gera uma mensagem por monitor aos seus endpoints de webhook.
5. Renovar. Após cada ciclo, o próximo é cobrado automaticamente, desde que o seu saldo cubra.

O intervalo de verificação fica entre 1 e 30 dias. O horário exato de uma verificação pode variar dentro de uma hora. Cada verificação olha alguns dias para trás, então registros publicados com atraso também chegam.

Um monitor entrega os temas de Signals do seu plano: cinco em qualquer conta, Insolvências com o Pro, Transformações & M&A com o Max. Um webhook traz no campo data.signal o mesmo sinal que signals.

Para monitores pausados e erros, status_reason explica o motivo, por exemplo no_verified_endpoint ou insufficient_cycle_floor.

Todos os caminhos ficam em /v1/account. Você lê e escreve com sua chave de API no header x-api-key.

Toda requisição de escrita precisa do header Idempotency-Key, um valor único por operação, de preferência um UUID. Sem ele, a API responde com 428.

Se você repetir uma requisição com a mesma chave e os mesmos dados em até 24 horas, recebe de volta a resposta armazenada. Ela traz o header Idempotency-Status: replayed. Assim um erro de rede não cria um segundo monitor.

Isso vale também para respostas de erro. Por isso, para uma nova tentativa após uma correção, use uma chave nova. A mesma chave com dados diferentes retorna 409.

São permitidos até 128 caracteres: letras, dígitos e . _ : -. O primeiro caractere é uma letra ou um dígito. Uma chave em qualquer outro formato retorna 400.

Você precisa do entity_id da empresa e de pelo menos um endpoint de webhook verificado, veja account/webhook-endpoints.

A API responde com 202: o monitor é criado, e linha de base e ativação rodam em segundo plano. meta.billing.charged_credits mostra que nada foi cobrado por isso.

GET /v1/account/monitors retorna até 100 monitores em monitors, com total. Os arquivados não estão na lista.

GET /v1/account/monitors/{id} também mostra o ciclo atual em billing_cycle e as últimas verificações em recent_runs.

PATCH /v1/account/monitors/{id} muda o intervalo de verificação. A próxima verificação segue então no novo intervalo, contado a partir da mudança.

O ciclo atual mantém seu preço e suas verificações incluídas. O novo preço vale a partir do próximo ciclo. Um intervalo mais curto pode gerar verificações extras no ciclo atual.

POST …/{id}/pause para um monitor ativo. O ciclo pago continua até o fim, e nada é reembolsado.

POST …/{id}/resume retoma um monitor pausado ou um monitor com erro. Verificamos de novo endpoints de webhook, saldo e preço.

Dentro do ciclo pago atual, retomar não custa nada. Se o ciclo terminou, um novo ciclo começa agora pelo preço atual. meta.request_credit_cost mostra o valor.

Se, por exemplo, faltar um endpoint de webhook verificado, a API ainda responde com 200, mas com meta.activated: false. O status do monitor e status_reason informam o motivo.

Se o preço mudou, um monitor ativo para no fim do ciclo com pricing_consent_required. Com resume, você aceita o novo preço.

DELETE …/{id} arquiva o monitor definitivamente. Isso é final e não reembolsa nada.

Erros têm a estrutura {"error": "…", "meta": {"message": "…"}}. No seu programa, verifique o valor de error. O texto em meta.message está em inglês e pode mudar. Erros não custam nada.