Documentação da API Cloud2Pdf

Gere PDFs profissionais a partir de HTML com nossa API RESTful

Sobre a API

A Cloud2Pdf API permite que você converta HTML em PDFs de alta qualidade usando uma simples requisição HTTP. Nossa API é baseada em créditos pré-pagos, onde cada PDF gerado consome créditos proporcionais ao tamanho do arquivo.

Seguro

Autenticação via Bearer Token

Rápido

Geração em segundos

Escalável

Rate limits por plano

URL Base

https://api.cloud2pdf.com/v1

Autenticação

A API usa Bearer Token para autenticação. Você precisa criar um token no seu dashboard e incluí-lo no header Authorization de todas as requisições.

Como obter seu token:

Faça login no Dashboard
Vá para API Tokens
Clique em "Gerar Novo Token"
Copie o token gerado (você só verá uma vez!)

Exemplo de requisição autenticada:

                            curl -X POST https://api.cloud2pdf.com/v1/pdf/generate \
  -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  -H "Content-Type: application/json" \
  -d '{"html": "<h1>Hello World</h1>"}'
                        

⚠️: Nunca compartilhe seu token ou o exponha em código cliente (frontend). Mantenha-o seguro no backend.

Sistema de Créditos

Como funciona?

O Cloud2Pdf usa um sistema de créditos pré-pagos. Cada PDF gerado consome créditos baseado no tamanho do arquivo resultante.

Regra de Cálculo:

1 crédito = 0.5 MB de PDF

Exemplos:

• PDF de 500 KB = 1 crédito
• PDF de 1 MB = 2 créditos
• PDF de 2.5 MB = 5 créditos

Recursos de IA

Usuários com planos Pro, Business ou AI+ podem usar recursos de IA sem custo adicional.

Plano Free

❌ Sem recursos de IA

Planos Pro+

✨ IA incluída sem custo extra

Comprar Créditos

Você pode comprar pacotes de créditos diretamente no Dashboard. Os créditos nunca expiram!

Rate Limiting

A API implementa rate limiting baseado no seu plano. Cada plano tem um limite de requisições por minuto para garantir qualidade e disponibilidade do serviço.

Limites por Plano:

Free 10 req/min

Pro 60 req/min

Business 120 req/min

Enterprise 300 req/min

Headers de Response:

Toda requisição retorna headers informativos sobre o rate limit:

                            X-RateLimit-Limit: 60        # Limite total do plano
X-RateLimit-Remaining: 45   # Requisições restantes
X-RateLimit-Reset: 1736423700  # Unix timestamp do próximo reset
                        

Quando o limite é excedido:

Você receberá uma resposta 429 Too Many Requests:

                            {
  "error": "Rate Limit Exceeded",
  "message": "Você excedeu o limite de 60 requisições por minuto. Tente novamente em 32 segundos.",
  "rate_limit": 60,
  "retry_after": 32
}
                        

💡: Implemente exponential backoff em seu código para lidar com rate limits automaticamente.

Endpoints da API

Autenticação

GET /api/auth/google

Inicia o fluxo de autenticação via Google OAuth.

Redireciona para a página de login do Google

GET /api/auth/me

Retorna informações do usuário autenticado.

Resposta (200 OK):

                                {
  "id": 1,
  "name": "João Silva",
  "email": "joao@example.com",
  "plan": {
    "id": 2,
    "name": "Pro",
    "rate_limit": 60
  },
  "credits": 150
}
                            

POST /api/auth/logout

Revoga o token atual e faz logout.

Resposta (200 OK):

                                {
  "success": true,
  "message": "Logged out successfully"
}
                            

PDF

POST /api/pdf/generate

Gera um PDF a partir de HTML com suporte a recursos de IA.

Corpo da Requisição:

                            {
  "html": "<h1>Título</h1><p>Conteúdo</p>",
  "options": {
    "format": "A4",           // A4, Letter, Legal
    "landscape": false,       // true/false
    "margin_top": "20mm",
    "margin_right": "15mm",
    "margin_bottom": "20mm",
    "margin_left": "15mm",
    "print_background": true
  },
  "is_disk": false,           // true = Salva no CDN e retorna link
  "is_ia_resume": false,      // true = Resume o conteúdo antes de gerar PDF
  "is_ia_translate": false,   // true = Traduz antes de gerar
  "translate_language": "en", // en, es, pt, fr, de, it, ja, zh
  "is_ia_correction_gramatical": false  // true = Corrige gramática
}
                        

