Skip to main content
POST
Fire resolves internally which fiscal provider matches the store’s country, asks it for the numbering, and hands you the data ready to print.
Three things before you integrate:
  1. There is no order id here. When you charge, the order does not exist in Fire yet. The orderCode is the only thing tying this request to the sale, so it must be the same string you later send when injecting.
  2. The response does not say the document is authorized. It says there are numbers to print. The authority’s approval arrives later, asynchronously.
  3. You request an operation, not a document type. INVOICE or CANCEL. Which fiscal instrument materializes it — invoice, credit note, cancellation event — is the country’s call, and not the point of sale’s business.
v1 is still alive, with no sunset date. If your integration already consumes it, you do not have to do anything: same contract, same behavior.v2 differs in one thing only: a CANCEL is checked against the account’s cancellation policy first — if the policy does not allow it, nothing is numbered. INVOICE behaves identically to v1, down to the HTTP status codes.

​
Migrating from v1

What your channel has to handle before switching the URL:
  1. A CANCEL can come back without document. That is the whole migration. Check requestStatus === "BLOCKED_BY_POLICY" (or simply document === null with printing.mode: "NONE", which you already handle for NOT_APPLICABLE).
  2. Show the person why. policy.cancellation.reason in one line, reasonDetail as the paragraph. Branch on code, never on the text.
  3. Do not retry. retryable: false — the policy will answer the same thing.
INVOICE requires no change at all: same request, same responses, same status codes as v1.

​
The full flow

1

You charge

The customer pays at the POS or the kiosk.
2

You request the numbering

You call this endpoint. Fire resolves the store, the issuer and the provider, and stores the request before going out for the numbers.
3

You print

Depending on printing.mode you print the fiscal receipt or a provisional ticket.
4

You inject the order

With your usual body, adding nothing to it. Fire correlates the sale with its numbering through the orderCode.
5

The authority approves

Minutes later. Fire receives the provider’s result and updates the order. If you want to see it, query this same request.
Fire never stops you on its own. Whatever fails, this endpoint answers with an explicit decision in policy.numberingFailure.action — not with an error that leaves you guessing.But the decision is not always to carry on: the account can configure that without a receipt there is no sale. Branch on action, never on the HTTP status:
  • CONTINUE (the default) — print according to printing.mode and inject the order. If it went out unnumbered, call again with the same orderCode: nothing completes it on its own, and a 202 nobody retries stays that way forever.
  • REFUND — give the money back and do not inject the order. There is nothing to complete later: retrying numbering for a sale you refunded would produce a receipt for something that did not happen.
In both cases: do not hold the sale or retry in a loop with the customer waiting.How many times to retry, on the CONTINUE path: twice. While retryable comes back true, call again with the same orderCode up to two more times. If it still has no numbers after the second retry, treat it as final: the sale is already injected with a provisional ticket, and what is missing gets resolved through support, not at the counter.With REFUND there is no retry at all: zero. The sale was refunded, and numbering it later would produce a receipt for something that did not happen.The cap is yours to apply. Fire numbers every attempt and stores it for support, but it does not cut you off on its own: if you call a fourth time, it asks the provider again. And the answer will not change by insisting — action does not depend on retryable, so what the third attempt says, the first one already said.

​
Headers

​
string
required
Your Fire API key, with the Fiscal Gateway (numbering) permission.The account and the vendor are derived from the key, never from the body. That is why the payload carries no accountId or vendorId: a credential cannot lie about who it belongs to.
​
string
required
A UUID identifying this attempt. Generate it once per sale and reuse it across the retries of that same sale.
This is not what prevents a duplicate document — the orderCode does that, being the natural key on both ends: if you repeat the same orderCode, you get the same document back even if you generate a new key.What this key adds is detecting that you reused it for a different sale: if the same key arrives with a different body, Fire answers 409 instead of numbering. It guards against a point-of-sale bug — not regenerating the key — that would otherwise go unnoticed.
​
string
Optional. An identifier of your own for this operation — the one you already use in your logs.Fire stores it with the request and returns it in correlationId. It changes no behaviour: it exists so that, when something fails, you can cross your records with ours without matching by timestamp and orderCode.If you do not send it, correlationId comes back null.

