Changelog da API

Acompanhe aqui as mudanças que afetam quem integra com a API v2: rotas e campos novos, eventos de webhook, permissões e comportamentos que exigem ação. As entradas estão em ordem cronológica decrescente.

Mudanças internas que não alteram o contrato (painel, e-mails, observabilidade) não aparecem aqui.

12 de out, 2026: produto e preço nos eventos de checkout; filtros desconhecidos recusadosCopiar link da seção

• Os eventos checkout.* trazem price_ids e product_ids quando a sessão foi criada pela Adila (API, SDK, MCP, páginas de checkout ou links de pagamento), e os filtros products/prices passam a valer para eles. Sessões criadas fora da Adila trazem null nesses campos.
• Exige ação se você mandava chaves desconhecidas: uma chave desconhecida em filters agora retorna 422 integration_filter_unknown, com a chave em fields. Antes, ela era descartada sem aviso e um PATCH só com chaves desconhecidas apagava os filtros salvos.

12 de out, 2026: evento account.updated, filtros por produto, preço e metadataCopiar link da seção

• Novo evento account.updated: a situação da conta de pagamentos (cobranças e repasses habilitados, status das capacidades e se há pendências), só quando ela muda e sem dados pessoais. Assine o tipo no endpoint para recebê-lo.
• filters aceita products, prices (ids prod_…/price_…, só em eventos de assinatura) e metadata (pares chave=valor do pagamento, checkout, assinatura, fatura ou repasse). Veja Filtros para saber quais eventos carregam cada campo.
• O servidor MCP ganhou ferramentas para listar, criar, pausar e testar endpoints e para ver e reenviar entregas.

12 de out, 2026: SDKs Python e PHP/Laravel, licença MITCopiar link da seção

A versão 0.3 publica o SDK nas três linguagens, gerado do mesmo contrato e com as mesmas 43 operações:

npm install @adila-sh/pay       # Node.js e Bun
pip install adila-pay           # Python 3.10+, clientes síncrono e assíncrono
composer require adila-sh/pay   # PHP 8.1+ e Laravel

No Laravel, o pacote registra sozinho o facade AdilaPay e a configuração config/adila-pay.php. A partir da 0.3.1, os três pacotes são distribuídos sob a licença MIT. Instalação e exemplos estão em SDK.

12 de out, 2026: API keys nascem de testeCopiar link da seção

Uma API key criada sem mode agora é sempre de teste (pk_test_). Antes, em instalações de produção, ela saía como pk_live_. Para uma chave de produção, envie mode: "live" ou escolha Produção no campo Ambiente do painel.

Chaves já criadas não mudam. Veja Ambientes.

12 de out, 2026: SDK 0.2.0 com configuração de repassesCopiar link da seção

@adila-sh/pay 0.2.0 traz payoutSettings.retrieve, que consulta a configuração de repasses da conta conectada. O SDK passa a cobrir 43 operações.

npm install @adila-sh/[email protected]

12 de out, 2026: SDK Node.js/Bun publicado no npmCopiar link da seção

O SDK oficial está publicado como @adila-sh/pay:

npm install @adila-sh/pay

O pacote Python ainda não está no PyPI. Em Python, use o quickstart HTTP. Instalação e uso estão em SDK.

11 de out, 2026: Ambiente por workspaceCopiar link da seção

Sandbox e produção passam a ser workspaces da mesma organização. Cada workspace tem um ambiente fixo, escolhido na criação, que define as chaves da Stripe (test ou live) e a conta conectada usadas em cada operação. Uma organização pode ter uma conta conectada por ambiente.

• Páginas de checkout e endpoints de webhook pertencem ao ambiente em que foram criados.
• Membros developer e viewer só operam em ambientes de workspaces a que têm acesso. Fora disso, a API responde 403 com code: "workspace_access_required".
• Cada pessoa tem uma organização. Criar uma segunda organização retorna 409.

Detalhes em Ambientes.

11 de out, 2026: API keys gerenciam webhooks com escopo próprioCopiar link da seção

API keys podem gerenciar destinos de webhook, desde que tenham escopo explícito:

O acesso total (*) não concede esse escopo, para que chaves existentes não passem a gerenciar destinos e segredos de assinatura sem uma decisão explícita. Sem a permissão, a API responde 403 com code: "endpoint_management_forbidden". A auditoria registra a API key como autora.

11 de out, 2026: Rotação de segredo sem perder entregasCopiar link da seção

POST /v2/organizations/{organizationId}/integrations/endpoints/{id}/rotate-secret guarda o segredo anterior por 24 horas. Nesse período, as entregas novas saem com duas assinaturas no header Adila-Signature:

Adila-Signature: t=1760200000,v1=<novo>,v1=<anterior>

Aceite a entrega se qualquer v1 conferir. Você pode atualizar o consumidor a qualquer momento dentro das 24 horas. Entregas que já estavam na fila continuam assinadas só com o segredo anterior.

11 de out, 2026: Novos eventos de webhookCopiar link da seção

Entraram no catálogo:

checkout.completed com payment_status diferente de paid não confirma pagamento: em Pix e boleto, espere checkout.payment_succeeded ou payment.succeeded. Os campos de data de cada tipo estão no catálogo de eventos.

