From dc4de2be082f0fae6c081dab518ea595ecb7a758 Mon Sep 17 00:00:00 2001 From: Lucas Zago Date: Mon, 3 Aug 2026 10:09:51 -0300 Subject: [PATCH 1/2] feat: added filter date to api --- openapi.yaml | 320 ++++++++++--------------------- pages/client/list.mdx | 2 +- pages/coupons/list.mdx | 2 +- pages/payment-links/list.mdx | 2 +- pages/payment/list.mdx | 2 +- pages/payouts/list.mdx | 2 +- pages/pix/list.mdx | 2 +- pages/products/list.mdx | 2 +- pages/reference/introduction.mdx | 52 ++++- pages/subscriptions/list.mdx | 2 +- pages/transparents/list.mdx | 2 +- pages/webhooks/list.mdx | 2 + 12 files changed, 161 insertions(+), 231 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index 52891cd..1c286ab 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -130,28 +130,11 @@ paths: security: - bearerAuth: [] parameters: - - name: after - in: query - description: Cursor para buscar itens após este ponto - required: false - schema: - type: string - - name: before - in: query - description: Cursor para buscar itens antes deste ponto - required: false - schema: - type: string - - name: limit - in: query - description: Quantidade de itens por página (1-100) - required: false - schema: - type: integer - minimum: 1 - maximum: 100 - default: 100 - example: 100 + - $ref: '#/components/parameters/QueryAfter' + - $ref: '#/components/parameters/QueryBefore' + - $ref: '#/components/parameters/QueryLimit' + - $ref: '#/components/parameters/QueryStartDate' + - $ref: '#/components/parameters/QueryEndDate' - name: id in: query description: Filtrar por identificador único do cliente @@ -391,28 +374,11 @@ paths: security: - bearerAuth: [] parameters: - - name: after - in: query - description: Cursor para buscar itens após este ponto - required: false - schema: - type: string - - name: before - in: query - description: Cursor para buscar itens antes deste ponto - required: false - schema: - type: string - - name: limit - in: query - description: Quantidade de itens por página (1-100) - required: false - schema: - type: integer - minimum: 1 - maximum: 100 - default: 100 - example: 100 + - $ref: '#/components/parameters/QueryAfter' + - $ref: '#/components/parameters/QueryBefore' + - $ref: '#/components/parameters/QueryLimit' + - $ref: '#/components/parameters/QueryStartDate' + - $ref: '#/components/parameters/QueryEndDate' - name: id in: query description: Filtrar por identificador único do cupom @@ -772,28 +738,11 @@ paths: security: - bearerAuth: [] parameters: - - name: after - in: query - description: Cursor para buscar itens após este ponto - required: false - schema: - type: string - - name: before - in: query - description: Cursor para buscar itens antes deste ponto - required: false - schema: - type: string - - name: limit - in: query - description: Quantidade de itens por página (1-100) - required: false - schema: - type: integer - minimum: 1 - maximum: 100 - default: 100 - example: 100 + - $ref: '#/components/parameters/QueryAfter' + - $ref: '#/components/parameters/QueryBefore' + - $ref: '#/components/parameters/QueryLimit' + - $ref: '#/components/parameters/QueryStartDate' + - $ref: '#/components/parameters/QueryEndDate' - name: id in: query description: Filtrar por identificador único do produto @@ -1472,28 +1421,11 @@ paths: security: - bearerAuth: [] parameters: - - name: after - in: query - description: Cursor para buscar itens após este ponto - required: false - schema: - type: string - - name: before - in: query - description: Cursor para buscar itens antes deste ponto - required: false - schema: - type: string - - name: limit - in: query - description: Quantidade de itens por página (1-100) - required: false - schema: - type: integer - minimum: 1 - maximum: 100 - default: 100 - example: 100 + - $ref: '#/components/parameters/QueryAfter' + - $ref: '#/components/parameters/QueryBefore' + - $ref: '#/components/parameters/QueryLimit' + - $ref: '#/components/parameters/QueryStartDate' + - $ref: '#/components/parameters/QueryEndDate' - name: id in: query description: Filtrar por identificador único do Checkout @@ -1573,28 +1505,11 @@ paths: security: - bearerAuth: [] parameters: - - name: after - in: query - description: Cursor para buscar itens após este ponto - required: false - schema: - type: string - - name: before - in: query - description: Cursor para buscar itens antes deste ponto - required: false - schema: - type: string - - name: limit - in: query - description: Quantidade de itens por página (1-100) - required: false - schema: - type: integer - minimum: 1 - maximum: 100 - default: 100 - example: 100 + - $ref: '#/components/parameters/QueryAfter' + - $ref: '#/components/parameters/QueryBefore' + - $ref: '#/components/parameters/QueryLimit' + - $ref: '#/components/parameters/QueryStartDate' + - $ref: '#/components/parameters/QueryEndDate' - name: id in: query description: Filtrar por identificador único do link de pagamento @@ -2048,28 +1963,11 @@ paths: security: - bearerAuth: [] parameters: - - name: after - in: query - description: Cursor para buscar itens após este ponto - required: false - schema: - type: string - - name: before - in: query - description: Cursor para buscar itens antes deste ponto - required: false - schema: - type: string - - name: limit - in: query - description: Quantidade de itens por página (1-100) - required: false - schema: - type: integer - minimum: 1 - maximum: 100 - default: 100 - example: 100 + - $ref: '#/components/parameters/QueryAfter' + - $ref: '#/components/parameters/QueryBefore' + - $ref: '#/components/parameters/QueryLimit' + - $ref: '#/components/parameters/QueryStartDate' + - $ref: '#/components/parameters/QueryEndDate' - name: id in: query description: Filtrar por identificador único do QRCode Pix @@ -2414,28 +2312,11 @@ paths: security: - bearerAuth: [] parameters: - - name: after - in: query - description: Cursor para buscar itens após este ponto - required: false - schema: - type: string - - name: before - in: query - description: Cursor para buscar itens antes deste ponto - required: false - schema: - type: string - - name: limit - in: query - description: Quantidade de itens por página (1-100) - required: false - schema: - type: integer - minimum: 1 - maximum: 100 - default: 100 - example: 100 + - $ref: '#/components/parameters/QueryAfter' + - $ref: '#/components/parameters/QueryBefore' + - $ref: '#/components/parameters/QueryLimit' + - $ref: '#/components/parameters/QueryStartDate' + - $ref: '#/components/parameters/QueryEndDate' - name: id in: query description: Filtrar por identificador único da transação @@ -2696,28 +2577,11 @@ paths: security: - bearerAuth: [] parameters: - - name: after - in: query - description: Cursor para buscar itens após este ponto - required: false - schema: - type: string - - name: before - in: query - description: Cursor para buscar itens antes deste ponto - required: false - schema: - type: string - - name: limit - in: query - description: Quantidade de itens por página (1-100) - required: false - schema: - type: integer - minimum: 1 - maximum: 100 - default: 100 - example: 100 + - $ref: '#/components/parameters/QueryAfter' + - $ref: '#/components/parameters/QueryBefore' + - $ref: '#/components/parameters/QueryLimit' + - $ref: '#/components/parameters/QueryStartDate' + - $ref: '#/components/parameters/QueryEndDate' - name: id in: query description: Filtrar por identificador único da transação PIX na AbacatePay @@ -2929,28 +2793,11 @@ paths: security: - bearerAuth: [] parameters: - - name: after - in: query - description: Cursor para buscar itens após este ponto - required: false - schema: - type: string - - name: before - in: query - description: Cursor para buscar itens antes deste ponto - required: false - schema: - type: string - - name: limit - in: query - description: Quantidade de itens por página (1-100) - required: false - schema: - type: integer - minimum: 1 - maximum: 100 - default: 100 - example: 100 + - $ref: '#/components/parameters/QueryAfter' + - $ref: '#/components/parameters/QueryBefore' + - $ref: '#/components/parameters/QueryLimit' + - $ref: '#/components/parameters/QueryStartDate' + - $ref: '#/components/parameters/QueryEndDate' - name: id in: query description: Filtrar por identificador único do Checkout de assinatura @@ -3594,28 +3441,11 @@ paths: schema: type: string example: pagamentos - - name: after - in: query - description: Cursor para buscar itens após este ponto - required: false - schema: - type: string - - name: before - in: query - description: Cursor para buscar itens antes deste ponto - required: false - schema: - type: string - - name: limit - in: query - description: Quantidade de itens por página (1-100) - required: false - schema: - type: integer - minimum: 1 - maximum: 100 - default: 100 - example: 100 + - $ref: '#/components/parameters/QueryAfter' + - $ref: '#/components/parameters/QueryBefore' + - $ref: '#/components/parameters/QueryLimit' + - $ref: '#/components/parameters/QueryStartDate' + - $ref: '#/components/parameters/QueryEndDate' - name: id in: query description: Filtrar por identificador único do webhook @@ -3775,6 +3605,56 @@ paths: description: Mensagem de erro indicando que o webhook não foi encontrado. example: Webhook não encontrado. components: + parameters: + QueryAfter: + name: after + in: query + description: Cursor para buscar itens após este ponto (use o `publicId` retornado em `pagination.next`). + required: false + schema: + type: string + QueryBefore: + name: before + in: query + description: Cursor para buscar itens antes deste ponto (use o `publicId` retornado em `pagination.before`). + required: false + schema: + type: string + QueryLimit: + name: limit + in: query + description: Quantidade de itens por página (1-100). + required: false + schema: + type: integer + minimum: 1 + maximum: 100 + default: 100 + example: 100 + QueryStartDate: + name: startDate + in: query + description: > + Filtra registros criados a partir desta data (inclusive). Formato + `YYYY-MM-DD`. O intervalo é interpretado no fuso horário + `America/Sao_Paulo` (00:00 do dia inicial). + required: false + schema: + type: string + format: date + example: '2026-01-01' + QueryEndDate: + name: endDate + in: query + description: > + Filtra registros criados até esta data (inclusive). Formato + `YYYY-MM-DD`. O intervalo é interpretado no fuso horário + `America/Sao_Paulo` (23:59:59.999 do dia final). + required: false + schema: + type: string + format: date + example: '2026-01-31' schemas: Success: type: boolean diff --git a/pages/client/list.mdx b/pages/client/list.mdx index fe9f2a1..90b1fe9 100644 --- a/pages/client/list.mdx +++ b/pages/client/list.mdx @@ -9,4 +9,4 @@ Retorna todos os clientes cadastrados na sua loja. Requer a permissão `CUSTOMER:READ`. -Use `limit`, `after` e `before` para paginar. Cada item segue o mesmo formato da resposta do [Criar Cliente](/pages/client/create), incluindo `id`, `email`, `name` e `taxId`. +Use `limit`, `after` e `before` para paginar e `startDate`/`endDate` (`YYYY-MM-DD`) para filtrar por data de criação. Consulte [Paginação e filtro por data](/pages/reference/introduction#paginação-e-filtro-por-data). Cada item segue o mesmo formato da resposta do [Criar Cliente](/pages/client/create), incluindo `id`, `email`, `name` e `taxId`. diff --git a/pages/coupons/list.mdx b/pages/coupons/list.mdx index fc19fd6..c5e5509 100644 --- a/pages/coupons/list.mdx +++ b/pages/coupons/list.mdx @@ -9,4 +9,4 @@ Retorna todos os cupons da sua loja, incluindo ativos e inativos. Requer a permissão `COUPON:READ`. -Use `limit`, `after` e `before` para paginar. Cada item segue o mesmo formato da resposta do [Criar Cupom](/pages/coupons/create), incluindo `status`, `redeemsCount` e `maxRedeems`. +Use `limit`, `after` e `before` para paginar e `startDate`/`endDate` (`YYYY-MM-DD`) para filtrar por data de criação. Consulte [Paginação e filtro por data](/pages/reference/introduction#paginação-e-filtro-por-data). Cada item segue o mesmo formato da resposta do [Criar Cupom](/pages/coupons/create), incluindo `status`, `redeemsCount` e `maxRedeems`. diff --git a/pages/payment-links/list.mdx b/pages/payment-links/list.mdx index bbff5e1..7e91094 100644 --- a/pages/payment-links/list.mdx +++ b/pages/payment-links/list.mdx @@ -9,4 +9,4 @@ Retorna todos os links de pagamento (`frequency: MULTIPLE_PAYMENTS`) da sua loja Requer a permissão `CHECKOUT:READ`. -Use `limit`, `after` e `before` para paginar. Cada item segue o mesmo formato da resposta do [Criar link de pagamento](/pages/payment-links/create). +Use `limit`, `after` e `before` para paginar e `startDate`/`endDate` (`YYYY-MM-DD`) para filtrar por data de criação. Consulte [Paginação e filtro por data](/pages/reference/introduction#paginação-e-filtro-por-data). Cada item segue o mesmo formato da resposta do [Criar link de pagamento](/pages/payment-links/create). diff --git a/pages/payment/list.mdx b/pages/payment/list.mdx index a36cc10..94213b7 100644 --- a/pages/payment/list.mdx +++ b/pages/payment/list.mdx @@ -9,7 +9,7 @@ Retorna todos os checkouts da sua loja em ordem cronológica decrescente. Requer a permissão `CHECKOUT:READ`. -Use os parâmetros de paginação `limit`, `after` e `before` para navegar pelos resultados. Cada item da lista segue o mesmo formato da resposta do [Criar Checkout](/pages/payment/create). +Use os parâmetros de paginação `limit`, `after` e `before` para navegar pelos resultados, e `startDate`/`endDate` (`YYYY-MM-DD`) para filtrar por data de criação. Consulte [Paginação e filtro por data](/pages/reference/introduction#paginação-e-filtro-por-data). Cada item da lista segue o mesmo formato da resposta do [Criar Checkout](/pages/payment/create). Combine com `status` para buscar só cobranças pendentes, pagas ou canceladas. diff --git a/pages/payouts/list.mdx b/pages/payouts/list.mdx index fe9c619..0aaffc6 100644 --- a/pages/payouts/list.mdx +++ b/pages/payouts/list.mdx @@ -9,4 +9,4 @@ Retorna todos os saques realizados pela sua conta. Requer a permissão `WITHDRAW:READ`. -Use `limit`, `after` e `before` para paginar. Cada item segue o mesmo formato da resposta do [Criar Saque](/pages/payouts/create), incluindo `status`, `amount`, `platformFee` e `receiptUrl`. +Use `limit`, `after` e `before` para paginar e `startDate`/`endDate` (`YYYY-MM-DD`) para filtrar por data de criação. Consulte [Paginação e filtro por data](/pages/reference/introduction#paginação-e-filtro-por-data). Cada item segue o mesmo formato da resposta do [Criar Saque](/pages/payouts/create), incluindo `status`, `amount`, `platformFee` e `receiptUrl`. diff --git a/pages/pix/list.mdx b/pages/pix/list.mdx index 78da75f..3cb7fb1 100644 --- a/pages/pix/list.mdx +++ b/pages/pix/list.mdx @@ -9,4 +9,4 @@ Retorna todas as transações PIX enviadas pela sua conta. Requer a permissão `WITHDRAW:READ`. -Use `limit`, `after` e `before` para paginar. Cada item segue o mesmo formato da resposta do [Enviar PIX](/pages/pix/create), incluindo `status`, `amount`, `platformFee` e `receiptUrl`. +Use `limit`, `after` e `before` para paginar e `startDate`/`endDate` (`YYYY-MM-DD`) para filtrar por data de criação. Consulte [Paginação e filtro por data](/pages/reference/introduction#paginação-e-filtro-por-data). Cada item segue o mesmo formato da resposta do [Enviar PIX](/pages/pix/create), incluindo `status`, `amount`, `platformFee` e `receiptUrl`. diff --git a/pages/products/list.mdx b/pages/products/list.mdx index 6fd3fa8..b0eec43 100644 --- a/pages/products/list.mdx +++ b/pages/products/list.mdx @@ -9,4 +9,4 @@ Retorna todos os produtos do seu catálogo. Requer a permissão `PRODUCT:READ`. -Use `limit`, `after` e `before` para paginar. Cada item segue o mesmo formato da resposta do [Criar Produto](/pages/products/create), incluindo `id`, `name`, `price`, `cycle`, `trialDays` e `status`. +Use `limit`, `after` e `before` para paginar e `startDate`/`endDate` (`YYYY-MM-DD`) para filtrar por data de criação. Consulte [Paginação e filtro por data](/pages/reference/introduction#paginação-e-filtro-por-data). Cada item segue o mesmo formato da resposta do [Criar Produto](/pages/products/create), incluindo `id`, `name`, `price`, `cycle`, `trialDays` e `status`. diff --git a/pages/reference/introduction.mdx b/pages/reference/introduction.mdx index 602b320..ce93c56 100644 --- a/pages/reference/introduction.mdx +++ b/pages/reference/introduction.mdx @@ -77,9 +77,57 @@ Cada chave de API pode ter permissões granulares por recurso. Se você receber --- -## Paginação +## Paginação e filtro por data -Endpoints de listagem retornam todos os registros disponíveis. Futuramente suportarão paginação via `limit` e `offset`. +Endpoints de listagem suportam **paginação por cursor** e **filtro por intervalo de datas** de criação (`createdAt`). + +### Paginação por cursor + +| Param | Tipo | Descrição | +|-------|------|-----------| +| `limit` | `integer` | Itens por página (1–100, default `100`) | +| `after` | `string` | Cursor — `publicId` do último item da página anterior | +| `before` | `string` | Cursor — `publicId` do primeiro item da página seguinte | + +A resposta inclui metadados em `pagination`: + +```json +{ + "success": true, + "data": [ ... ], + "pagination": { + "hasMore": true, + "next": "cust_abc123", + "before": "cust_xyz789" + }, + "error": null +} +``` + +Para avançar, passe `after` com o valor de `pagination.next`: + +```bash +GET /v2/customers/list?limit=20&after=cust_abc123 +``` + +### Filtro por data + +| Param | Tipo | Descrição | +|-------|------|-----------| +| `startDate` | `string` | Data inicial inclusive (`YYYY-MM-DD`) | +| `endDate` | `string` | Data final inclusive (`YYYY-MM-DD`) | + +Os dois parâmetros são opcionais e podem ser usados isoladamente ou combinados com `limit`, `after` e `before`. + +```bash +GET /v2/customers/list?startDate=2026-01-01&endDate=2026-01-31&limit=50 +``` + + + As datas são interpretadas no fuso horário **America/Sao_Paulo**. Por exemplo, `startDate=2026-01-15` inclui registros a partir de 15/01/2026 00:00 (horário de Brasília). + + +Endpoints com suporte a paginação e filtro de data: clientes, cupons, produtos, checkouts, links de pagamento, assinaturas, webhooks, saques, PIX enviados, pagamentos transparentes e demais rotas `*/list` da v2. --- diff --git a/pages/subscriptions/list.mdx b/pages/subscriptions/list.mdx index 02702e6..46b77f1 100644 --- a/pages/subscriptions/list.mdx +++ b/pages/subscriptions/list.mdx @@ -9,7 +9,7 @@ Retorna todos os checkouts de assinatura da sua loja. Requer a permissão `CHECKOUT:READ`. -Use `limit`, `after` e `before` para paginar. Cada item segue o mesmo formato da resposta do [Criar Checkout de assinatura](/pages/subscriptions/create), incluindo `status`, `url`, `amount` e `items`. +Use `limit`, `after` e `before` para paginar e `startDate`/`endDate` (`YYYY-MM-DD`) para filtrar por data de criação. Consulte [Paginação e filtro por data](/pages/reference/introduction#paginação-e-filtro-por-data). Cada item segue o mesmo formato da resposta do [Criar Checkout de assinatura](/pages/subscriptions/create), incluindo `status`, `url`, `amount` e `items`. **Valores de `status`:** diff --git a/pages/transparents/list.mdx b/pages/transparents/list.mdx index a09d14c..1115d8b 100644 --- a/pages/transparents/list.mdx +++ b/pages/transparents/list.mdx @@ -9,4 +9,4 @@ Retorna todos os checkouts transparentes (PIX QR Code) da sua loja. Requer a permissão `CHECKOUT:READ`. -Use `limit`, `after` e `before` para paginar. Cada item segue o mesmo formato da resposta do [Criar QRCode PIX](/pages/transparents/create), incluindo `status`, `brCode`, `amount` e `expiresAt`. +Use `limit`, `after` e `before` para paginar e `startDate`/`endDate` (`YYYY-MM-DD`) para filtrar por data de criação. Consulte [Paginação e filtro por data](/pages/reference/introduction#paginação-e-filtro-por-data). Cada item segue o mesmo formato da resposta do [Criar QRCode PIX](/pages/transparents/create), incluindo `status`, `brCode`, `amount` e `expiresAt`. diff --git a/pages/webhooks/list.mdx b/pages/webhooks/list.mdx index c6dcb99..1e0c026 100644 --- a/pages/webhooks/list.mdx +++ b/pages/webhooks/list.mdx @@ -6,3 +6,5 @@ openapi: "GET /webhooks/list" Requer a permissão `WEBHOOK:READ`. + +Use `limit`, `after` e `before` para paginar e `startDate`/`endDate` (`YYYY-MM-DD`) para filtrar por data de criação. Consulte [Paginação e filtro por data](/pages/reference/introduction#paginação-e-filtro-por-data). From dd12198e2b2b26bf0752eb1f33660d69af513815 Mon Sep 17 00:00:00 2001 From: Lucas Zago Date: Tue, 4 Aug 2026 08:20:16 -0300 Subject: [PATCH 2/2] feat: adicionando ao changelog --- pages/changelog/index.mdx | 44 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/pages/changelog/index.mdx b/pages/changelog/index.mdx index 7293a02..fd16dc5 100644 --- a/pages/changelog/index.mdx +++ b/pages/changelog/index.mdx @@ -11,6 +11,50 @@ Feedbacks também são bem-vindos no nosso Discord (#dev). ## Atualizações Recentes + +## Listagem: filtro por data (`startDate` / `endDate`) + +Todos os endpoints de listagem da API v2 agora suportam filtro por intervalo de datas de criação, além da paginação por cursor já existente. + +**O que mudou:** + +- Novos query params opcionais `startDate` e `endDate` (`YYYY-MM-DD`) em todas as rotas `GET /v2/*/list` +- Compatível com `limit`, `after` e `before` — paginação e filtro de data podem ser usados juntos +- As datas são interpretadas no fuso horário `America/Sao_Paulo` (início do dia para `startDate`, fim do dia para `endDate`) +- Validações aplicadas automaticamente: + - `startDate` não pode ser posterior a `endDate` + - Nenhuma data pode ser anterior a `2024-01-01` + - Nenhuma data pode ser superior a **1 ano no futuro** em relação à data atual + +**Endpoints afetados:** + +Clientes, cupons, produtos, checkouts, links de pagamento, assinaturas, webhooks, saques, PIX enviados, checkouts transparentes e demais rotas `*/list` da v2. + +**Exemplo:** + +```http +GET /v2/customers/list?startDate=2026-01-01&endDate=2026-01-31&limit=50 +``` + +```json +{ + "success": true, + "data": [ ... ], + "pagination": { + "hasMore": false, + "next": null, + "before": null + }, + "error": null +} +``` + +Consulte [Paginação e filtro por data](/pages/reference/introduction#paginação-e-filtro-por-data) para detalhes completos. + +--- + + + ## Boleto: data de vencimento customizável (`dueDate`)