¿Cómo integrar la API de PayPal?

PayPal es una de las plataformas de pago más utilizadas del mundo, y millones de empresas la usan para cobrar, enviar facturas y controlar su tesorería. Si tu software da servicio a esas empresas, conectarte a PayPal te permite:

• Recuperar facturas, su estado y el detalle de las líneas de forma automática
• Extraer datos de pagos y saldos para la conciliación y el reporting
• Acceder a los datos de productos y catálogo vinculados a las facturas
• Reducir la introducción manual de datos y los errores para tus usuarios

Esta guía explica cómo funciona la API de PayPal, los casos de uso que abre, cómo configurarla y las mejores prácticas que conviene conocer. Y como PayPal está disponible tanto en la API de Pagos unificada como en la API de Facturación unificada de Chift, también te mostramos cómo ahorrarte el trabajo pesado.

¿Qué es la API de PayPal?

PayPal expone una API REST que devuelve JSON y usa los métodos HTTP estándar. En realidad es un conjunto de API organizadas por dominio. Para los casos de uso de facturación y pagos, las más importantes son:

• Invoicing API (v2) (/v2/invoicing/), para buscar, crear y recuperar facturas. A tener en cuenta: listar facturas se hace mediante un endpoint de búsqueda en POST (/v2/invoicing/search-invoices) en lugar de un GET tradicional, una decisión de diseño poco habitual.
• Catalog Products API (v1) (/v1/catalogs/products), para recuperar datos de productos y catálogo.
• Reporting API (v1) (/v1/reporting/balances), utilizada para probar la conexión mediante una comprobación de saldo.
• OAuth2 API (v1) (/v1/oauth2/token), que gestiona la autenticación.

La autenticación funciona con un flujo pseudo-OAuth2. Te autenticas con tu client_id y tu client_secret mediante HTTP Basic Auth para obtener un token Bearer. No hay redirección de autorización del lado del usuario, así que es esencialmente un flujo Client Credentials. Además, PayPal ofrece dos entornos, Sandbox y Producción, con un comportamiento idéntico y que solo se diferencian por la URL base.

Los datos a los que puedes acceder incluyen facturas (con sus estados, importes y líneas), pagos, datos de catálogo y saldos de cuenta. La búsqueda de facturas admite filtros por rango de fechas y por estado, con paginación por página de hasta 100 elementos.

Documentación oficial: developer.paypal.com

{{CTA-1}}

Ejemplos de casos de uso de la integración con la API de PayPal

Conectarte a PayPal abre automatizaciones prácticas para cualquier producto que trabaje con datos financieros. Así es como los editores de software aprovechan los datos de facturas y pagos de PayPal a través de Chift.

Acelerar las decisiones de crédito con datos de facturas y pagos

Las entidades de préstamo a empresas pueden recuperar facturas abiertas, historial de pagos e importes pendientes para evaluar la salud financiera de una empresa en tiempo real. Más datos significan decisiones de crédito más rápidas y mejor fundamentadas, con una respuesta de elegibilidad en menos de un minuto.

Descubre más en el caso de estudio de Defacto.

Ampliar la conectividad de pagos y facturación de las plataformas de precontabilidad

Plataformas de precontabilidad como Inqom se conectan a PayPal junto con decenas de otras herramientas para centralizar sus datos de pagos y facturación. Una sola integración con Chift les permite añadir nuevas fuentes rápidamente, sin construir ni mantener cada conexión por separado.Descubre el caso de estudio: Cómo Inqom amplía rápidamente su conectividad de POS, Facturación y Pagos con Chift.

Seguimiento y previsión de tesorería

Las herramientas de gestión de tesorería pueden recuperar facturas abiertas y el estado de los pagos de PayPal para construir una visión precisa y prospectiva de la posición de caja de una empresa. En cuanto entra un pago, la previsión se actualiza, de modo que tus usuarios siempre ven lo que realmente está entrando.

Para más ejemplos de cómo las integraciones de pagos y facturación pueden mejorar tu producto, explora nuestros casos de estudio de Chift.

Mejores prácticas para la integración con la API de PayPal

Algunos puntos que conviene resolver bien desde el primer día:

