API de Partners

Da de alta el Libro de Reclamaciones de tus clientes desde tu sistema.

Base URL: https://respondo.pe/api/v1

Resumen

Tu clave la generas en respondo.pe/partner → Clave API. Se muestra una sola vez.

Empieza por la colección de Postman: trae las llamadas en orden y con ejemplos. Pega tu clave y prueba.

Crear un libro

POST /partners/books

La cuenta del cliente

Si el número ya pertenece a otra cuenta de respondo.pe, la cuenta se crea igual — solo se queda sin ese WhatsApp guardado, y la bienvenida le llega por correo. Si ya administras esa cuenta (una empresa tuya previa con ese correo), el número que mandes no reemplaza el que ya tenía guardado.

La empresa

Por qué pedimos la ubicación: departamento, provincia y distrito salen impresos en el libro y son la dirección por defecto de la sede. No pedimos el código de ubigeo: no lo usamos para nada, y resolverlo es trabajo que no tienes por qué hacer.

El libro

Todo el objeto libro es opcional. Si no lo mandas, hereda los datos de la empresa.

El logo no se enlaza: lo descargamos y lo servimos desde cdn.respondo.pe, así el libro no depende de tu servidor. Tiene que ser una URL http/https accesible, en JPG, PNG, WEBP o GIF, de hasta 1MB. Si no se puede traer, el libro se crea igual sin logo — el alta no falla por eso.

El color de la hoja sale del logo. Al traerlo le leemos la paleta y pintamos el libro con su color más dominante, igual que cuando alguien se da de alta por la web. Si no mandas logo, o si no se le puede sacar un color legible, el libro queda con el color por defecto. Tu cliente puede cambiarlo cuando quiera desde su panel.

curl -X POST https://respondo.pe/api/v1/partners/books \
  -H "X-Partner-Key: rsp_partner_tu_clave" \
  -H "Content-Type: application/json" \
  -d '{
    "usuario": {
      "email": "rosa@bodegacentral.pe",
      "nombre": "Rosa Quispe",
      "whatsapp": "+51987654321"
    },
    "empresa": {
      "ruc": "20512345678",
      "razon_social": "Bodega Central S.A.C.",
      "direccion": "Av. Angamos Este 1234",
      "departamento": "Lima",
      "provincia": "Lima",
      "distrito": "Surquillo"
    },
    "libro": {
      "nombre": "Bodega Central - Surquillo",
      "direccion": "Av. Angamos Este 1234",
      "departamento": "Lima",
      "provincia": "Lima",
      "distrito": "Surquillo",
      "url_libro": "bodega-central-surquillo",
      "url_sitio": "https://bodegacentral.pe",
      "logo_url": "https://bodegacentral.pe/logo.png"
    }
  }'

{
  "success": true,
  "data": {
    "estado": "creado",
    "libro": {
      "id": "8f3c1a90-5d21-4e7b-9c44-2b6e8a1f0d33",
      "url_libro": "bodega-central-s-a-c",
      "url_publica": "https://respondo.pe/libro/bodega-central-s-a-c"
    },
    "fecha_fin": "2026-10-19T12:00:00.000Z"
  }
}

Mira el estado, no el código HTTP:

Guarda el url_libro: es lo que enlazas en la web de tu cliente.

Listar lo que creaste

GET /partners/books
GET /partners/books?ruc=20512345678

Devuelve solo lo tuyo. Sirve para comprobar un alta y para recuperar un libro_id perdido.

{
  "success": true,
  "data": [{
    "id": "8f3c1a90-…",
    "url_publica": "https://respondo.pe/libro/bodega-central-s-a-c",
    "empresa": { "ruc": "20512345678", "razon_social": "Bodega Central S.A.C." },
    "estado": "prueba",
    "precio": 19,
    "fecha_fin": "2026-10-19T12:00:00.000Z",
    "recibe_reclamos": true,
    "reclamos": 0,
    "se_puede_borrar": true
  }]
}

Borrar una empresa

DELETE /partners/companies/{ruc}

curl -X DELETE -H "X-Partner-Key: rsp_partner_tu_clave" \
  https://respondo.pe/api/v1/partners/companies/20512345678

Deshace el alta entera: la empresa, sus libros y la cuenta que creamos para ella. El RUC queda libre.

