refactor: improve autopay docs

src/assets/apis/autopay/en.yaml

@@ -9,6 +9,13 @@ paths:
       summary: Get balance
       operationId: post-balance
       parameters:
+        - name: Authorization
+          in: header
+          required: true
+          description: "Basic Auth credentials. Ex: `Basic <base64(client_id:client_secret)>`"
+          schema:
+            type: string
+            example: "Basic YWFiYmNjZGQ..."
         - schema:
             type: string
             example: application/json;charset=UTF-8
@@ -46,7 +53,7 @@ paths:
           application/json:
             schema:
               type: object
-              required: [ auth, reference, id ]
+              required: [ reference, id ]
               properties:
                 reference:
                   type: string
@@ -61,6 +68,13 @@ paths:
       summary: Settle an AutoPay
       operationId: post-settlement
       parameters:
+        - name: Authorization
+          in: header
+          required: true
+          description: "Basic Auth credentials. Ex: `Basic <base64(client_id:client_secret)>`"
+          schema:
+            type: string
+            example: "Basic YWFiYmNjZGQ..."
         - schema:
             type: string
             example: application/json;charset=UTF-8
@@ -976,6 +990,47 @@ components:
           $ref: '../checkout/en.yaml#/components/schemas/AutopayRequest'
           x-conditional:
             - id
+        buyer:
+          $ref: '../checkout/en.yaml#/components/schemas/Person'
+          description: |
+            Data of the **buyer** user, refers to the user who is purchasing a product or service.
+
+            **When creating a session**: Can be sent if you know the user making the purchase, as it helps complete the session information.
+            If this data is sent, the user will have their personal data pre-filled and can change it in Checkout.
+        payer:
+          $ref: '../checkout/en.yaml#/components/schemas/Person'
+          description: |
+            Data of the **payer** user, refers to the owner of the payment method or user who paid the requested amount.
+
+            **When creating a session**: Should only be used when you want to "force" the data of the user who will complete the process.
+            If this data is sent, the user will have their personal data pre-filled but **cannot change it**.
+        fields:
+          $ref: '../checkout/en.yaml#/components/schemas/Fields'
+        paymentMethod:
+          type: string
+          description: |
+            Used to restrict the payment methods available in checkout.
+            Multiple codes can be sent separated by commas.
+            See more at [Payment methods](/checkout/payment-methods)
+
+            Ex: `visa,master,pse`
+          example: visa
+        cancelUrl:
+          type: string
+          description: |
+            Cancel URL, the user is redirected to this URL when they decide not to continue with the process.
+            Occurs when the user clicks on _I do not wish to continue_.
+          example: 'https://commerce.test/cancel'
+        skipResult:
+          type: boolean
+          description: |
+            If `true` is sent, when the user finishes the process the session result page will not be displayed, instead they will be redirected to the `returnUrl`. See more at [Skip result](/checkout/skip-result)
+          default: false
+        noBuyerFill:
+          type: boolean
+          description: |
+            By default, the data sent as `buyer` is pre-filled in the Checkout interface to speed up the payment process, if this parameter is sent as `true` then this pre-filling will not be done.
+          default: false
         ipAddress:
           $ref: '../checkout/en.yaml#/components/schemas/IpAddress'
         userAgent:

src/assets/apis/autopay/es.yaml

@@ -8,6 +8,15 @@ paths:
       summary: Obtener balance
       operationId: post-balance
       parameters:
+        - name: Authorization
+          in: header
+          description: |
+            Credenciales Basic Auth codificadas en Base64.
+            Ejemplo: `Basic <base64(client_id:client_secret)>`
+          required: true
+          schema:
+            type: string
+            example: "Basic YWFiYmNjZGQ..."
         - schema:
             type: string
             example: application/json;charset=UTF-8
@@ -45,7 +54,7 @@ paths:
           application/json:
             schema:
               type: object
-              required: [ auth, reference, id ]
+              required: [ reference, id ]
               properties:
                 reference:
                   type: string
@@ -59,6 +68,15 @@ paths:
       summary: Asentar un AutoPago
       operationId: post-settlement
       parameters:
+        - name: Authorization
+          in: header
+          description: |
+            Credenciales Basic Auth codificadas en Base64.
+            Ejemplo: `Basic <base64(client_id:client_secret)>`
+          required: true
+          schema:
+            type: string
+            example: "Basic YWFiYmNjZGQ..."
         - schema:
             type: string
             example: application/json;charset=UTF-8
