Conceptos

Términos que usa toda la documentación de Fotofacturas y cómo se llama cada uno en la web app business y en la API.

Dirigido a: administradores y equipos técnicos de las empresas cliente. Los valores de cada catálogo están en Catálogos.

Organización de la cuenta

Una empresa cliente factura con Fotofacturas los tickets de compra de sus colaboradores. Su cuenta se organiza así:

Asociación raíz (la empresa cliente)
  ├── RFC de asociación
  ├── Colaboradores ── RFC propios ── Tickets ── Facturas
  └── Asociaciones hijas (sucursales, empresas, áreas…)
       ├── RFC de asociación
       ├── Colaboradores ── RFC propios ── Tickets ── Facturas
       └── Asociaciones hijas…

• El usuario B2B administra asociaciones, colaboradores, RFC, tickets y webhooks desde la web app business o la API.
• Los colaboradores suben fotos de sus tickets por cualquier canal y Fotofacturas los convierte en facturas (CFDI).

Usuarios

Usuario B2B

Cuenta del responsable de la empresa cliente. Entra a la web app business con usuario y contraseña y es dueño del token de API con el que los sistemas de la empresa usan la API Enterprise.

• Cada usuario B2B está vinculado a una sola asociación raíz.
• Solo puede ver y modificar la información de su propio árbol de asociaciones. Cualquier asociación, colaborador, RFC o ticket fuera de ese árbol se rechaza.
• Si Fotofacturas lo bloquea, no puede entrar a la web app business y su token deja de funcionar hasta que se desbloquee.

Colaborador

Persona (por ejemplo, un empleado) que sube tickets para facturar. Pertenece a una asociación y puede tener sus propios RFC.

• Puede subir tickets desde la app móvil, la app web, WhatsApp o el flujo embebido. El usuario B2B también puede subirlos a su nombre desde la web app business o la API.
• Puede estar activo o inactivo. Un colaborador inactivo no puede subir tickets.
• Su correo y su teléfono deben ser únicos en Fotofacturas.

Usuario raíz

Registro que se crea automáticamente con cada asociación. No es una persona: es el titular de los RFC de asociación y de los tickets de asociación.

• En la API aparece en GetUsersByAssociation con isAssociationRoot: true, siempre en primer lugar.
• No se edita, no se desactiva y no se puede mover de su asociación. Sus RFC y tickets se administran con las APIs de asociación.
• No aparece en la web app business.

Estructura de la cuenta

Asociación

Unidad de la empresa cliente: la empresa misma, una sucursal, un área, un departamento, un proyecto o una sub-empresa. Las asociaciones forman un árbol sin límite de niveles.

• Cada asociación puede tener sus propios RFC de asociación, colaboradores y configuración.
• Las asociaciones no se pueden eliminar; si una ya no se usa, se puede cambiar su nombre.

Asociación raíz

La asociación principal de la cuenta, por encima de todas las demás.

• La crea Fotofacturas al dar de alta la cuenta.
• No se puede mover dentro del árbol.

Asociación hija

Cualquier asociación que está debajo de otra.

• La crea y la edita el usuario B2B desde la web app business o la API.
• Se puede mover dentro del árbol, pero no debajo de sí misma ni de una de sus descendientes.

Árbol de la cuenta y subárbol

• Árbol de la cuenta: la asociación raíz y todas sus descendientes. Es el alcance del usuario B2B, del plan, de los reportes y de los webhooks.
• Subárbol de una asociación: esa asociación y todas sus descendientes. Los reportes de la API que reciben associationId opcional se limitan a ese subárbol; sin el parámetro cubren todo el árbol de la cuenta.

Configuración de la asociación

Valores opcionales que personalizan una asociación (UpdateAssociationConfig). Si no se configuran, se usan los valores por defecto de Fotofacturas.

Plan y límites

Plan

Reglas sobre tickets y RFC que se asignan a la asociación raíz y aplican a todo su árbol. Lo asigna Fotofacturas; se consulta en la web app business (Planes) o con GetAccountInfo.

Límites de tickets

• Un límite vacío (null) significa sin límite; un límite en 0 significa que no se puede subir ningún ticket.
• Los límites se reinician el día 1 de cada mes a las 00:00, hora del centro de México.
• Cuentan todos los tickets del mes sin importar su estatus, excepto los tickets descartados.

Tipo multi RFC

Define con qué RFC se pueden facturar los tickets de los colaboradores (multiRfcType). Solo Fotofacturas puede cambiarlo.

Los tickets de asociación siempre se facturan con los RFC de esa misma asociación.

Límites de RFC

Un RFC deshabilitado no ocupa lugar, pero reactivarlo sí cuenta contra el límite.

Información fiscal

RFC

Registro Federal de Contribuyentes con el que se emite la factura. Cada RFC guarda su razón social, domicilio fiscal y regímenes fiscales; a ese conjunto se le llama información fiscal (userTaxInfoId en la API).

• Un RFC puede estar activo o deshabilitado. Solo los activos se usan para facturar y cuentan para los límites del plan.

RFC propio y RFC de asociación

Constancia de Situación Fiscal (CSF)

PDF que emite el SAT con los datos fiscales de un contribuyente. Un RFC se registra subiendo su CSF: Fotofacturas lee el PDF y obtiene el RFC, la razón social, el domicilio y los regímenes. Si se vuelve a subir la CSF de un RFC ya registrado, se actualiza y se reactiva.

Régimen fiscal, uso de CFDI y forma de pago

Datos del SAT que se indican al subir cada ticket (valores en Catálogos):