​
Body

It is a payload of its own, not the order injection one: only what numbering requires. The names match the ones you already use (store, device, orderCode) so you can build it by trimming what you have, but do not send the full order body — no products, payments or shippingMethod. Five fields, and none of them is an authority code.
​
string
required
The sale’s code. It is the idempotency key, both Fire’s and the provider’s.It must be unique per account and country, and the same one you later send when injecting the order. If two stores of the same account use the same orderCode, Fire stops with 409 before issuing: without that stop, the second store would print the first one’s sequential.
​
string
required
The order’s creation date and time.It has two uses, and they are worth keeping apart. It is the fallback for the issue date — the primary source is the store’s open business day, because a sale made after midnight belongs to the day that is still open, not to the clock’s — and it also travels to the fiscal provider as the wall-clock time the sale happened, for regimes that require it on the receipt.With no timezone (2026-08-12 17:26:09), it is read as UTC. It always leaves for the provider normalized, with Z.
​
string
default:"INVOICE"
What you are asking for. One of:
  • INVOICE — number the sale.
  • CANCEL — void it.
You request an operation, not a document type. Which fiscal instrument materializes it is the country’s call: in Ecuador a cancellation is a credit note with its own run of sequentials; in Brazil it is a cancellation event that produces no new receipt.
To void, send the sale’s same orderCode with operation: "CANCEL". Nothing else: no fiscal keys, no original document number, no Fire identifiers.Fire finds the document to compensate through the natural key —country + orderCode + operation— and tells you which one it matched in document.compensates. Your point of sale does not need to store anything of ours in order to void.
​
object
required
The issuing store. From code, Fire resolves the country, the issuer’s fiscal identity and the establishment — do not send those yourself.
​
object
required
The issuing device. It is the same block you already send when injecting orders — nothing needs to be added to it.
Do not declare the point of emission. There used to be an externalId the channel used to report it; it was removed. The authority assigns it under the issuer’s tax id and the point of sale does not speak that language: the provider now resolves it from the uid, just as it does with store.code.It comes back in countryData.puntoEmision, with the value it was actually issued under.
​
array
What was charged. It is the same payments.totals you already send when injecting orders — send it as is, whole.
What is sent today, per country:Send taxes[] with amount, not a loose percentage. One element per tax, with name, base, rate and amount — the same shape in every country.The amount has to come computed by you, who charged and printed it. Where the fiscal identifier is a hash of the invoice —the Colombian CUFE— deriving it from the percentage forces someone else to round, and if they round differently than the register, the identifier stops matching the paper the customer is holding.
Amounts travel unscaled. Send the number exactly as you charged it: 50000, 42016.81. Do not multiply it by 10,000.That scale does exist, but it belongs to another path: the order’s events (order.completed and the rest) carry the same amounts as an integer in a string ×10,000, because that is how FIRE stores them. Not here.If you integrate both paths, that is the only conversion you have to make — and doing it backwards means declaring ten thousand times the amount.
Send the amount exactly as you charged and printed it. Fire neither rounds it nor reformats it: the number in the request and the one on the receipt are the same.It matters because there are regimes where the fiscal identifier is a hash of the invoice — the Colombian CUFE, for example. If the amount going into the hash is not the one printed, the identifier does not correspond to the invoice the customer has in hand.
​
object
Who bought. It is the same block you already send when injecting orders: send it whole, as is. Do not trim it, do not rename it, do not translate it.Fire reads from there whatever the country’s regime needs and discards the rest. That it is the complete block and not a subset is deliberate: if each country demanded its own trim, the point of sale would have to know which field each authority looks at — which is exactly what this contract avoids.The remaining fields —uid, email, phone, gender, birthdate, externalId— travel and are not fiscalized. Fire does not forward them to the fiscal provider: they are not the authority’s business.
The values Fire expects in govIdType:There is no guard today: whatever you send, the sale gets numbered. The field travels as is to the fiscal provider, so a value outside this list does not break the numbering — it reaches them, and they are the ones who have to recognize it.That is why it pays to stick to it: a CEDULA where CI belongs, or two different spellings for the final consumer, are documents that come out wrong without anything failing along the way.
Final consumer: send both fields, translating neither.
You send the number, same as in any other sale. What you must not do is convert it into what each regime requires: the DIAN’s generic NIT 222222222222 in Colombia, the absence of a recipient in Brazil. That is resolved by the fiscal provider, who is the one certified before the authority.It is deliberate: that rule changes per country and per resolution of the authority, and it should not force you to deploy the point of sale when it changes.Fire does not touch it either. The client block travels as is to the provider: we do not fill in the number, we do not normalize it and we do not validate it. What you send is what they receive.
​
object
Key-value of the sale: what changes on every transaction and some country requires.It is opaque to your integration: Fire does not interpret it, it carries it. Valid keys depend on the store’s country, and an unknown key is rejected with 400 — a Fire error is preferable to a made-up field travelling to the authority.In most cases it goes empty: what is constant about the store is not sent here, it is configured once (see below).

