Integración vía API

Guía de integración para ecommerce

Índice

Introducción

Esta guía describe cómo integrar tu ecommerce directamente con PuntoPost a través de nuestra API de merchant. Está pensada para comercios que gestionan su propia plataforma o que no utilizan Shopify o WooCommerce (para los que ofrecemos plugin de Shopify y plugin de WooCommerce).

La integración se organiza en unos pocos pasos secuenciales que cubren todo el ciclo de vida de un envío: validar cobertura, mostrar los puntos disponibles a tu cliente, crear el envío, gestionarlo y recibir actualizaciones automáticas de estado.

Todos los ejemplos concretos de request y response, así como el listado completo de campos, se encuentran en la documentación técnica de la API. Esta guía te acompaña en el orden en el que tienes que utilizarlos.

Requisitos previos

Antes de comenzar la integración necesitas:

  • Contactar con PuntoPost para dar de alta tu comercio en la plataforma.
  • Recibir tu Merchant ID y las credenciales del usuario merchant que utilizarás para autenticarte.
  • Confirmar con tu contacto de PuntoPost el tipo o tipos de envío que utilizará tu comercio (B2C, C2C o C2B) para que queden habilitados.
  • Definir la URL pública de tu webhook si vas a recibir eventos de cambios de estado.

Si aún no dispones de credenciales, escríbenos a [email protected] y te acompañamos en el proceso de alta.

Autenticación

Todas las llamadas a la API se autentican mediante un token JWT que se envía en la cabecera Authorization como Bearer. El token se obtiene iniciando sesión con las credenciales del usuario merchant.

Endpoints implicados:

  • POST /api/v1/auth/login — obtención del token de acceso.

Guarda el token de forma segura y rótalo de acuerdo con tus políticas internas.

1. Validar cobertura

Antes de ofrecer PuntoPost como opción de envío en tu checkout, comprueba que el código postal del cliente está dentro de nuestra red. Consideramos que un código postal tiene cobertura cuando existe un punto de recogida a menos de 3 km.

Tienes dos formas de trabajar con la cobertura:

  • Consulta puntual: GET /api/merchant/v1/coverage/{postalCode} — devuelve si un código postal concreto tiene o no cobertura. Recomendado para validar en tiempo real durante el checkout.
  • Descarga completa: GET /api/merchant/v1/coverage — devuelve el listado completo de códigos postales cubiertos. Útil si prefieres cachearlo en tu plataforma y validar en local.

Si eliges la descarga completa, actualiza tu base local al menos una vez al día. Nuestra red se amplía continuamente y los códigos postales cubiertos pueden cambiar de un día para otro. Refrescar el listado diariamente garantiza que tus clientes no pierdan la opción de envío a PuntoPost cuando incorporamos su zona.

Si el código postal no tiene cobertura, oculta la opción de envío a PuntoPost en tu checkout.

2. Obtener puntos de recogida

Una vez confirmado que hay cobertura, muestra a tu cliente los puntos de recogida cercanos a su dirección para que elija uno.

Endpoint:

  • GET /api/merchant/v1/pudos — devuelve la lista de puntos de recogida (PUDOs) filtrada por coordenadas o código postal, con paginación.

Cada punto de recogida incluye su nombre, dirección completa, horarios de atención y datos de contacto. Con esta información puedes construir tu propio selector visual (mapa, lista, buscador…) o mostrar directamente el listado a tu cliente.

Al finalizar este paso, tu cliente habrá elegido un punto de recogida y tu plataforma tendrá guardado el id del punto seleccionado para usarlo en el siguiente paso.

3. Crear un envío

Con el punto elegido y los datos del pedido, ya puedes crear el envío en PuntoPost. Ofrecemos tres tipos de envío según el origen y el destino. Utiliza el que corresponda a tu flujo de negocio:

Tipo Flujo Endpoint
B2C Almacén desde el que sale el paquete → cliente que recoge en un punto. Es el flujo más habitual para un ecommerce. POST /api/merchant/v1/{merchantId}/parcels/b2c
C2C Cliente que deja en un punto → cliente que recoge en otro punto. POST /api/merchant/v1/{merchantId}/parcels
C2B Cliente que deja en un punto → almacén donde llega el paquete (devoluciones). POST /api/merchant/v1/{merchantId}/parcels/c2b

En la llamada de creación tendrás que enviar los datos del contenido, los datos de contacto (según el tipo, remitente y/o destinatario) y los identificadores de origen y destino. Puedes incluir opcionalmente una merchant_reference con tu propio identificador de pedido, lo que te permitirá consultar el envío después usando tu referencia interna y evitar duplicados.

Como respuesta recibirás el envío creado con su código de rastreo y dos códigos QR con usos distintos:

  • qr_tracking — es el QR que tienes que compartir con tu cliente (por correo, WhatsApp o dentro de tu propia app). Le sirve para mostrarlo en el punto cuando vaya a dejar o recoger el paquete. No hace falta imprimirlo: basta con que lo enseñe desde el móvil.
  • qr_label — es la etiqueta que va pegada al paquete. Solo aplica al flujo B2C, en el que el paquete sale de tu almacén: en ese caso tienes que imprimirla y adherirla al exterior del paquete antes de entregarlo al operador o dejarlo en el punto de origen. En los flujos C2C y C2B es el propio cliente quien deposita el paquete en el punto usando su qr_tracking, y no necesitas imprimir nada.

4. Marcar como listo o cancelar

Después de crear un envío, hay dos acciones que puedes ejecutar sobre él desde tu plataforma:

  • PUT /api/merchant/v1/parcels/{identifier}/ready — marca el envío como listo para que nuestro operador pase a recogerlo por tu almacén. Solo aplica al flujo B2C: es la señal de que ya tienes el paquete preparado con su etiqueta. En los flujos C2C y C2B no se utiliza porque el paquete lo deposita directamente el cliente en un punto de recogida.
  • DELETE /api/merchant/v1/parcels/{identifier} — cancela un envío. Solo es posible mientras el envío no haya iniciado el tránsito.

5. Recibir eventos por webhook

Para mantener tu plataforma sincronizada sin necesidad de hacer polling continuo, PuntoPost envía notificaciones a la URL de webhook que hayas configurado en tu comercio cada vez que ocurre un evento relevante.

Eventos disponibles:

  • parcel_status_changed — el envío cambia de estado (llegó al punto, sale a tránsito, es entregado, etc.).
  • parcel_origin_changed — cambia el punto de origen del envío.
  • parcel_destination_changed — cambia el punto de destino del envío (por ejemplo, cuando el cliente pide cambio de punto).

Tu endpoint debe responder con un código HTTP 2xx para confirmar la recepción. Si respondes con un error, se reintentará automáticamente.

Recomendamos que tu procesamiento sea idempotente: podrías recibir el mismo evento más de una vez ante reintentos por red.

Documentación completa

En esta guía hemos cubierto los pasos y los endpoints principales que necesitas para integrar tu ecommerce con PuntoPost. Para consultar el detalle completo de cada endpoint (parámetros, campos de request y response, códigos de error y ejemplos) accede a la documentación técnica interactiva:

Ver documentación técnica de la API

Si tienes cualquier duda durante la integración, escríbenos a [email protected] y te ayudamos.