Getnet DocsGetnet Docs

Arquitectura de API Cloud

View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page
Connect to CursorUse these docs in CursorConnect to VS CodeUse these docs in VS Code

Get Smart API Cloud está diseñada para cerrar la brecha entre tu software de gestión basado en la nube y los terminales de pago físicos (TPV-PC). A diferencia de las APIs puramente de comercio electrónico, donde las transacciones ocurren instantáneamente en el navegador, los pagos físicos requieren interacción humana (insertar una tarjeta, introducir un PIN).

Para adaptarse a esto, la API utiliza una arquitectura asíncrona de dos fases. Entender este flujo es esencial para evitar errores comunes de integración, como asumir que una transacción se ha completado al recibir la respuesta HTTP inicial.

Flujo de datos de alto nivel

El ciclo de vida de una transacción involucra a tres partes: tu Aplicación, API Cloud y el Terminal físico.

  1. Iniciación (Síncrona): Tu aplicación envía una petición a la nube.
  2. Procesamiento (Físico): La nube da instrucciones al terminal para que se active. El cliente interactúa con el dispositivo.
  3. Finalización (Asíncrona): La nube notifica a tu aplicación el resultado final.

Fase 1: La petición síncrona

Cuando envías una petición (p. ej., a /pago), API Cloud realiza una comprobación de validación inmediata.

  • Qué ocurre: El sistema verifica tus credenciales, la firma del mensaje y el formato JSON.
  • La respuesta: Recibes una respuesta HTTP 200 OK inmediata con un código de resultado.
  • Concepto crucial: Un código de resultado "0" no significa que el pago esté aprobado. Solo significa “Petición recibida y validada”.
// Example Synchronous Response
{
    "resultado": {
        "codigo": "0" // The command was successfully queued for the terminal.
    }
}

No trates esta respuesta como un recibo. En esta fase, no se ha movido dinero. Es posible que el terminal ni siquiera se haya iluminado todavía. Debes actualizar el estado de tu pedido local a “Pendiente” o “En curso”.

Fase 2: La notificación asíncrona

Una vez completada la fase síncrona, API Cloud envía el comando al ID de terminal específico definido en tu petición.

  1. Interacción: El terminal solicita la acción al usuario. El usuario inserta su tarjeta e introduce su PIN.
  2. Generación de resultados: El terminal comunica el resultado (Aprobada, Denegada, Cancelada) de vuelta a la nube.
  3. Notificación: API Cloud envía una petición POST a la urlNotificacion que definiste en tu petición inicial.

Esta notificación contiene el resultado final de la transacción, incluyendo los códigos de autorización, los datos del recibo y los detalles de la tarjeta.

Respaldo de notificación

El sistema está diseñado para asegurar que recibas el resultado incluso si tu servidor es inaccesible.

  • Canal principal: urlNotificacion (HTTP POST).
  • Canal secundario: Si la llamada a tu URL falla (p. ej., tu servidor está inactivo o devuelve un error), el sistema intenta enviar un correo electrónico a la dirección definida en correoNotificacion.

Requisitos del sistema

Para participar en esta arquitectura, tu integración debe cumplir restricciones específicas definidas en el estándar.

Red y seguridad

  • Protocolo: Todas las conexiones deben estar securizadas mediante TLS 1.2 o superior.
  • Acceso: La conectividad se establece a través de líneas públicas de Internet; no se requieren VPN ni líneas dedicadas para la interfaz REST.
  • Codificación: Todos los datos deben estar codificados en UTF-8.

Restricciones JSON

La API es estricta con respecto a los tipos de datos para garantizar la estabilidad entre los diferentes softwares de los terminales.

  • Sin valores null: Los campos no deben establecerse explícitamente en null nunca. Si un campo es opcional y no tiene valor, debe omitirse por completo del objeto JSON.
  • Minimización: Aunque no se impone estrictamente para el procesamiento (parsing), se recomienda evitar el uso excesivo de espacios en blanco, tabuladores o saltos de línea en los payloads de producción para prevenir problemas en la verificación de la firma.

Próximos pasos