​
What you do not send: the store configuration

Everything that is constant about the store is configured once in the backoffice and travels on its own: the issuer’s fiscal identity, plus a key-value block per country for the attributes that country’s provider needs.
That key-value lives in the store’s fiscal configuration, separated by country. It is the reason this endpoint is the same everywhere: what is country-specific is administered, not programmed and not sent on every sale.If your integration starts needing a new field per country, the answer is almost always to configure it there — not to add it to the payload.
​
string
Only for CANCEL, and only when automatic resolution is not enough: a cancellation referencing a document from another order, or several invoices for the same one.In the normal case, do not send it. Fire finds the original through the natural key, so your point of sale does not need to store any identifier of ours in order to void.

​
Response

​
string
The request’s identifier in Fire. It is what you query the outcome with later.
​
string
Echo of the code you sent.
​
string
Echo of the x-correlation-id header, or null if you did not send it. It is for traceability: it takes no part in numbering or idempotency.
​
boolean
true if this request already existed and was returned as-is, without numbering again.
​
string
The status of the numbering: did I get numbers to print?Six possible values. The first four describe how the attempt ended; the last two say there was no attempt — because this store does not number, or because the cancellation policy did not allow the void.
PENDING does not mean “there is no receipt”: it means “we do not know”. Communication dropped and the provider may have numbered, consumed a sequential and issued the document without us finding out.Retry with the same orderCode. Fire resumes the request and asks the provider again; if it numbered the first time, you get that same document instead of a new one. Numbering again under a different orderCode would declare the same sale twice to the authority.
NOT_APPLICABLE and BLOCKED_BY_POLICY are not stored: neither creates a fiscal request (fiscalRequestId: null) nor appears in the order’s events. The first exists because the POS always calls this endpoint — that is how it discovers whether the store numbers — and answering with an error would make every sale of a gateway-less store look like a failure. The second, because nothing was numbered: there is no document to reconcile against the authority, and a stored request without one would pollute exactly the table reconciliation reads from.
​
string
The status of the document before the authority: did it approve it?PENDING · AUTHORIZED · REJECTED · CANCELLED
In this response it is always PENDING: there are numbers, there is no verdict. Only the provider’s result moves it, and that arrives later. Collapsing the two statuses into one is the mistake that makes a POS believe a sale is authorized when it is merely numbered.
​
string
Which environment Fire numbered in: SANDBOX or PRODUCTION.It is ours, not the authority’s. It comes from the account’s fiscal configuration —which is per vendor and per country, so the same account can have Ecuador in production and Colombia in sandbox— and it is frozen on the request: if the configuration changes tomorrow, this value still says what this sale was numbered with.
Do not confuse it with the authority’s environment, which travels inside countryData in the country’s own vocabulary (ambiente: "PRUEBAS" | "PRODUCCION" in Ecuador). They are two different facts: one says which configuration Fire issued against, the other what the tax authority declared. They normally match — and when they do not, that is exactly what you need to be able to see, which is why neither is derived from the other.
null when requestStatus is NOT_APPLICABLE: nothing was numbered, so there was no environment to number in.
​
object
What you need in order to print, without knowing about countries. null if nothing was numbered.
sequential and serie are no longer here. They are country-shaped pieces —in Ecuador the serie is six digits split in half— and they live in countryData under the name their authority gives them. Only what means the same everywhere stayed in document.
​
object
The country’s identifiers, in its authority’s vocabulary and ready to print.
The block changes entirely per country, and so do the labels. In Colombia documentLabel is FACTURA ELECTRONICA DE VENTA and authorizationLabel is VALIDACION PREVIA — those are the DIAN’s names, not a variant of the Ecuadorian text.ambiente arrives translated in both countries, and that is the point: the DIAN encodes 1 as production and the SRI encodes it as testing. Fire resolves it so no channel has to carry that table.
It is an open map: the keys are defined by each country’s tax regime, not by this contract. A new country comes in without the response’s shape changing.
The values come translated, not as authority codes. The provider sends ambiente: "2" —that is how the SRI defines it— and what arrives here is "PRODUCCION", which is what the ticket says. Translating it on the channel’s side would mean every integrator carries its own copy of the authority’s table, and the first one to copy it wrong prints “PRUEBAS” on a production invoice.
Do not look for fixed fields: iterate the keys that arrive. Ecuador brings claveAcceso, Colombia cufe, Brazil chaveAcesso. A channel reading countryData.claveAcceso outright works in Ecuador and breaks in the second country.

