Filtrar Pagamentos

📌 Endpoint

GET /stores/:storeId/payments/filter Filtra pagamentos de uma loja com suporte a paginação, ordenação e filtros por metadata.

🔐 Autenticação

Rota privada. Envie o header Authorization com sua API key e plano ativo.

{
  "Authorization": "SUA_API_KEY_AQUI"
}

🧾 Parâmetro de rota

Parâmetro	Tipo	Obrigatório	Descrição
`storeId`	string	Sim	ID da loja

🔎 Query params

Campo	Tipo	Obrigatório	Descrição
`id`	string	Não	ID do pagamento
`uuid`	string	Não	UUID do pagamento
`status`	string	Não	`PENDING`, `APPROVED`, `REJECTED`, `CANCELLED`, `REFUNDED`, `CHARGED_BACK`, `EXPIRED`
`name`	string	Não	Nome do comprador (contains)
`email`	string	Não	Email do comprador (contains)
`cpf`	string	Não	CPF (contains)
`price`	number	Não	Preço exato
`minPrice`	number	Não	Preço mínimo
`maxPrice`	number	Não	Preço máximo
`coupon`	boolean	Não	Filtra pagamentos com ou sem cupom
`gateway`	string	Não	`MERCADOPAGO`, `ASAAS` ou `EFI_BANK` (legado)
`shipment`	string	Não	`PENDING`, `PREPARING`, `SHIPPED`, `DELIVERED`, `RETURNED`, `CANCELLED`
`createdAtFrom`	string (ISO)	Não	Data inicial de criação
`createdAtTo`	string (ISO)	Não	Data final de criação
`updatedAtFrom`	string (ISO)	Não	Data inicial de atualização
`updatedAtTo`	string (ISO)	Não	Data final de atualização
`productId`	string	Não	Filtra compras que contenham um produto específico
`metadataKey`	string	Não	Caminho da chave em metadata (aceita caminho aninhado com `.`)
`metadataValue`	string	Não	Valor procurado em metadata
`sortBy`	string	Não	`createdAt`, `updatedAt`, `price`, `name`, `email`
`sortOrder`	string	Não	`asc` ou `desc`
`page`	number	Não	Página atual (padrão: `1`)
`limit`	number	Não	Itens por página (padrão: `20`, máximo: `100`)
`cursor`	string	Não	Cursor opaco para paginação por cursor. Suportado apenas com `sortBy=createdAt` (padrão). Não pode ser usado junto com `page`

🔄 Paginação por cursor

Para listas grandes (mais de ~100 itens), prefira paginação por cursor no lugar de page. O cursor é suportado somente quando sortBy=createdAt (padrão):

Faça a primeira chamada sem cursor.
Se hasMore for true, a resposta traz o campo nextCursor.
Envie esse nextCursor no parâmetro cursor da próxima requisição para buscar a página seguinte.

curl -X GET "https://api.cabrapi.com.br/stores/STORE_ID/payments/filter?cursor=v1:SEU_CURSOR_AQUI&limit=20" \
  -H "Authorization: SUA_API_KEY_AQUI"

No modo cursor, a paginação é retornada apenas com nextCursor, hasMore e limit (sem total/totalPages):

{
  "status": true,
  "code": "PAYMENTS_FILTERED",
  "payments": [ /* ... */ ],
  "pagination": {
    "nextCursor": "v1:e2xFn...",
    "hasMore": true,
    "limit": 20
  }
}

cursor e page não podem ser usados juntos (400 INVALID_PAGINATION).
Usar cursor com sortBy diferente de createdAt retorna 400 INVALID_CURSOR_SORT.
nextCursor: null com hasMore: false indicam o fim da lista (a API responde 200 com array vazio).
Filtros de metadata muito amplos continuam podendo retornar 422 FILTER_TOO_BROAD.

✅ Exemplo de requisição

curl -X GET "https://api.cabrapi.com.br/stores/STORE_ID/payments/filter?gateway=MERCADOPAGO&limit=1" \
  -H "Authorization: SUA_API_KEY_AQUI"

🧠 Exemplo para metadata aninhada

Filtrar por metadata.items[0].product.sold = 19:

curl -X GET "https://api.cabrapi.com.br/stores/STORE_ID/payments/filter?gateway=MERCADOPAGO&metadataKey=items.0.product.sold&metadataValue=19&limit=1" \
  -H "Authorization: SUA_API_KEY_AQUI"

📦 Resposta de sucesso (200)

{
  "status": true,
  "code": "PAYMENTS_FILTERED",
  "payments": [
    {
      "id": "PAYMENT_ID",
      "uuid": "8cf7de6e-4c92-4baf-b978-2f9195f2e0e2",
      "status": "APPROVED",
      "name": "Sebastian Jn",
      "email": "[email protected]",
      "gateway": "MERCADOPAGO",
      "shipment": "PENDING",
      "storeId": "STORE_ID"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 1,
    "total": 38,
    "totalPages": 38,
    "nextCursor": "v1:e2xFn...",
    "hasMore": true
  }
}

A primeira chamada (sem cursor) já retorna nextCursor e hasMore na paginação, permitindo iniciar a paginação por cursor sem chamadas extras.

⚠️ Possíveis erros

400 INVALID_DATA → parâmetros inválidos
400 INVALID_PAGINATION_LIMIT → limit fora do intervalo permitido (1 a 100)
400 INVALID_PAGINATION_PAGE → page inválida
400 INVALID_PAGINATION_CURSOR → cursor inválido ou malformado
400 INVALID_PAGINATION → page e cursor utilizados juntos
400 INVALID_CURSOR_SORT → cursor usado com sortBy diferente de createdAt
401/403 → sem autorização para a loja
422 FILTER_TOO_BROAD → filtro por metadata muito amplo; refine metadataKey/metadataValue
500 INTERNAL_SERVER_ERROR → erro interno

Introdução

Lojas

Webhooks

Categorias

Produtos

Cupons

Pagamentos

Afiliados

Pagina da loja

Filtrar Pagamentos

📌 Endpoint

🔐 Autenticação

🧾 Parâmetro de rota

🔎 Query params

🔄 Paginação por cursor

✅ Exemplo de requisição

🧠 Exemplo para metadata aninhada

📦 Resposta de sucesso (200)

⚠️ Possíveis erros

​📌 Endpoint

​🔐 Autenticação

​🧾 Parâmetro de rota

​🔎 Query params

​🔄 Paginação por cursor

​✅ Exemplo de requisição

​🧠 Exemplo para metadata aninhada

​📦 Resposta de sucesso (200)

​⚠️ Possíveis erros

📌 Endpoint

🔐 Autenticação

🧾 Parâmetro de rota

🔎 Query params

🔄 Paginação por cursor

✅ Exemplo de requisição

🧠 Exemplo para metadata aninhada

📦 Resposta de sucesso (200)

⚠️ Possíveis erros