• Régimen fiscal: régimen del RFC con el que se factura. Solo se pueden elegir los regímenes registrados para ese RFC.
• Uso de CFDI: para qué se usará la factura ante el SAT (por ejemplo, G03 – Gastos en general). Debe ser válido para el régimen fiscal.
• Forma de pago: cómo se pagó el ticket (efectivo, tarjeta…). En la API se llama método de pago (ticketPaymentMethodId).

Últimos 4 dígitos de la tarjeta

Dato CardLastFour del ticket. Es obligatorio con tarjeta de crédito (04) o de débito (28) y opcional con las demás formas de pago. En el ambiente de pruebas además elige el escenario del simulador.

Tickets y facturas

Ticket

Foto del comprobante de compra que se sube para facturar. Cada foto cuenta como un ticket del plan.

Origen del ticket

Canal por el que llegó el ticket (ticketOriginId): app móvil, app web, web app business, API, flujo embebido o WhatsApp. Todos los tickets se tratan igual sin importar el origen: cuentan para el plan, aparecen en reportes y generan webhooks. Los valores están en Catálogos.

Factura (CFDI)

Comprobante fiscal digital generado a partir del ticket. Se entrega en dos archivos:

• XML: el comprobante válido ante el SAT. Contiene el UUID (folio fiscal), emisor, receptor, conceptos e impuestos.
• PDF: su representación impresa.

Normalmente un ticket facturado tiene ambos archivos, pero puede tener solo uno si es lo único que entregó el comercio.

Método de facturación

Cómo se obtuvo la factura (invoiceMethod): manual, automática, automática (reintento) o automática con correcciones. En la web app business aparece como Tipo de facturación en el detalle del ticket.

Estatus del ticket

Etapa en la que está el ticket (ticketStatusId). La web app business y los reportes los agrupan en tres: Facturados (11), En proceso (1, 3, 5, 6, 7, 8) y Rechazados (10). La lista completa está en Catálogos.

• Todo ticket empieza en 1 (Creado). 10 y 11 son finales, aunque Fotofacturas puede reabrir un ticket; por eso el estatus vigente es siempre el más reciente.

Código del ticket

Resultado o motivo de rechazo de un ticket (ticketCodeId, catálogo GetTicketCodes). El estatus dice si el ticket ya terminó y el código dice cómo terminó. Por ejemplo, un ticket ilegible tiene estatus 10 (No facturable) y código Ticket ilegible.

• Mientras el ticket está en proceso vale 1 (Creado, sin resultado).
• Cada código tiene un mensaje para el usuario (userMessage).
• Es el motivo de rechazo que muestran el detalle del ticket y Reportes › Atención en la web app business.

La diferencia completa entre estatus y código está en Flujo del ticket.

Ticket archivado y ticket descartado

• Ticket archivado: ticket que se sacó del proceso. Mientras está archivado no se procesa automáticamente.
• Ticket descartado: ticket que se archivó cuando todavía estaba en Creado. No se puede desarchivar y no cuenta en reportes, listas ni en el consumo del plan.

Integración

Web app business

Aplicación web donde el usuario B2B administra su cuenta: tablero, reportes, subida de tickets, empresas y colaboradores, plan, pagos, token de API y webhooks. Ver Web app business.

API

API para que los sistemas de la empresa administren su cuenta y suban tickets. Ver API.

Token de API

Clave del usuario B2B con la que se autentican todas las peticiones a la API Enterprise (Authorization: Bearer <token>). Se trata como una contraseña. Al regenerarlo, el anterior deja de funcionar de inmediato. Cada ambiente (producción y pruebas) tiene su propio token. Se consulta en la web app business, sección API y plan.

Permiso de API

Autorización para usar una API concreta de la API Enterprise. Fotofacturas los habilita por cuenta. Sin el permiso, la API responde No estas autorizado para usar esta API.

Webhook

Aviso (POST) que Fotofacturas envía a un servidor de la empresa cuando un ticket cambia de estatus.

• Evento: tipo de aviso: ticket.invoiced (facturado), ticket.failed (no facturable) y ticket.status_changed (cambio de estatus, incluida la creación). El evento ping solo se envía al probar un webhook.
• Webhook: combinación de una asociación, un evento, una URL y un secreto. Cada asociación puede tener uno por evento. Si la asociación del ticket no tiene uno activo para ese evento, se usa el de la asociación raíz, si está configurado.
• Secreto: clave (whsec_...) con la que se firma cada aviso para verificar que viene de Fotofacturas. Cada webhook tiene el suyo y solo se muestra al crearlo o regenerarlo.
• Entrega: un envío inmediato y hasta 4 reintentos. El evento termina como entregado o fallido y se puede reenviar. El historial se conserva 45 días.

Se configura desde la web app business (Webhooks) o la API. Ver la guía completa en Webhooks.

Ambiente de pruebas y simulador

• Ambiente de pruebas: ambiente separado para desarrollar la integración, con su propia URL, su propio token y sus propios datos. Las APIs, permisos, validaciones y webhooks funcionan igual que en producción.
• Simulador: en el ambiente de pruebas los tickets no se facturan de verdad. Un simulador mueve cada ticket por un recorrido de estatus según los últimos 4 dígitos de la tarjeta: el tercero son los minutos de espera entre cambios y el cuarto el escenario. Los tickets facturados reciben una factura genérica, siempre la misma.

Ver Simulación de tickets.

Convenciones

• Hora de México: las fechas que muestran la web app business, la API y los webhooks están en hora del centro de México, sin zona horaria. La única excepción es el header X-FF-Timestamp de los webhooks, en segundos Unix (UTC).
• Mes calendario: los límites del plan y los reportes mensuales usan el mes completo en hora de México.
• Fechas de entrada en la API: formato yyyy-MM-dd, en fecha de México, e incluyen el día completo.
• Respuestas de la API: valida siempre isSuccess; una respuesta HTTP 200 puede traer un error de negocio.

Tabla de equivalencias