​
countryData by country

Today the gateway numbers in Ecuador and Colombia. Every country that comes in adds its tab here — and only that: the response’s shape does not change, because the block is open.
SRI receipts.
The number is composed by the provider, not by Fire. The format belongs to the regime —fifteen digits in three segments, article 18 of the Reglamento de Comprobantes de Venta— and it is known by whoever is certified before the SRI. If the regime changes the convention, it changes there and Fire does not need to deploy.document.documentNumber is an echo of this same value, so you do not have to reach into the country block just to print. It is the same fact, not two.
The three loose pieces are not a substitute. The Reglamento allows omitting the sequential’s leading zeros, so 001-020-123 can be just as legal as 001-020-000000123. Composing the number yourself out of establecimiento, puntoEmision and secuencial means adopting a convention that is not yours to adopt: print numeroComprobante exactly as it arrives.
​
object
The issuing branch, for the receipt’s header.
​
object
The issuing legal entity: the receipt’s header and footer, already resolved.
store, company and document.compensates come in every response of this endpoint, including NOT_APPLICABLE and the 400 for a store that cannot issue, including the idempotent retry — the channel needs the header both the first time and when it repeats after a network drop.Queries (GET by fiscalRequestId or orderCode) return them as null: they are resolved at issue time and are not stored with the request. If your integration needs them to reprint, use the printing data.
​
object
Key → the exact string to encode, ready to render. For example { "qr": "1208202601…811" }.It is an open map because each country’s receipt does not always carry the same thing, and a country may need more than one element. Iterate the keys that arrive, do not look for fixed fields.Fire does not generate images: size and resolution depend on your printer, and only whoever prints knows that.
​
object
What you may print. It is a legal rule of the country, not a derivation of whether there is a document: which is why Fire resolves it and not each channel.
​
object
What to do with the sale when numbering failed. The account decides, not you: it is configured per vendor in the backoffice and Fire returns the decision already made, just like printing.It travels always, including when numbering succeeded. Branch on the value, never on the presence of the key.
What this policy decides, and what it does not.It decides one single thing: whether the register gives the customer their money back when the sale was charged and could not be numbered. Nothing else.It does not decide what you print — that is printing, and it is a legal rule of the country, not anybody’s preference. It does not block sales: by the time you request numbering the customer has already paid, so there is no sale left to block. And it does not depend on retryable: a failure that heals on its own is still a failure, and if the account configured a refund, you refund.The account configures it, per country and per vendor, in the backoffice. You neither derive it nor negotiate it: Fire returns it resolved, just like printing. If it is not configured, if it carries a value we do not recognize, or if we could not read it, CONTINUE applies — the default points that way on purpose, because a badly written configuration must not be able to trigger refunds.Two cases ignore it entirely, however it is configured: when nothing failed (GENERATED or NOT_APPLICABLE), and when what failed was a cancellation (operation: "CANCEL") — there the order exists and its money was not refunded, so there is nothing to give back.The other two fields are the decision’s receipt: configVersion says which configuration decided it and resolvedFrom with what context. They let you reconstruct a refund from three weeks ago even if the account is configured differently today.
​
object | null
What the cancellation policy said about THIS void. In v1 it is always null.null means “it was not asked”, not “it could not be evaluated”: issuing is not voiding, so on INVOICE there is nothing to consult. The key always travels — same criterion as the rest of the block — so your channel branches on the content and never on the presence of a key.
Where it is configured and what happens without it. The policy is set per account, country and vendor. If the vendor has none, if it carries a value we do not recognize, or if we could not read it, CONTINUE applies — and that default points that way on purpose: a badly written configuration cannot trigger refunds. You will see it as configVersion: null.
Cancellations never ask for a refund. If what failed was an operation: "CANCEL", the response carries CONTINUE regardless of configuration: there is no charge to reverse, because the sale already happened and still stands. What is missing is the cancellation document.PENDING does obey the configuration. The provider not answering is not an exception: for the register, no number means no receipt. You tell it apart from a rejection only by resolvedFrom.requestStatus. A PENDING carries a failureCode like any other — a timeout arrives as PROVIDER_TIMEOUT / TECHNICAL — so do not look for it in the absence of a code.It carries a consequence worth keeping in mind: the provider may have numbered anyway and been unable to tell us. If that document shows up later, a receipt will exist for a sale you refunded, and it has to be cancelled.

