📖 Glosario

Términos comúnes utilizados en la documentación de Corresponsales API.

A

Ambiente (Environment): Espacio aislado donde corre la aplicación. Existen dos: Sandbox (pruebas) y Producción (datos reales).
API-key: Identificador único de la aplicación cliente. Se incluye en el header api-key junto con el JWT para autencar requests.
Auditoría: Registro de todas las operaciones realizadas (quién, cuándo, qué). Todos los requests y responses se almacenan en audit.log con enriptación.
Autenticación: Proceso de verificar la identidad del usuario. En Corresponsales API: JWT Bearer token + API-key.

B

Bearer Token: Token JWT enviado en el header Authorization: Bearer {token}. Válida la identidad del usuario de forma securizada.
Bill / Factura: Documento de cobro emitido por un corresponsal a su cliente. Contiene monto, concepto, vencimiento y estado de pago.
Business Logic: Reglas de negocio codificadas: cuándo se puede consultar una factura, cuándo se puede pagar, restricciones de reversas, etc.

C

Cliente: Aplicación o sistema que consume la API (ej: tu banco, aplicación móvil, sistema backend).
Corresponsal / Correspondencia: Entidad financiera (banco, caja, cooperativa) que actúa como intermediaria en transacciones. Los corresponsales facturan sus servicios.
CORS (Cross-Origin Resource Sharing): Mecanismo de seguridad del navegador. Si consumis la API desde JavaScript en el navegador, CORS debe estar habilitado.
Criptografía / Encriptación: Proceso de convertir datos legibles en código ilegible usando una clave. Los datos sensibles (passwords de BD, payloads) se encriptan con Fernet.

E

Empresa (EmpresaSafe): Entidad corresponsal registrada en el sistema. Cada empresa tiene su propia base de datos SQL Server y conecta via DBConnection.
Endpoint: Ruta de la API con su método (GET, POST, etc.). Ej: POST /corresponsales/api/factura/consulta/
Estado / Status: Condición de un recurso: pendiente, pagado, parcialmente_pagado, cancelado, reversado.

F

Factura (Invoice): Ver "Bill / Factura".
Fernet: Método simétrico de encriptación usado para proteger passwords de BD y payloads de transacciones en reposo.
Filtro (Filter): Criterio opcional para reducir resultados. Ej: filtrar facturas por número, cliente, estado o rango de fechas.
Frecuencia de Rate Limit: Número máximo de requests permitidos en un tiempo determinado. Ej: 100 req/minuto en sandbox, 1000 req/minuto en producción.

H

Header: Metadatos del request HTTP. Incluyen Authorization, api-key, Content-Type.
HTTPS: Protocolo seguro HTTP con cifrado TLS. Obligatorio en todos los requests a la API (en producción).

J

JWT (JSON Web Token): Estándar de token autenticación. Contiene usuario, permisos y expiración codificados en un formato autofirmado. Ej: eyJhbGc...
JSON: Formato de estructura de datos. Todos los requests y responses usan JSON. Ej: {"invoice_id": "2025407608"}

L

Log / Auditoría: Registro de eventos: requests, responses, errores, cambios de estado. Almacenado en audit.log con encriptación Fernet.
Logitud de Token: Duración de validez: JWT access token = 8 horas, refresh token = 9 horas (un solo ciclo de renovación).

M

Método HTTP: Tipo de operación: GET (leer), POST (crear), PUT (actualizar), DELETE (borrar). Corresponsales API solo usa POST.
Monto: Cantidad de dinero en una transacción o factura.
Multi-tenancy: Arquitectura donde múltiples empresas (tenants) comparten la aplicación pero aisladas por base de datos diferente.

O

OWASP Top 10: Lista de las 10 vulnerabilidades web más críticas (SQL injection, XSS, CSRF, etc.). La API es auditada contra estas.
OpenAPI / Swagger: Estándares para documentar APIs de forma automatizada. (Próximamente disponible en Corresponsales API)

P

Parámetro: Valor enviado al servidor: en URL (query parameter), en body (JSON), o en headers.
Pago (Payment): Transacción de cobro de una factura. Notificada via POST /corresponsales/api/factura/pago/.
Permiso (Permission): Autorización para ejecutar una acción. Se define por usuario, endpoint, empresa, y stored procedure.
Payload: Datos del body de un request (el "contenido" que se envía).
Producción: Ambiente donde corren datos reales y transacciones vinculantes. URL: {URL de producción — contacta a tu equipo de operaciones}