@@ -966,6 +984,37 @@ components:
           $ref: '../checkout/es.yaml#/components/schemas/AutopayRequest'
           x-conditional:
             - id
+        buyer:
+          $ref: '../checkout/es.yaml#/components/schemas/Person'
+          description: |
+            Datos del usuario **buyer**, se refiere al usuario que está comprando un producto o servicio.
+        payer:
+          $ref: '../checkout/es.yaml#/components/schemas/Person'
+          description: |
+            Datos del usuario **payer**, se refiere al dueño del medio de pago o usuario que pagó el monto solicitado.
+        fields:
+          $ref: '../checkout/es.yaml#/components/schemas/Fields'
+        paymentMethod:
+          type: string
+          description: |
+            Se usa para restringir los medios de pago disponibles en el checkout.
+            Se pueden enviar múltiples códigos separados por comas.
+          example: visa
+        cancelUrl:
+          type: string
+          description: |
+            URL de cancelación, el usuario es redirigido a esta url cuando decide no continuar con el proceso.
+          example: 'https://commerce.test/cancel'
+        skipResult:
+          type: boolean
+          description: |
+            Si se envía `true`, cuando el usuario finalice el proceso no se mostrará la página de resultado de la sesión, en su lugar será redirigido a la `returnUrl`.
+          default: false
+        noBuyerFill:
+          type: boolean
+          description: |
+            Por defecto, los datos enviados como `buyer` son pre-llenados en la interfaz de Checkout para agilizar el proceso de pago, si este parámetro se envía como `true` entonces no se realizará este pre-llenado.
+          default: false
         ipAddress:
           $ref: '../checkout/es.yaml#/components/schemas/IpAddress'
         userAgent:

src/components/ApiReader.jsx

@@ -16,6 +16,10 @@ const TITLES = {
     es: 'Respuesta',
     en: 'Response',
   },
