API

Todo lo que hay

Con una clave de pruebas

Un método que una ruta no atiende responde 405 con la cabecera Allow. Manda siempre Content-Type: application/json: sin él, la protección contra envíos de formulario cruzados lo rechaza antes de llegar a la ruta.

Autenticación

Todas las peticiones llevan Authorization: Bearer <clave>. Las claves se crean en el panel, en Integración.

sk_live_…

Servidor a servidor. Sin captcha. Nunca la expongas en el navegador: quien la tenga puede registrar reclamos en tu libro.

pk_live_…

Para el navegador. Exige turnstile_token y solo funciona desde los dominios que declaraste. Sin cabecera Origin válida se rechaza, aunque la clave sea buena. El captcha se monta en tres líneas: más abajo está el formulario entero.

El proveedor sale de la clave, no del cuerpo: una clave no puede escribir en el libro de otra empresa.

Los bloques que debes capturar

La hoja oficial tiene cuatro secciones. Las tres primeras las llena el consumidor; la cuarta la llena el proveedor al responder, desde el panel o por API.

Registrar un reclamo

POST /api/v1/complaints

curl -X POST https://app.dbtech.cloud/api/v1/complaints \
  -H "Authorization: Bearer sk_live_TU_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "sede": "miraflores",
    "tipo": "reclamo",
    "consumidor_nombre": "María Ñahui",
    "consumidor_doc_tipo": "DNI",
    "consumidor_doc_num": "70112233",
    "consumidor_domicilio": "Av. Ejemplo 500, Lima",
    "consumidor_email": "maria@ejemplo.pe",
    "bien_tipo": "producto",
    "bien_descripcion": "Pedido #A-4471",
    "monto_reclamado": 79.90,
    "detalle": "El pedido llegó incompleto y con el empaque abierto.",
    "pedido": "Reposición del producto faltante.",
    "consentimiento": true,
    "datos_adicionales": { "numero_pedido": "A-4471", "mesa": 12 }
  }'

Respuesta 201

{
  "id": "cdbe525a-50fe-41d6-927f-5d5302ed7f23",
  "codigo": "MIR-00001-2026",
  "correlativo": 1,
  "deadline_at": "2026-09-04",
  "consulta_url": "https://app.dbtech.cloud/consulta/9771b92f…",
  "pdf_url": "https://app.dbtech.cloud/api/v1/complaints/cdbe…/pdf?token=9771…"
}

Guarda el codigo y la consulta_url: son lo que el consumidor necesita para seguir su caso. La copia por correo se envía sola.

Buscar una hoja — tu propio buscador

POST /api/v1/complaints/lookup

Para montar el buscador de seguimiento en tu web, con tu diseño. El consumidor teclea su número de hoja y su documento; esto te dice a dónde mandarlo.

curl -X POST https://app.dbtech.cloud/api/v1/complaints/lookup \
  -H "Authorization: Bearer pk_live_TU_CLAVE" \
  -H "Origin: https://www.tu-restaurante.pe" \
  -H "Content-Type: application/json" \
  -d '{
    "codigo": "MIR-00001-2026",
    "doc_num": "70112233",
    "turnstile_token": "…"
  }'

Respuesta 200

{
  "codigo": "MIR-00001-2026",
  "consulta_url": "https://app.dbtech.cloud/consulta/9771b92f…",
  "pdf_url": "https://app.dbtech.cloud/api/v1/complaints/cdbe…/pdf?token=9771…"
}

Redirige al consumidor a consulta_url.

Cuando el número encaja en varios de tus locales

El correlativo se cuenta por sede, así que cada local tiene su «00001». Si el consumidor solo recuerda el número corto, la respuesta trae con qué preguntarle — y no trae el enlace: la credencial que abre el expediente se entrega cuando no queda duda de cuál es la hoja.

{
  "ambiguo": true,
  "mensaje": "Ese número existe en más de uno de tus locales. Pregunta en cuál fue.",
  "sedes": [
    { "sede": "miraflores", "nombre": "Miraflores" },
    { "sede": "barranco",   "nombre": "Barranco" }
  ]
}

Repite la llamada añadiendo "sede": "barranco".

Límites: 60 por minuto y clave; con claves publishable, 10 por minuto e IP —contadas antes que la clave, que pasa a ser un techo de 600— porque ahí cada IP es un consumidor, y sin ese freno el buscador sería una forma de probar documentos en serie.

El captcha, en tu formulario

Solo si usas una clave pk_live_. Las sk_live_ no llevan captcha: viven en tu servidor, donde no hay nadie a quien comprobar.

