Console manual

This manual is for the person who uses the service, not for whoever programs against it: whoever reviews readings, whoever pays the invoice and whoever gives a colleague access. It can be read from start to finish without ever having opened the console, and it also works for looking up a single section on the day you need it.

The console itself is in Spanish, so this manual quotes its labels exactly as they appear on screen, in «angle quotes», with an English gloss next to them the first time: «Resumen» (Overview).

The technical side —how a program of yours connects to ours— is in the integration guide and in the API reference. You do not need it here.

Why this manual is outside the console

Because the three situations in which you need it most are precisely the ones in which you cannot get in to read it: the verification email does not arrive, you sign in and it tells you your user does not belong to any account, or the account is suspended. That is why this page is public and asks for no password.

Part one: what you are buying

What the service does, in one sentence

You give it an electricity or gas invoice as a PDF and it gives it back to you read: the data printed on it, already split field by field, so that your program can use it without anyone typing it in.

That is all it does, and that is deliberate. The service reads; what is done afterwards with what it read —comparing tariffs, working out a saving, filing— is up to whoever uses it.

Which files it accepts

• Electricity and gas invoices. If the document carries both, that works too: it is called a dual invoice and the result comes split, one part per supply.
• PDF only. Today neither a photo nor a loose scanned image is accepted: if the file is not a PDF, the reading is created as failed with the reason unsupported_file_type (file type not accepted).
• Short documents. The limit is 10 pages per file, and between 8 and 10 MB depending on the plan. Above that, the reading is created as failed and tells you why.

A file that does not meet these does not break the request and is not charged: it is recorded as a failed reading, with the reason written down, and you see it on the Readings screen like any other.

What a reading is and what it gives you

A reading is a file you have sent to be read. It is the unit of everything: of what is counted, of what is charged and of what is reviewed. A PDF sent once is one reading, whether it goes well or fails.

Every reading goes through four statuses, and you will see them under these names:

From a completed reading you get, besides the file's record (name, pages, date, which of your API keys sent it), the invoice as read. On the reading's screen, in the «Factura» (Invoice) tab, each field has its own row with its label. This is what each label is and the field of the Bill object behind it —the name a program sees—:

The last six are breakdowns: they are long, so they are shown folded, and they are never edited.

There is a third tab called «JSON»: it is exactly the same content, but written in the raw format a program receives. If you are not going to paste it to anyone, you do not need it.

Your invoices do not train our reader

The invoices you upload are read, returned to you, and that is the end of their role. They are not used to improve the reader.

The reader is tuned against a separate set of invoices, gathered and reviewed by us, which is kept somewhere else and is not fed from what comes in through the service. Nothing you upload goes into that set, neither with your name nor without it.

It is not a statement of intent: the separation is checked by the test suite itself, which fails if anyone connects the two. You can ask us to show you.

What we keep, where and for how long

We keep two things from every invoice you upload: the original PDF exactly as you gave it to us, and the reading we obtained from it.

Today we do not delete them. There is no expiry date and no automatic deletion after so many months. They stay for as long as the relationship lasts, and we do this on purpose for three reasons: if one day you dispute an invoice with your comercializadora, the document is there; if we improve the reader, we can read the same page again and give you a better reading without you having to upload it again; and if a charge surprises you, we can show you where it came from.

That is today's policy, not a promise for ever. If one day we were to start deleting, we would say so here before we started doing it, not afterwards.

Where they are. In Google Cloud, in data centres in the European Union, encrypted at rest.

Who sees them. The people you add to your account, each one according to the role you give them — whoever reviews the queue opens the document because their job is to look at it; whoever does not have that role does not. On Spock's side, only whoever has to deal with an incident of yours.

If you need us to delete something. Write to us and we will sort it out with you. We tell you plainly: today there is no button for this, it is done by hand, so it is not immediate — and because of how the storage is configured, a deleted document still takes a few days to disappear completely from the internal copies. We would rather tell you this than promise you a button that does not exist.

When a reading goes through on its own and when it asks you to look at it

Almost all of them go through on their own. That is the idea of the service: that nobody has to look at an invoice unless there is a specific reason.

After reading, the service checks its own work. It checks what can be checked without knowing anything about your business: that the line items add up to the printed total, that the taxable base matches, that the dates are consistent, that the CUPS looks like a CUPS, that the consumption matches the prices, that the IVA is not missing, that no critical data is missing. Every thing that does not fit is recorded as a check with its severity: «Error», «Aviso» (Warning) or «Info».

Confidence

