Pular para o conteúdo
ecdsa.com

Registro de alterações

Mudanças na API pública, das mais recentes para as mais antigas. A versão da API faz parte do caminho; mudanças incompatíveis sairiam como /api/v2 — as respostas da v1 podem ganhar campos e códigos, mas não vão perdê-los nem alterá-los.

  1. Com chaves de API

    Ainda não lançada

    Já mescladas, mas não lançadas: estas mudanças entram no ar quando as chaves de API forem lançadas, junto com as contas do ecdsa.com. Chamadas sem chave continuam exatamente como estão.

    • Alterado

      Uma chave bem formada, mas desconhecida, revogada ou expirada é recusada com 401 unauthorized e um desafio WWW-Authenticate, em vez de ser atendida de forma anônima.

      Códigos:unauthorized

      Cabeçalhos:WWW-Authenticate

    • Adicionado

      403 forbidden_scope: a chave é válida, mas não tem um escopo de que a operação precisa; a mensagem indica qual. A chamada é recusada antes de consumir qualquer limite de taxa ou cota.

      Códigos:forbidden_scope

    • Adicionado

      429 quota_exceeded: uma cota diária ou mensal da conta da chave se esgotou. Retry-After vai até a cota recomeçar; os SDKs nunca tentam de novo nesse caso.

      Códigos:quota_exceeded

    • Adicionado

      Toda resposta a uma chamada com chave traz a cota que se esgota primeiro; os navegadores também podem ler esses cabeçalhos.

      Cabeçalhos:X-Quota-LimitX-Quota-RemainingX-Quota-Reset

    • Adicionado

      503 service_unavailable: no momento não é possível verificar as chaves. Uma chamada com chave nunca é atendida de forma anônima — tente de novo em instantes.

      Códigos:service_unavailable

    • Alterado

      Chamadas com chave são limitadas por chave, e não por IP: 120 por minuto no plano gratuito, 600 no plano pro. Chaves de teste sempre ficam no plano gratuito.

      Códigos:rate_limited

    • Alterado

      O campo auth do índice da API informa que as chaves são opcionais, o que uma chave muda e quais operações precisam de uma, em vez de “no API keys”.

      Operações:GET /v1

    • Adicionado

      Webhooks: /api/v1/webhooks lista (GET) e cria (POST) os endpoints da conta da chave, /api/v1/webhooks/delete exclui um e /api/v1/webhooks/test envia um evento de teste. Essas operações exigem uma chave com o escopo webhooks e só são oferecidas via REST — não como ferramentas MCP nem nos SDKs.

      Operações:GET /v1/webhooksPOST /v1/webhooksPOST /v1/webhooks/deletePOST /v1/webhooks/test

    • Adicionado

      As entregas são assinadas com ECDSA P-256: ECDSA-Signature traz o timestamp, o ID da chave e a assinatura, e as chaves públicas são o JWKS em /.well-known/ecdsa-webhook-keys.json — dois IDs de chave coexistem durante uma rotação. Todo SDK verifica uma entrega com verifyWebhook().

    • Adicionado

      Novos códigos para webhooks: webhook_url_refused (400), webhook_limit_reached (403), webhook_not_found (404) e webhooks_unavailable (503).

      Códigos:webhook_url_refusedwebhook_limit_reachedwebhook_not_foundwebhooks_unavailable

  2. v1.1.0

    Lançada em 22 de outubro de 2026

    O núcleo da API foi reconstruído sobre operações declarativas, e as varreduras de um domínio agora compartilham uma cota por host verificado. Para os clientes existentes, a mudança só acrescenta: toda requisição v1.0 recebe o mesmo status e o mesmo corpo, além dos novos campos. A maioria destas mudanças está no ar desde 20 de outubro de 2026; o índice informa 1.1.0 a partir desta versão.

    • Adicionado

      As varreduras reais de um domínio consomem cotas compartilhadas por todos os clientes: um host no máximo 6 vezes a cada 10 minutos, todas as varreduras juntas no máximo 300 por minuto. Uma varredura além de uma cota recebe como resposta 429 rate_limited e Retry-After; respostas vindas do cache de uma hora não consomem nada.

      Códigos:rate_limited

      Operações:GET /v1/health/{domain}

    • Adicionado

      Os corpos de erro ganham requestId — informe esse valor ao relatar um problema — e docs, um link para os códigos de erro. code e message não mudam.

      Campos:error.requestIderror.docs

    • Adicionado

      Toda resposta traz X-Request-Id. Envie o seu próprio (de 1 a 128 letras, dígitos, pontos, sublinhados, dois-pontos ou hifens) para correlacionar requisições: ele é devolvido na resposta.

      Cabeçalhos:X-Request-Id

    • Alterado

      Caminhos desconhecidos respondem 404 not_found, e métodos errados, 405 method_not_allowed com um cabeçalho Allow — envelopes JSON com CORS em vez de páginas HTML.

      Códigos:not_foundmethod_not_allowed

      Cabeçalhos:Allow

    • Corrigido

      Um JSON aninhado em mais de 64 níveis — incluindo JSON dentro de campos de string — recebe como resposta 400 invalid_json no envelope JSON. Antes, isso falhava com um 500 que não era JSON.

      Códigos:invalid_json

    • Adicionado

      As respostas do health check de domínio ganham certificate: a expiração do certificado folha, os dias restantes, o algoritmo da chave e a curva.

      Campos:certificate

      Operações:GET /v1/health/{domain}

    • Adicionado

      Um cabeçalho Authorization ou X-API-Key malformado é recusado com 401 unauthorized em vez de ser ignorado, para que um cliente que pretendia se autenticar fique sabendo do erro de digitação. Chaves bem formadas continuam sendo atendidas de forma anônima até o lançamento das chaves de API.

      Códigos:unauthorized

    • Adicionado

      Uma operação que não termina dentro do limite de tempo de 10 segundos responde 504 timeout.

      Códigos:timeout

    • Alterado

      Os navegadores podem enviar Authorization, X-API-Key, X-Request-Id e Idempotency-Key entre origens (cross-origin) e ler X-Request-Id.

    • Alterado

      O documento OpenAPI é gerado a partir dos próprios schemas da API: cada operação lista seus códigos de erro por status, seus exemplos e os escopos de que uma chave de API precisa.

      Operações:GET /v1/openapi.json

  3. v1.0.0

    Lançada em 20 de agosto de 2026

    A API de assinaturas gratuita se torna pública.