# Documentación

- [Bienvenido](/docs): La API pública de Verifika — qué hace, dónde sacar la llave y por dónde empezar.
- Guías
  - [Empezar](/docs/guias/empezar): De cero a tu primer request en cinco minutos.
  - [Autenticación y permisos](/docs/guias/autenticacion): Cómo funciona la llave, qué puede hacer, cómo se rota y qué hacer si se filtra.
  - [Paginación](/docs/guias/paginacion): Cómo recorrer meses de movimientos sin repetir ni saltarte filas.
  - [Idempotencia](/docs/guias/idempotencia): Cómo reintentar sin registrar la misma venta dos veces.
  - [Límites de uso](/docs/guias/rate-limits): Cuántas peticiones por minuto, qué devuelve un 429 y cómo reintentar bien.
  - [Errores](/docs/guias/errores): El catálogo completo, qué se reintenta y qué no, y para qué sirve el requestId.
  - [Webhooks](/docs/guias/webhooks): Recibe cada pago verificado en tu propia URL, firmado y con reintentos.
  - [Verifica desde tu propio bot](/docs/guias/bots): Cómo un bot de WhatsApp ajeno valida comprobantes con Verifika por dentro.
- Referencia
  - [Referencia de la API](/docs/referencia): Cada endpoint con sus parámetros, sus respuestas y un playground para probarlo.
  - Identidad
    - [Quién soy](/docs/referencia/identidad/getMe): Valida la llave y devuelve a qué negocios entra, qué permisos tiene y en qué plan está la cuenta.

Es el request que conviene hacer primero en cualquier integración: si algo va a fallar por configuración, falla aquí y no a mitad del flujo.
    - [Plan y consumo](/docs/referencia/identidad/getPlan): Plan actual, funciones incluidas, límites y verificaciones consumidas en el mes.

Sirve para que un bot pregunte «¿esta cuenta todavía puede verificar?» antes de pedirle la foto al cliente.
  - Verificar
    - [Verificar un comprobante](/docs/referencia/verificar/createVerification): Registra un comprobante y devuelve el veredicto.

Pasa por la misma cadena que el bot propio de Verifika: candado de la cuenta → plan → cupo → duplicado → cruce con el aviso del banco. Consume una verificación del cupo mensual salvo que resulte duplicado.

El pago nace PENDING, nunca VERIFIED: solo el cruce con el aviso real del banco puede confirmarlo. Si el banco ya había avisado, el cruce ocurre en esta misma llamada y el ingreso vuelve verificado.
  - Ingresos
    - [Declarar un ingreso](/docs/referencia/ingresos/createIncome): Anota un pago en el libro. Nace DECLARED: editable, borrable y sin consumir cupo de verificaciones — nadie pidió verificar nada.

No confundir con POST /v1/verifications, que sí verifica y sí consume. Son dos intenciones distintas: esta es para sincronizar lo que ya sabes; aquella, para preguntar si un pago es real.
    - [Eliminar un ingreso declarado](/docs/referencia/ingresos/deleteIncome): Solo ingresos DECLARED. Borra también sus comprobantes del almacenamiento.
    - [Ver un ingreso](/docs/referencia/ingresos/getIncome): Detalle de un pago.

Un id que no sea de un negocio de esta llave devuelve 404, no 403: responder «no tienes permiso» confirmaría que ese id existe.
    - [Listar ingresos](/docs/referencia/ingresos/listIncomes): Lista los pagos del negocio, del más reciente al más antiguo, paginada por cursor.

Acepta los mismos filtros que el panel: si el reporte que descarga el dueño y lo que lee tu integración salieran de filtros distintos, dirían cosas distintas del mismo mes.
    - [Corregir un ingreso declarado](/docs/referencia/ingresos/updateIncome): Solo funciona sobre ingresos DECLARED. Nunca toca status ni origin.
  - Egresos
    - [Registrar un egreso](/docs/referencia/egresos/createExpense): Queda con source: "API", para que en el libro se distinga lo que escribió un sistema de lo que escribió una persona.
    - [Crear una categoría de egreso](/docs/referencia/egresos/createExpenseCategory): Un negocio nace con once categorías por defecto y puede crear las suyas.

Crear categorías propias es una función aparte del módulo de egresos (expense_categories_custom): en el plan más bajo se usan solo las que vienen.
    - [Eliminar un egreso](/docs/referencia/egresos/deleteExpense)
    - [Eliminar una categoría de egreso](/docs/referencia/egresos/deleteExpenseCategory): Solo si no tiene gastos. Una categoría con movimientos no se borra: borrarla dejaría egresos huérfanos y rompería el histórico, que es justo el dato por el que el negocio paga. Para esas, PATCH { "active": false }.
    - [Ver un egreso](/docs/referencia/egresos/getExpense)
    - [Listar categorías de egreso](/docs/referencia/egresos/listExpenseCategories): Las categorías del negocio, para poder mandar un categoryId válido al crear un egreso.

Solo lectura, a propósito. Un ERP con su propio catálogo llenaría el libro de categorías duplicadas sin querer, y el dueño ya las administra en el panel, donde las ve todas de una vez.
    - [Listar egresos](/docs/referencia/egresos/listExpenses): Gastos del negocio, paginados por cursor. Requiere el módulo de egresos en el plan además del permiso expenses.read.
    - [Editar un egreso](/docs/referencia/egresos/updateExpense)
    - [Editar una categoría de egreso](/docs/referencia/egresos/updateExpenseCategory): Renombrar, cambiar el emoji o la descripción, reordenar — y desactivar, que es lo que se hace con una categoría que ya tiene gastos.
  - Negocio
    - [Ver el negocio](/docs/referencia/negocio/getCompany)
    - [Listar sucursales](/docs/referencia/negocio/listBranches): Si la llave está acotada a una sucursal, aquí solo aparece esa.
    - [Catálogo de categorías de negocio](/docs/referencia/negocio/listBusinessCategories): A qué se dedican los negocios: las veinte categorías que ofrece el onboarding, con su etiqueta en español y el icono que usa el panel.

