> ## Documentation Index > Fetch the complete documentation index at: https://docs.4seletpay.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Changelog da API > Histórico de versões, novas funcionalidades e correções da API 4Selet Pay. Acompanhe as atualizações e o histórico de versões da API. Este changelog é atualizado continuamente com melhorias, novas funcionalidades e correções relevantes. ## Atualizações Recentes ## Cartões: um único endpoint para salvar e tokenizar Unificamos o cadastro de cartão em **um só endpoint**. Antes, salvar um cartão para uso posterior exigia duas chamadas — uma para criar o cartão e outra, separada, apenas para tokenizá-lo. Agora **a criação do cartão já dispara a tokenização**, e não existe mais rota de tokenização avulsa. **Endpoints removidos:** | Método | Endpoint | Substituído por | | ------ | ------------------------------------------------ | -------------------------------------------- | | `POST` | `/v1/clients/{clientCode}/cards` | `POST /v1/clients/{clientCode}/cards/tokens` | | `POST` | `/v1/clients/{clientCode}/cards/{cardId}/tokens` | `POST /v1/clients/{clientCode}/cards/tokens` | **Endpoint único de cadastro:** ```http theme={null} POST /v1/clients/{clientCode}/cards/tokens ``` **Mudança incompatível.** Se a sua integração chamava `POST .../cards` seguido de `POST .../cards/{cardId}/tokens`, troque as duas chamadas por uma única chamada a `POST .../cards/tokens` com o mesmo corpo do antigo cadastro. As demais rotas de cartão (listar, consultar, atualizar e excluir) permanecem inalteradas. O comportamento é o mesmo já documentado: a resposta volta imediatamente com `202 Accepted` e `tokenization_status: "pending"`, e o resultado da tokenização chega por webhook (`card.token_created` / `card.token_failed`). Não é necessário fazer polling. **`card_token` em toda representação de cartão:** O campo `card_token` passa a aparecer em **todas** as respostas e eventos de cartão — não apenas no `card.token_created`. Ele é o identificador do cartão salvo e continua sendo o valor enviado em `payment.card.card_token` ao criar uma cobrança. *** ## Webhooks: campo `webhook_version` no payload Todo webhook desta documentação passa a incluir o campo `webhook_version` no envelope, identificando o formato do payload: ```json theme={null} { "type": "charge.canceled", "id": "hook_a1b2c3d4e5f6", "webhook_version": "v1", "data": { ... } } ``` O valor é sempre `v1` para os eventos documentados aqui. É uma **adição** ao payload — nenhum campo existente mudou de nome ou de formato. Trate valores desconhecidos de forma tolerante para conviver com formatos futuros. *** ## Novo evento: `tax_invoice.issued` A emissão de nota fiscal agora notifica sua aplicação. O evento `tax_invoice.issued` é disparado quando **todas** as notas de um pedido são autorizadas, e traz os links públicos dos PDFs prontos para entregar ao cliente. ```json Payload theme={null} { "type": "tax_invoice.issued", "id": "hook_a1b2c3d4e5f6", "webhook_version": "v1", "data": { "order_code": "ord_9f3c1b2a", "email": "joao@exemplo.com.br", "customer_name": "João Silva", "corporate_name": "Minha Empresa LTDA", "total_amount": "R$ 199,90", "invoices": [ { "model": "serviceInvoice", "code": "000000123", "pdf_url": "https://app.spedy.com.br/public/service-invoices/8f14e45f-ea1c-4f2b-9d61-3f2c7b8a1d05/pdf" } ], "products": "Plano Mensal Premium", "payment_method": "Cartão de Crédito" } } ``` Consulte a [referência do evento](/pages/webhooks/events/tax-invoice) para a descrição completa dos campos. ## Cartões salvos, tokenização e cobrança com `card_token` Novo conjunto de rotas para **gerenciar os cartões salvos de um cliente** e reutilizá-los nas cobranças, além de melhorias no `/charge`. **Novos endpoints — Cartões:** | Método | Endpoint | Descrição | | -------- | ----------------------------------------- | ------------------------------------------------- | | `POST` | `/v1/clients/{clientCode}/cards/tokens` | Salvar cartão do cliente (tokenização assíncrona) | | `GET` | `/v1/clients/{clientCode}/cards` | Listar cartões do cliente | | `GET` | `/v1/clients/{clientCode}/cards/{cardId}` | Consultar cartão | | `PUT` | `/v1/clients/{clientCode}/cards/{cardId}` | Atualizar cartão (nome, tipo, bandeira, validade) | | `DELETE` | `/v1/clients/{clientCode}/cards/{cardId}` | Excluir cartão (soft delete) | **Cobrança com cartão salvo (`/charge`):** * Agora é possível enviar `payment.card.card_token` (o token retornado ao salvar o cartão / no evento `card.token_created`) **no lugar dos dados completos do cartão**. Os campos `number`, `name`, `month`, `year` e `security_code` tornam-se opcionais quando `card_token` é enviado (continue enviando `installments`). * Toda cobrança com cartão passa a retornar o `card_token` em `data.orders[].charges[].payment.card_token` — tanto ao enviar `card_token` quanto os dados completos (nesse caso o cartão é salvo e o `card_token` é devolvido). Em pagamentos sem cartão (ex.: PIX), vem `null`. * O billing address **não** é tokenizado: ao cobrar com `card_token`, informe o billing address (`client.address`) na requisição. **Segurança e comportamento:** * O número completo do cartão (PAN) e o CVV **nunca** são retornados — apenas `first_six_digits` e `last_four_digits`. * As rotas de cartão e o uso de `card_token` são **escopados por conta** — um `card_token` de outra conta é rejeitado com `422`. * **Tokenização assíncrona por webhook**: ao salvar um cartão (`POST .../cards/tokens`), a resposta retorna imediatamente com `tokenization_status: "pending"` e o resultado é entregue por webhook. Novos eventos de cartão: `card.created`, `card.updated`, `card.deleted`, `card.expired`, `card.token_pending`, `card.token_created` e `card.token_failed`. * Exclusão é *soft delete* e é bloqueada (`409`) quando o cartão está vinculado a uma assinatura ativa. **Exemplo — cobrar com cartão salvo:** ```json Request theme={null} POST /v1/charge Authorization: Bearer {token} account: {accountcode} { "client": { "name": "João Silva", "email": "joao@exemplo.com.br", "phone": { "ddi": "55", "ddd": "11", "number": "999999999" }, "document": { "type": "CPF", "number": "123.456.789-09" } }, "items": [ { "id": "produto_001", "description": "Camiseta Premium", "amount": 99.90, "quantity": 1 } ], "payment": { "type": "CreditCard", "card": { "card_token": "9b2f5c8e-3a1d-4f7b-8c6e-2d9a1b4c5e6f", "installments": 1 } } } ``` ## Links de Pagamento Lançamento dos **Links de Pagamento** — um novo recurso que permite criar checkouts pré-configurados e compartilhá-los diretamente com seus clientes, sem precisar construir uma página de pagamento do zero. Cada link gera uma URL única com token de segurança. O cliente acessa, confirma os dados e paga. Você recebe a notificação via webhook. **Novos endpoints:** | Método | Endpoint | Descrição | | -------- | --------------------------------- | -------------------------------- | | `POST` | `/v1/payment-links` | Criar novo link de pagamento | | `GET` | `/v1/payment-links` | Listar links da conta (paginado) | | `GET` | `/v1/payment-links/{code}` | Consultar link por código | | `POST` | `/v1/payment-links/{code}/cancel` | Cancelar link | | `DELETE` | `/v1/payment-links/{code}` | Excluir link | **Principais funcionalidades:** * **Dados do cliente pré-preenchidos** — nome, e-mail, telefone, documento e endereço já chegam preenchidos no checkout * **Métodos de pagamento configuráveis** — `CreditCard`, `PIX` ou `Boleto`; se omitido, todos os métodos ativos da conta são exibidos * **Parcelamento por milestones** — defina faixas de parcelas com taxas de juros específicas; o sistema expande automaticamente de 1x a 12x * **Imagem no checkout** — envie uma URL pública ou string base64; o servidor processa e armazena automaticamente (fail-soft: se falhar, o link é criado sem imagem e a resposta inclui `image_warning`) * **Desconto exclusivo PIX** — percentual ou valor fixo aplicado apenas para pagamentos via PIX * **Expiração automática** — defina `expires_at` para desativar o link em uma data futura * **Limite de usos** — defina `max_uses` para encerrar o link após um número máximo de pagamentos * **Split de pagamento** — divida o recebimento automaticamente entre múltiplos recebedores por percentual ou valor fixo * **Privacidade no checkout** — `obfuscate_client` mascara os dados do pagador; `obfuscate_items` oculta itens e valores * **URLs de navegação** — `back_url` para o botão "Voltar" e `redirect_url` para redirecionar após pagamento confirmado * **Frete** — valor adicional somado ao total dos itens **Exemplo — criar link básico:** ```json Request theme={null} POST /v1/payment-links Authorization: Bearer {token} account: {accountcode} { "client": { "name": "Hugo Belo", "email": "hugo@exemplo.com.br", "phone": { "ddi": "55", "ddd": "62", "number": "984063942" } }, "items": [ { "id": "plano-premium", "description": "Plano Mensal Premium", "amount": 97.99, "quantity": 1 } ], "config": { "payment_types": ["CreditCard", "PIX"], "expires_at": "2026-12-31 23:59:59", "pix_discount_value": 10, "pix_discount_type": "percentage", "redirect_url": "https://meusite.com.br/obrigado" } } ``` ```json Resposta (HTTP 201) theme={null} { "mensagem": "Link de pagamento criado com sucesso", "erro": false, "mensagenserro": [], "codigoretorno": 201, "id": "00000000-0000-0000-0000-000000000000", "data": { "code": "lnk_abc123xyz", "url": "https://checkout.4seletpay.com.br/lnk_abc123xyz?token=...", "status": "InProgress", "value": 97.99, "uses_count": 0, "created_at": "2026-05-27T10:00:00.000000Z" } } ``` Consulte a [documentação de Links de Pagamento](/pages/links-de-pagamento/reference) para detalhes completos de todos os campos.