11 de out, 2026: Filtros, testes e saúde dos endpoints de webhookCopiar link da seção

• Filtros: POST /endpoints e PATCH /endpoints/{id} aceitam filters com currencies, amountMin e amountMax. amountMin maior que amountMax retorna 422 com code: "integration_filter_invalid".
• Evento sintético: POST /endpoints/{id}/test com { "type": "..." } envia um evento de teste (test: true) para um endpoint ativo de sandbox. Limite de cinco testes por minuto por endpoint.
• Falhas recentes: GET /endpoints traz recentFailures, a contagem de entregas que falharam de vez nas últimas 24 horas (testes não contam). Com três ou mais, owners e admins recebem um aviso por e-mail, no máximo uma vez por dia por endpoint. O endpoint não é pausado automaticamente.

Detalhes em Eventos e confirmação de pagamento.

11 de out, 2026: Pix nas contas conectadas e consulta de repassesCopiar link da seção

• A capacidade pix_payments é pedida ao criar a conta conectada e a cada link de onboarding, o que inclui contas antigas. O pedido é idempotente e não bloqueia o cadastro. A disponibilidade final depende da aprovação da Stripe.
• GET /v2/organizations/{organizationId}/stripe/payout-settings retorna a situação, a frequência e o prazo de liberação dos repasses e os destinos de repasse mascarados. A rota é somente leitura: no Brasil a Stripe oferece só repasse automático diário.

9 de out, 2026: Webhooks de pagamentoCopiar link da seção

Sua aplicação pode receber eventos assinados da conta conectada. A gestão fica em /v2/organizations/{organizationId}/integrations:

O primeiro catálogo cobre pagamentos (payment.succeeded, payment.failed, payment.refunded), disputas, checkout.completed, assinaturas (subscription.created, renewed, canceled, payment_failed) e repasses (payout.paid, payout.failed). Endpoints que já existiam continuam assinando payment.succeeded.

Veja envelope, assinatura e política de retries em Eventos e confirmação de pagamento.

9 de out, 2026: Códigos de erro estáveisCopiar link da seção

Erros passam a trazer code, um identificador estável para tratar o erro no código sem depender da mensagem em inglês, e fields com os campos recusados:

{
  "error": "Destination must be a public HTTPS URL without credentials or query parameters",
  "code": "destination_rejected",
  "fields": ["url"],
  "requestId": "IDENTIFICADOR_DA_REQUISICAO"
}

Erros de parâmetro recusado pela Stripe trazem o parâmetro em fields e o código da Stripe como stripe_<code>. Por exemplo, um código promocional duplicado aponta para o campo code.

9 de out, 2026: Códigos promocionais e links de pagamentoCopiar link da seção

Novas rotas em /v2/organizations/{organizationId}/stripe:

• O desconto pode ser percentual ou fixo, valer uma vez, para sempre ou por N meses, e ser restrito a produtos com products (até 100 IDs prod_).
• Links aceitam quantidade ajustável, allow_promotion_codes, limite de vendas que fecha o link e mensagens de link encerrado e pós-pagamento.
• Sessões de Checkout aceitam allow_promotion_codes.

Veja Catálogo e Checkout.

9 de out, 2026: Produtos e preços mais completosCopiar link da seção

• POST /stripe/products e PATCH /stripe/products/{id} aceitam preço padrão (default_price_data, único ou recorrente), até 8 imagens https, url, statement_descriptor, unit_label, marketing_features, shippable e active. O PATCH também troca o preço padrão.
• POST /stripe/product-images envia uma foto (JPG, PNG ou WebP, até 4 MB) e retorna a URL pública para usar em images.
• POST /stripe/prices aceita criar o produto junto (product_data), nickname, lookup_key, tax_behavior, recorrência a cada N períodos com período de teste, preços por faixa (tiers, graduado ou por volume, até 25 faixas), valor livre (custom_unit_amount) e preço por pacote (transform_quantity). product e unit_amount passam a ser opcionais quando substituídos por esses campos.

Preços por uso medido (usage_type: metered) não são suportados: o campo é descartado antes de chegar à Stripe.

9 de out, 2026: Filtros nas listagens e limite de requisiçõesCopiar link da seção

created_gte e created_lte são timestamps Unix em segundos. Sem status, a Stripe omite assinaturas canceladas da listagem.

O limite padrão de requisições subiu para 600 por minuto. Acima disso, a API responde 429.

6 de out, 2026: API v2 com Stripe ConnectCopiar link da seção

A API v2 passa a operar sobre a conta Stripe conectada de cada organização, em /v2/organizations/{organizationId}/stripe: conta e onboarding, clientes, produtos, preços, intenções de pagamento, cobranças, reembolsos, Checkout, assinaturas, faturas, portal do cliente, saldo, repasses e disputas.

• Autenticação por API key da organização no header x-api-key.
• Mutações financeiras exigem Idempotency-Key.
• Listas usam paginação por cursor com limit e starting_after.

Comece pela Primeira integração e consulte a referência da API.

Antes da API v2Copiar link da seção

As rotas anteriores, sobre o provedor Asaas, e a gestão de identidade em /v1 não fazem parte deste changelog nem do contrato público. Integrações novas devem usar só a API v2.