Concepts

Terms used throughout the Fotofacturas documentation, and what each one is called in the business web app and in the API.

For: administrators and technical teams at client companies. The values of each catalog are in Catalogs.

How the account is organized

A client company uses Fotofacturas to get invoices for its collaborators’ purchase tickets. Its account is organized like this:

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…

That is: root association (the client company) → association RFCs, collaborators (with their own RFCs, tickets and invoices) and child associations (branches, companies, departments…), which repeat the same structure.

• The B2B user manages associations, collaborators, RFCs, tickets and webhooks from the business web app or the API.
• Collaborators upload photos of their tickets through any channel, and Fotofacturas turns them into invoices (CFDI).

Users

B2B user

The account of the person in charge at the client company. They sign in to the business web app with a username and password, and own the API token the company’s systems use to call the Enterprise API.

• Each B2B user is linked to a single root association.
• They can only view and modify the information in their own association tree. Any association, collaborator, RFC or ticket outside that tree is rejected.
• If Fotofacturas blocks them, they can’t sign in to the business web app and their token stops working until they’re unblocked.

Collaborator

A person (for example, an employee) who uploads tickets to be invoiced. They belong to one association and can have their own RFCs.

• They can upload tickets from the mobile app, the web app, WhatsApp or the embedded flow. The B2B user can also upload tickets on their behalf from the business web app or the API.
• They can be active or inactive. An inactive collaborator can’t upload tickets.
• Their email and phone number must be unique in Fotofacturas.

Root user

A record created automatically with every association. It isn’t a person: it’s the owner of the association RFCs and of the association tickets.

• In the API it appears in GetUsersByAssociation with isAssociationRoot: true, always first.
• It can’t be edited, deactivated or moved out of its association. Its RFCs and tickets are managed with the association APIs.
• It doesn’t appear in the business web app.

Account structure

Association

A unit of the client company: the company itself, a branch, an area, a department, a project or a sub-company. Associations form a tree with no limit on levels.

• Each association can have its own association RFCs, collaborators and configuration.
• Associations can’t be deleted; if one is no longer used, you can rename it.

Root association

The account’s main association, above all the others.

• Fotofacturas creates it when the account is set up.
• It can’t be moved within the tree.

Child association

Any association that sits under another one.

• The B2B user creates and edits it from the business web app or the API.
• It can be moved within the tree, but not under itself or under one of its descendants.

Account tree and subtree

• Account tree: the root association and all its descendants. It’s the scope of the B2B user, the plan, the reports and the webhooks.
• Subtree of an association: that association and all its descendants. API reports that take an optional associationId are limited to that subtree; without the parameter they cover the whole account tree.

Association configuration

Optional values that customize an association (UpdateAssociationConfig). If they aren’t set, Fotofacturas defaults are used.

Plan and limits

Plan

Rules about tickets and RFCs that are assigned to the root association and apply to its whole tree. Fotofacturas assigns it; you can check it in the business web app (Planes) or with GetAccountInfo.

Ticket limits

• An empty limit (null) means no limit; a limit of 0 means no tickets can be uploaded.
• Limits reset on the 1st of each month at 00:00, central Mexico time.
• All of the month’s tickets count regardless of status, except discarded tickets.

Multi-RFC type

Defines which RFCs collaborators’ tickets can be invoiced to (multiRfcType). Only Fotofacturas can change it.

Association tickets are always invoiced to the RFCs of that same association.

RFC limits

A disabled RFC doesn’t take up a slot, but reactivating it does count against the limit.

Tax information

RFC

The Registro Federal de Contribuyentes (Mexican taxpayer ID) the invoice is issued to. Each RFC stores its legal name, tax address and tax regimes; that set is called tax information (userTaxInfoId in the API).

• An RFC can be active or disabled. Only active RFCs are used for invoicing and count toward the plan limits.

Own RFC and association RFC

Constancia de Situación Fiscal (CSF)

The PDF the SAT issues with a taxpayer’s tax data (tax status certificate). An RFC is registered by uploading its CSF: Fotofacturas reads the PDF and extracts the RFC, legal name, address and regimes. If you upload the CSF of an RFC that’s already registered again, it’s updated and reactivated.

Tax regime, CFDI use and payment method

SAT data you specify when uploading each ticket (values in Catalogs):

• Tax regime: the regime of the RFC being invoiced. Only the regimes registered for that RFC can be chosen.
• CFDI use: what the invoice will be used for before the SAT (for example, G03 – General expenses). It must be valid for the tax regime.
• Payment method: how the ticket was paid (cash, card…). In the web app it’s called forma de pago; in the API, ticketPaymentMethodId.

