Crystal Dark API - Documentação

🔐 Autenticação

Todas as requisições para a API precisam incluir uma chave de API válida no header < Authorization .

Chave de API:
sk_test_4eC39HqLyjWDarjtT1zdp7dc

    
      curl -H "Authorization: sk_test_4eC39HqLyjWDarjtT1zdp7dc" \
      https://api.syszyra.sbs/api/transaction

Respostas de Autenticação

401 Unauthorized - API key inválida ou ausente

💳 Criar Transação

POST < /api/transaction

Cria uma nova transação na adquirente e retorna o QR Code PIX para pagamento.

Headers Obrigatórios

Header	Valor	Descrição
`Content-Type`	`application/json`	Tipo do conteúdo
`Authorization`	`sk_test_4eC39HqLyjWDarjtT1zdp7dc`	Chave de API

Parâmetros (JSON Body)

Campo	Tipo	Obrigatório	Descrição
`paymentMethod`	string	Sim	Método de pagamento (ex: "pix")
`customer`	object	Sim	Dados do cliente (nome, email, documento, etc)
`items`	array	Sim	Lista de itens da compra
`amount`	integer	Sim	Valor total em centavos (ex: 10000 = R$ 100,00)
`postbackUrl`	string	Sim	URL para receber notificações de webhook
`idSeller`	string	Sim	ID do vendedor
`nameSeller`	string	Não	Nome do vendedor
`emailSeller`	string	Não	Email do vendedor

Exemplo de Requisição

      
        curl -X POST https://api.syszyra.sbs/api/transaction \
        -H "Content-Type: application/json" \
        -H "Authorization: sk_test_4eC39HqLyjWDarjtT1zdp7dc" \
        -d '{
        "paymentMethod": "pix",
        "customer": {
        "name": "João Silva",
        "email": "joao@example.com",
        "document": "12345678900",
        "phone": "11999999999"
        },
        "items": [
        {
        "name": "Produto Teste",
        "quantity": 1,
        "price": 10000
        }
        ],
        "amount": 10000,
        "postbackUrl": "https://seu-site.com/webhook",
        "idSeller": "seller_123",
        "nameSeller": "Loja Teste",
        "emailSeller": "loja@example.com"
        }'

Resposta de Sucesso

201 Created

      
        {
        "status": "waiting_payment",
        "transactionId": "txn_abc123xyz",
        "qrcode": "00020126580014br.gov.bcb.pix..."
        }

Respostas de Erro

400 Bad Request - Campos obrigatórios faltando

401 Unauthorized - API key inválida

500 Internal Server Error - Erro ao processar transação

📋 Listar Transações

GET < /api/transactions

Lista todas as transações cadastradas no sistema com estatísticas.

Exemplo de Requisição

      
        curl -X GET https://api.syszyra.sbs/api/transactions \
        -H "Authorization: sk_test_4eC39HqLyjWDarjtT1zdp7dc"

Resposta de Sucesso

200 OK

      
        {
        "success": true,
        "data": [
        {
        "id": 1,
        "transactionId": "txn_abc123",
        "paymentMethod": "PIX",
        "amount": 10000,
        "paidAmount": 10000,
        "status": "paid",
        "postbackUrl": "https://seu-site.com/webhook",
        "seller": {...},
        "customer": {...},
        "items": [...],
        "pix": {...},
        "createdAt": "2025-01-01T10:00:00Z",
        "paidAt": "2025-01-01T10:05:00Z",
        "reserved": false
        }
        ],
        "statistics": {
        "totalTransactions": 150,
        "totalPaid": 120,
        "totalPending": 25,
        "totalRefunded": 5,
        "totalReserved": 10,
        "amounts": {
        "total": 1500000,
        "paid": 1200000,
        "refunded": 50000,
        "net": 1150000
        }
        }
        }

🔒 Listar Transações Reservadas

GET < /api/reserved-transactions

Lista todas as transações que não tiveram o webhook entregue ao cliente (vendas reservadas).

Importante: Uma transação reservada é aquela onde o webhook falhou ao ser enviado ao cliente. Essas transações ficam marcadas como < reserved = true e podem ser reenviadas manualmente.

Exemplo de Requisição

      
        curl -X GET https://api.syszyra.sbs/api/reserved-transactions \
        -H "Authorization: sk_test_4eC39HqLyjWDarjtT1zdp7dc"

Resposta de Sucesso

200 OK

      
        {
        "success": true,
        "data": [...],
        "statistics": {
        "totalReserved": 10,
        "totalPaidReserved": 8,
        "totalTransactions": 150,
        "totalPaid": 120,
        "percentageReserved": 6.67
        }
        }

