> ## Documentation Index > Fetch the complete documentation index at: https://docs.abacatepay.com/llms.txt > Use this file to discover all available pages before exploring further. # Changelog da API > Mantenha-se atualizado com as mudanças e histórico de versões da API Acompanhe as atualizações e o histórico de versões da API. Este changelog é atualizado continuamente com melhorias, correções e mudanças relevantes. Sugestões de features ou melhorias podem ser enviadas pela área de Roadmap no dashboard. Feedbacks também são bem-vindos no nosso Discord (#dev). ## Atualizações Recentes ## Saques via API v1: validação de titularidade obrigatória A partir de hoje, saques criados via **API v1** passam a ter a **titularidade do destinatário validada**. Não será mais permitido enviar dinheiro para uma chave PIX cujo CPF/CNPJ seja diferente do CPF/CNPJ da sua conta AbacatePay. **O que mudou:** * Saques via `POST /v1/payouts/create` agora rejeitam chaves PIX cujo `taxId` do titular seja diferente do `taxId` da conta autenticada * Tentativas de saque para chaves de terceiros retornam erro `400` com a mensagem indicando a incompatibilidade de titularidade **O que fazer se você precisa enviar dinheiro a terceiros?** Use a rota de **Enviar PIX** da **API v2**, que foi projetada exatamente para esse caso de uso: ```http theme={null} POST /v2/pix/send ``` ```json theme={null} { "amount": 10000, "description": "Pagamento fornecedor #42", "externalId": "pix-123", "pixKey": "contato@fornecedor.com", "pixKeyType": "EMAIL" } ``` Consulte a [documentação de Enviar PIX](/pages/pix/create) para mais detalhes e tipos de chave aceitos. Se o seu sistema usa `POST /v1/payouts/create` para transferir valores a terceiros, **a integração precisa ser atualizada para `POST /v2/pix/send`**. Chamadas que tentarem enviar para uma chave com `taxId` diferente passarão a falhar a partir de hoje. *** ## Checkout Transparente: campo `receiptUrl` na resposta Os endpoints de checkout transparente agora retornam o campo **`receiptUrl`** no objeto de resposta, em todos os métodos de pagamento (PIX, Boleto e Cartão). **O que mudou:** * Adicionado campo `receiptUrl` (`string | null`) às respostas de `POST /v2/transparents/create`, `GET /v2/transparents/get` e `GET /v2/transparents/list` * O campo é `null` enquanto a cobrança está pendente e é preenchido automaticamente com a URL do comprovante após o pagamento ser confirmado **Exemplo de resposta após pagamento confirmado:** ```json theme={null} { "data": { "id": "pix_char_abc123xyz", "status": "PAID", "receiptUrl": "https://app.abacatepay.com/receipts/pix_char_abc123xyz", ... }, "success": true, "error": null } ``` *** ## Produtos digitais: arquivo para download Produtos agora suportam um **PDF vinculado para entrega digital**. Após o pagamento ser confirmado, o comprador recebe acesso automático ao arquivo — sem nenhuma etapa manual da sua parte. Casos de uso: e-books, ingressos, licenças de software, apostilas, certificados. **O que mudou:** * Novo campo opcional `fileUrl` em `POST /v2/products/create` — informe a URL pública de um PDF (máximo 20 MB); a AbacatePay baixa e armazena o arquivo de forma segura * Novo campo `hasFile` (boolean) no modelo `Product` — retornado em todos os endpoints de produto; indica se há arquivo vinculado * O URL real do arquivo **nunca é exposto** pela API — segurança por padrão **Exemplo:** ```json theme={null} POST /v2/products/create { "externalId": "ebook-guia-completo", "name": "E-book: Guia Completo de Vendas Online", "price": 4990, "currency": "BRL", "fileUrl": "https://exemplo.com/guia-completo.pdf" } ``` ```json theme={null} // Resposta { "data": { "id": "prod_abc123xyz", "name": "E-book: Guia Completo de Vendas Online", "hasFile": true, "price": 4990, ... }, "success": true, "error": null } ``` Consulte a [documentação de produtos](/pages/products/reference) para mais detalhes. *** ## Correção: `imageUrl` de produto agora funciona via API O campo `imageUrl` em `POST /v2/products/create` não estava sendo processado corretamente. A imagem era recebida mas ignorada — o produto era criado sem imagem mesmo quando uma URL válida era enviada. **O que foi corrigido:** * A API agora baixa a imagem da URL fornecida e a armazena internamente (assim como já ocorre com `fileUrl`) * O campo foi renomeado de `image` para `imageUrl` no contrato da API, corrigindo uma inconsistência que impedia o campo de ser reconhecido * Validações adicionadas: a URL deve apontar para um arquivo de imagem válido; tamanho máximo de **5 MB** Se você tentou criar produtos com imagem via API e o campo não era persistido, basta recriar ou atualizar o produto com `imageUrl`. *** ## Assinaturas: novo ciclo trimestral (`QUARTERLY`) e PIX Automático Duas melhorias no fluxo de assinaturas foram lançadas hoje. ### Ciclo trimestral O valor `QUARTERLY` foi adicionado ao campo `cycle` de produtos e ao campo `frequency.cycle` de assinaturas. Use para cobranças a cada 3 meses. **Ciclos disponíveis:** `WEEKLY` · `MONTHLY` · `QUARTERLY` · `SEMIANNUALLY` · `ANNUALLY` ```json theme={null} POST /v2/products/create { "externalId": "plano-trimestral", "name": "Plano Trimestral", "price": 12990, "currency": "BRL", "cycle": "QUARTERLY" } ``` ### PIX Automático para assinaturas Lojas com o recurso **PIX Automático** habilitado podem agora criar assinaturas com `methods: ["PIX"]`. Anteriormente, assinaturas aceitavam apenas cartão de crédito. ```json theme={null} POST /v2/checkouts/create { "items": [{ "id": "prod_abc123", "quantity": 1 }], "methods": ["PIX"], ... } ``` PIX Automático para assinaturas está disponível mediante habilitação no dashboard. Entre em contato com o suporte caso seu plano ainda não tenha acesso. *** ## Reembolsos via API Três novos endpoints permitem solicitar reembolso diretamente pela API, cobrindo os três fluxos de cobrança da plataforma. | Endpoint | Uso | | ------------------------------- | ----------------------------------------------------------------------------------- | | `POST /v2/checkouts/refund` | Reembolsa uma cobrança de checkout único (`bill_`, `char_`, `pix_char_` ou `card_`) | | `POST /v2/payment-links/refund` | Reembolsa um pagamento de link de pagamento (`char_`, `pix_char_` ou `card_`) | | `POST /v2/transparents/refund` | Reembolsa uma cobrança de checkout transparente | **Permissão necessária:** `REFUND:CREATE` **Body (todos os endpoints):** ```json theme={null} { "id": "char_abc123xyz", "reason": "Solicitação do cliente" } ``` **Resposta:** ```json theme={null} { "data": { "id": "ref_abc123xyz", "status": "PENDING", "amount": 4990, "reason": "Solicitação do cliente", "originalId": "char_abc123xyz", "createdAt": "2026-05-14T14:30:00.000Z" }, "success": true, "error": null } ``` Use o `id` correto para cada rota: `bill_` refere-se ao checkout, enquanto `char_`, `pix_char_` e `card_` referem-se à cobrança individual. Passar o ID errado retorna uma mensagem de erro indicando qual rota usar. *** ## Assinaturas: cancelar, alterar plano e registrar uso Três novos endpoints de gerenciamento de assinaturas foram adicionados à API v2, completando o ciclo de vida de cobranças recorrentes. **O que mudou:** * **`POST /v2/subscriptions/cancel`** — cancela uma assinatura ativa imediatamente, interrompendo todas as cobranças futuras * **`POST /v2/subscriptions/change-plan`** — troca o produto principal da assinatura (upgrade ou downgrade); o novo valor começa a ser cobrado no próximo ciclo * **`POST /v2/subscriptions/record-usage`** — registra unidades de uso de produtos pay-as-you-go vinculados à assinatura; o total é incluído na próxima cobrança do ciclo **Permissões necessárias:** | Endpoint | Permissão | | ---------------------------------- | --------------------- | | `POST /subscriptions/cancel` | `SUBSCRIPTION:DELETE` | | `POST /subscriptions/change-plan` | `SUBSCRIPTION:CREATE` | | `POST /subscriptions/record-usage` | `SUBSCRIPTION:CREATE` | Consulte a [documentação de assinaturas](/pages/subscriptions/reference) para exemplos completos e detalhes de cada endpoint. *** ## Webhooks de Assinatura: novos eventos `subscription.plan_changed` e `subscription.payment_failed` Dois novos eventos de webhook foram adicionados ao fluxo de assinaturas, dando mais visibilidade sobre o ciclo de vida das cobranças recorrentes dos seus clientes. **O que mudou:** * **`subscription.plan_changed`** — disparado quando o cliente muda de plano dentro de uma assinatura ativa (upgrade ou downgrade). O payload inclui o objeto `subscription` atualizado com o novo valor e frequência. * **`subscription.payment_failed`** — disparado quando uma tentativa de cobrança recorrente falha (ex: cartão recusado, saldo insuficiente). O payload inclui o objeto `payment` com o status `FAILED` e o campo `reason` indicando o motivo da falha. **Por que isso importa?** Antes, quando um pagamento falhava ou um plano era alterado, seu sistema dependia de consultas ativas à API para detectar a mudança. Agora você recebe a notificação automaticamente, podendo reagir em tempo real — enviar um e-mail de cobrança, pausar acesso, ou registrar a troca de plano sem nenhuma consulta adicional. **Eventos disponíveis em assinaturas:** | Evento | Quando é disparado | | ----------------------------- | --------------------------------------- | | `subscription.completed` | Assinatura criada e ativada | | `subscription.renewed` | Cobrança recorrente paga com sucesso | | `subscription.cancelled` | Assinatura cancelada | | `subscription.plan_changed` | Plano da assinatura alterado | | `subscription.payment_failed` | Tentativa de cobrança recorrente falhou | *** ## API v2 disponível para todos A **API v2 está agora disponível publicamente** para todos os integradores, encerrando a fase beta. Não é mais necessário entrar em contato com o suporte para obter acesso. **O que mudou:** * A API v2 deixa de ser exclusiva para clientes selecionados e passa a ser o padrão para todos * Novos cadastros já têm acesso à v2 diretamente, sem nenhuma etapa adicional * Toda a documentação oficial passa a referenciar a v2 como versão atual **Próximos passos recomendados:** Se você ainda utiliza a v1, recomendamos iniciar a migração para a v2. A v1 continuará funcionando até **1º de março de 2028**. *** ## Checkout Transparente: rotas de Boleto e Boleto Transparente Adicionadas as rotas de **Boleto** e **Boleto Transparente** ao Checkout Transparente, permitindo a criação de cobranças via boleto bancário diretamente pela API. **O que mudou:** * Adicionado suporte ao método `BOLETO` na rota `POST /v2/transparents/create` * Boleto passa a ser uma opção de pagamento no fluxo de checkout transparente **Exemplo de uso:** ```json theme={null} // POST /v2/transparents/create { "method": "BOLETO", "data": { "amount": 10000, "customer": { "name": "João Silva", "taxId": "123.456.789-00", "email": "joao@exemplo.com" } } } ``` *** ## Checkouts e Assinaturas: suporte ao campo `metadata` na criação As rotas de criação de cobrança passam a aceitar e persistir um campo **`metadata`** customizado enviado pelo integrador. **O que mudou:** * Adicionado campo `metadata` (objeto chave-valor) no body das rotas: * `POST /v2/checkouts/create` * `POST /v2/subscriptions/create` * O `metadata` enviado é salvo e retornado no objeto de cobrança dentro do campo `metadata` **Exemplo de uso:** ```json theme={null} // POST /v2/checkouts/create { "items": [{ "id": "prod_abc123", "quantity": 1 }], "metadata": { "orderId": "order_xyz", "source": "mobile" }, ... } ``` **Resposta:** ```json theme={null} { "id": "bill_abc123", "metadata": { "orderId": "order_xyz", "source": "mobile" }, ... } ``` *** ## Webhooks de Assinatura: novo campo `checkout` no payload Os eventos de assinatura (`subscription.completed`, `subscription.renewed`, `subscription.cancelled`) passam a retornar um novo campo **`checkout`** dentro de `data`, contendo o objeto completo do checkout associado à cobrança. **O que mudou:** * Adicionado campo `checkout` em `data` com os detalhes do checkout associado à cobrança (id, url, amount, items, status, methods, etc.) * Adicionado campo `id` no nível raiz do payload (identificador único do log do webhook) **Estrutura anterior:** ```json theme={null} { "event": "subscription.completed", "data": { "subscription": { ... }, "customer": { ... }, "payment": { ... }, "payerInformation": { ... } } } ``` **Nova estrutura:** ```json theme={null} { "id": "log_abc123xyz", "event": "subscription.completed", "data": { "subscription": { ... }, "customer": { ... }, "payment": { ... }, "payerInformation": { ... }, "checkout": { ... } } } ``` *** ## Nova versão da API A **API v2 está em beta** e passa a ser o novo padrão oficial. Tudo que é novo daqui pra frente roda nela. **O que isso significa na prática?** Todas as features novas — **Checkout Transparente**, **Cartão de crédito**, **Assinatura** ou qualquer novidade que vier — estarão disponíveis **somente na API v2**. Se você quiser usar o que há de mais recente, v2 é o caminho. **Como usar a API v2?** A API v2 está disponível para **clientes selecionados** até o fim da fase beta. Se você quiser participar do beta, entre em contato com o nosso suporte ao cliente. **Posso usar v1 e v2 ao mesmo tempo?** Pode, sim. As duas convivem em paralelo. Mas a gente recomenda **migrar para a v2 o quanto antes**: mais estabilidade e acesso a todas as funcionalidades novas. **E a API v1?** A API v1 segue funcionando e será mantida até **1º de março de 2028**. Depois dessa data ela será descontinuada. Então vale ir se organizando e fazendo a migração com calma. Se você ainda precisa consultar a documentação da v1 durante a migração: * Em produção, selecione a versão **v1** no seletor de versões no topo desta documentação ou acessar o [link](/pages/v1/introduction) *** Esquecemos os updates antes da v2. Prometemos que todo novo update aparecerá por aqui.