Resposta (200 OK) - Base64:

                            {
  "success": true,
  "pdf": "JVBERi0xLjQK...",  // Base64 encoded
  "metadata": {
    "id": 123,
    "file_size": 45678,
    "credits_used": 2,
    "balance_remaining": 98,
    "ai_processed": false
  }
}
                        

Resposta (200 OK) - Link CDN (is_disk=true):

                            {
  "success": true,
  "pdf_url": "https://cdn.cloud2pdf.com/pdfs/abc123...",
  "public_link": "https://cloud2pdf.com/l/token123",
  "metadata": {
    "id": 123,
    "file_size": 45678,
    "credits_used": 2,
    "balance_remaining": 98
  }
}
                        

💡: Use is_disk: true para salvar o PDF no CDN. Você receberá um link público com 30 dias de validade.

Erros Possíveis:

• 402 - Créditos insuficientes
• 422 - HTML inválido ou parâmetros incorretos
• 429 - Rate limit excedido

⚡

Geração Assíncrona de PDFs

NOVO - Recomendado para PDFs grandes

🎯 Quando usar?

✅ PDFs grandes (>1MB de HTML ou >1000 páginas)
✅ Processamento com IA (resume, tradução, correção)
✅ Integração com webhooks (receba notificação quando pronto)
✅ Melhor performance (não bloqueia sua aplicação)

💡 Dica: A API assíncrona é mais rápida e confiável para PDFs maiores que 10MB. O sistema detecta automaticamente PDFs grandes e aplica otimizações.

POST /api/pdf/generate-async

Inicia a geração de PDF em background e retorna imediatamente um ID para monitoramento.

Request Body:

                            {
  "html": "<h1>Título</h1><p>Conteúdo</p>",
  "options": {
    "format": "A4",
    "landscape": false,
    "margins": {
      "top": "20mm",
      "right": "15mm",
      "bottom": "20mm",
      "left": "15mm"
    }
  },
  "is_disk": true,              // Recomendado: salvar no CDN
  "reference": "order-12345",   // Opcional: sua referência única
    "webhook_url": "https://seusite.com/webhook/pdf-pronto",
  "is_ia_resume": false,
  "is_ia_translate": false,
  "is_ia_correction_gramatical": false
}
                        

🔑 Webhook: Configure webhook padrão em /tokens; você também pode enviar webhook_url por requisição; se ambos estiverem configurados, envia para ambos.

Response (202 Accepted):

                            {
  "success": true,
  "message": "PDF generation started",
    "pdf_code": "AB12-CD34",
  "job_id": "456",
  "reference": "order-12345",
  "status": "pending",
  "estimated_credits": 3,
    "status_url": "https://api.cloud2pdf.com/v1/pdf/status/AB12-CD34"
}
                        

Exemplo cURL:

                            curl -X POST https://api.cloud2pdf.com/v1/pdf/generate-async \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<h1>Test</h1>",
    "is_disk": true,
    "reference": "test-123"
  }'
                        

GET /api/pdf/status/{pdf_code}

Verifica o status atual da geração do PDF.

Status possíveis:

• pending - Aguardando processamento
• processing - Gerando PDF
• completed - Pronto para download
• failed - Erro na geração

Response (Status: pending/processing):

                            {
  "success": true,
    "pdf_code": "AB12-CD34",
  "job_id": "456",
  "reference": "order-12345",
  "status": "processing",
  "created_at": "2026-01-13T12:00:00Z"
}
                        

Response (Status: completed):

                            {
  "success": true,
    "pdf_code": "AB12-CD34",
  "job_id": "456",
  "reference": "order-12345",
  "status": "completed",
  "created_at": "2026-01-13T12:00:00Z",
  "metadata": {
    "file_size": 17576000,           // 17.5 MB
    "credits_used": 36,
    "balance_remaining": 164
  },
  "public_link": {
    "url": "https://cloud2pdf.com/l/abc123",
    "expires_at": "2026-01-20T12:00:00Z"
  },
    "download_url": "https://api.cloud2pdf.com/v1/pdf/download/AB12-CD34",
  "webhook": {
    "status": "sent",
    "attempts": 1,
    "sent_at": "2026-01-13T12:01:00Z"
  }
}
                        