🔄 Reenviar Webhook de Transação Reservada

POST < /api/reserved-transactions/:id/resend

Reenvia o webhook de uma transação reservada e marca como não reservada.

Parâmetros de URL

Parâmetro	Tipo	Descrição
`id`	integer	ID da transação a ser reenviada

Exemplo de Requisição

      
        curl -X POST https://api.syszyra.sbs/api/reserved-transactions/123/resend \
        -H "Authorization: sk_test_4eC39HqLyjWDarjtT1zdp7dc"

Resposta de Sucesso

200 OK

      
        {
        "success": true,
        "message": "Webhook reenviado com sucesso",
        "transaction": {
        "id": 123,
        "transactionId": "txn_abc123",
        "status": "paid",
        "reserved": false,
        "webhookSent": true,
        "webhookStatus": 200
        }
        }

Respostas de Erro

400 Bad Request - ID da transação não fornecido

404 Not Found - Transação não encontrada

500 Internal Server Error - Falha ao enviar webhook

🔔 Webhook de Notificação

POST < /api/webhook

Este endpoint recebe notificações da adquirente sobre mudanças de status nas transações.

Uso Interno: Este endpoint é usado pela adquirente para notificar o sistema. Configure a URL < https://api.syszyra.sbs/api/webhook na sua conta da adquirente.

Como Funciona

Adquirente envia notificação para < /api/webhook
Sistema atualiza a transação no banco de dados
Sistema reenvia o webhook para a < postbackUrl do cliente
Se o webhook falhar, a transação é marcada como < reserved = true

Payload Enviado ao Cliente

Quando uma transação muda de status, o sistema envia o seguinte payload para a < postbackUrl configurada:

      
        {
        "id": 123,
        "tenantId": null,
        "companyId": null,
        "amount": 10000,
        "paymentMethod": "PIX",
        "status": "paid",
        "paidAt": "2025-01-01T10:05:00Z",
        "paidAmount": 10000,
        "refundedAt": null,
        "refundedAmount": 0,
        "postbackUrl": "https://seu-site.com/webhook",
        "metadata": null,
        "ip": "192.168.1.1",
        "externalRef": "ref_123",
        "createdAt": "2025-01-01T10:00:00Z",
        "updatedAt": "2025-01-01T10:05:00Z",
        "items": [...],
        "customer": {...},
        "pix": {...},
        "shipping": null
        }

Status Possíveis

Status	Descrição
`waiting_payment`	Aguardando pagamento
`paid`	Pagamento confirmado
`approved`	Pagamento aprovado
`refunded`	Pagamento estornado
`refused`	Pagamento recusado

🏦 Gerenciamento de Adquirentes

GET < /api/acquirer

Lista todas as adquirentes cadastradas e seus status.

      
        curl https://api.syszyra.sbs/api/acquirer \
        -H "Authorization: sk_test_4eC39HqLyjWDarjtT1zdp7dc"

      
        {
        "success": true,
        "data": [
        {"id": 1, "acquirer_type": "medusa",   "is_active": true},
        {"id": 2, "acquirer_type": "pluggou",  "is_active": false},
        {"id": 3, "acquirer_type": "fullpix",  "is_active": false},
        {"id": 4, "acquirer_type": "rapdyn",   "is_active": false},
        {"id": 5, "acquirer_type": "simpay",   "is_active": false},
        {"id": 6, "acquirer_type": "hubpague", "is_active": false}
        ]
        }

GET < /api/acquirer/active

Retorna qual adquirente está ativa no momento.

      
        curl https://api.syszyra.sbs/api/acquirer/active \
        -H "Authorization: sk_test_4eC39HqLyjWDarjtT1zdp7dc"

      
        {
        "success": true,
        "active_acquirer": "medusa"
        }

POST < /api/acquirer/set

Define qual adquirente estará ativa. Apenas uma pode estar ativa por vez.

Adquirentes disponíveis

      
        curl -X POST https://api.syszyra.sbs/api/acquirer/set \
        -H "Content-Type: application/json" \
        -H "Authorization: sk_test_4eC39HqLyjWDarjtT1zdp7dc" \
        -d '{"acquirer_type": "rapdyn"}'

      
        {
        "success": true,
        "message": "Adquirente 'rapdyn' definida como ativa",
        "active_acquirer": "rapdyn"
        }

📦 Regra de Reserva

Controla se o sistema deve reservar transações (não entregar webhook ao cliente) de acordo com a posição no ciclo de vendas.

GET < /api/reservation-rule/status

