# API de Intenções de Pagamento

A API de Intenções de Pagamento permite gerenciar e rastrear intenções de pagamento para seu negócio. Esta API fornece recursos abrangentes de gerenciamento de pagamentos, incluindo recuperação, filtragem e funcionalidade de exportação de dados de Inteligência de Negócios (BI).

# Visão Geral

A API de Intenções de Pagamento foi projetada para:

  • Gerenciamento de Pagamentos: Criar, recuperar e gerenciar intenções de pagamento
  • Inteligência de Negócios: Exportar dados agregados de pagamentos para análise e relatórios
  • Rastreamento Financeiro: Monitorar status, métodos e métricas financeiras dos pagamentos
  • Integração: Suporte para múltiplos métodos de pagamento e moedas

# Autenticação

Todas as solicitações à API de Intenções de Pagamento requerem autenticação com token Bearer usando tokens JWT.

Formato do Header:

Authorization: Bearer SEU_TOKEN_JWT

# URLs Base

Ambiente URL
Produção https://sdm.smarttalks.ai/v1
Desenvolvimento http://localhost:3000/v1

# Modelos de Dados

# Item de Pagamento

Representa um item de linha em um pagamento (produto ou serviço).

Campo Tipo Descrição
reference string Referência do produto/serviço ou SKU
description string Descrição do produto/serviço
quantity number Quantidade pedida
unitPrice number Preço unitário
customData object Campos personalizados adicionais (objeto livre)

# Pagamento

Registro completo de pagamento com todos os detalhes.

Campo Tipo Descrição
id string Identificador único do pagamento
groupId string ID do grupo de negócios
accountId string ID da conta/organização
contactId string ID do cliente/contato
amount number Valor do pagamento (sem descontos)
grossAmount number Valor total (incluindo descontos)
discount number Valor do desconto aplicado
voucherDiscount string Código do vale/cupom
voucherDiscountType string Tipo de desconto do vale: percent ou fixed
voucherDiscountAmount number Valor descontado pelo vale
description string Descrição do pagamento
reference string Número de referência externa
currency string Código da moeda: BRL, USD, EUR, ARC, UYU, PYG
status string Status atual do pagamento
method string Método de pagamento utilizado
paymentNsu string NSU (Numero Sequencial Único) do processador
paymentReference string ID de referência do processador de pagamento
billCode string Código do boleto para transferências bancárias
billUrl string URL do boleto para transferências bancárias
billAccessKey string Chave de acesso para transferências bancárias
paidAt string (ISO 8601) Quando o pagamento foi concluído
confirmedAt string (ISO 8601) Quando o pagamento foi confirmado
createdAt string (ISO 8601) Quando o pagamento foi criado
updatedAt string (ISO 8601) Quando o pagamento foi atualizado pela última vez
installments number Número de parcelas
items array Itens de linha do pagamento

Valores de Status do Pagamento:

  • pending - Pagamento aguardando processamento
  • analysis - Pagamento sob análise
  • completed - Pagamento concluído com sucesso
  • failed - Pagamento falhou
  • cancelled - Pagamento foi cancelado
  • expired - Pagamento expirou
  • integration_fail - Erro de integração ocorreu

Valores de Método de Pagamento:

  • credit_card - Pagamento com cartão de crédito
  • debit_card - Pagamento com cartão de débito
  • bank_transfer - Transferência bancária
  • cash - Pagamento em dinheiro
  • apple_pay - Apple Pay
  • google_pay - Google Pay
  • link - Link de pagamento
  • pix - Pix (pagamento instantâneo brasileiro)

# Listar Pagamentos

Obtenha uma lista paginada de pagamentos com filtragem e classificação opcionais.

GET https://sdm.smarttalks.ai/v1/intentions/payments

# Parâmetros de Query

Parâmetro Tipo Obrigatório Descrição Padrão
skip number Não Número de registros a pular para paginação 0
limit number Não Número máximo de registros a retornar 10
status string Não Filtrar por status do pagamento -
method string Não Filtrar por método de pagamento -
contactId string Não Filtrar por ID do cliente/contato -
sortBy string Não Campo para ordenar createdAt
sortOrder string Não Ordem de classificação: asc ou desc desc

# Resposta (200 - Sucesso)

{
  "status": "ok",
  "result": {
    "items": [
      {
        "id": "67290a1234567890abcdef01",
        "groupId": "6888cdb3d544272f5f6f471d",
        "accountId": "688a09fd359c2af61a637439",
        "contactId": "690d0796c7777a4009fdb906",
        "amount": 1150,
        "grossAmount": 1150,
        "currency": "BRL",
        "status": "completed",
        "method": "credit_card",
        "createdAt": "2025-11-07T16:00:20.408Z",
        "updatedAt": "2025-11-07T16:00:33.195Z",
        "paidAt": "2025-11-07T16:00:33.192Z",
        "items": [
          {
            "reference": "SKU-001",
            "description": "Produto A",
            "quantity": 1,
            "unitPrice": 1150
          }
        ]
      }
    ],
    "count": 21
  }
}