​
What to do when REFUND arrives

Three steps, in this order. The third one is the one people forget.
1

Give the money back at the counter

The customer already paid. That refund is yours to make with your payment method — Fire moves no money and does not know whether you refunded.
2

Do not inject the order

Do not send it to Create order. That sale did not happen: injecting it would leave a charged order with no fiscal receipt, which is worse than not having it.
3

Report it with Record lost sale

POST /orders/lost-sales, copying policy.numberingFailure.lostSaleReason into reason. It is the only step that tells us.
If you skip step 3, that sale exists nowhere.There is no order — you did not inject it — and no event. On our side all that is left is the fiscal request that failed, which says numbering did not work but says nothing about money having changed hands or about you refunding it. Nobody finds out that store stopped selling, and the cash close cannot explain it.The report is the only trace. Retrying is safe — it is idempotent by orderId + vendor — so if you lost connectivity right there, queue it and resend.

​
When what fails is a cancellation

Cancelling is two calls, in this order: first you request the credit note’s numbering here (operation: "CANCEL"), and only then you call Cancel order. If the credit note’s numbering fails, this endpoint answers just as always: never a 4xx. PENDING and FAILED_RETRYABLE come back 202; FAILED_FINAL comes back 200. The body carries the failure with the reason and the fiscalRequestId to escalate with. And policy.numberingFailure.action always comes back CONTINUE, with lostSaleReason: null, regardless of how the account is configured. It is not an arbitrary exception: there is no charge to reverse here. The sale already happened, it is in orders and it still stands — what is missing is the cancellation paperwork, not the money.
But the order does not get cancelled. The cancel call validates that the credit note exists, and without it answers 409 FISCAL_CREDIT_NOTE_MISSING.That is the big difference from a sale: on a sale the failure lets you carry on with a provisional ticket; on a cancellation it leaves you stuck, with the order still standing.What to do: if retryable is true, call here again with the same orderCode — Fire resumes the request. If it is FAILED_FINAL, read failure.scope and escalate with the fiscalRequestId: there is nothing the register can do, and nobody retries it for you.
A FAILED_FINAL on the credit note does not heal with time. That request is stored as final, and calling again with the same orderCode — even once the provider is healthy — returns the same answer without asking it again. It is not a retry that fails: it is the archived answer.The consequence is that the order can no longer be cancelled through this path: it stays live in Fire, with its invoice, and Cancel order answers 409 FISCAL_CREDIT_NOTE_MISSING forever. Escalating here does not mean “report it and retry later” — it means report it, because this no longer clears on its own.
​
object
Why there is no document. null when there is one.
PROVIDER_TIMEOUT and PROVIDER_CONTRACT_VIOLATION arrive with requestStatus: "PENDING", not with a definitive failure. In both cases the provider may have numbered without us being able to read it: issuing another receipt outside would declare the same sale twice to the authority.
​
string
Our adapter identifier (hio), not the provider’s name. It says which integration numbered this sale. null on NOT_APPLICABLE: none was involved.
​
object
Who numbered, on the provider’s side. It has a shape —all three fields are part of the contract— and that is why it travels apart from the opaque bag. null when nothing was numbered.
​
object
The provider’s diagnostic bag, exactly as it arrived. Opaque: it has no guaranteed shape and nobody should program against its keys — they change with no notice and without versioning the contract. It is there to paste into a ticket, not to branch on.null when the provider sent nothing.
It is the same field that travels in the event, same name and same content. All three provider fields —providerCode, providerIdentity, providerMetadata— read the same here and in fiscalRepresentation: what you learn at one end works at the other.