Retorna se a regra de reserva está ativa.

      
        curl https://api.syszyra.sbs/api/reservation-rule/status \
        -H "Authorization: sk_test_4eC39HqLyjWDarjtT1zdp7dc"

      
        {
        "success": true,
        "reservation_rule_active": true
        }

POST < /api/reservation-rule/activate

Ativa a regra de reserva.

      
        curl -X POST https://api.syszyra.sbs/api/reservation-rule/activate \
        -H "Authorization: sk_test_4eC39HqLyjWDarjtT1zdp7dc"

POST < /api/reservation-rule/deactivate

Desativa a regra de reserva. Todas as transações serão entregues normalmente.

      
        curl -X POST https://api.syszyra.sbs/api/reservation-rule/deactivate \
        -H "Authorization: sk_test_4eC39HqLyjWDarjtT1zdp7dc"

⚡ Força de Reserva

Substitui todas as regras de reserva e força que 100% das transações sejam reservadas. Útil para pausar entregas emergencialmente.

GET < /api/force-reservation/status

      
        curl https://api.syszyra.sbs/api/force-reservation/status \
        -H "Authorization: sk_test_4eC39HqLyjWDarjtT1zdp7dc"

      
        {
        "success": true,
        "force_reservation_active": false,
        "message": "Força de reserva INATIVA"
        }

POST < /api/force-reservation/activate

Ativa a força de reserva. Todas as transações passarão a ser reservadas imediatamente.

      
        curl -X POST https://api.syszyra.sbs/api/force-reservation/activate \
        -H "Authorization: sk_test_4eC39HqLyjWDarjtT1zdp7dc"

POST < /api/force-reservation/deactivate

Desativa a força de reserva. As regras normais voltam a ser aplicadas.

      
        curl -X POST https://api.syszyra.sbs/api/force-reservation/deactivate \
        -H "Authorization: sk_test_4eC39HqLyjWDarjtT1zdp7dc"

⚙️ Reserva Customizada

Permite configurar ciclos de reserva customizados. O padrão do sistema é reservar as posições 9 e 10 de cada grupo de 10 transações.

GET < /api/custom-reservation/config

Retorna a configuração de reserva atual (padrão ou customizada).

      
        curl https://api.syszyra.sbs/api/custom-reservation/config \
        -H "Authorization: sk_test_4eC39HqLyjWDarjtT1zdp7dc"

      
        {
        "success": true,
        "config": {
        "total_transactions": 10,
        "reserved_positions": [9, 10],
        "reserved_count": 2,
        "is_custom": false,
        "description": "Configuração padrão do sistema"
        }
        }

POST < /api/custom-reservation/config

Define uma configuração customizada de reserva.

Parâmetros (JSON Body)

Campo	Tipo	Descrição
`total_transactions`	integer	Tamanho do ciclo (ex: 10 = grupos de 10 transações)
`reserved_positions`	array	Posições a reservar dentro do ciclo (ex: [9, 10])
`description`	string	Descrição opcional da configuração

      
        curl -X POST https://api.syszyra.sbs/api/custom-reservation/config \
        -H "Content-Type: application/json" \
        -H "Authorization: sk_test_4eC39HqLyjWDarjtT1zdp7dc" \
        -d '{
        "total_transactions": 5,
        "reserved_positions": [5],
        "description": "Reservar 1 de cada 5 vendas"
        }'

DELETE < /api/custom-reservation/config

Remove a configuração customizada e volta ao padrão do sistema (10 vendas, reservar posições 9 e 10).

      
        curl -X DELETE https://api.syszyra.sbs/api/custom-reservation/config \
        -H "Authorization: sk_test_4eC39HqLyjWDarjtT1zdp7dc"

GET < /api/custom-reservation/simulate?total_paid=N

Simula como as próximas 20 transações serão tratadas a partir de um número de vendas pagas.

      
        curl "https://api.syszyra.sbs/api/custom-reservation/simulate?total_paid=8" \
        -H "Authorization: sk_test_4eC39HqLyjWDarjtT1zdp7dc"

      
        {
        "success": true,
        "current_config": {
        "total_transactions": 10,
        "reserved_positions": [9, 10],
        "is_custom": false
        },
        "simulation": [
        {"transaction_number": 9,  "position_in_cycle": 9,  "reserved": true,  "reason": "Posição reservada"},
        {"transaction_number": 10, "position_in_cycle": 10, "reserved": true,  "reason": "Posição reservada"},
        {"transaction_number": 11, "position_in_cycle": 1,  "reserved": false, "reason": "Posição normal"},
        ...
        ]
        }

