A API do Arcalotl

• Uma URL base, com escopo por comunidade

  Todos os recursos ficam sob https://api.arcalotl.com/v1. Cada recurso é limitado à comunidade dona da chave de API usada para chamá-lo. Um id que pertence a outra comunidade responde 404 em vez de 403, então as respostas não podem ser usadas para sondar os dados de outra comunidade.

• Chaves de API bearer com escopos explícitos

  Cada requisição carrega um cabeçalho Authorization com uma chave bearer criada no painel, em Desenvolvedores e depois Chaves de API. Uma chave guarda os escopos escolhidos na criação, e uma requisição sem o escopo que uma rota exige retorna 403 com o código missing_scope. A chave completa aparece exatamente uma vez na criação; depois só um prefixo de exibição é armazenado.

• As leituras cobrem toda a cobrança

  Os endpoints GET retornam assinaturas com filtros de status, plano e nível, níveis de plano com seus planos de cobrança aninhados, membros com suas identidades de plataforma, os direitos de acesso resolvidos de um membro, compras únicas, cupons de desconto com contagem de resgates e um resumo de análises com MRR, assinantes ativos e cadastros e cancelamentos recentes.

• As escritas são poucas e deliberadas

  As escritas cobrem todo o ciclo de vida da assinatura: criar um link de checkout para um comprador específico, trocar uma assinatura de plano, cancelá-la no fim do período ou reativá-la, abrir o portal do membro para um membro, associar o seu próprio id de usuário a um membro e gerenciar endpoints de webhook. Os links de checkout aceitam uma identidade de plataforma conectada, um id de membro existente ou um id de usuário externo com namespace que pertence a você, que é como uma aplicação controlada pelo operador vende pelo Arcalotl.

• A paginação é por cursor

  Os endpoints de listagem recebem um cursor opaco e um limite, com máximo de 100 e padrão de 25, e retornam um next_cursor. O campo é null ou ausente na última página. Devolva o valor exatamente como veio; a forma interna de um cursor não faz parte do contrato, então não construa nem interprete um.

• Chaves de idempotência tornam as novas tentativas seguras

  Requisições de cancelamento e de link de checkout aceitam um cabeçalho Idempotency-Key. A mesma chave com o mesmo corpo em até 24 horas repete a resposta original e adiciona Idempotent-Replayed: true. A mesma chave com um corpo diferente retorna 422 idempotency_key_reuse, e reutilizá-la enquanto a primeira requisição ainda está em andamento retorna 409 request_in_flight. Gere uma chave nova por operação lógica.

• Os erros são documentos problem conforme a RFC 9457

  Falhas retornam application/problem+json com um membro code estável, por exemplo unauthorized, missing_scope, not_found, invalid_request, conflict, not_eligible ou rate_limited. Compare pelo code. Os campos title e detail são legíveis por pessoas e a redação deles pode mudar sem aviso.

• Os limites de taxa são publicados em toda resposta

  O tráfego autenticado é limitado por chave a 300 requisições por minuto com rajada de 60. Requisições com chave ausente ou inválida são limitadas por IP do cliente a 20 por minuto com rajada de 10, e não afetam as chamadas autenticadas com sucesso. Toda resposta carrega RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset, e um 429 adiciona Retry-After em segundos.

• Os webhooks seguem a especificação Standard Webhooks

  Cada entrega carrega os cabeçalhos webhook-id, webhook-timestamp e webhook-signature. A assinatura é HMAC-SHA256 sobre o id, o timestamp e o corpo bruto unidos por pontos, com a parte decodificada do seu segredo whsec_ como chave. Verifique contra o corpo bruto antes de interpretar o JSON, aceite qualquer um dos tokens v1 separados por espaço para que a rotação de segredo funcione, e rejeite um timestamp a mais de cinco minutos do seu relógio.

• A entrega é pelo menos uma vez, com novas tentativas e desativação automática

  Qualquer 2xx conta como sucesso. Qualquer outra coisa é tentada de novo em um cronograma fixo de cerca de dez tentativas espalhadas por cerca de 2,3 dias antes de a entrega ser marcada como esgotada. Um endpoint com dez entregas esgotadas consecutivas é desativado automaticamente, e qualquer sucesso zera esse contador. Uma comunidade pode registrar até cinco endpoints HTTPS, inspecionar o registro de tentativas e reenfileirar uma entrega específica.

• O feed de eventos cobre o que os webhooks perdem

  GET /v1/events retorna os mesmos envelopes que os seus endpoints recebem, os mais novos primeiro, filtráveis por tipo e por after_id para você acompanhar um ponto de controle em vez de um timestamp. Eventos projetados são mantidos por 90 dias e registros de entrega por 30, então você pode reconciliar muito depois de um registro de entrega ter expirado.

• Mudanças dentro de uma versão são só aditivas

  A API e o envelope de webhook compartilham uma única string de versão. Dentro de uma versão você recebe campos novos, parâmetros opcionais novos, tipos de evento novos e endpoints novos, e os campos existentes não mudam de forma nem de significado. Ignore campos que você não reconhece e mudanças aditivas nunca vão quebrar a sua integração.

• O contrato é publicado como OpenAPI 3.1

  O contrato completo de requisições e respostas é um documento OpenAPI 3.1 servido pelo site, e as páginas de referência da API são geradas desse mesmo documento, então a referência não pode divergir da especificação que o seu gerador de código lê.

Escopos das chaves de API