+  body: {
+    es: 'Cuerpo',
+    en: 'Body',
+  },
   params: {
     es: {
       params: 'Parámetros',
@@ -384,9 +388,11 @@ export const ApiParams = ({ params = [], type = 'params' }) => {
   )
 }
 
-export const ApiRequest = ({ request = {} }) => {
+export const ApiRequest = ({ request = {}, params = [] }) => {
   const { locale } = useLocale()
-  const [selected, setSelected] = useState(0);
+  const [selected, setSelected] = useState(0)
+
+  const headers = params ? params.filter((p) => p.in === 'header') : []
 
   const requestBody =
     request?.content?.['application/json'] ??
@@ -400,7 +406,7 @@ export const ApiRequest = ({ request = {} }) => {
     body = multiBodies[selected]
   }
 
-  if (!body?.properties) {
+  if (!body?.properties && headers.length === 0) {
     return null
   }
 
@@ -421,19 +427,33 @@ export const ApiRequest = ({ request = {} }) => {
         )}
       </div>
 
-      {body.deprecated && (
-        <Note type='warning'>{TITLES.deprecated[locale]}</Note>
-      )}
-
-      {body.description && (
-        <ReactMarkdown>{body.description}</ReactMarkdown>
-      )}
+       {headers.length > 0 && (
+            <div className="mb-6">
+              <ApiParams params={headers} type="header" />
+            </div>
+        )}
 
-      <ApiProperties
-        properties={Object.entries(body?.properties || {})}
-        requireds={body?.required || []}
-        conditionals={body?.['x-conditional'] || []}
-      />
+        {body && (
+            <>
+              {headers.length > 0 && (
+                 <h3>{TITLES.body[locale]}</h3>
+              )}
+
+              {body.deprecated && (
+                <Note type='warning'>{TITLES.deprecated[locale]}</Note>
+              )}
+
+              {body.description && (
+                <ReactMarkdown>{body.description}</ReactMarkdown>
+              )}
+
+              <ApiProperties
+                properties={Object.entries(body?.properties || {})}
+                requireds={body?.required || []}
+                conditionals={body?.['x-conditional'] || []}
+              />
+            </>
+          )}
     </>
   )
 }
@@ -449,7 +469,7 @@ export function ApiReader({ path, method = '', api = {}, type = 'request' }) {
   }
 
   if (type === 'request') {
-    return <ApiRequest request={data.requestBody} />
+    return <ApiRequest request={data.requestBody} params={data.parameters} />
   }
 
   if (type === 'response') {

src/components/AutoPayDocsList.jsx

@@ -0,0 +1,77 @@
+import { ItemList } from '@/components/ItemsList'
+import { useLocalizePath } from '@/hooks/useLocalizePath'
+import { useLocale } from './LocaleProvider'
+
+const guides = [
+  {
+    href: '/autopay',
+    action: { es: 'Ver más', en: 'Learn more' },
+    name: {
+      es: 'Inicio',
+      en: 'Home',
+    },
+    description: {
+      es: 'Conoce AutoPay, sus beneficios y obtén una visión general de su integración.',
+      en: 'Discover AutoPay, its benefits, and a high-level overview of the integration.',
+    },
+  },
+  {
+    href: '/autopay/authentication',
+    action: { es: 'Ver más', en: 'Learn more' },
+    name: {
+      es: 'Integración',
+      en: 'Integration',
+    },
+    description: {
+      es: 'Conoce las capacidades, conceptos y flujos clave de AutoPay para lograr una integración exitosa.',
+      en: 'Learn about AutoPay capabilities, concepts, and key workflows for a successful integration.',
+    },
+  },
+  {
+    href: '/autopay/api/',
+    action: { es: 'Ver más', en: 'Learn more' },
+    name: {
+      es: 'API',
+      en: 'API',
+    },
+    description: {
+      es: 'Consulta en detalle los métodos HTTP disponibles, los parámetros y las posibles respuestas de cada servicio.',
+      en: 'Explore available HTTP methods, parameters, and possible responses for each service in detail.',
+    },
+  },
+  {
+    href: '/autopay/contracts/',
+    action: { es: 'Ver más', en: 'Learn more' },
+    name: {
+      es: 'Contratos',
+      en: 'Contracts',
+    },
+    description: {
+      es: 'Implementa los endpoints necesarios en tu servidor para gestionar balances, confirmaciones de pago y notificaciones.',
+      en: 'Implement the required endpoints on your server to handle balances, payment confirmations, and notifications.',
+    },
+  },
+]
+
+export function AutoPayDocsList() {
+  const { locale } = useLocale()
+  const localizePath = useLocalizePath()
+
+  return (
+    <div className="my-8 xl:max-w-none">
+      <div className="not-prose grid grid-cols-1 gap-8 border-gray-900/5 dark:border-white/5 sm:grid-cols-3">
+        {guides
+          .map((guide) => ({
+            ...guide,
+            href: localizePath(guide.href),
+            name: guide.name[locale],
+            description: guide.description[locale],
+            action: guide.action[locale],
+          }))
+          .map((guide) => (
+            <ItemList key={guide.name} {...guide}></ItemList>
+          ))}
+      </div>
+    </div>
+  )
+}

src/components/AutoPayRequirements.jsx

@@ -0,0 +1,44 @@
+import { ItemList } from '@/components/ItemsList'
+import { useLocale } from './LocaleProvider'
+import { Scroll, UserOctagon } from 'iconsax-react'
+
+const guides = [
+  {
+    name: { es: 'Cuenta de Placetopay', en: 'Placetopay account' },
+    icon: () => <UserOctagon variant="TwoTone"/>,
+    description: {
+      es: 'Debes tener una cuenta activa en PlacetoPay para acceder a tu sitio y tus credenciales API.',
+      en: 'You must have an active account in PlacetoPay to access your site and your API credentials.',
+    },
+  },
+  {
+    name: {
+      es: 'Conocimientos básicos en programación',
+      en: 'Basic programming knowledge',
+    },
+    icon: () => <Scroll variant="TwoTone"/>,
+    description: {
+      es: 'Se recomienda tener conocimientos de desarrollo web y programación, ya que esta documentación se enfoca en la integración de la API de AutoPay con tu aplicación.',
+      en: 'Web development and programming knowledge is recommended, as this documentation focuses on integrating the AutoPay API into your application.',
+    },
+  },
+]
+
+export function AutoPayRequirements() {
+  const { locale } = useLocale()
+  return (
+    <div className="my-8 xl:max-w-none">
+      <div className="not-prose grid grid-cols-1 gap-8 border-gray-900/5 dark:border-white/5 sm:grid-cols-2">
+        {guides
+          .map((guide) => ({
+            ...guide,
+            name: guide.name[locale],
+            description: guide.description[locale],
+          }))
+          .map((guide) => (
+            <ItemList key={guide.name} {...guide} />
+          ))}
+      </div>
+    </div>
+  )
+}