Exemplo de Polling:

                            // JavaScript
async function waitForPDF(pdfCode) {
  const maxAttempts = 60; // 5 minutos (5s * 60)

  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(
            `https://api.cloud2pdf.com/v1/pdf/status/${pdfCode}`,
      { headers: { 'Authorization': 'Bearer YOUR_TOKEN' } }
    );

        if (response.status === 429) {
            const rateLimitData = await response.json();
            const retryAfter = rateLimitData.retry_after ?? 5;
            await new Promise(r => setTimeout(r, retryAfter * 1000));
            continue;
        }

    const data = await response.json();

    if (data.status === 'completed') {
      return data; // PDF pronto!
    }

    if (data.status === 'failed') {
      throw new Error(data.error);
    }

    await new Promise(r => setTimeout(r, 5000)); // Espera 5s
  }

  throw new Error('Timeout');
}
                        

GET /api/pdf/download/{pdf_code}

Faz download do PDF gerado (binário).

📦 Performance: Para PDFs salvos no CDN (is_disk: true), este endpoint baixa do Bunny CDN, garantindo velocidade máxima.

Response:

• Content-Type: application/pdf
• Content-Disposition: attachment; filename="..."
• Body: PDF binário

Exemplo cURL:

                            curl https://api.cloud2pdf.com/v1/pdf/download/AB12-CD34 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o output.pdf
                        

Exemplo JavaScript:

                            async function downloadPDF(pdfId) {
  const response = await fetch(
    `https://api.cloud2pdf.com/v1/pdf/download/${pdfId}`,
    { headers: { 'Authorization': 'Bearer YOUR_TOKEN' } }
  );

  const blob = await response.blob();
  const url = window.URL.createObjectURL(blob);
  const a = document.createElement('a');
  a.href = url;
  a.download = 'document.pdf';
  a.click();
}
                        

⚡ Dicas de Performance

📊 PDFs Grandes (>20MB)

✅ Sistema detecta HTML >1MB e aplica otimizações automáticas
✅ Testado até 24MB (3000 páginas) - funciona perfeitamente
✅ Timeout configurado para 15 minutos
⏱️ Tempo médio: 10-45 segundos para PDFs de 10-25MB

🎯 Melhores Práticas

1. Sempre use `is_disk: true` para armazenar no CDN
2. Configure webhook ao invés de polling
3. Use `reference` para rastrear seus pedidos
4. Polling: verifique status a cada 5-10 segundos
5. Otimize HTML: remova CSS não utilizado e comprima imagens

🔔 Webhooks

Configure em /tokens:

                                    {
    "event": "pdf.generated",
  "status": "completed",
    "reference": "order-12345",
    "data": {
        "id": 123,
        "status": "completed",
        "file_size": 17576000,
        "credits_used": 36,
        "created_at": "2026-01-13T12:00:00Z",
        "download_url": "..."
    }
}
                                

Headers: X-Webhook-Signature e User-Agent: Cloud2Pdf-Webhook/1.0.

GET /api/pdf/history

Lista o histórico de PDFs gerados.

Parâmetros de Query:

• page - Número da página (padrão: 1)
• per_page - Itens por página (padrão: 20)