Confidence is a number between 0 and 1 that sums up those checks. It starts at 1 —everything fits— and every problem found takes something off it: a lot if a critical piece of data is missing or the document is incomplete, less if the only odd thing is that the IVA rate is missing. On screen it is shown as a percentage: «Confianza: 92 %» (Confidence: 92%).

It is not an opinion on whether the invoice is correct: it is how reliable our reading of it is.

The review policy

The policy is your rule: from which confidence you want us to warn you. It has two parts.

• The mode. «Marcar las dudosas» (Flag the doubtful ones) or «No marcar ninguna» (Flag none). With the second, nothing is ever flagged and there is no review queue to look at; everything is taken as good.
• The threshold. A number between 0 and 1. By default it is 0.85.

With the mode «Marcar las dudosas», an invoice is flagged for someone to look at when either of two things happens: a check of the kind considered serious has failed, or its confidence falls below your threshold.

The higher you set the threshold, the more invoices will reach you flagged. Raising it to 0.95 is asking to be warned at almost any doubt; lowering it to 0.70 is letting more things through unchecked. There is no right answer: it depends on what a misread figure costs you compared with what the time to look at it costs you.

What is flagged ends up in the review queue, which is where someone looks at it; the threshold is changed on its own screen.

Getting in

Signing up

Whether you can sign up on your own depends on how the environment is configured, and the sign-up screen, «Crea tu cuenta» (Create your account), tells you which of the three cases you are in:

• Open: you enter the name of your company or team, «Empresa o equipo», and sign in with Google or with email and password.
• By invitation: you also need a code that we give you. The screen tells you which plan and which discount that code brings before you create anything.
• Closed: we create the accounts. The screen tells you which address to write to.

A new account starts on the plan its invitation code names or, without a code, on Starter; and with a trial period if the environment has trials switched on. When the account is created you get a welcome email with the name of the account and a link to the console.

If you sign up with Google, the account is created straight away. If you sign up with email and password, there is one more step: verifying the email.

Verifying your email

When you sign up with email and password we send a link to that address, and the console stays on a screen that says «Revisa tu correo» (Check your email). Open the link and go back to that screen; the button «Ya lo he verificado» (I have verified it) is what finishes creating the account.

When you cannot get in

These are the three situations why this manual is public. Each has its own screen, and each has something specific to do.

«Revisa tu correo» and the email does not arrive

On that same screen there is a button «Reenviar el correo» (Resend the email). Use it before anything else.

If it still does not arrive:

1. Look in your spam folder. That link is not sent by our server: it is sent by Google's identity system, which is where your password is kept, and some corporate filters set it aside.
2. Check that the address shown on the screen is yours and is spelled correctly. If it is not, «Cancelar» (Cancel) takes you back to the sign-up to start with another one.
3. If you press «Ya lo he verificado» and it answers «Todavía no consta como verificado» (Not verified yet), the link has not been opened: it is not your fault, that click is literally missing.

«Tu usuario no pertenece a ninguna cuenta»

This message (Your user does not belong to any account) means your user exists and the password is correct, but that email is not registered in any account. It is what you see if you were invited at another address, or if you sign in with a personal Google account when the invitation went to your work one.

What to do:

• If your team already uses the service: ask the account's owner to invite you with this same email, the one shown on the screen. There is no other way to associate them.
• If you do not have an account yet: the screen offers to create one, «Crear una cuenta», when sign-up is open, or gives you the support address when it is not.
• The same screen has a button to sign out, «Cerrar sesión», and sign in with another address.

The account is suspended, or the subscription is not active

They are two different things and it is worth not mixing them up.

«Tu cuenta está suspendida» (Your account is suspended). It is our decision and it is lifted by hand. You can keep looking at what is already there, but no new readings or changes are accepted. What to do: write to the support address shown in the notice itself. No button solves it, and it is not a fault.

«Tu suscripción no está activa» (Your subscription is not active) or «Tu periodo de prueba ha terminado» (Your trial period has ended). Here you can get in and move around the console normally: what stops is reading invoices with live keys, whose API requests answer 402 (payment_required). Requests with test keys keep working. What to do: the notice takes you to the Billing screen to subscribe or reactivate, and, when that screen is not available in your environment, to the support address.

Two more notices, which do not stop you

These two appear in the same banner at the top, but they do not cut anything off. It is worth recognising them so as not to be alarmed.

«No hemos podido cobrar tu última factura» (We could not charge your last invoice). The charge failed and is being retried; meanwhile the service keeps working as before. What to do: update the card from «Pago y facturas» (Payment and invoices), in «Facturación» (Billing). It is a reminder, not a cut-off.