En tu página

<script src="https://challenges.cloudflare.com/turnstile/v0/api.js"
        async defer></script>

<form id="buscar">
  <input name="codigo"  placeholder="MIR-00001-2026" required>
  <input name="doc_num" placeholder="Tu documento"   required>

  <!-- El widget inyecta aquí dentro un input oculto: cf-turnstile-response -->
  <div class="cf-turnstile" data-sitekey="TU_SITEKEY"></div>

  <button>Buscar mi reclamo</button>
</form>

Al enviar

document.getElementById('buscar').addEventListener('submit', async (e) => {
  e.preventDefault();
  const fd = new FormData(e.target);

  const r = await fetch('https://app.dbtech.cloud/api/v1/complaints/lookup', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer pk_live_TU_CLAVE',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      codigo:  fd.get('codigo'),
      doc_num: fd.get('doc_num'),
      // Ya viene en el FormData: lo puso el widget al resolverse.
      turnstile_token: fd.get('cf-turnstile-response'),
    }),
  });

  const data = await r.json();
  if (data.consulta_url) location.href = data.consulta_url;
  else alert(data.error ?? data.mensaje);

  // El token es de UN SOLO USO. Sin esto, la segunda búsqueda da 400.
  turnstile.reset();
});

No copies el token a mano ni lo busques en el DOM: el widget deja un input oculto dentro de tu formulario, así que el FormData ya lo lleva. Y no pongas la cabecera Origin: la pone el navegador, y por eso una clave publishable puede ser pública — la clave se copia, el origen no.

Para probar desde Postman, que no es un navegador: abre tu formulario, deja que el widget se resuelva y en la consola pide copy(turnstile.getResponse()). Tienes 5 minutos y un solo envío.

El Libro

GET /api/v1/complaints

Filtros: estado (pendiente · cerrado), sede, desde y hasta (AAAA-MM-DD), limit (1–100, por defecto 25).

Se pagina por cursor, no por número de página: pasa el siguiente_cursor que devuelve la respuesta. Con offset, un reclamo nuevo mientras paginas desplaza todo y hace que se repita una fila y se salte otra. Cuando llega null, no hay más.

El listado trae lo justo para pintar una bandeja. El documento, el domicilio y el detalle están en GET /api/v1/complaints/{id}, uno a uno: repartir cincuenta expedientes enteros por página es multiplicar copias de datos personales para que uses tres campos.

El detalle no devuelve el consulta_token —es la llave que abre la constancia sin más comprobación— ni la IP del envío. Sí devuelve el hash, para que puedas comprobar por tu cuenta que el expediente no cambió.

La agenda

GET /api/v1/reservations?fecha=AAAA-MM-DD

fecha es obligatoria. Sin ella lo natural sería devolver «todas», y en un local con dos años de historial eso son decenas de miles de filas con datos personales por una llamada distraída. Filtros opcionales: sede y estado.

PATCH /api/v1/reservations/{id}

Hace dos cosas distintas, y por eso no se pueden pedir juntas:

Mandar las dos cosas a la vez responde 422. No es rigidez: el resultado dependería del orden en que se aplicaran —¿se mueve y luego se sienta, o se sienta y luego se mueve una reserva ya sentada?— y ese orden no está definido en ninguna parte. Que lo decida quien llama, en dos peticiones.

La frontera de lo que puedes cambiar no es «reservas sí, reclamos no»: es si la acción se puede deshacer. Marcar que alguien llegó se corrige diciendo lo contrario y no sale del local. Cancelar, no — por eso tiene su propio verbo y no se puede hacer sin querer con un PATCH.

Reprogramar

Cambiar la hora es una cosa; cambiar cuántos son es otra, y las dos van por aquí. Una reserva de dos que pasa a cuatro necesita otra mesa, así que el sistema replanifica desde cero: suelta el cupo viejo y busca sitio para el grupo nuevo. Puede acabar en un tamaño de mesa distinto del que tenía.

Si mandas la misma fecha, hora y grupo que ya tenía, responde 200 con "sin_cambios": true y no toca nada.

Al comensal no se le avisa. Es lo mismo que hace el panel cuando reprograma el local: quien mueve una reserva suele estar hablando con él por teléfono, y un correo automático llegaría tarde y contradiciendo lo acordado. Si tu sistema mueve reservas sin hablar con nadie, avísale tú.

Es PATCH y no PUT porque no se reemplaza el recurso: se cambian los campos que mandas. Un PUT prometería poder enviar la reserva entera, incluidos el código y el estado, y eso no es cierto.