​
Status codes

The HTTP code does not tell you whether you got a receipt. 200 may be an idempotent retry that numbered perfectly, or a definitive rejection by the authority. Branch on printing.mode and requestStatus, never on the code alone.
The call is synchronous, but it has a time budget. The customer is standing at the register: Fire waits a few seconds for the provider and, if it does not answer, cuts and returns 202 instead of leaving the sale hanging.That 202 is not a promise that it will reach your POS later through another channel: it is Fire saying “I have no numbers yet, print provisional and carry on”.To complete it, retry with the same orderCode. Fire resumes the request and asks the provider again. It is rare, but it exists because the alternative — failing the sale — is worse.

​
What to do with each response

What follows describes the CONTINUE path, which is the default and what most accounts run. If policy.numberingFailure.action says REFUND, the instruction is inverted: you do not inject the order and do not retry numbering — you refund and report the lost sale.Everything else about each status — what it means and whether the failure fixes itself — holds in both cases.
printing.mode: "FISCAL_DOCUMENT". Print the receipt with document.documentNumber and draw the codes from graphic. Inject the order with the same orderCode.If printing.reason is ISSUED_OFFLINE, the receipt is valid but was issued under contingency: print the legend that country requires.
The provider did not answer: timeout or dropped connection. It may have numbered and consumed a sequential without us finding out.Print the provisional ticket and inject the order. Then retry with the same orderCode: Fire resumes the request and asks the provider again, so if it numbered the first time, you recover that document.
Do not assume the sale ended up without a receipt. Issuing a new one through another path may declare the same sale twice to the authority.
The provider answered that it cannot right now. Unlike PENDING, here we know for certain that nothing was numbered.Print provisional, inject the order and retry with the same orderCode.
Retrying with the same body will give you the same thing. Read failure.message, which carries the real reason, and failure.scope, which says whose problem it is:
  • FUNCTIONAL — some value the tax authority does not accept. It is fixed in the sale or in the store’s configuration.
  • TECHNICAL — the integration with the provider is broken. The sale is fine; what fails is the connection to whoever assigns the numbers. Nobody at the register can fix it.
