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:
Entre em contato para obter sua chave de API

    
      curl -H "Authorization: SUA_CHAVE_DE_API" \
      https://crystaldark.online/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`	`SUA_CHAVE_DE_API`	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://crystaldark.online/api/transaction \
        -H "Content-Type: application/json" \
        -H "Authorization: SUA_CHAVE_DE_API" \
        -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://crystaldark.online/api/transactions

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://crystaldark.online/api/reserved-transactions

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://crystaldark.online/api/reserved-transactions/123/resend

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. Você deve configurar a URL < https://crystaldark.online/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

🛠️ 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

💡 Exemplos de Integração

Exemplo Completo - Criar e Processar Transação

1. Criar transação PIX

      
        # Criar transação
        curl -X POST https://crystaldark.online/api/transaction \
        -H "Content-Type: application/json" \
        -H "Authorization: SUA_CHAVE_DE_API" \
        -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"
        }'
        
        # Resposta:
        # {
        #   "status": "waiting_payment",
        #   "transactionId": "txn_abc123",
        #   "qrcode": "00020126580014br.gov.bcb.pix..."
        # }

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://crystaldark.online/api/reserved-transactions
        
        # Reenviar webhook de uma transação específica
        curl -X POST https://crystaldark.online/api/reserved-transactions/123/resend

📞 Suporte

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

Email: suporte@crystaldark.online
Documentação: < href="/" Crystal Dark API Docs
Status da API: Operacional ✅