/
home
/
suroeste
/
public_html
/
payments.transportessuroeste.com
/
docs
/
/home/suroeste/public_html/payments.transportessuroeste.com/docs
mkdir
upload
Name
Size
Mode
Actions
DIAGRAMAS.html
27426
0644
edit
dl
rm
DOCUMENTACION.html
16050
0644
edit
dl
rm
DOCUMENTACION_FUNCIONAL.md
34232
0644
edit
dl
rm
Edit:
/home/suroeste/public_html/payments.transportessuroeste.com/docs/DOCUMENTACION.html
(16050B)
<!DOCTYPE html> <html lang="es"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>Transportes Suroeste - API de Pagos</title> <style> :root { --primary: #1e40af; --secondary: #059669; --danger: #dc2626; --bg: #f8fafc; --card: #fff; --text: #1e293b; --border: #e2e8f0; } * { margin: 0; padding: 0; box-sizing: border-box; } body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: var(--bg); color: var(--text); line-height: 1.6; } .container { max-width: 1100px; margin: 0 auto; padding: 0 20px; } header { background: linear-gradient(135deg, var(--primary), #1e3a8a); color: #fff; padding: 50px 0; text-align: center; } header h1 { font-size: 2.2rem; margin-bottom: 10px; } nav { background: var(--card); border-bottom: 1px solid var(--border); position: sticky; top: 0; z-index: 100; } nav ul { display: flex; list-style: none; overflow-x: auto; } nav a { display: block; padding: 15px 18px; color: var(--text); text-decoration: none; font-weight: 500; border-bottom: 3px solid transparent; } nav a:hover { color: var(--primary); border-color: var(--primary); } main { padding: 30px 0; } section { background: var(--card); border-radius: 10px; padding: 25px; margin-bottom: 25px; box-shadow: 0 1px 3px rgba(0,0,0,0.1); } h2 { color: var(--primary); font-size: 1.6rem; margin-bottom: 15px; border-bottom: 2px solid var(--border); padding-bottom: 10px; } h3 { margin: 20px 0 10px; font-size: 1.2rem; } pre { background: #1e293b; color: #e2e8f0; padding: 15px; border-radius: 8px; overflow-x: auto; font-size: 0.85rem; margin: 15px 0; } code { background: #f1f5f9; color: var(--primary); padding: 2px 6px; border-radius: 4px; font-size: 0.9em; } pre code { background: none; color: inherit; padding: 0; } table { width: 100%; border-collapse: collapse; margin: 15px 0; } th, td { padding: 10px 12px; text-align: left; border-bottom: 1px solid var(--border); } th { background: var(--bg); font-weight: 600; } .badge { display: inline-block; padding: 3px 8px; border-radius: 4px; font-size: 0.75rem; font-weight: 600; } .badge-get { background: #dbeafe; color: #1e40af; } .badge-post { background: #dcfce7; color: #166534; } .alert { padding: 12px 15px; border-radius: 6px; margin: 15px 0; border-left: 4px solid; } .alert-info { background: #eff6ff; border-color: var(--primary); } .alert-warning { background: #fffbeb; border-color: #d97706; } .endpoint { border: 1px solid var(--border); border-radius: 8px; margin: 15px 0; } .endpoint-header { background: var(--bg); padding: 12px 15px; display: flex; align-items: center; gap: 12px; border-bottom: 1px solid var(--border); } .endpoint-body { padding: 15px; } ul, ol { margin: 10px 0 10px 25px; } li { margin-bottom: 6px; } .grid { display: grid; gap: 15px; grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); } footer { background: #1e293b; color: #fff; padding: 30px 0; text-align: center; margin-top: 30px; } .str { color: #a5d6ff; } .num { color: #79c0ff; } .kw { color: #ff7b72; } .cm { color: #8b949e; } </style> </head> <body> <header> <div class="container"> <h1>🚌 Transportes Suroeste</h1> <p>API de Pasarela de Pagos con ePayco | v1.0.0</p> </div> </header> <nav> <div class="container"> <ul> <li><a href="#inicio">Inicio</a></li> <li><a href="#auth">Autenticación</a></li> <li><a href="#endpoints">Endpoints</a></li> <li><a href="#integracion">Integración</a></li> <li><a href="#seguridad">Seguridad</a></li> <li><a href="#errores">Errores</a></li> <li><a href="#db">Base de Datos</a></li> <li><a href="#install">Instalación</a></li> </ul> </div> </nav> <main class="container"> <section id="inicio"> <h2>📋 Introducción</h2> <p>API REST para procesar pagos de tickets de autobús mediante ePayco. Implementa estándares bancarios de seguridad.</p> <div class="grid"> <div> <h3>Características</h3> <ul> <li>✅ Cifrado AES-256-GCM</li> <li>✅ Autenticación API Key + HMAC</li> <li>✅ Rate Limiting Anti-DDoS</li> <li>✅ Protección SQL Injection/XSS</li> <li>✅ Webhooks para notificaciones</li> <li>✅ Auditoría completa</li> </ul> </div> <div> <h3>URLs Base</h3> <table> <tr><th>Entorno</th><th>URL</th></tr> <tr><td>Producción</td><td><code>https://api.transportessuroeste.com</code></td></tr> <tr><td>Sandbox</td><td><code>https://sandbox.transportessuroeste.com</code></td></tr> </table> </div> </div> </section> <section id="auth"> <h2>🔐 Autenticación</h2> <p>Incluir estos headers en cada petición:</p> <table> <tr><th>Header</th><th>Descripción</th><th>Requerido</th></tr> <tr><td><code>X-API-Key</code></td><td>API Key proporcionada</td><td>✅ Sí</td></tr> <tr><td><code>X-Timestamp</code></td><td>Unix timestamp actual</td><td>⚠️ Recomendado</td></tr> <tr><td><code>X-Signature</code></td><td>Firma HMAC-SHA512</td><td>⚠️ Recomendado</td></tr> </table> <h3>Generar Firma</h3> <pre><code><span class="cm">// PHP</span> $dataToSign = <span class="str">"{$method}\n{$uri}\n{$timestamp}\n{$body}"</span>; $signature = hash_hmac(<span class="str">'sha512'</span>, $dataToSign, $apiSecret);</code></pre> </section> <section id="endpoints"> <h2>📡 Endpoints</h2> <div class="endpoint"> <div class="endpoint-header"> <span class="badge badge-post">POST</span> <code>/api/v1/payments</code> - Crear transacción </div> <div class="endpoint-body"> <pre><code><span class="cm">// Request</span> { <span class="str">"ticket_reference"</span>: <span class="str">"TK-2024-001234"</span>, <span class="str">"amount"</span>: <span class="num">45000</span>, <span class="str">"description"</span>: <span class="str">"Ticket Medellín-Bogotá | Asiento 12A"</span>, <span class="str">"payer_email"</span>: <span class="str">"cliente@email.com"</span>, <span class="str">"payer_name"</span>: <span class="str">"Juan Pérez"</span>, <span class="str">"payer_document_type"</span>: <span class="str">"CC"</span>, <span class="str">"payer_document"</span>: <span class="str">"1234567890"</span>, <span class="str">"extra_data"</span>: { <span class="str">"route"</span>: <span class="str">"MDE-BOG"</span>, <span class="str">"seat"</span>: <span class="str">"12A"</span> } } <span class="cm">// Response 201</span> { <span class="str">"success"</span>: <span class="kw">true</span>, <span class="str">"data"</span>: { <span class="str">"transaction_uuid"</span>: <span class="str">"f47ac10b-58cc-4372-a567-0e02b2c3d479"</span>, <span class="str">"internal_reference"</span>: <span class="str">"TS20241215A1B2C3D4"</span>, <span class="str">"status"</span>: <span class="str">"pending"</span>, <span class="str">"payment_url"</span>: <span class="str">"https://api.../payment/f47ac10b..."</span> } }</code></pre> <h4>Parámetros</h4> <table> <tr><th>Campo</th><th>Tipo</th><th>Descripción</th></tr> <tr><td>ticket_reference</td><td>string</td><td>Referencia única del ticket (máx 100)</td></tr> <tr><td>amount</td><td>integer</td><td>Monto en COP (sin decimales)</td></tr> <tr><td>payer_email</td><td>string</td><td>Email del pagador</td></tr> <tr><td>payer_name</td><td>string</td><td>Nombre completo</td></tr> <tr><td>payer_document_type</td><td>string</td><td>CC, CE, NIT, PP, TI</td></tr> <tr><td>payer_document</td><td>string</td><td>Número de documento</td></tr> </table> </div> </div> <div class="endpoint"> <div class="endpoint-header"> <span class="badge badge-get">GET</span> <code>/api/v1/payments/{uuid}</code> - Consultar transacción </div> </div> <div class="endpoint"> <div class="endpoint-header"> <span class="badge badge-get">GET</span> <code>/api/v1/payments/ticket/{reference}</code> - Consultar por ticket </div> </div> <div class="endpoint"> <div class="endpoint-header"> <span class="badge badge-get">GET</span> <code>/api/v1/health</code> - Health check (sin auth) </div> </div> </section> <section id="integracion"> <h2>🔗 Guía de Integración</h2> <h3>Ejemplo Completo PHP</h3> <pre><code><span class="kw"><?php</span> $apiUrl = <span class="str">'https://api.transportessuroeste.com'</span>; $apiKey = <span class="str">'ts_live_xxxxxxxx'</span>; $apiSecret = <span class="str">'your_secret'</span>; <span class="kw">function</span> createPayment($ticket) { <span class="kw">global</span> $apiUrl, $apiKey, $apiSecret; $body = json_encode([ <span class="str">'ticket_reference'</span> => $ticket[<span class="str">'id'</span>], <span class="str">'amount'</span> => $ticket[<span class="str">'price'</span>], <span class="str">'description'</span> => <span class="str">"Ticket {$ticket['route']}"</span>, <span class="str">'payer_email'</span> => $ticket[<span class="str">'email'</span>], <span class="str">'payer_name'</span> => $ticket[<span class="str">'name'</span>], <span class="str">'payer_document_type'</span> => <span class="str">'CC'</span>, <span class="str">'payer_document'</span> => $ticket[<span class="str">'document'</span>] ]); $timestamp = time(); $signature = hash_hmac(<span class="str">'sha512'</span>, <span class="str">"POST\n/api/v1/payments\n{$timestamp}\n{$body}"</span>, $apiSecret); $ch = curl_init($apiUrl . <span class="str">'/api/v1/payments'</span>); curl_setopt_array($ch, [ CURLOPT_POST => <span class="kw">true</span>, CURLOPT_POSTFIELDS => $body, CURLOPT_RETURNTRANSFER => <span class="kw">true</span>, CURLOPT_HTTPHEADER => [ <span class="str">'Content-Type: application/json'</span>, <span class="str">'X-API-Key: '</span> . $apiKey, <span class="str">'X-Timestamp: '</span> . $timestamp, <span class="str">'X-Signature: '</span> . $signature ] ]); <span class="kw">return</span> json_decode(curl_exec($ch), <span class="kw">true</span>); } <span class="cm">// Uso</span> $result = createPayment([ <span class="str">'id'</span> => <span class="str">'TK-001'</span>, <span class="str">'price'</span> => <span class="num">45000</span>, <span class="str">'route'</span> => <span class="str">'MDE-BOG'</span>, <span class="str">'email'</span> => <span class="str">'cliente@mail.com'</span>, <span class="str">'name'</span> => <span class="str">'Juan'</span>, <span class="str">'document'</span> => <span class="str">'123456'</span> ]); header(<span class="str">'Location: '</span> . $result[<span class="str">'data'</span>][<span class="str">'payment_url'</span>]);</code></pre> <h3>Webhook de Notificación</h3> <pre><code><span class="kw"><?php</span> <span class="cm">// webhook.php</span> $payload = file_get_contents(<span class="str">'php://input'</span>); $signature = $_SERVER[<span class="str">'HTTP_X_WEBHOOK_SIGNATURE'</span>]; <span class="kw">if</span> (!hash_equals(hash_hmac(<span class="str">'sha512'</span>, $payload, $webhookSecret), $signature)) { http_response_code(<span class="num">401</span>); exit; } $data = json_decode($payload, <span class="kw">true</span>); <span class="kw">if</span> ($data[<span class="str">'status'</span>] === <span class="str">'approved'</span>) { markTicketAsPaid($data[<span class="str">'ticket_reference'</span>]); } http_response_code(<span class="num">200</span>);</code></pre> </section> <section id="seguridad"> <h2>🛡️ Seguridad</h2> <div class="alert alert-info"><strong>Estándares:</strong> PCI-DSS, ISO 27001, OWASP Top 10</div> <table> <tr><th>Amenaza</th><th>Protección</th></tr> <tr><td>SQL Injection</td><td>Prepared Statements PDO</td></tr> <tr><td>XSS</td><td>Sanitización + CSP Headers</td></tr> <tr><td>DDoS</td><td>Rate Limit 100 req/min + Bloqueo automático</td></tr> <tr><td>MITM</td><td>TLS 1.3 + HSTS</td></tr> <tr><td>Data Breach</td><td>AES-256-GCM para datos sensibles</td></tr> </table> </section> <section id="errores"> <h2>⚠️ Códigos de Error</h2> <table> <tr><th>Código</th><th>Tipo</th><th>Descripción</th></tr> <tr><td>400</td><td>Bad Request</td><td>Petición malformada</td></tr> <tr><td>401</td><td>Unauthorized</td><td>API Key inválida</td></tr> <tr><td>403</td><td>Forbidden</td><td>IP no autorizada</td></tr> <tr><td>404</td><td>Not Found</td><td>Recurso no encontrado</td></tr> <tr><td>422</td><td>Validation Error</td><td>Datos inválidos</td></tr> <tr><td>429</td><td>Rate Limited</td><td>Límite excedido</td></tr> <tr><td>500</td><td>Server Error</td><td>Error interno</td></tr> </table> </section> <section id="db"> <h2>🗄️ Base de Datos</h2> <h3>Tablas Principales</h3> <ul> <li><strong>api_clients</strong> - Clientes autorizados</li> <li><strong>transactions</strong> - Transacciones de pago</li> <li><strong>transaction_status_history</strong> - Historial de estados</li> <li><strong>audit_trail</strong> - Auditoría del sistema</li> <li><strong>security_events</strong> - Eventos de seguridad</li> <li><strong>rate_limit_tracking</strong> - Control anti-DDoS</li> <li><strong>webhook_deliveries</strong> - Entregas de webhooks</li> </ul> <p>Ver archivo <code>sql/database.sql</code> para el esquema completo.</p> </section> <section id="install"> <h2>⚙️ Instalación</h2> <h3>Requisitos</h3> <ul> <li>PHP 8.1+ con extensiones: pdo_mysql, openssl, mbstring, curl, json</li> <li>MySQL 8.0+ o MariaDB 10.5+</li> <li>Composer 2.0+</li> <li>Apache 2.4+ o Nginx 1.18+</li> </ul> <h3>Pasos de Instalación</h3> <pre><code><span class="cm"># 1. Instalar PHP y extensiones (Ubuntu)</span> sudo apt install php8.1 php8.1-mysql php8.1-curl php8.1-mbstring php8.1-xml <span class="cm"># 2. Instalar Composer</span> curl -sS https://getcomposer.org/installer | php sudo mv composer.phar /usr/local/bin/composer <span class="cm"># 3. Clonar e instalar</span> cd /var/www git clone [repo] payment-gateway && cd payment-gateway composer install --no-dev <span class="cm"># 4. Configurar</span> cp config/.env.example config/.env nano config/.env <span class="cm"># Editar credenciales ePayco</span> <span class="cm"># 5. Base de datos</span> mysql -u root -p < sql/database.sql <span class="cm"># 6. Permisos</span> chmod 755 logs && chmod 644 config/.env <span class="cm"># 7. Probar</span> php -S localhost:8000 -t public</code></pre> <div class="alert alert-warning"> <strong>⚠️ Producción:</strong> Usar HTTPS, credenciales reales de ePayco, claves únicas de cifrado, backups automáticos. </div> </section> </main> <footer> <div class="container"> <p><strong>Transportes Suroeste</strong> - API de Pagos v1.0.0</p> <p>© 2024 - Estándares PCI-DSS | ISO 27001</p> </div> </footer> </body> </html>
Save
cmd:
run