DELETE /api/v1/reservations/{id}

Cancela; no borra. La reserva queda como cancelada y se sigue pudiendo consultar: es lo que distingue «se canceló» de «nunca existió». Acepta ?motivo=…, en la query y no en el cuerpo, porque un cuerpo en un DELETE lo descartan muchos proxies sin avisar.

Manda un correo al comensal, y ese correo no se retira. Cancelar dos veces es 200 y no avisa dos veces: puedes reintentar tras un fallo de red sin miedo. Una mesa ya atendida (completada o no_show) responde 409: no se anula lo que ya ocurrió.

Sedes

La numeración correlativa es por establecimiento, así que sede es obligatoria si el proveedor tiene más de uno. Nunca elegimos una por ti: un reclamo en el libro equivocado deja mal numerados los dos.

Si la omites con varias sedes, la respuesta es 422 con la lista de slugs disponibles.

Qué hay libre

GET /api/v1/reservations/availability

Devuelve las reglas del local —tamaños de grupo, hasta qué fecha se puede reservar, cuántas horas antes se cancela— y, si mandas fecha, también las horas libres. Sin fecha solo las reglas: es la llamada que hace tu formulario al cargarse.

Pide las reglas en vez de codificarlas a mano. El día que el local cambie su configuración desde el panel, tu formulario se entera; si las escribiste tú, mentirá.

curl "https://app.dbtech.cloud/api/v1/reservations/availability?sede=miraflores&fecha=2026-10-30&personas=4" \
  -H "Authorization: Bearer pk_live_TU_CLAVE" \
  -H "Origin: https://www.tu-restaurante.pe"

Respuesta 200

{
  "sede": "miraflores",
  "nombre": "Miraflores",
  "acepta_reservas": true,
  "grupo_min": 1,
  "grupo_max": 8,
  "aforo_maximo": 8,
  "fecha_min": "2026-09-01",
  "fecha_max": "2026-10-31",
  "anticipacion_min_horas": 2,
  "cancelacion_horas": 2,
  "confirmacion_automatica": true,
  "fecha": "2026-10-30",
  "personas": 4,
  "horarios": [
    { "hora": "19:00", "mesas_libres": 3, "mesa": "Mesa para 4", "capacidad": 4 },
    { "hora": "19:30", "mesas_libres": 2, "mesa": "Mesa para 4", "capacidad": 4 }
  ]
}

Si la sede todavía no acepta reservas en línea, responde 200 con acepta_reservas: false — no un error. Así puedes enseñar «reserva por teléfono» en vez de romperte.

Reservar

POST /api/v1/reservations

curl -X POST https://app.dbtech.cloud/api/v1/reservations \
  -H "Authorization: Bearer pk_live_TU_CLAVE" \
  -H "Origin: https://www.tu-restaurante.pe" \
  -H "Content-Type: application/json" \
  -d '{
    "sede": "miraflores",
    "fecha": "2026-10-30",
    "hora": "19:30",
    "personas": 4,
    "nombre": "Ana Torres",
    "telefono": "987654321",
    "email": "ana@ejemplo.pe",
    "notas": "Alergia a los frutos secos",
    "turnstile_token": "…"
  }'

Respuesta 201

{
  "id": "ab56292a-3730-4c7b-b2e3-58ca0bdfee0f",
  "codigo": "MIR-78761D",
  "estado": "confirmada",
  "sede": "miraflores",
  "gestion_url": "https://app.dbtech.cloud/reserva/d39cdebf…"
}

telefono es obligatorio y email no — al revés que en el Libro. Si el local necesita avisar de un imprevisto una hora antes, el correo no sirve.

Manda al comensal a gestion_url: ahí ve su reserva y puede cancelarla. Es la llave — quien tenga el enlace puede cancelar, así que se le entrega a él y no se publica.

Cuando no se puede

El cuerpo trae motivo, un código estable. Úsalo tú, no el texto: «esa hora acaba de ocuparse» no se comprueba con un if.

{
  "error": "Esa hora acaba de ocuparse. Vuelve a elegir entre las horas disponibles.",
  "motivo": "sin_cupo",
  "campos": { "hora": ["Esa hora acaba de ocuparse. …"] }
}

Límites: 60 altas por minuto y clave. Con claves publishable, 5 cada diez minutos por IP —el mismo tope que el formulario hospedado—, contadas antes que la clave, que pasa a ser un techo de 600. Una reserva falsa no llena una tabla: deja una mesa vacía toda la noche.

Errores