Changelog

v2.0.0 — 2025-05-08

Infraestrutura

• Migração para PostgreSQL: banco de dados migrado de SQLite para PostgreSQL. Campos JSON que eram armazenados como strings (evidenceUrls, events, payload, metadata) agora usam o tipo nativo Json do PostgreSQL.
• Deploy no Railway: configuração railway.toml adicionada. O build usa Nixpacks com npm run build e prisma generate é executado automaticamente no postinstall.
• Health check: novo endpoint GET /api/health retorna { status: "ok", timestamp } usado pelo Railway para monitorar disponibilidade.

API

• Paths corretos: todos os endpoints públicos estão sob /api/v1/ (não /v1/). Base URL: https://api.cyrus.com.br/api/v1.
• Endpoint de payouts: o endpoint de pagamento de saída é POST /api/v1/payouts (não /v1/payments).
• Formato de resposta: respostas retornam JSON direto, sem wrapper { success, data }.
• Status em lowercase: valores de status e type são sempre lowercase (pending, completed, deposit, etc.).
• Prefixo de API Key corrigido: chaves de teste usam sk_test_ (não sk_sandbox_). Chaves de produção continuam com sk_live_.

Webhooks

• Eventos renomeados: os nomes dos eventos foram alinhados ao modelo interno:
  • charge.paid → transaction.completed
  • payment.sent → withdrawal.completed
  • payment.failed → transaction.failed
  • refund.created → chargeback.created
  • refund.completed → chargeback.updated
  • Novos: transaction.created, withdrawal.created
• Gerenciamento pelo painel: webhooks são cadastrados via painel Cyrus, não via API pública.
• Assinatura simplificada: o header X-Cyrus-Signature contém o secret do webhook diretamente para verificação.

Endpoints removidos da API pública v1

Os seguintes endpoints foram removidos por não terem implementação no backend:

• GET /v1/balance (saldo disponível via painel interno)
• GET /v1/charges/:txid (status de cobrança)
• GET /v1/transactions/:id (transação individual)
• GET /v1/payments/:referenceCode (status de pagamento)
• POST /v1/refunds (estornos)
• GET /v1/refunds/:referenceCode (status de estorno)
• POST /GET /DELETE /v1/webhooks (gerenciamento de webhooks)

v1.3.0 — 2024-01-15

Novo

• Estornos parciais: o endpoint POST /v1/refunds passou a aceitar o campo amount para estornos de valor menor que o original.
• Evento chargeback.resolved: novo evento de webhook disparado quando uma disputa é encerrada.
• Campo externalRef nas cobranças: identificador próprio na criação de cobranças e pagamentos.

Melhorias

• Header Retry-After incluído em todas as respostas 429 Too Many Requests.
• Mensagens de erro de validação (422) agora incluem o campo fields com detalhes por campo.

v1.2.0 — 2023-11-20

Novo

• Pagamento via QR Code: novo endpoint POST /v1/payments/qrcode.
• Evento payment.failed: webhook disparado quando um pagamento falha.
• Consulta por TXID: GET /v1/charges/:txid passou a aceitar tanto o TXID PIX quanto o ID interno.

Correções

• Corrigido: cobranças expiradas não disparavam o evento charge.expired.
• Corrigido: campo paidAt podia retornar null mesmo para cobranças completed.

v1.1.0 — 2023-09-05

Novo

• Webhooks: sistema de notificações em tempo real com HMAC-SHA256.
• Ambiente sandbox: suporte completo com processamento automático em ~2–3 segundos.

Melhorias

• Campo netAmount adicionado nas respostas de transação.
• Objeto pagination agora inclui totalPages.

v1.0.0 — 2023-07-10

Lançamento inicial

• GET /v1/balance
• POST /v1/charges e GET /v1/charges/:txid
• POST /v1/payments e GET /v1/payments/:referenceCode
• GET /v1/transactions e GET /v1/transactions/:id
• POST /v1/refunds e GET /v1/refunds/:referenceCode

Política de versionamento

• Mudanças compatíveis (novos campos, novos endpoints, novos eventos) podem ser lançadas sem incremento de versão.
• Mudanças incompatíveis (remoção de campos, alteração de tipos, mudança de comportamento) resultam em nova versão major.
• Versões anteriores são mantidas por no mínimo 12 meses após o lançamento da próxima versão, com aviso prévio de 90 dias.