R

Rate Limit / Throttling: Límite de requests por hora. 200 requests/hora para usuarios autenticados. Si se excede, retorna error 429 (Too Many Requests).
Request / Request ID: Solicitud enviada a la API. Cada request recibe un ID único (ej: f7002954-8ec2-4248-9c8e-6625a2588117) para rastreo y vinculación de operaciones.
Response: Respuesta que retorna el servidor: datos, estado (OK/ERROR), timestamps.
Refresh Token: Token de corta duración (9 horas) que permite renovar el access token una vez sin reautenticarse. Después de las 9 horas se requiere un nuevo login.
Reversa / Rollback: Operación para deshacer un pago (cancelarlo). Via POST /corresponsales/api/factura/pago/reversar/.
REST: Estilo arquitectónico de API basado en recursos HTTP. Corresponsales API es una REST API.

S

Sandbox / Testing Environment: Ambiente de pruebas con datos ficticios. URL: {URL de sandbox — contacta a tu equipo de operaciones}
Seguridad / Security: Prácticas para proteger datos y APIs: autenticación, autorización, encriptación, validación, auditoría.
Session / Sesión: Período de uso de la API. Comienza con autenticación (obtener JWT) y termina con logout o expiración.
SLA (Service Level Agreement): Garantía de disponibilidad: Sandbox 99%, Producción 99.9%.
SQL Server: Sistema gestor de BD usado por los corresponsales. Conectado via ODBC + pyodbc.
Stored Procedure / SP: Código SQL pre-compilado en la BD. Cada endpoint ejecuta un SP (ej: SP_BILL_QUERY, SP_PAYMENT_NOTIFY).

T

TLS / SSL: Protocolos de seguridad para encriptar comunicaciones HTTPS.
Token: Credencial temporal que identifica al usuario autenticado. Válido por 8 horas (access) o 9 horas (refresh).
Transacción / Transaction: Operación atómica de negocio: consulta, pago, reversa. Registrada y auditada completamente.
Timestamp: Hora exacta de un evento, guardada en formato ISO 8601 (ej: 2026-04-05T14:32:15Z).
Timeout: Tiempo máximo de espera para una respuesta. Si se excede, la API cierra la conexión.

U

UUID / GUID: Identificador único universal. Usado en lugar de IDs secuenciales para evitar enumeración (seguridad).
Usuario (User): Identidad que autentica en la API (username + password). Vinculado a una empresa y un conjunto de permisos.

V

Validación: Verificación de que los datos de input son correctos (formato, rango, requeridos, etc.).
Variable de Entorno: Configuración inyectada al sistema (FERNET_KEY, DB_URL, DEBUG, etc.). Nunca hardcodeada.
Versionado de API: Soporte de múltiples versiones de la API (/v1/, /v2/) para retro-compatibilidad. Actualmente: v1.
Webhook (Futuro): Sistema de notificaciones donde el servidor llama a tu aplicación cuando ocurre un evento. Próximamente en Corresponsales API.

X

XSS (Cross-Site Scripting): Vulnerabilidad donde código JS malicioso se inyecta. La API valida y sanitiza todos los inputs.

Z

ZIP Code / Código Postal: Código geográfico. Puede ser parte de datos de cliente o factura en algunos casos.

Common terms used in Corresponsales API documentation.

A

API-key: Unique identifier of the client application. Included in the api-key header along with JWT to authenticate requests.
Authentication: Process of verifying user identity. In Corresponsales API: JWT Bearer token + API-key.
Authorization: Process of determining what an authenticated user can do. Based on roles, permissions, and endpoints.
Audit Log: Record of all operations performed (who, when, what). All requests and responses are stored in audit.log with encryption.

B

Bearer Token: JWT token sent in the Authorization: Bearer {token} header. Validates user identity securely.
Bill / Invoice: Billing document issued by a correspondent to their client. Contains amount, concept, due date, and payment status.
Business Logic: Coded business rules: when an invoice can be queried, when it can be paid, reversal restrictions, etc.

C

