By
·
3 minute read
El endpoint /checkout no es solo código; es el momento exacto en que la intención de compra se convierte en ingresos. A continuación, te explicamos cómo escribir una documentación que prevenga errores, gestione pagos de forma segura y garantice una transacción fluida en cada llamada.
El Momento de la Verdad
.svg)
En la arquitectura de cualquier plataforma de e-commerce, el endpoint de checkout (a menudo /v1/orders o /v1/checkout) es el "Money Endpoint".
Es el cuello de botella por el que debe pasar cada euro de facturación. A diferencia de un endpoint GET /products —donde un fallo es simplemente molesto—, un fallo en el checkout es catastrófico. Significa una venta perdida, un cliente frustrado y una marca dañada.
Para los desarrolladores frontend e ingenieros móviles que integran tu API, la documentación del checkout es el manual de desactivación de una bomba. Un cable cortado (parámetro) incorrectamente y todo explota (transacción rechazada).
Esta guía cubre los componentes esenciales que a menudo faltan en la documentación estándar, asegurando que tus integradores puedan construir un flujo de pago robusto y de alta conversión.
El Contexto "Pre-Vuelo" (Autenticación y Estado)
Antes de que un desarrollador mire el cuerpo del JSON, necesita conocer las reglas de combate.
Dependencias de Estado
El checkout rara vez ocurre en el vacío. Tu documentación debe aclarar:
- ¿Se requiere un Cart ID? ¿Puedo llamar a este endpoint con una lista raw de SKUs, o debo crear primero un carrito vía POST /carts?
- Alcance del Token (Scope): ¿El token de API requiere scopes específicos como write:orders o payments?
- Bloqueo de Sesión: ¿Llamar a este endpoint "bloquea" el inventario temporalmente?
Documenta esto: “Nota: Este endpoint requiere un cart_id válido generado en los últimos 30 minutos. El carrito no debe estar vacío.”
El "Contrato" del Payload (Validación y Dependencias)
Una documentación estándar lista campos. Una gran documentación explica relaciones.
Un payload de checkout es complejo. Contiene PII del cliente, direcciones de envío y tokens de pago. La mayor fuente de fricción es la Lógica Condicional.
Manejo de Dependencias entre Campos
Debes documentar explícitamente reglas como:
- Dirección de Facturación: Opcional a menos que el método de pago sea Tarjeta de Crédito (verificación AVS).
- Tax ID: Requerido solo para transacciones B2B o países específicos (ej. el Codice Fiscale en Italia o el CPF en Brasil).
- Teléfono: Requerido para transportistas Express (DHL/FedEx) pero opcional para correo postal estándar.
Idempotencia (La Red de Seguridad)
Este es el concepto técnico más crítico para pagos, y a menudo el gran olvidado en la documentación.
El Escenario: Un usuario móvil en un tren hace clic en "Pagar". El tren entra en un túnel. La solicitud se envía, pero la respuesta se pierde. La app reintenta automáticamente.
- Sin Idempotencia: Al usuario se le cobra dos veces.
- Con Idempotencia: El servidor reconoce la "Clave de Reintento" y devuelve el mensaje de éxito original sin volver a cobrar.
Cómo Documentarlo:
- Define el Header: Indica explícitamente qué cabecera usar (ej. Idempotency-Key o X-Request-ID).
Procesamiento Asíncrono (El Estado "Pendiente")
En el e-commerce moderno, el pago no siempre es instantáneo. Métodos como Buy Now Pay Later (Klarna), SEPA Direct Debit o Cripto toman tiempo.
Tu documentación debe preparar al desarrollador para el limbo del "Pending".
- Respuesta Síncrona: "Tarjeta Aprobada" (200 OK).
- Respuesta Asíncrona: "Pago Iniciado" (202 Accepted). La orden se crea, pero el estado es pending_payment.
- El Relevo del Webhook: Tu documentación debe enlazar a la sección de Webhooks. Explica que para métodos asíncronos, la confirmación final de "Orden Pagada" llegará vía evento (payment.success), no en la respuesta inmediata de la API.
Manejo de Errores Granular (El "Camino Infeliz")
Un 400 Bad Request o 500 Server Error genérico durante el checkout es una pesadilla para soporte. La app cliente necesita saber exactamente qué decirle al usuario.
Tu documentación necesita una Tabla de Códigos de Error dedicada al checkout.
FAQ: Preguntas Frecuentes
¿Cómo manejo el cumplimiento PCI con este endpoint?
La mayoría de las APIs modernas no aceptan números de tarjeta en crudo (RAW). Tu documentación debe explicar que el frontend debe primero tokenizar la tarjeta vía un SDK de Pagos (como Stripe Elements) y enviar solo el payment_token (ej. tok_123) a tu endpoint de checkout. Esto mantiene tu API fuera del alcance PCI.
¿Qué pasa si el inventario se agota durante la llamada de checkout?
Documenta tu lógica de "Condición de Carrera" (Race Condition). Usualmente, la API debería devolver un error 409 Conflict identificando exactamente qué ítem ya no está disponible, permitiendo al frontend actualizar el carrito.
¿Puedo modificar una orden después de que el checkout devuelva éxito?
Generalmente, no. Una vez que /checkout devuelve 201 Created, la orden es inmutable para el cliente. Las modificaciones suelen requerir un endpoint separado /orders/{id}/cancel o intervención de atención al cliente.
No dejes que una mala documentación mate tu conversión
Un checkout sin fricción comienza con un código sin fricción. Al documentar los "caminos infelices" y los flujos asíncronos con claridad, empoderas a los desarrolladores para construir una experiencia de pago en la que los usuarios confían.
¿Necesitas una API de envíos que documente cada caso límite?
👉 Explora la Referencia de API de ShippyPro
ShippyPro es el software de envío completo para el comercio online y offline. Con las funciones Label Creator, Track & Trace, Easy Return y Analytics, nuestro software simplifica sus operaciones de envío. ShippyPro se integra con más de 180 transportistas y 80 canales de venta, por lo que es compatible con una amplia gama de productos y casos de uso.