📊 Dashboard

GET < /api/dashboard

Retorna métricas completas de negócio: faturamento do dia, semana e mês, taxa de conversão, transações reservadas e atividades recentes.

      
        curl https://api.syszyra.sbs/api/dashboard \
        -H "Authorization: sk_test_4eC39HqLyjWDarjtT1zdp7dc"

      
        {
        "success": true,
        "data": {
        "today": {
        "total_cents": 150000,
        "total_formatted": "R$ 1.500,00",
        "percentage_change": 12.5,
        "comparison": "increase"
        },
        "week": {
        "total_cents": 980000,
        "total_formatted": "R$ 9.800,00",
        "percentage_change": -3.2,
        "comparison": "decrease"
        },
        "gross_month": {
        "total_cents": 3200000,
        "total_formatted": "R$ 32.000,00"
        },
        "active_acquirers": 1,
        "conversion_rate": {
        "rate": 78.5,
        "total_transactions": 200,
        "successful_transactions": 157
        },
        "reserved": {
        "today":  {"total_cents": 20000, "total_formatted": "R$ 200,00"},
        "week":   {"total_cents": 80000, "total_formatted": "R$ 800,00"},
        "month":  {"total_cents": 300000, "total_formatted": "R$ 3.000,00"}
        },
        "recent_activities": [...]
        }
        }

🛠️ Códigos de Status HTTP

Código	Significado	Descrição
200	OK	Requisição bem-sucedida
201	Created	Transação criada com sucesso
400	Bad Request	Parâmetros inválidos ou faltando
401	Unauthorized	API key inválida ou ausente
404	Not Found	Recurso não encontrado
500	Internal Server Error	Erro no servidor

💡 Exemplo Completo — Criar e Processar Transação

1. Criar transação PIX

      
        curl -X POST https://api.syszyra.sbs/api/transaction \
        -H "Content-Type: application/json" \
        -H "Authorization: sk_test_4eC39HqLyjWDarjtT1zdp7dc" \
        -d '{
        "paymentMethod": "pix",
        "customer": {
        "name": "João Silva",
        "email": "joao@example.com",
        "document": "12345678900"
        },
        "items": [{"name": "Produto", "quantity": 1, "price": 10000}],
        "amount": 10000,
        "postbackUrl": "https://seu-site.com/webhook",
        "idSeller": "seller_123"
        }'

2. Cliente paga o PIX

O cliente escaneia o QR Code e realiza o pagamento.

3. Receber notificação

Seu endpoint em < postbackUrl receberá:

      
        POST https://seu-site.com/webhook
        {
        "status": "paid",
        "transactionId": "txn_abc123",
        "amount": 10000,
        "paidAmount": 10000,
        "paidAt": "2025-01-01T10:05:00Z",
        ...
        }

4. Verificar transações reservadas

      
        # Listar transações que falharam no webhook
        curl https://api.syszyra.sbs/api/reserved-transactions \
        -H "Authorization: sk_test_4eC39HqLyjWDarjtT1zdp7dc"
        
        # Reenviar webhook de uma transação específica
        curl -X POST https://api.syszyra.sbs/api/reserved-transactions/123/resend \
        -H "Authorization: sk_test_4eC39HqLyjWDarjtT1zdp7dc"

📞 Suporte

Para dúvidas ou suporte técnico, entre em contato:

Email: suporte@syszyra.sbs
Documentação: < href="/" Syszyra API Docs
Status da API: Operacional ✅

Syszyra API

🔐 Autenticação

Respostas de Autenticação

💳 Criar Transação

Headers Obrigatórios

Parâmetros (JSON Body)

Exemplo de Requisição

Resposta de Sucesso

Respostas de Erro

📋 Listar Transações

Exemplo de Requisição

Resposta de Sucesso

🔒 Listar Transações Reservadas

Exemplo de Requisição

Resposta de Sucesso

🔄 Reenviar Webhook de Transação Reservada

Parâmetros de URL

Exemplo de Requisição

Resposta de Sucesso

Respostas de Erro

🔔 Webhook de Notificação

Como Funciona

Payload Enviado ao Cliente

Status Possíveis

🏦 Gerenciamento de Adquirentes

Adquirentes disponíveis

📦 Regra de Reserva

⚡ Força de Reserva

⚙️ Reserva Customizada

Parâmetros (JSON Body)

📊 Dashboard

🛠️ Códigos de Status HTTP

💡 Exemplo Completo — Criar e Processar Transação

1. Criar transação PIX

2. Cliente paga o PIX

3. Receber notificação

4. Verificar transações reservadas

📞 Suporte