«Te quedan N días de prueba» (N days of trial left), with the trial readings you have left underneath. The trial period lasts fourteen days and also includes a number of readings that depends on the plan; it ends with whichever of the two runs out first. What to do: nothing, as long as the number is not close to zero.

Part two: the screens

The menu on the left is not the same for everyone, and that is on purpose. Two things trim it:

Your role. There are three —«Propietaria» (Owner), «Desarrolladora» (Developer) and «Revisora» (Reviewer)— and what changes between them is above all what you see in the menu. Every screen below says who sees it and who can change what; the full breakdown is in Members.

The environment. Three screens are switched on or off per environment, so they may not be there in yours:

• «Lecturas» (Readings, the history).
• «Cola de revisión» (Review queue).
• «Facturación» (Billing).

Overview (Resumen): is everything all right today?

It is the entry screen and answers at a glance "is there anything to look at?".

• Your plan: the monthly fee, how many readings it includes, how much each extra reading costs and the monthly cap on readings. If the account has no plan yet, it says so and invites you to write to us.
• «Este mes» (This month): the readings of the current month with a bar against those the plan includes, and the breakdown of how they ended. It counts only live readings: test ones do not appear here.
• «Últimas lecturas» (Latest readings): the last five, with their date and amount. Each file name is a link to its record.
• What is missing for the integration to work: if you have not configured the webhook, or if you do not have any production key yet, it says so here.

Not everyone sees all four blocks: whoever only reviews invoices sees the plan and little else, because the rest is data their role does not consult.

Usage (Uso): how much have I used and how much is left?

It is the screen that measures how much you have used the service.

You choose a date range —there are shortcuts for «7 días», «30 días», «Mes en curso» (current month) and «Mes anterior» (previous month), and you can enter your own dates— and a mode: «Producción (live)» or «Pruebas (test)». They are two separate counts and they never mix.

The range can be at most 92 days. If you ask for a longer one, the screen tells you before querying anything.

Below you will see six figures and a chart of readings per day. These are the figures, and it is worth reading them slowly the first time:

And there is an «Exportar CSV» (Export CSV) button, which downloads a file any spreadsheet opens, with the day-by-day detail of what you are looking at.

Readings (Lecturas): what happened to that invoice?

It is the complete history and the place you come to with a specific question: what happened to the invoice we sent on Tuesday?

You search with seven filters that can be combined: «Desde» / «Hasta» (from / to), «Estado» (status: queued, processing, completed, failed), «Revisión» (review: to review or not), «Modo» (mode: live, test or «Los dos modos», both), «Key», the API key that sent it, and «Origen» (origin), which is a free label your program can put on each upload —"web", "app", "nightly-load"— so they can be told apart later. The list is walked through with «Cargar más» (Load more), not with numbered pages, and always runs from the newest to the oldest.

Clicking the file name opens its record, with three tabs:

• «Resumen» (Summary): when it arrived, when it finished, how many pages it had, which API key sent it, in which mode, with which origin, how much it cost and with which version of the reader it was read (on screen, «Motor»). If it failed, the reason is here, in red.
• «Factura» (Invoice): the data read, field by field. If the invoice was dual, you will see one section per supply. Above each one, the checks that were made and its confidence. And if someone already reviewed this reading, a box with who resolved it, when and what they said about each invoice.
• «JSON»: the raw result, with a button to copy it. It is what you should paste into an email when you write to us about a specific reading.

If you open a link to a reading that does not exist or belongs to another account, the screen says so and offers to go back to the list. It does not insist on retrying, because there is nothing to retry.

Review queue (Cola de revisión): what do I have left to look at, and how do I resolve it?

Here is only what the review policy flagged. It is the day's work of whoever reviews invoices, and it is designed to be got through in one go.

By default the list opens on «Pendientes» (Pending), and can be switched to «Resueltas» (Resolved) or «Todas» (All). It can also be filtered by mode, origin and dates. Each row tells you, without opening anything: the date, the file, the invoice type, how many of its invoices are flagged (for example «1 / 2»), the reading's lowest confidence and which checks failed, summed up in one line (the column is literally called «Checks»).

When there is nothing pending, the screen does not show you an empty table: it says «Nada pendiente.» (Nothing pending.) and offers a button to see the ones already resolved. It is the difference between "there is no work" and "there are no results with these filters", and the console respects it.

How to resolve one

When you open a reading from the queue you will see the original PDF on the left and, on the right, one card per invoice in the document. At the top, the date, the API key, the origin and which policy was in force when it was read.

On each card there are three buttons, and you have to choose one:

• «Aceptar» (Accept) — what was read is right.
• «Corregir» (Correct) — something is wrong. When you press it, the fields become editable boxes: change whatever is wrong, and what you have touched is highlighted in amber. The long breakdowns (costs, consumption, prices) and the normalised address are not edited; the single fields are.
• «Rechazar» (Reject) — the whole invoice is no good. This one asks for confirmation, because it is the only one that says there is nothing usable.

When every invoice in the document has a verdict, the «Resolver» (Resolve) button at the bottom becomes active. A progress indicator tells you where you are: «1 de 2 facturas con veredicto» (1 of 2 invoices with a verdict).

Three things worth knowing before the first time:

1. Correcting does not change the reading. What you write is saved next to the reading, as what a person said about it; the result your program already received is not rewritten. It is recorded —who, when and what changed— and can be seen when opening that reading, but it does not patch a figure that has already been delivered.
2. It is resolved only once. If a colleague resolves it while you have it open, when you press «Resolver» it will tell you someone else got there first and show you their resolution instead of yours. Nothing is lost: that one was simply already done.
3. If the account is suspended or the subscription is not active, the «Resolver» button is there but does not respond, and hovering the mouse over it tells you why.

If the document has no file, or the PDF cannot be displayed in your browser —it happens with Safari on iPhone and iPad—, there is a link «Abrir en una pestaña» (Open in a tab) that opens it separately.

Review policy (Revisión): how much do I want it to ask me?

In the menu it is called «Revisión»; the screen is titled «Política de revisión» (Review policy). Two fields and a save button. It is the screen that decides how much work ends up in the queue.

• «Modo» (Mode): «Marcar las dudosas» or «No marcar ninguna».
• «Umbral de confianza» (Confidence threshold): a number between 0 and 1, with two decimals.

What they mean is explained in part one, in The review policy. Here you only need to know who can change it: only the account's owner. Whoever has the developer role sees the policy —they need it, because it explains why some readings arrive flagged and others do not— but cannot change it, and the screen tells them so. Whoever reviews invoices does not have this entry in the menu: the rule is set by whoever integrates, not by whoever looks.

Members (Miembros): who gets in, and what can each one do?

The list of people with access to this account. For each one: their email, their role, whether they have signed in yet and since when they have been in the account.

The three roles

What changes between them is, above all, which entries you see in the menu on the left.

«Propietaria» (Owner). Answers for the account. Sees everything and is the only role that can change the review policy, invite or remove people, and subscribe or change plan.

«Desarrolladora» (Developer). The role of whoever connects the service. Manages the API keys and the webhook, looks at usage and the history, and sees the review policy without being able to change it —they need it to understand why some readings arrive flagged—. Sees the list of members but cannot change it. Does not get into the review queue: reviewing invoices is not their job.

«Revisora» (Reviewer). The role of whoever looks at invoices and nothing else. Their menu is genuinely short: «Resumen» and «Cola de revisión» —and only «Resumen» where the queue is not switched on—. They do not see the API keys, the webhook, usage, the readings history, the list of members, the review policy, or «Facturación»: they do see the plan in the Overview, but the period's consumption, the charges and the invoices are the company's accounts, not the work of whoever reviews readings.

This is each one's menu, counting only the screens switched on in your environment:

If you are unsure which to give, the rule is simple: owner to whoever answers for the account and the payment, developer to whoever connects it, reviewer to whoever uses it to look at invoices. The role selected by default when inviting is «Desarrolladora».

Inviting someone

An «Invitar» (Invite) button, an email address and a role; you confirm with «Dar de alta» (Add them). The person is added straight away and gets an email telling them, with the name of the account, the role and the link to sign in.

Changing a role and removing access

The role is changed from the row itself, in a drop-down; it saves on its own. «Quitar» (Remove) asks for confirmation, and access is cut off as soon as that person makes their next request.

You can remove yourself, and the console warns you that you are going to lose access. What you cannot do is leave the account with no owner: if you try, the system refuses and tells you to name another one first.

API keys and Webhook: what they are, and what to hand to whoever develops the integration

These two screens are not for you to use: they are for producing two things that have to be handed to whoever programs the integration, usually someone with the developer role. What is done with them is in the integration guide; here it is enough to understand what they are.

API keys

An API key is a long password that identifies your company when a program of yours sends us an invoice. It does not identify a person: it identifies the program. That is why they are never typed by hand and are kept the way a password is kept.

Every API key has a mode, and that is the part worth understanding:

• «Pruebas (test)»: so that whoever programs can test without worry. They are not charged, they are counted separately and have their own monthly cap. They are real readings, with a real result; they simply do not go onto the invoice. Test mode has nothing to do with the trial period.
• «Producción (live)»: the working ones. These do count and are charged.

What you will see on the screen: the list of API keys with their name, their mode, a prefix —the first characters, which let you recognise it without showing it whole—, when it was last used, when it was created and whether it is still active. A «Nueva key» (New key) button to create one and another, «Revocar» (Revoke), for one you no longer want.

Three rules that matter:

1. The secret is shown only once. When the API key is created it appears on screen with a warning to save it now. If that window is closed without copying it, there is no way to recover it: you have to create another API key.
2. Revoking is immediate and cannot be undone. The API key stops working at once. If it was in use, whatever used it stops working too, so it is best to have the new one in place before revoking the old one.
3. There is a cap on active API keys. The screen itself says how many your account allows. If you reach the cap, you have to revoke one to be able to create another.

Creating and revoking is for the owner and developer roles.

Webhook

A webhook is an automatic notice to your server: you give us an address on your server, and every time a reading finishes we call it to tell you, without anyone having to keep asking "is it done yet?".

The screen has a field, «URL del webhook» (Webhook URL) —the address, which has to start with https://— and a save button. When you save, a signing secret appears: a string that lets your server check that the notice comes from us and not from a third party.

The «Desactivar» (Disable) button stops sending notices; it can be switched back on whenever you want. And there is a link, «Cómo verificar la firma» (How to verify the signature), that goes to the technical part of the documentation.

This screen is handled by owner and developer. Neither this one nor the API keys screen appears in the menu of whoever has the reviewer role.

Billing (Facturación): my plan, my invoice, my card and how to cancel

Owner and developer see it; only the owner subscribes, changes plan or opens «Pago y facturas». Whoever has the reviewer role does not have it in the menu and, if they reach it through a link, the console answers «Tu rol no permite ver esta sección».

How charging works

The model is the same in the three public plans, and understanding it avoids almost every surprise:

1. A fixed monthly fee, which already includes a number of readings.
2. A price for every reading beyond the included ones —the "overage"—, cheaper the bigger the plan.
3. A monthly cap on readings above which the service stops admitting more. It is not the same as the included ones: between them and the cap is the band billed as overage.

The public plans are Starter, Pro and Business, from smallest to largest. The prices, the included readings and each one's cap are on this screen and in the Overview, taken from the service's live configuration; this manual does not repeat them on purpose, so that it does not go stale the day they change. All the amounts you will see are without IVA. If none of them fits, write to us: there are bespoke plans that are not advertised.

What is on the screen

• Your subscription: the plan, its status, the current period, the next charge and the discount if there is one.
• «Lecturas de este periodo» (Readings this period): how many of the included ones you have used, and how much overage you have accrued with its estimated amount. It is an estimate: the invoice is what counts.
• «Facturas» (Invoices): number, date, period, total, status and the PDF to download.
• Two buttons: «Cambiar de plan» (Change plan) and «Pago y facturas» (Payment and invoices).

The statuses the subscription can have, as the console shows them and what they mean:

Subscribing, changing plan and cancelling

Subscribing opens Stripe in a separate window, you pay by card and come back on your own. The console confirms with a notice if the payment went through, or tells you it was not completed if you change your mind halfway.

Changing plan is done from the screen itself and is immediate. The console explains it before you confirm, and it is worth reading: the fee is adjusted for the days left in the period and the difference is charged at that moment; the readings made up to then are settled with the old plan and the following ones count with the new one.

The card, the tax details, the invoice history and cancellation are not in our console: they are behind the «Pago y facturas» button, which opens Stripe's portal. It is the place where the subscription is cancelled. If you cancel it, the screen says so with the date —«Tu plan termina el …» (Your plan ends on …)— and makes it clear that there will be no more charges; until that day everything stays the same.

All of this —subscribing, changing plan and opening the portal— is for the owner. The other roles see the screen, but without buttons.

If something does not add up

Before writing, two checks that solve half the cases:

1. Which account and which email does the banner at the top show? It is the most frequent cause of "I cannot see my readings".
2. Are you looking at the right mode? live and test are two separate worlds in «Uso», in «Lecturas» and in the «Cola de revisión».

And if you write: paste the reading's identifier or the content of its «JSON» tab, and the approximate date and time (in Europe/Madrid time, which is the console's). With that it is found in a minute. If what you saw is an error message with a code, the errors page says what each one means.

Checked against the service's code: what this page says comes from it, not from an earlier note.