curl -X GET 'https://sdm.smarttalks.ai/v1/intentions/payments?skip=0&limit=10&status=completed&sortOrder=desc' \
  -H 'Authorization: Bearer SEU_TOKEN_JWT'

# Obter Pagamento por ID

Recupere um único pagamento intencional por seu ID com todos os detalhes.

GET https://sdm.smarttalks.ai/v1/intentions/payments/{id}

# Parâmetros de Caminho

Parâmetro Tipo Obrigatório Descrição
id string Sim Identificador único do pagamento

# Resposta (200 - Sucesso)

{
  "status": "ok",
  "result": {
    "id": "67290a1234567890abcdef01",
    "groupId": "6888cdb3d544272f5f6f471d",
    "accountId": "688a09fd359c2af61a637439",
    "contactId": "690d0796c7777a4009fdb906",
    "amount": 1150,
    "grossAmount": 1150,
    "discount": 0,
    "voucherDiscount": null,
    "voucherDiscountType": null,
    "voucherDiscountAmount": 0,
    "description": "Reserva Suite Júnior Luxo - Suites Beach Park Resort - Thiago Almeides 15/12/2025 a 18/12/2025",
    "reference": "H-823742",
    "currency": "BRL",
    "status": "completed",
    "method": "credit_card",
    "paymentNsu": "337407",
    "paymentReference": "2095",
    "paidAt": "2025-11-07T16:03:20.888Z",
    "confirmedAt": "2025-11-07T16:03:20.888Z",
    "createdAt": "2025-11-07T16:00:20.408Z",
    "updatedAt": "2025-11-07T16:03:20.195Z",
    "installments": null,
    "items": [
      {
        "reference": "Hospedagem Particular (pacotes) -- Map (Sem Parque)",
        "description": "Reserva Suite Júnior Luxo - Suites Beach Park Resort - Thiago Almeides 15/12/2025 a 18/12/2025",
        "quantity": 1,
        "unitPrice": 1150
      }
    ]
  }
}

curl -X GET 'https://sdm.smarttalks.ai/v1/intentions/payments/67290a1234567890abcdef01' \
  -H 'Authorization: Bearer SEU_TOKEN_JWT'

# Exportar Dados BI

Exporte dados de pagamento agregados para plataformas de Inteligência de Negócios com múltiplas opções de agrupamento e filtragem.

GET https://sdm.smarttalks.ai/v1/intentions/payments/bi/export

# Parâmetros de Query

Parâmetro Tipo Obrigatório Descrição Padrão
groupBy string Não Como agrupar os dados agregados day
startDate string (ISO 8601) Não Data inicial do intervalo (ex: 2025-11-01T00:00:00Z) -
endDate string (ISO 8601) Não Data final do intervalo (ex: 2025-11-30T23:59:59Z) -
status string Não Filtrar por status do pagamento -
method string Não Filtrar por método de pagamento -
currency string Não Filtrar por moeda -
contactId string Não Filtrar por ID do cliente/contato -
includeDetails boolean Não Incluir registros de pagamento individuais na resposta false
limit number Não Número máximo de registros a retornar 1000

Valores de groupBy:

  • day - Agrupar por dia do calendário
  • week - Agrupar por semana
  • month - Agrupar por mês
  • status - Agrupar por status do pagamento
  • method - Agrupar por método de pagamento
  • currency - Agrupar por moeda

# Resposta (200 - Sucesso)

{
  "status": "ok",
  "result": {
    "summary": {
      "totalRevenue": 1310,
      "totalGrossRevenue": 1310,
      "totalDiscount": 0,
      "totalVoucherDiscount": 0,
      "totalPayments": 21,
      "successCount": 21,
      "failedCount": 0,
      "pendingCount": 0,
      "avgAmount": 62.38,
      "avgInstallments": 0
    },
    "aggregated": [
      {
        "date": "2025-11-07",
        "totalAmount": 5385,
        "totalGrossAmount": 5385,
        "totalDiscount": 0,
        "count": 1,
        "successfulPayments": 1,
        "failedPayments": 0,
        "pendingPayments": 0
      },
      {
        "date": "2025-11-06",
        "totalAmount": 1310,
        "totalGrossAmount": 1310,
        "totalDiscount": 0,
        "count": 20,
        "successfulPayments": 20,
        "failedPayments": 0,
        "pendingPayments": 0
      }
    ],
    "details": null,
    "metadata": {
      "groupBy": "day",
      "format": "json",
      "generatedAt": "2025-11-07T16:00:00.000Z",
      "filters": {
        "status": "completed",
        "method": null,
        "currency": null,
        "contactId": null,
        "dateRange": null
      }
    }
  }
}