Either way: print the provisional ticket, inject the order and escalate with the fiscalRequestId. With CONTINUE, the sale ends up charged without a fiscal receipt — that also travels in the order’s events, so you can compensate for it. With REFUND there is no order and no event: the only trace is the lost-sale report.
PROVIDER_AUTH_FAILED is not a provider outage. It answered, and fast: 742 ms in the example. What it rejected is our credential —wrong, revoked or rotated on their side— so it is configuration, not something transient: that is why retryable is false and the status is FAILED_FINAL rather than PENDING.If you see PROVIDER_TIMEOUT with requestStatus: "PENDING" instead, then the provider really did not answer in time — and there retrying is worth it.Note the company block in the example too: identity arrives for the header, but countryLines and legends come back empty because there is no document declaring anything.
It is not an error. This vendor has no fiscal representation: there is nothing to number and no request was created (fiscalRequestId: null).Print your usual ticket and inject the order normally. It is the expected answer for aggregators, countries with no fiscal gateway and businesses with numbering switched off.
store and company come here too. Nothing was numbered, so you get the issuer’s identity and not the fiscal apparel (countryLines and legends empty). It is the same block as in any other response: there is no separate shape to learn for this case.
In these cases no fiscal request was created: fix it and call again.If you get a 404 with a store-not-found message, check that your API key belongs to the vendor that owns that store — the message includes which vendor it searched against.The 400 for a store that cannot issue carries the issuer’s identity in data. That is the case of a store with no tax id or not enabled: the sale already happened and you still have to print a provisional receipt, so the header travels with the error.
Always call it. This is how you find out whether the store numbers.You do not need to sync configuration or decide per country: if that vendor has no fiscal representation, the answer is 200 with requestStatus: "NOT_APPLICABLE" and printing.mode: "NONE" — you print your ticket and carry on. It is not an error and no request is created.It is the same branch you already have: you branch on printing.mode, not on the HTTP code.

​
Voiding

You send the sale’s same orderCode with operation: "CANCEL". Nothing else.
The response has the same shape as an invoice’s. Three things change:
The credit note has its own numbering. It does not continue the invoices’: in the example, the invoice is 005-004-000000068 and its cancellation 005-004-000000002. They are two different runs under the same establishment and point of emission.
A cancellation is a new fiscal receipt, not a deletion. The original invoice still exists before the authority and must be kept: what the credit note does is compensate it.That is why GET /numbering?orderCode=… returns two documents for that order.

​
The policy can say no

In v1 a CANCEL always numbers; here Fire first asks the account’s cancellation policy, and if it does not allow it, nothing is numbered. Two steps, in this order:
1

Fire finds the original document

By the natural key, the same way v1 already did. If there is no document to void, there is no point in going further.
2

Fire asks the cancellation policy

It looks up the order — the one that has the context the policy evaluates: country, fiscal status, whether the buyer identified themselves, how many minutes since authorization — and runs Fire’s baseline rules plus the rules the account configured.
3

It numbers, or it blocks