Es lo que hace utilizable el category de GET /v1/company: sin esta lista tendrías que mantener tu propia traducción de los slugs y quedarte desactualizado la primera vez que agreguemos uno.
    - [Listar cuentas de recaudo](/docs/referencia/negocio/listPaymentAccounts): Las cuentas donde el negocio recibe plata. Nunca el número completo: se identifican por su alias y los últimos cuatro, que es todo lo que hace falta para conciliar.
  - Equipo
    - [Ver el equipo](/docs/referencia/equipo/getTeam): Quién está en el negocio, con qué rol y en qué sucursal, más las invitaciones pendientes y el cupo de usuarios del plan.

Sin correos ni fotos de perfil. Una integración necesita saber quién puede registrar pagos, no la libreta de direcciones del negocio.
    - [Listar roles](/docs/referencia/equipo/listRoles): Los roles que se pueden asignar, del de más autoridad al de menos. Sin esta lista habría que adivinar la key de un rol para invitar a alguien.
  - Pagos sospechosos
    - [Ver un intento sospechoso](/docs/referencia/pagos-sospechosos/getSuspiciousAttempt)
    - [Listar intentos sospechosos](/docs/referencia/pagos-sospechosos/listSuspiciousAttempts): Comprobantes repetidos y comprobantes que el banco nunca respaldó.

No salen en /v1/incomes, y es a propósito: meterlos entre los ingresos inflaría el total del periodo que el negocio le manda a su contador.
  - Bancos
    - [Estado de la conexión](/docs/referencia/bancos/getConnections): Por dónde entran los avisos del banco y si el canal sigue vivo.

healthy es el dato que importa: cuando se pone en false, el negocio dejó de tener con qué verificar y todavía no lo sabe. Un monitor que consulte esto cada mañana se entera antes que el cliente que reclama.
  - Reportes
    - [Métricas del periodo](/docs/referencia/reportes/getMetrics): Los mismos cortes de la pantalla de Métricas: totales del periodo y del anterior, serie por día, perfil por hora, ranking por persona y por cuenta de recaudo.

Acepta los filtros del libro. fromTime/toTime acotan a un turno (por ejemplo, 18:00–23:59 para la noche).
  - Webhooks
    - [Crear un webhook](/docs/referencia/webhooks/createWebhookEndpoint): Devuelve el secreto de firma en claro. Guárdalo: con él verificas que cada entrega vino de nosotros.

La URL tiene que ser https y resolver a una dirección pública — se valida al guardar y otra vez en cada entrega, porque un dominio que hoy apunta a un servidor público puede apuntar mañana a una red interna.
    - [Eliminar un webhook](/docs/referencia/webhooks/deleteWebhookEndpoint)
    - [Historial de entregas](/docs/referencia/webhooks/listWebhookDeliveries): Qué mandamos, qué respondió tu servidor y en qué intento. Incluye el cuerpo del evento y un recorte de tu respuesta, que es lo que permite depurar sin mirar tus propios logs.
    - [Listar webhooks](/docs/referencia/webhooks/listWebhookEndpoints): Cada endpoint viene con su salud de las últimas 24 horas, que es la pregunta real: ¿esto está llegando o no?
    - [Catálogo de eventos](/docs/referencia/webhooks/listWebhookEventTypes): Todos los eventos que existen, con allowed según el plan del negocio.

Se devuelve entero y sin filtrar a propósito: esconder lo que no se puede suscribir deja al dueño sin saber que existe.
    - [Reenviar una entrega](/docs/referencia/webhooks/retryWebhookDelivery): La vuelve a encolar para el próximo barrido. Útil cuando arreglaste tu endpoint y no quieres esperar al siguiente reintento automático.
    - [Rotar el secreto de firma](/docs/referencia/webhooks/rotateWebhookSecret): Durante 24 horas firmamos cada entrega con los dos secretos, así despliegas el nuevo cuando quieras sin perder un solo evento.
    - [Probar un webhook](/docs/referencia/webhooks/testWebhookEndpoint): Encola un evento webhook.test contra ese endpoint. El resultado aparece en el historial de entregas en menos de un minuto.
    - [Editar un webhook](/docs/referencia/webhooks/updateWebhookEndpoint): enabled: true vuelve a encender uno que desactivamos por fallos, y le pone el contador a cero.
- MCP
  - [Qué es el MCP de Verifika](/docs/mcp): Conecta Verifika a tu asistente de IA y pregúntale a tus datos en lenguaje natural.
  - [Conectar con un clic](/docs/mcp/autorizacion): Autoriza Verifika desde tu asistente sin copiar ninguna llave. Cómo funciona, qué se concede y cómo se quita.
  - [Cómo se conecta](/docs/mcp/conectar): La configuración exacta para Claude, ChatGPT, Cursor, VS Code y clientes propios.
  - [Herramientas](/docs/mcp/herramientas): Las 37 herramientas del servidor, una por una, y qué permiso exige cada cosa.
  - [Seguridad](/docs/mcp/seguridad): Qué puede ver el asistente, qué no, y cómo acotarlo.