curl -X GET 'https://sdm.smarttalks.ai/v1/intentions/payments/bi/export?groupBy=day&startDate=2025-11-01T00:00:00Z&endDate=2025-11-30T23:59:59Z&status=completed' \
  -H 'Authorization: Bearer SEU_TOKEN_JWT'

# Tratamento de Erros

# Formato de Resposta de Erro

Todos os erros são retornados em um formato consistente:

{
  "status": "error",
  "errors": [
    {
      "code": "INVALID_PARAMETER",
      "message": "Parâmetro de query inválido",
      "path": ["startDate"]
    }
  ]
}

# Códigos de Status HTTP Comuns

Status Descrição
200 Sucesso - Solicitação concluída com sucesso
400 Requisição Inválida - Parâmetros inválidos ou solicitação malformada
401 Não Autorizado - Token de autenticação ausente ou inválido
404 Não Encontrado - Pagamento não encontrado
500 Erro Interno do Servidor - Erro no servidor

# Exemplos de Uso

# Exemplo 1: Listar Pagamentos Recentes Concluídos

Obtenha os 10 pagamentos concluídos mais recentes:

curl -X GET 'https://sdm.smarttalks.ai/v1/intentions/payments?limit=10&status=completed&sortOrder=desc' \
  -H 'Authorization: Bearer SEU_TOKEN_JWT'

# Exemplo 2: Filtrar Pagamentos por Método e Status

Obtenha pagamentos feitos com cartão de crédito que estão pendentes:

curl -X GET 'https://sdm.smarttalks.ai/v1/intentions/payments?method=credit_card&status=pending&limit=20' \
  -H 'Authorization: Bearer SEU_TOKEN_JWT'

# Exemplo 3: Obter Resumo de Receita Mensal

Exporte dados de receita agrupados por mês para novembro de 2025:

curl -X GET 'https://sdm.smarttalks.ai/v1/intentions/payments/bi/export?groupBy=month&startDate=2025-11-01T00:00:00Z&endDate=2025-11-30T23:59:59Z' \
  -H 'Authorization: Bearer SEU_TOKEN_JWT'

# Exemplo 4: Obter Detalhes do Pagamento

Recupere detalhes completos de um pagamento específico:

curl -X GET 'https://sdm.smarttalks.ai/v1/intentions/payments/67290a1234567890abcdef01' \
  -H 'Authorization: Bearer SEU_TOKEN_JWT'

# Exemplo 5: Exportar Dados BI Detalhados

Exporte dados agregados incluindo registros de pagamento individuais:

curl -X GET 'https://sdm.smarttalks.ai/v1/intentions/payments/bi/export?groupBy=day&includeDetails=true&limit=1000&startDate=2025-11-01T00:00:00Z&endDate=2025-11-30T23:59:59Z' \
  -H 'Authorization: Bearer SEU_TOKEN_JWT'

# Filtragem e Ordenação

# Filtros Disponíveis

Todos os endpoints de listagem suportam os seguintes filtros:

  • status: Filtrar por status do pagamento (pending, analysis, completed, failed, cancelled, expired, integration_fail)
  • method: Filtrar por método de pagamento (credit_card, debit_card, bank_transfer, cash, apple_pay, google_pay, link, pix)
  • currency: Filtrar por moeda (BRL, USD, EUR, ARC, UYU, PYG)
  • contactId: Filtrar por ID do cliente/contato

# Ordenação

O endpoint de listagem suporta ordenação com os seguintes parâmetros:

  • sortBy: Campo para ordenar (padrão: createdAt)
  • sortOrder: asc (crescente) ou desc (decrescente) - padrão: desc

# Paginação

Use os parâmetros skip e limit para paginação:

  • skip: Número de registros a pular (padrão: 0)
  • limit: Número máximo de registros a retornar (padrão: 10)

# Recursos de Exportação BI

# Opções de Agrupamento

O endpoint de exportação BI suporta múltiplas estratégias de agrupamento:

  • day - Agrupar dados por dia do calendário
  • week - Agrupar dados por semana
  • month - Agrupar dados por mês
  • status - Agrupar dados por status do pagamento
  • method - Agrupar dados por método de pagamento
  • currency - Agrupar dados por moeda

# Capacidades de Exportação

A exportação BI inclui:

  1. Estatísticas de Resumo - Métricas gerais para todo o conjunto de dados
  2. Dados Agregados - Dados agrupados de acordo com o parâmetro groupBy
  3. Registros Detalhados Opcionais - Registros de pagamento individuais (quando includeDetails=true)
  4. Metadados - Informações sobre os parâmetros de exportação e filtros aplicados

# Filtragem por Intervalo de Data

Use o formato ISO 8601 para filtragem de data:

startDate: 2025-11-01T00:00:00Z
endDate: 2025-11-30T23:59:59Z

# Suporte

Para suporte e dúvidas sobre a API de Intenções de Pagamento:

  • Email: api@smarttalks.ai
  • Documentação: Consulte este guia para detalhes dos endpoints e exemplos
Last Updated: 11/10/2025, 3:13:44 PM