• Desarrolla primero en Sandbox. PayPal ofrece un entorno de pruebas completo con cuentas de test. Pasa a Producción solo al lanzar, lo único que cambia es la URL base.
• Gestiona con cuidado el endpoint de búsqueda. Listar facturas implica un POST a /v2/invoicing/search-invoices con los filtros en el cuerpo de la petición, no un simple GET. Pasa siempre total_required=true y total_count_required=true como parámetros para obtener una paginación fiable.
• Anticipa los estados de las facturas. Las facturas de PayPal tienen muchos estados (DRAFT, SENT, SCHEDULED, PAID, UNPAID, PARTIALLY_PAID, CANCELLED, REFUNDED y más). Filtrar por un estado de pago a menudo obliga a consultar varias combinaciones de estados, un simple filtro «unpaid» puede requerir dos llamadas distintas que cubran grupos de estados diferentes.
• Recupera las líneas una a una. El endpoint de búsqueda devuelve resúmenes de facturas, sin el detalle de las líneas. Para obtener los datos completos (líneas, importes, pagos), llama a GET /v2/invoicing/invoices/{id} por cada factura. Tenlo en cuenta al estimar tu consumo de API.
• Revisa los permisos de tu app. Un error 406 casi siempre significa que la funcionalidad Invoicing no está activada en «Apps & Credentials», no que la petición esté mal formada.
• Respeta los límites de peticiones. Mantente por debajo de unas 30 peticiones por segundo, y añade backoff exponencial y caché para volúmenes altos, sobre todo alrededor del endpoint de búsqueda.

Conéctate a PayPal, Stripe, Mollie y muchos más con una sola integración

Construir una conexión directa con PayPal exige tiempo, esfuerzo y mantenimiento continuo, sobre todo cuando también necesitas dar soporte a las demás herramientas de pagos y facturación que usan tus clientes.

Con la API de Pagos unificada y la API de Facturación unificada de Chift, te conectas una sola vez y accedes a PayPal, Stripe, Payplug, Mollie, Axonaut, Qonto, Sellsy y muchos más, a través de un modelo de datos único y coherente.

• Una sola integración para decenas de herramientas de pagos y facturación
• Autenticación, paginación y límites de peticiones gestionados de serie
• Datos unificados y estandarizados
• Sincronización bajo demanda con caché y monitorización avanzada
• Una experiencia fluida para tus usuarios

Las integraciones son nuestro trabajo. Tú tienes cosas mejores que hacer.

Reservar una demo

FAQ de la API de PayPal

¿Qué endpoints incluye la API de PayPal?

A través de Chift, PayPal está disponible en la API de Pagos unificada y la API de Facturación unificada, con un conjunto de endpoints estandarizados, entre los que se incluyen (sin limitarse a):

• Facturas /invoices
• Pagos /payments
• Productos /products
• Saldos /balances

Consulta nuestra documentación de la API de PayPal para ver la lista completa de rutas disponibles.

¿Cuáles son los límites de peticiones de la API de PayPal?

PayPal no publica límites de peticiones detallados por endpoint. La limitación se aplica por app y varía según el endpoint y el historial de la cuenta. La Invoicing API es conocida por ser más restrictiva: un exceso de llamadas al endpoint de búsqueda puede provocar respuestas HTTP 429 (Too Many Requests). Como norma general, mantente por debajo de unas 30 peticiones por segundo, y usa backoff exponencial y caché para cargas elevadas. El conector de Chift se encarga de ello por ti gracias a su capa de caché. Puedes consultar las recomendaciones de PayPal en su referencia sobre rate limiting.

¿Cómo obtengo mis credenciales de la API de PayPal?

En versión corta:

1. Entra en el PayPal Developer Dashboard e inicia sesión con tu cuenta de PayPal Business (o crea una).
2. Abre Apps & Credentials y alterna entre Sandbox y Live según tus necesidades.
3. Haz clic en Create App, dale un nombre y selecciona la cuenta sandbox asociada.
4. Copia tu Client ID (visible) y tu Secret (haz clic en «Show» para mostrarlo).
5. En los ajustes de funcionalidades de la app, asegúrate de que Invoicing esté activado.

Esas son las credenciales que introducirás en tu conexión con Chift. Pronto detallaremos todo el proceso en una guía dedicada.