Resposta (200 OK):

                            {
  "success": true,
  "pdfs": [
    {
      "id": 123,
      "file_size": 45678,
      "credits_used": 2,
      "status": "success",
      "is_disk": true,
      "public_link": "https://cloud2pdf.com/l/token123",
      "ai_features_used": ["translate"],
      "created_at": "2026-01-02T14:30:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 5,
    "per_page": 20,
    "total": 98
  }
}
                        

GET /api/pdf/stats

Retorna estatísticas de geração de PDFs do usuário.

Resposta (200 OK):

                            {
  "success": true,
  "total_generations": 150,
  "successful": 145,
  "failed": 5,
  "total_credits_used": 320,
  "total_file_size": 5242880,
  "avg_file_size": 35000,
  "recent": [
    {
      "id": 150,
      "file_size": 15234,
      "credits_used": 1,
      "status": "success",
      "created_at": "2026-01-09T10:30:00Z"
    }
  ]
}
                        

Verificação de Documentos

💰 Reduza Custos: Valide documentos antes de enviar para birôs de crédito (Serasa, SPC) ou agências de análise. Economize até 70% em consultas desnecessárias.

POST /api/documents/verify

Analisa documentos (RG, CNH, CPF, comprovantes) com IA e retorna score de risco 0-100. Detecta fraudes, extrai dados via OCR e gera certificado público com QR Code.

Request Body (multipart/form-data):

                                POST /api/documents/verify
Content-Type: multipart/form-data
Authorization: Bearer {token}

document: [arquivo PDF/imagem]
document_type: "RG" // Opcional: RG, CNH, CPF, comprovante_residencia
expires_in_days: 30 // Opcional: validade do certificado (padrão 30)
                            

Response (200 OK):

                                {
  "success": true,
  "verification": {
    "id": 42,
    "risk_score": 15,        // 0-100 (menor = melhor)
    "risk_level": "low",     // low, medium, high, critical
    "risk_message": "Baixo risco de fraude",
    "status": "completed",
    "document_type": "RG",
    "confidence_score": 95.5,

    // Dados extraídos via OCR
    "extracted_data": {
      "nome": "João Silva",
      "cpf": "123.456.789-00",
      "rg": "12.345.678-9",
      "data_nascimento": "01/01/1990"
    },

    // Análise de metadados
    "metadata_analysis": {
      "file_size": 1048576,
      "format": "PDF",
      "creation_date": "2026-01-12",
      "has_suspicious_metadata": false
    },

    // Análise visual com IA
    "visual_analysis": {
      "image_quality": "high",
      "has_tampering_signs": false,
      "text_clarity": "excellent"
    },

    // Indicadores de risco detectados
    "risk_indicators": {
      "low_image_quality": false,
      "suspicious_metadata": false,
      "inconsistent_data": false,
      "duplicated_document": false
    },

    // Certificado público
    "public_code": "A1B2C3D4E5F6...",
    "certificate_hash": "sha256:abc123...",
    "public_verification_url": "https://cloud2pdf.com/verification/A1B2C3D4E5F6",

    // Datas
    "processed_at": "2026-01-12T14:30:00Z",
    "expires_at": "2026-02-11T14:30:00Z",
    "credits_used": 3
  }
}
                            

💡 Custos: 3 créditos por verificação. Compare com R$ 3,50+ por consulta ao Serasa/SPC.

GET /api/documents/verify/{id}

Consulta detalhes de uma verificação específica.

Response (200 OK):

                                {
  "success": true,
  "verification": { /* mesmo formato acima */ }
}
                            

GET /api/documents/verify

Lista todas as verificações com filtros opcionais.

Query Parameters:

GET /api/documents/verify?risk_level=low&status=completed&page=1

Response (200 OK):

                                {
  "success": true,
  "verifications": [
    { /* verificação 1 */ },
    { /* verificação 2 */ }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 3,
    "per_page": 20,
    "total": 45
  }
}
                            

POST /api/documents/{id}/certificate

Gera certificado PDF com QR Code para verificação pública. Ideal para compartilhar com clientes/parceiros sem revelar dados sensíveis.

Response (200 OK - PDF Download):

📄 Certificado Inclui:

✓ QR Code público para validação
✓ Score de risco e nível (sem dados pessoais)
✓ Hash SHA-256 do certificado
✓ Data de processamento e validade
✓ URL de verificação pública

GET /verification/{code}

🌐 Endpoint Público (sem autenticação): Qualquer pessoa pode validar o certificado usando o código público.

Exemplo de URL Pública:


                                    https://cloud2pdf.com/verification/A1B2C3D4E5F6G7H8I9J0

💡 Casos de Uso & Economia

🏦 Fintechs & Bancos

Pré-filtro antes de consultas ao Serasa/SPC. Rejeite documentos suspeitos sem gastar créditos caros.

Economia: R$ 3,50/consulta → R$ 0,10

🏢 RH & Recrutamento

Valide diplomas e certificados automaticamente antes de contratar.

Economia: 2-3 dias → 3 segundos

🛒 E-commerce

Reduza fraudes em compras de alto valor ou crediário.

ROI: 10x em prevenção de fraudes

🏘️ Imobiliárias

Valide comprovantes de renda e residência antes de análise de crédito.

Redução: 70% em consultas

🤖 Validação de PDF com IA

🤖 Detecção de Fraude com IA: Analise PDFs automaticamente para detectar adulterações, modificações não autorizadas e tentativas de falsificação. Disponível nos planos Business, AI+ e Enterprise.

POST /api/pdf/validate

Valida um arquivo PDF usando IA para detectar fraudes, adulterações e manipulações. Retorna score de risco de 0-100 e análise detalhada.

Request Body (multipart/form-data):

                                POST /api/pdf/validate
Content-Type: multipart/form-data
Authorization: Bearer {token}

file: [arquivo PDF]
is_disk: true  // Opcional: salva no CDN (padrão: true)
                            

Response (200 OK):

                                {
  "success": true,
  "message": "PDF enviado para análise com sucesso",
  "data": {
    "validation": {
      "id": 42,
      "file_name": "documento.pdf",
      "file_size": 1048576,
      "status": "completed",        // pending, completed, valid, suspicious, invalid

      // Score de Risco (0-100, menor = melhor)
      "risk_score": 15,
      "risk_level": "low",           // low, medium, high, critical

      // Análise com IA
      "analysis_summary": {
        "ai_findings": [
          "Estrutura do PDF está íntegra",
          "Metadados consistentes com data de criação",
          "Sem sinais de edição incremental suspeita"
        ],
        "ai_recommendations": [
          "Documento aprovado para processamento",
          "Baixo risco de fraude detectado"
        ]
      },

      // Metadados do PDF
      "pdf_metadata": {
        "creator": "Microsoft Word",
        "producer": "Adobe PDF Library",
        "creation_date": "2026-01-10",
        "modification_date": "2026-01-10",
        "page_count": 3
      },

      // CDN Storage
      "is_disk": true,
      "cdn_url": "https://cdn.cloud2pdf.com/validations/abc123.pdf",
      "uuid": "550e8400-e29b-41d4-a716-446655440000",

      // Hash do arquivo original
      "original_hash": "sha256:abc123def456...",

      // Datas
      "created_at": "2026-01-12T14:30:00Z",
      "analysis_completed_at": "2026-01-12T14:30:03Z",

      // Créditos
      "credits_used": 2  // 1 crédito/MB + IA
    }
  }
}
                            

💡 Como funciona:

1. Upload do PDF para CDN seguro
2. Análise de metadados e estrutura do arquivo
3. IA analisa padrões suspeitos e anomalias
4. Geração de score de risco e recomendações

💰 Custos: 1 crédito por MB + análise de IA (variável). Exemplo: PDF de 2MB = ~3 créditos total.

Possíveis Erros:

• 402 - Créditos insuficientes
• 403 - Recurso não disponível no seu plano
• 422 - Arquivo inválido ou muito grande (máx 50MB)
• 429 - Rate limit excedido

GET /api/pdf/validations

Lista todas as validações de PDF com filtros opcionais.

Query Parameters:

GET /api/pdf/validations?status=completed&risk_level=low&page=1

Filtros Disponíveis:

• status - pending, completed, valid, suspicious, invalid
• risk_level - low, medium, high, critical
• page - Número da página (padrão: 1)
• per_page - Itens por página (padrão: 15, máx: 100)

Response (200 OK):

                                {
  "success": true,
  "validations": [
    {
      "id": 42,
      "file_name": "documento.pdf",
      "file_size": 1048576,
      "status": "completed",
      "risk_score": 15,
      "risk_level": "low",
      "cdn_url": "https://cdn.cloud2pdf.com/validations/abc123.pdf",
      "created_at": "2026-01-12T14:30:00Z",
      "analysis_completed_at": "2026-01-12T14:30:03Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 3,
    "per_page": 15,
    "total": 42
  }
}
                            

GET /api/pdf/validate/{id}

Consulta detalhes completos de uma validação específica.

Response (200 OK):

                                {
  "success": true,
  "validation": {
    /* Mesmo formato do POST /api/pdf/validate */
  }
}
                            

GET /api/pdf/validate/{id}/report

Baixa relatório PDF detalhado da validação com análise completa, findings e recomendações.

📄 Relatório Inclui:

✓ Score de risco e nível de confiança
✓ Análise detalhada de metadados
✓ Findings da IA (anomalias detectadas)
✓ Recomendações de ação
✓ Hash SHA-256 do arquivo original
✓ Timestamp de análise

DELETE /api/pdf/validate/{id}

Remove uma validação e seu arquivo do CDN.

Response (200 OK):

                                {
  "success": true,
  "message": "Validação removida com sucesso"
}
                            

💡 Casos de Uso & ROI

📄 Documentos Fiscais

Valide notas fiscais e recibos antes de processar pagamentos. Detecte valores adulterados automaticamente.

ROI: Evite fraudes de R$ 1.000+ com custo de R$ 0,10

📋 Contratos Legais

Verifique integridade de contratos e acordos. Detecte modificações não autorizadas.

Proteção: Evite litígios por documentos adulterados

🏦 Compliance Bancário

Valide extratos e comprovantes em processos de KYC. Reduza risco de lavagem de dinheiro.

Conformidade: Atenda regulações com auditoria completa

🎓 Certificados Acadêmicos

Detecte diplomas e certificados falsos em processos de RH. Validação automática em segundos.

Eficiência: 3 segundos vs 2-3 dias de verificação manual

IA (Inteligência Artificial)

✨ Recursos de IA disponíveis apenas para planos Pro, Business e Enterprise

POST /api/ai/resume

Gera um resumo inteligente do conteúdo fornecido.

Corpo da Requisição:

                                {
  "content": "Texto longo para resumir...",
  "generate_pdf": false  // Opcional: Gera PDF do resumo
}
                            

Response (200 OK):

                                {
  "success": true,
  "data": {
    "text": "Resumo gerado pela IA...",
    "credits_used": 1,
    "pdf_url": null
  }
}
                            

Erros Possíveis:

• 402 - Créditos insuficientes ou plano incompatível
• 400 - Conteúdo inválido (máx 50.000 caracteres)

POST /api/ai/translate

Traduz conteúdo para o idioma desejado usando IA.

Request Body:

                                {
  "content": "Text to translate...",
  "target_language": "pt",  // en, es, pt, fr, de, it, ja, zh
  "generate_pdf": false
}
                            

Idiomas Suportados:

en - Inglês

es - Espanhol

pt - Português

fr - Francês

de - Alemão

it - Italiano

ja - Japonês

zh - Chinês

Response (200 OK):

                                {
  "success": true,
  "data": {
    "text": "Texto traduzido...",
    "source_language": "en",
    "target_language": "pt",
    "credits_used": 2
  }
}
                            

POST /api/ai/grammar-correction

Corrige erros gramaticais e melhora a escrita usando IA.

Request Body:

                                {
  "content": "Texto com erros gramaticais...",
  "language": "pt",  // Idioma do texto
  "generate_pdf": false
}
                            

Response (200 OK):

                                {
  "success": true,
  "data": {
    "text": "Texto corrigido...",
    "corrections_count": 5,
    "credits_used": 1
  }
}
                            

Créditos

GET /api/credits/balance

Retorna o saldo atual de créditos e estatísticas de uso.

Response (200 OK):

                            {
  "success": true,
  "balance": 150,
  "total_purchased": 200,
  "total_used": 50
}
                        

GET /api/credits/history

Retorna o histórico completo de transações de créditos (compras, usos, etc).

Query Parameters:

• limit - Número de transações a retornar (padrão: 50, máx: 200)

Response (200 OK):

                            {
  "success": true,
  "transactions": [
    {
      "id": 456,
      "type": "debit",        // purchase, debit, refund, bonus
      "amount": -2,
      "balance_before": 100,
      "balance_after": 98,
      "reason": "pdf_generation",
      "created_at": "2026-01-09T10:30:00Z"
    },
    {
      "id": 455,
      "type": "purchase",
      "amount": 100,
      "balance_before": 0,
      "balance_after": 100,
      "reason": "purchase_order_123",
      "created_at": "2026-01-08T15:20:00Z"
    }
  ]
}
                        

📊 Tipos de Transação: purchase = Compra de créditos | debit = Uso (PDF/IA) | refund = Reembolso | bonus = Crédito promocional

Checkout

GET /api/packages

Lista todos os pacotes de créditos disponíveis para compra.

Response (200 OK):

                            {
  "success": true,
  "packages": [
    {
      "id": 1,
      "name": "Starter",
      "credits": 100,
      "bonus_credits": 0,
      "total_credits": 100,
      "price": 10.0,
      "price_cents": 1000
    },
    {
      "id": 2,
      "name": "Growth",
      "credits": 500,
      "bonus_credits": 50,
      "total_credits": 550,
      "price": 40.0,
      "price_cents": 4000
    }
  ]
}
                        

POST /api/checkout/create

Cria uma sessão de checkout no Stripe para compra de créditos.

Request Body:

                            {
  "package_id": 2  // ID do pacote de créditos
}
                        

Response (200 OK):

                            {
  "success": true,
  "checkout_url": "https://checkout.stripe.com/pay/cs_test_...",
  "order_id": 789
}
                        

💳 Fluxo de Pagamento:
1. Crie o checkout com este endpoint
2. Redirecione o usuário para checkout_url
3. Após pagamento, Stripe redireciona para success_url
4. Créditos são adicionados automaticamente via webhook

Erros Possíveis:

• 400 - Pacote não disponível
• 404 - Pacote não encontrado
• 500 - Erro ao criar sessão Stripe

GET /api/checkout/order/{orderId}

Verifica o status de um pedido específico.

Response (200 OK):

                            {
  "success": true,
  "order": {
    "id": 789,
    "status": "completed",  // pending, completed, failed, refunded
    "package_name": "Growth",
    "credits": 550,
    "amount": 40.0,
    "created_at": "2026-01-09T10:00:00Z",
    "completed_at": "2026-01-09T10:02:15Z"
  }
}
                        

Status Possíveis:
• pending - Aguardando pagamento
• completed - Pago e créditos adicionados
• failed - Pagamento falhou
• refunded - Reembolsado

Códigos de Erro

Código	Significado	Solução
`401`	Não autenticado	Verifique o token no header Authorization
`402`	Créditos insuficientes	Compre mais créditos no dashboard
`422`	Dados inválidos	Verifique os parâmetros da requisição
`429`	Rate limit excedido	Aguarde antes de fazer nova requisição
`500`	Erro interno	Entre em contato com suporte

Exemplos de Código

JavaScript (Node.js)

                            const axios = require('axios');

async function generatePDF() {
  try {
    const response = await axios.post(
      'https://api.cloud2pdf.com/v1/pdf/generate',
      {
        html: '<h1>Meu Relatório</h1><p>Conteúdo do relatório...</p>',
        options: {
          format: 'A4',
          landscape: false
        }
      },
      {
        headers: {
          'Authorization': 'Bearer SEU_TOKEN',
          'Content-Type': 'application/json'
        }
      }
    );

    // Decodificar base64 e salvar
    const pdfBuffer = Buffer.from(response.data.pdf, 'base64');
    require('fs').writeFileSync('output.pdf', pdfBuffer);

    console.log('PDF gerado! Créditos usados:', response.data.metadata.credits_used);
  } catch (error) {
    if (error.response?.status === 402) {
      console.error('Créditos insuficientes!');
    } else {
      console.error('Erro:', error.message);
    }
  }
}

generatePDF();
                        

Python

                            import requests
import base64

def generate_pdf():
    url = 'https://api.cloud2pdf.com/v1/pdf/generate'
    headers = {
        'Authorization': 'Bearer SEU_TOKEN',
        'Content-Type': 'application/json'
    }
    data = {
        'html': '<h1>Meu Relatório</h1><p>Conteúdo...</p>',
        'options': {
            'format': 'A4',
            'landscape': False
        }
    }

    response = requests.post(url, json=data, headers=headers)

    if response.status_code == 200:
        result = response.json()
        pdf_data = base64.b64decode(result['pdf'])

        with open('output.pdf', 'wb') as f:
            f.write(pdf_data)

        print(f"PDF gerado! Créditos usados: {result['metadata']['credits_used']}")
    elif response.status_code == 402:
        print("Créditos insuficientes!")
    else:
        print(f"Erro: {response.status_code}")

generate_pdf()
                        

PHP

                            <?php
$token = 'SEU_TOKEN';
$url = 'https://api.cloud2pdf.com/v1/pdf/generate';

$data = [
    'html' => '<h1>Meu Relatório</h1><p>Conteúdo...</p>',
    'options' => [
        'format' => 'A4',
        'landscape' => false
    ]
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token,
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 200) {
    $result = json_decode($response, true);
    $pdfData = base64_decode($result['pdf']);
    file_put_contents('output.pdf', $pdfData);
    echo "PDF gerado! Créditos usados: " . $result['metadata']['credits_used'];
} elseif ($httpCode === 402) {
    echo "Créditos insuficientes!";
} else {
    echo "Erro: " . $httpCode;
}
?>
                        