Last 4 digits of the card

The ticket’s CardLastFour field. It’s required with a credit card (04) or debit card (28) and optional with other payment methods. In the test environment it also selects the simulator scenario.

Tickets and invoices

Ticket

A photo of the purchase receipt uploaded to be invoiced. Each photo counts as one ticket in the plan.

Ticket origin

The channel the ticket came in through (ticketOriginId): mobile app, web app, business web app, API, embedded flow or WhatsApp. All tickets are handled the same way regardless of origin: they count toward the plan, appear in reports and trigger webhooks. Values are in Catalogs.

Invoice (CFDI)

The digital tax receipt generated from the ticket. It’s delivered as two files:

• XML: the receipt that’s valid before the SAT. It contains the UUID (tax folio), issuer, recipient, line items and taxes.
• PDF: its printable version.

An invoiced ticket usually has both files, but it may have only one if that’s all the merchant provided.

Invoicing method

How the invoice was obtained (invoiceMethod): manual, automatic, automatic (retry) or automatic with corrections. In the business web app it appears as Tipo de facturación in the ticket detail.

Ticket status

The stage the ticket is in (ticketStatusId). The business web app and the reports group them into three: Invoiced (11), In progress (1, 3, 5, 6, 7, 8) and Rejected (10). The full list is in Catalogs.

• Every ticket starts at 1 (Created). 10 and 11 are final, although Fotofacturas can reopen a ticket; that’s why the current status is always the most recent one.

Ticket code

The result or rejection reason of a ticket (ticketCodeId, GetTicketCodes catalog). The status tells you whether the ticket is finished and the code tells you how it finished. For example, an illegible ticket has status 10 (Not invoiceable) and code Illegible ticket.

• While the ticket is in progress it’s 1 (Created, no result).
• Each code has a message for the user (userMessage).
• It’s the rejection reason shown in the ticket detail and in Reportes › Atención in the business web app.

The full difference between status and code is in Ticket flow.

Archived ticket and discarded ticket

• Archived ticket: a ticket taken out of the process. While archived, it isn’t processed automatically.
• Discarded ticket: a ticket that was archived while still in Created. It can’t be unarchived and doesn’t count in reports, lists or plan usage.

Integration

Business web app

The web application where the B2B user manages the account: dashboard, reports, ticket upload, companies and collaborators, plan, payments, API token and webhooks. See Business web app.

API

The API the company’s systems use to manage the account and upload tickets. See API.

API token

The B2B user’s key used to authenticate every Enterprise API request (Authorization: Bearer <token>). Treat it like a password. When you regenerate it, the previous one stops working immediately. Each environment (production and test) has its own token. You can find it in the business web app, under API y plan.

API permission

Authorization to use a specific Enterprise API endpoint. Fotofacturas enables them per account. Without the permission, the API responds No estas autorizado para usar esta API.

Webhook

A notification (POST) Fotofacturas sends to a company server when a ticket changes status.

• Event: the kind of notification: ticket.invoiced (invoiced), ticket.failed (not invoiceable) and ticket.status_changed (status change, including creation). The ping event is only sent when testing a webhook.
• Webhook: the combination of an association, an event, a URL and a secret. Each association can have one per event. If the ticket’s association has no active one for that event, the root association’s is used, if configured.
• Secret: the key (whsec_...) used to sign every notification so you can verify it comes from Fotofacturas. Each webhook has its own, and it’s only shown when you create or regenerate it.
• Delivery: one immediate send and up to 4 retries. The event ends up as delivered or failed and can be resent. History is kept for 45 days.

Set it up from the business web app (Webhooks) or the API. See the full guide in Webhooks.

Test environment and simulator

• Test environment: a separate environment for building your integration, with its own URL, token and data. APIs, permissions, validations and webhooks work the same as in production.
• Simulator: in the test environment tickets aren’t really invoiced. A simulator moves each ticket through a status path based on the last 4 digits of the card: the third digit is the minutes to wait between changes and the fourth is the scenario. Invoiced tickets get a generic invoice, always the same one.

See Ticket simulation.

Conventions

• Mexico time: dates shown by the business web app, the API and webhooks are in central Mexico time, without a time zone. The only exception is the webhooks’ X-FF-Timestamp header, in Unix seconds (UTC).
• Calendar month: plan limits and monthly reports use the full month in Mexico time.
• API input dates: yyyy-MM-dd format, as a Mexico date, covering the whole day.
• API responses: always check isSuccess; an HTTP 200 response can carry a business error.

Equivalence table