If the policy allows it, everything proceeds as usual: credit note, 201, document.compensates pointing at the voided document. If it denies, nothing is numbered: 200, requestStatus: "BLOCKED_BY_POLICY", document: null, and the reason in policy.cancellation.
Which rules run here, and which do not.The ones answerable from the order: its status, the fiscal status, the country, whether the buyer identified themselves, the minutes since authorization, and whatever the account configured.The credit-note rule does not run. The cancellation policy has a baseline rule that denies when it is missing — and it does apply to POST /cancel — but here it would ask this endpoint for a credit note to exist before issuing it: that is exactly what it is about to create.The business-day rule does not run either, for the same reason: it is a condition for cancelling the order, not for voiding the receipt.The question asked here is “can this sale be voided?”, not “can this order be cancelled?”. That one is answered by Cancellation eligibility.
The policy fails open. If Fire cannot evaluate it — the order is not found, the account’s configuration cannot be read — it numbers anyway. A legitimate void is never blocked because Fire could not answer its own question. Only an explicit DENY blocks.
Why a policy rejection is a 200 and not a 4xx. In this endpoint the HTTP code describes what happened to the REQUEST, not to the document — and that decision predates the policy: the authority’s definitive rejection also comes back 200, and so does a vendor with no fiscal representation. If the tax authority saying “no” is a 200, our policy saying “no” cannot be a 409: your channel would read it as a transport error and retry something that will not change by insisting. The blocked response is deliberately shaped like NOT_APPLICABLE, which your channel already handles: same document: null, same printing.mode: "NONE" (with reason: "CANCELLATION_NOT_ALLOWED"). If you branch on printing.mode — which is what this page already asks you to do — a NONE already protects you from printing an invalid receipt. Two things worth noting:
  • retryable: false. Insisting does not change the policy’s answer. What has to change is the account’s configuration, or the order — not the request.
  • policy.numberingFailure.lostSaleReason is null. A blocked void is NOT a lost sale: the sale stands and so does its money. Reporting it would put money in the cash close that was never given back.
​
string
default:"es"
It goes in the URL:
Language for policy.cancellation.reason and reasonDetail: es, en or pt.It only affects Fire’s own rules, which ship with labels in the three languages. The text of a rule the account configured comes back exactly as the account wrote it, in whatever language it was written.
BLOCKED_BY_POLICY is never persisted. Nothing was numbered, so there is no document to reconcile: it does not appear in the queries by fiscalRequestId or orderCode. If you need the verdict, it is in the response of this call — and only there.

​
If there is nothing to void

If the sale was never numbered —because the store does not invoice, or because numbering failed— the cancellation answers 400:
It is a 400, not a failure inside a 200. It is the one important difference between voiding and invoicing: when invoicing, an authority rejection travels as a successful response with requestStatus: "FAILED_FINAL", because it is the answer to your question. Here there is no question to answer — you asked to compensate something that does not exist.Your point of sale prints its internal cancellation receipt and carries on.

​
When the void does not settle right away

Voiding has the same uncertain outcomes as invoicing, and it is worth saying out loud because it is easy to assume a void always closes.
A refusal leaves the sale invoiced. If the void comes back FAILED_FINAL, the original document was not compensated and still has fiscal effects. This is not an intermediate state the system recovers from on its own: there is no automatic retry.Measured in production across 72 cancelled orders: 67 closed the chain, 3 were left waiting for confirmation and 2 were refused. That ~7% does not resolve without intervention.
Cancelling the order and voiding the document are two different things. Your order can be cancelled instantly while the fiscal void is still in flight. If you need fiscal certainty — a book close, a reconciliation — query the document; the order status will not give it to you.

​
When the instrument is not a credit note

In Ecuador a cancellation produces a new document. In other countries it does not: in Brazil it is a cancellation event that generates no receipt, and there the response arrives with status: "CANCELLED" and document: null. It is not an error — it is the correct outcome of that operation in that country. That is why you request an operation and not a document type: the instrument is the tax regime’s call.

​
Querying a request

There are two read endpoints, and they exist for when the normal path is not enough: you lost the synchronous response, or you want to see whether the authority already approved without waiting for the event. In day-to-day operation you should not need them — the data arrives through the order’s events.
  • By identifier — GET /numbering/{fiscalRequestId}.
  • By order — GET /numbering?orderCode=…. It returns items[], because an order may have two documents: the invoice and the cancellation compensating it. It is the one you use when you lose the response to a network drop — the orderCode is all you have in hand.
When the authority approves, documentStatus becomes AUTHORIZED.
Both queries exist under /api/v2/… too, re-exported from v1 unchanged: querying does not change with the cancellation policy. A CANCEL that came back BLOCKED_BY_POLICY never shows up here — nothing was numbered, so there is nothing stored to return.