Solo si la empresa no tiene ningún reclamo. Con reclamos responde 409: eso ya no es tuyo para deshacer —son registros de cumplimiento y evidencia de consumidores— y lo borra su dueño desde su panel.

La cuenta solo se borra si la creamos nosotros en tu integración. Si ese correo ya tenía cuenta antes, si la persona pertenece al equipo de otra empresa, o si es la cuenta con la que un partner entra a su panel, la cuenta se queda y cuenta_borrada viene en false.

⚠️ Borrar no devuelve la prueba gratis. Queda marcada contra el correo y contra el RUC, así que volver a dar de alta con cualquiera de los dos responde requiere_pago. Para ver otro creado con sus 30 días, usa un RUC y un correo nuevos.

Lo mismo con un botón en respondo.pe/partner → Empresas.

Errores

{ "success": false, "error": { "code": "ALREADY_EXISTS", "message": "…", "details": { "codigo": "RUC_REGISTRADO" } } }

Sobre el 403 (CUENTA_AJENA). Solo puedes dar de alta empresas en cuentas que administras: las que creaste tú por esta API, o las que ya tienen alguna empresa tuya. Si el correo pertenece a alguien que llegó a Respondo.pe por su cuenta, no lo enganchamos — el correo de una empresa es público y no basta para demostrar que la representas. En ese caso, su dueño crea el libro desde su panel o te da acceso.

Probar

No hay sandbox: lo que creas es real.

• RUC desechable. Es único en toda la plataforma.
• RUC y correo nuevos en cada prueba. La prueba gratis queda marcada contra los dos y sobrevive al borrado, aunque la cuenta se vaya. Usa tucorreo+prueba1@gmail.com, +prueba2.
• Reintentar es seguro. Si se cortó a medias, repetir con el mismo RUC termina el alta.

POST   /partners/books           # crea
GET    /partners/books?ruc=…     # recibe_reclamos: true
DELETE /partners/companies/{ruc} # se lleva empresa, libros y cuenta

Tu comisión

GET /partners/me

Los totales se calculan sobre todos los movimientos: son la fuente de verdad.

Lo mismo sin código en respondo.pe/partner. Ahí también está tu enlace de referido: la empresa que se registre con él queda a tu nombre, sin integrar nada.

En JavaScript

const res = await fetch('https://respondo.pe/api/v1/partners/books', {
  method: 'POST',
  headers: {
    'X-Partner-Key': process.env.RESPONDO_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    usuario: {
      email: 'rosa@bodegacentral.pe',
      nombre: 'Rosa Quispe',
      whatsapp: '+51987654321',
    },
    empresa: {
      ruc: '20512345678',
      razon_social: 'Bodega Central S.A.C.',
      direccion: 'Av. Angamos Este 1234',
      departamento: 'Lima',
      provincia: 'Lima',
      distrito: 'Surquillo',
    },
    libro: {
      nombre: 'Bodega Central - Surquillo',
      direccion: 'Av. Angamos Este 1234',
      departamento: 'Lima',
      provincia: 'Lima',
      distrito: 'Surquillo',
      url_libro: 'bodega-central-surquillo',
      url_sitio: 'https://bodegacentral.pe',
      logo_url: 'https://bodegacentral.pe/logo.png',
    },
  }),
})

const { success, data } = await res.json()

if (success) {
  guardar(data.libro.url_publica)
  if (data.estado === 'requiere_pago') mandarAPagar()
}

Lo que no hace

• No actualiza. Si tu cliente cambia de dirección, el libro no se entera: lo corrige él desde su panel. ¿Lo necesitas? Escríbenos.
• Un alta, un libro. Para más sedes, escríbenos.
• No hay webhooks. Para saber de un reclamo nuevo, hoy toca consultar.

Después del alta

1. El cliente entra a respondo.pe con su correo: pide un código o usa Google. No le creamos contraseña.
2. A los 30 días paga (S/ 19 mensual o S/ 179 anual, por empresa, IGV incluido). Tu comisión se devenga sola, sobre el cobro sin IGV.

Notas

• La clave es secreta y de servidor. No hay CORS: en el navegador no funciona y la expondrías.
• Con clave nunca necesitas token CSRF.