Client: Application or system consuming the API (e.g., your bank, mobile app, backend system).
Correspondent: Financial entity (bank, cooperative, savings fund) that acts as intermediary in transactions. Correspondents bill their services.
CORS (Cross-Origin Resource Sharing): Browser security mechanism. If consuming the API from JavaScript in the browser, CORS must be enabled.
Cryptography / Encryption: Process of converting readable data into unreadable code using a key. Sensitive data (DB passwords, payloads) are encrypted with Fernet.

E

Endpoint: API route with its method (GET, POST, etc.). Ex: POST /corresponsales/api/factura/consulta/
Environment: Isolated space where the application runs. Two exist: Sandbox (testing) and Production (real data).
Error Code: The API identifies errors by HTTP status code + message field. There are no proprietary numeric error codes.

F

Fernet: Symmetric encryption method used to protect DB passwords and transaction payloads at rest.
Filter: Optional criterion to reduce results. Ex: filter invoices by number, client, status, or date range.

H

Header: HTTP request metadata. Include Authorization, api-key, Content-Type.
HTTPS: Secure HTTP protocol with TLS encryption. Required for all API requests (in production).

J

JSON (JavaScript Object Notation): Data structure format. All requests and responses use JSON. Ex: {"invoice_id": "2025407608"}
JWT (JSON Web Token): Authentication token standard. Contains user, permissions, and expiration encoded in a self-signed format. Ex: eyJhbGc...

M

Multi-tenancy: Architecture where multiple companies (tenants) share the application but isolated by different database.
Method (HTTP): Type of operation: GET (read), POST (create), PUT (update), DELETE (delete). Corresponsales API only uses POST.

O

OWASP Top 10: List of 10 most critical web vulnerabilities (SQL injection, XSS, CSRF, etc.). The API is audited against these.

P

Payload: Data in the body of a request (the "content" being sent).
Payment: Transaction that invoices a bill. Notified via POST /corresponsales/api/factura/pago/.
Permission: Authorization to perform an action. Defined by user, endpoint, company, and stored procedure.
Production: Environment where real data and binding transactions run. URL: {URL de producción — contacta a tu equipo de operaciones}

R

Rate Limit / Throttling: Limit of requests per hour. 200 requests/hour for authenticated users. If exceeded, returns error 429 (Too Many Requests).
Refresh Token: Short-duration token (9 hours) that allows renewing the access token once without re-authenticating. After 9 hours a new login is required.
Request / Request ID: Query sent to the API. Each request receives a unique ID (ex: f7002954-8ec2-4248-9c8e-6625a2588117) for tracing and linking operations.
Response: Server response: data, status (OK/ERROR), timestamps.
REST: Architectural style of API based on HTTP resources. Corresponsales API is a REST API.
Reversal / Rollback: Operation to undo a payment (cancel it). Via POST /corresponsales/api/factura/pago/reversar/.

S

Sandbox / Testing Environment: Test environment with fictional data. URL: {URL de sandbox — contacta a tu equipo de operaciones}
Security: Practices to protect data and APIs: authentication, authorization, encryption, validation, audit.
SLA (Service Level Agreement): Availability guarantee: Sandbox 99%, Production 99.9%.
SQL Server: Database management system used by correspondents. Connected via ODBC + pyodbc.
Stored Procedure / SP: Pre-compiled SQL code in the DB. Each endpoint executes a SP (e.g., SP_BILL_QUERY, SP_PAYMENT_NOTIFY).

T

TLS / SSL: Security protocols to encrypt HTTPS communications.
Token: Temporary credential identifying the authenticated user. Valid for 8 hours (access) or 9 hours (refresh, one renewal cycle).
Transaction: Atomic business operation: query, payment, reversal. Fully recorded and audited.
Timestamp: Exact time of an event, stored in ISO 8601 format (ex: 2026-04-05T14:32:15Z).

U

UUID / GUID: Universally unique identifier. Used instead of sequential IDs to prevent enumeration (security).

V

Validation: Verification that input data is correct (format, range, required, etc.).
Versioning (API): Support for multiple API versions (/v1/, /v2/) for backwards compatibility. Currently: v1.

X

XSS (Cross-Site Scripting): Vulnerability where malicious JS code is injected. The API validates and sanitizes all inputs.

📖 Glosario

📖 Glossary

A

B

C

E

F

H

J

L

M

O

P

R

S

T

U

V

X

Z

A

B

C

E

F

H

J

M

O

P

R

S

T

U

V

X