fiscalisto 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/cli.js CHANGED
@@ -17,6 +17,7 @@ import { createInterface } from "node:readline/promises";
17
17
  import { parseArgs } from "node:util";
18
18
  import { FiscalistoError, VERSION } from "./core.js";
19
19
  import { Fiscalisto } from "./index.js";
20
+ import { createMock } from "./mock.js";
20
21
  // ── Salida ─────────────────────────────────────────────────────────────────
21
22
  const env = process.env;
22
23
  const color = process.stdout.isTTY && !env.NO_COLOR;
@@ -412,6 +413,17 @@ async function init(args, g) {
412
413
  done.push(installed
413
414
  ? `SDK: ${install.join(" ")}`
414
415
  : `SDK: falló «${install.join(" ")}», córralo usted`);
416
+ // pip installs into the environment only: also into the file a deploy installs from.
417
+ const requirements = join(dir, "requirements.txt");
418
+ if (installed && install[0] === "pip" && existsSync(requirements)) {
419
+ const listed = readFileSync(requirements, "utf8");
420
+ if (!/^fiscalisto\b/im.test(listed)) {
421
+ await appendFile(requirements, `${listed && !listed.endsWith("\n") ? "\n" : ""}fiscalisto\n`);
422
+ done.push("requirements.txt: fiscalisto");
423
+ }
424
+ }
425
+ else if (installed && install[0] === "pip" && existsSync(join(dir, "pyproject.toml")))
426
+ done.push("pyproject.toml: agregue «fiscalisto» a dependencies");
415
427
  }
416
428
  }
417
429
  // An example that stamps.
@@ -440,15 +452,20 @@ async function init(args, g) {
440
452
  line(dim("Webhooks en su computadora: fiscalisto listen --forward-to http://localhost:3000/webhooks"));
441
453
  });
442
454
  }
455
+ /** An invoice's status as the app shows it (the API's value goes in --status and --json). */
443
456
  const STATUS = {
444
- valid: green,
445
- pending: yellow,
446
- processing: yellow,
447
- rejected: red,
448
- canceled: dim,
457
+ valid: ["vigente", green],
458
+ pending: ["pendiente", yellow],
459
+ processing: ["timbrando", yellow],
460
+ rejected: ["rechazada", red],
461
+ canceled: ["cancelada", dim],
462
+ };
463
+ const status = (s, width = 0) => {
464
+ const [label, color] = STATUS[s] ?? [s, String];
465
+ return color(label.padEnd(width));
449
466
  };
450
467
  function showInvoice(i) {
451
- line(`${bold(`${i.series ?? ""}${i.folio ?? ""}` || i.id)} ${(STATUS[i.status] ?? String)(i.status)} ${money(i.total, i.currency)}`);
468
+ line(`${bold(`${i.series ?? ""}${i.folio ?? ""}` || i.id)} ${status(i.status)} ${money(i.total, i.currency)}`);
452
469
  line(` ${i.customer.legal_name ?? ""} ${dim(i.customer.tax_id)}`);
453
470
  if (i.uuid)
454
471
  line(` UUID ${i.uuid}`);
@@ -552,7 +569,7 @@ async function invoices(args, g) {
552
569
  if (!page.data.length)
553
570
  return line(dim("Sin facturas."));
554
571
  for (const i of page.data)
555
- line(`${(`${i.series ?? ""}${i.folio ?? ""}` || "—").padEnd(8)} ${(STATUS[i.status] ?? String)(i.status.padEnd(10))} ${money(i.total, i.currency).padStart(14)} ${(i.customer.legal_name ?? "").slice(0, 32).padEnd(32)} ${dim(i.id)}`);
572
+ line(`${(`${i.series ?? ""}${i.folio ?? ""}` || "—").padEnd(8)} ${status(i.status, 10)} ${money(i.total, i.currency).padStart(14)} ${(i.customer.legal_name ?? "").slice(0, 32).padEnd(32)} ${dim(i.id)}`);
556
573
  if (page.has_more)
557
574
  line(dim(`… hay más: --limit ${Number(values.limit) * 2}`));
558
575
  });
@@ -850,6 +867,7 @@ async function listen(args, g) {
850
867
  query: { limit: 1 },
851
868
  });
852
869
  let last = first.data[0]?.id;
870
+ let lastAt = first.data[0]?.created_at;
853
871
  if (json)
854
872
  line(JSON.stringify({
855
873
  status: "ready",
@@ -874,9 +892,17 @@ async function listen(args, g) {
874
892
  query: { limit: 100 },
875
893
  });
876
894
  const at = last ? page.data.findIndex((e) => e.id === last) : -1;
877
- fresh = (at === -1 && last ? page.data : page.data.slice(0, at === -1 ? 0 : at)).reverse();
878
- if (!last && page.data[0])
895
+ // The last one seen may be gone (test data reset): what came after it, by time, not
896
+ // the whole page again.
897
+ fresh = (at !== -1
898
+ ? page.data.slice(0, at)
899
+ : last && lastAt
900
+ ? page.data.filter((e) => e.created_at > lastAt)
901
+ : []).reverse();
902
+ if (!last && page.data[0]) {
879
903
  last = page.data[0].id;
904
+ lastAt = page.data[0].created_at;
905
+ }
880
906
  }
881
907
  catch (e) {
882
908
  note(red(`No se pudieron leer los eventos: ${e instanceof Error ? e.message : String(e)}`));
@@ -884,6 +910,7 @@ async function listen(args, g) {
884
910
  }
885
911
  for (const event of fresh) {
886
912
  last = event.id;
913
+ lastAt = event.created_at;
887
914
  if (wanted && !wanted.includes(event.type))
888
915
  continue;
889
916
  const body = JSON.stringify(event);
@@ -891,7 +918,9 @@ async function listen(args, g) {
891
918
  status: null,
892
919
  ms: 0,
893
920
  };
894
- if (target) {
921
+ // A server that isn't answering (restarting after a change) gets the event again, as
922
+ // a real delivery would, instead of losing it: up to a minute, then it moves on.
923
+ for (let tries = 0; target; tries++) {
895
924
  const timestamp = Math.floor(Date.now() / 1000);
896
925
  const started = Date.now();
897
926
  try {
@@ -916,6 +945,11 @@ async function listen(args, g) {
916
945
  error: e instanceof Error ? e.message : String(e),
917
946
  };
918
947
  }
948
+ if (result.status !== null || tries >= 20)
949
+ break;
950
+ if (tries === 0 && !json)
951
+ note(dim(`${event.type} ${event.id}: ${target} no contesta; reintento cada 3 s…`));
952
+ await sleep(3000);
919
953
  }
920
954
  if (json)
921
955
  line(JSON.stringify({ event, forwarded: target ? result : null }));
@@ -923,7 +957,7 @@ async function listen(args, g) {
923
957
  const status = !target
924
958
  ? ""
925
959
  : result.status === null
926
- ? red(` → sin respuesta (${result.error})`)
960
+ ? red(` → sin respuesta (${result.error}); se perdió ${event.id}`)
927
961
  : ` → ${result.status >= 200 && result.status < 300 ? green(String(result.status)) : red(String(result.status))} ${dim(`${result.ms} ms`)}`;
928
962
  line(`${dim(new Date().toLocaleTimeString("es-MX"))} ${bold(event.type)} ${event.data.object.id}${status}`);
929
963
  }
@@ -1015,6 +1049,58 @@ async function docs() {
1015
1049
  else
1016
1050
  process.stdout.write(text);
1017
1051
  }
1052
+ // ── mock ───────────────────────────────────────────────────────────────────
1053
+ /** `fiscalisto mock`: the API's shapes on localhost, offline (./mock.ts). */
1054
+ async function mock(args) {
1055
+ const { values } = parseArgs({
1056
+ args,
1057
+ options: {
1058
+ port: { type: "string", default: "12111" },
1059
+ host: { type: "string", default: "127.0.0.1" },
1060
+ },
1061
+ });
1062
+ const { createServer } = await import("node:http");
1063
+ const api = createMock();
1064
+ const server = createServer(async (req, res) => {
1065
+ const chunks = [];
1066
+ for await (const c of req)
1067
+ chunks.push(c);
1068
+ const url = `http://${req.headers.host ?? "localhost"}${req.url ?? "/"}`;
1069
+ const headers = new Headers();
1070
+ for (const [k, v] of Object.entries(req.headers))
1071
+ if (typeof v === "string")
1072
+ headers.set(k, v);
1073
+ const request = new Request(url, {
1074
+ method: req.method,
1075
+ headers,
1076
+ body: chunks.length && req.method !== "GET" ? Buffer.concat(chunks) : undefined,
1077
+ });
1078
+ const started = Date.now();
1079
+ const response = await api.fetch(request);
1080
+ res.writeHead(response.status, Object.fromEntries(response.headers));
1081
+ res.end(Buffer.from(await response.arrayBuffer()));
1082
+ if (!json)
1083
+ line(`${dim(new Date().toTimeString().slice(0, 8))} ${(response.ok ? green : yellow)(String(response.status))} ${request.method} ${new URL(url).pathname} ${dim(`${Date.now() - started} ms`)}`);
1084
+ });
1085
+ const port = Number(values.port);
1086
+ await new Promise((ok, fail) => {
1087
+ server.once("error", fail);
1088
+ server.listen(port, values.host, ok);
1089
+ });
1090
+ const base = `http://${values.host === "0.0.0.0" ? "localhost" : values.host}:${port}`;
1091
+ print({ url: base }, () => {
1092
+ line(`${bold("Servidor de prueba de Fiscalisto")} en ${cyan(base)}`);
1093
+ line(dim("Contesta cada ruta como la API, sin internet; lo que crea vive en memoria mientras corre."));
1094
+ line(dim("No revisa reglas del SAT ni timbra: para eso use su llave fk_test_ contra la API."));
1095
+ line("");
1096
+ line(` ${bold("SDK")} new Fiscalisto("fk_test_mock", { baseUrl: "${base}" })`);
1097
+ line(` ${bold("curl")} curl ${base}/v1/account -H "Authorization: Bearer fk_test_mock"`);
1098
+ line(` ${bold("CLI")} FISCALISTO_BASE_URL=${base} FISCALISTO_API_KEY=fk_test_mock npx fiscalisto whoami`);
1099
+ line("");
1100
+ line(dim("Ctrl+C para salir."));
1101
+ });
1102
+ await new Promise(() => { });
1103
+ }
1018
1104
  // ── main ───────────────────────────────────────────────────────────────────
1019
1105
  const HELP = `${bold("fiscalisto")} ${dim(VERSION)} · facturación electrónica (CFDI 4.0) desde su terminal
1020
1106
 
@@ -1041,6 +1127,7 @@ ${bold("Webhooks")}
1041
1127
  ${bold("Otros")}
1042
1128
  issuers list|get Sus emisores
1043
1129
  api [METHOD] /v1/… [--data] Cualquier ruta de la API con su llave
1130
+ mock [--port 12111] La API en su computadora, sin internet, para desarrollar y probar
1044
1131
  open [panel|facturas|llaves|webhooks|eventos|docs]
1045
1132
  docs La guía completa para agentes (llms.txt)
1046
1133
 
@@ -1096,6 +1183,8 @@ export async function main(argv) {
1096
1183
  return await rawApi(args, globals);
1097
1184
  case "listen":
1098
1185
  return await listen(args, globals);
1186
+ case "mock":
1187
+ return await mock(args);
1099
1188
  case "trigger":
1100
1189
  return await trigger(args, globals);
1101
1190
  case "open":
package/dist/core.d.ts CHANGED
@@ -4,7 +4,12 @@
4
4
  * llamar.
5
5
  */
6
6
  import type { ErrorCode } from "./error-codes.js";
7
- export declare const VERSION = "0.1.0";
7
+ export declare const VERSION = "0.1.1";
8
+ /**
9
+ * La versión de la API para la que se hizo este SDK: la manda en cada solicitud
10
+ * (Fiscalisto-Version), así actualizar la API no cambia lo que recibe hasta que actualice el SDK.
11
+ */
12
+ export declare const API_VERSION = "2026-10-24";
8
13
  /** Lo que el SDK necesita de fetch. */
9
14
  export type Fetch = (url: URL, init: RequestInit) => Promise<Response>;
10
15
  export interface FiscalistoOptions {
@@ -16,6 +21,13 @@ export interface FiscalistoOptions {
16
21
  timeout?: number;
17
22
  /** Otro fetch (pruebas, proxies). Por omisión el global. */
18
23
  fetch?: Fetch;
24
+ /**
25
+ * La versión de la API (Fiscalisto-Version). Por omisión la del SDK (API_VERSION); null manda
26
+ * ninguna, así se usa la de su cuenta.
27
+ */
28
+ apiVersion?: string | null;
29
+ /** "en": los mensajes de error en inglés (Accept-Language). Por omisión en español. */
30
+ language?: "es" | "en";
19
31
  }
20
32
  export interface RequestOptions {
21
33
  /**
@@ -27,6 +39,11 @@ export interface RequestOptions {
27
39
  timeout?: number;
28
40
  maxRetries?: number;
29
41
  signal?: AbortSignal;
42
+ /**
43
+ * Campos con el id de otro objeto que llegan como ese objeto, en la misma respuesta:
44
+ * `{ expand: ["issuer", "recurring_invoice.last_invoice"] }`. Ver /docs/api/expandir.
45
+ */
46
+ expand?: string[];
30
47
  }
31
48
  export interface RequestSpec {
32
49
  method: string;
package/dist/core.js CHANGED
@@ -3,7 +3,12 @@
3
3
  * errores y las listas que se recorren solas. Los recursos (generated.ts) solo dicen qué ruta
4
4
  * llamar.
5
5
  */
6
- export const VERSION = "0.1.0";
6
+ export const VERSION = "0.1.1";
7
+ /**
8
+ * La versión de la API para la que se hizo este SDK: la manda en cada solicitud
9
+ * (Fiscalisto-Version), así actualizar la API no cambia lo que recibe hasta que actualice el SDK.
10
+ */
11
+ export const API_VERSION = "2026-10-24";
7
12
  const DEFAULT_BASE_URL = "https://api.fiscalisto.com";
8
13
  /**
9
14
  * Un error de la API (o de la conexión, con type connection_error). code es estable: decida
@@ -83,12 +88,20 @@ export class List {
83
88
  const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
84
89
  /** 0.5 s, 1 s, 2 s… hasta 8 s, con algo de azar para no llegar todos juntos. */
85
90
  const backoff = (attempt) => Math.min(8000, 500 * 2 ** attempt) * (0.75 + Math.random() / 2);
91
+ /** A success that isn't the API's JSON: a proxy's or a network portal's page answered instead. */
92
+ const invalidResponse = (status, text, requestId) => new FiscalistoError({
93
+ type: "api_error",
94
+ code: "invalid_response",
95
+ message: `La respuesta (${status}) no es de la API: ${text.replace(/\s+/g, " ").trim().slice(0, 80) || "vacía"}. ¿Hay un proxy o un portal de por medio?`,
96
+ }, status, requestId);
86
97
  export class Core {
87
98
  #key;
88
99
  #baseUrl;
89
100
  #maxRetries;
90
101
  #timeout;
91
102
  #fetch;
103
+ #apiVersion;
104
+ #language;
92
105
  constructor(apiKey, options = {}) {
93
106
  const env = globalThis
94
107
  .process?.env;
@@ -98,24 +111,33 @@ export class Core {
98
111
  if (!/^fk_(live|test)_/.test(key))
99
112
  throw new Error("La llave de la API empieza con fk_live_ o fk_test_. (Un secreto whsec_ es para verificar webhooks.)");
100
113
  this.#key = key;
101
- this.#baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
114
+ // A proxy's path stays: https://proxy.example.com/fiscalisto + /v1/invoices.
115
+ this.#baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
102
116
  this.#maxRetries = options.maxRetries ?? 2;
103
117
  this.#timeout = options.timeout ?? 80_000;
104
118
  this.#fetch = options.fetch ?? ((url, init) => fetch(url, init));
119
+ this.#apiVersion = options.apiVersion === undefined ? API_VERSION : options.apiVersion;
120
+ this.#language = options.language;
105
121
  }
106
122
  /** true con una llave fk_live_ (producción), false con fk_test_ (pruebas). */
107
123
  get livemode() {
108
124
  return this.#key.startsWith("fk_live_");
109
125
  }
110
126
  async request(spec, options = {}) {
111
- const url = new URL(spec.path, this.#baseUrl);
127
+ const url = new URL(this.#baseUrl + spec.path);
112
128
  for (const [k, v] of Object.entries(spec.query ?? {}))
113
129
  if (v !== undefined && v !== null)
114
130
  url.searchParams.set(k, String(v));
131
+ for (const e of options.expand ?? [])
132
+ url.searchParams.append("expand[]", e);
115
133
  const headers = {
116
134
  authorization: `Bearer ${this.#key}`,
117
135
  "user-agent": `fiscalisto-node/${VERSION}`,
118
136
  };
137
+ if (this.#apiVersion)
138
+ headers["fiscalisto-version"] = this.#apiVersion;
139
+ if (this.#language)
140
+ headers["accept-language"] = this.#language;
119
141
  const idempotencyKey = spec.idempotent
120
142
  ? (options.idempotencyKey ?? crypto.randomUUID())
121
143
  : undefined;
@@ -161,7 +183,13 @@ export class Core {
161
183
  return new Uint8Array(await response.arrayBuffer());
162
184
  if (spec.as === "text")
163
185
  return (await response.text());
164
- return (await response.json());
186
+ const text = await response.text();
187
+ try {
188
+ return JSON.parse(text);
189
+ }
190
+ catch {
191
+ throw invalidResponse(response.status, text, requestId);
192
+ }
165
193
  }
166
194
  const raw = await response
167
195
  .json()
@@ -3,6 +3,8 @@
3
3
  * `if (error.code === ErrorCode.InvoiceRejected)`. Vea https://fiscalisto.com/docs/api/errores.
4
4
  */
5
5
  export declare const ErrorCode: {
6
+ /** No existe esa versión de la API (en Fiscalisto-Version o api_version). El mensaje dice cuáles hay; vea Versiones. */
7
+ readonly ApiVersionInvalid: "api_version_invalid";
6
8
  /** El depósito no se puede conciliar, clasificar o reabrir así (ya está conciliado, las facturas son de otro cliente o una está cancelada…). El mensaje dice por qué. */
7
9
  readonly BankTransactionInvalid: "bank_transaction_invalid";
8
10
  /** Una factura del lote no pasa la revisión; param dice cuál (invoices.3.items.0.unit_price). Ninguna del lote se timbró. */
@@ -35,15 +37,19 @@ export declare const ErrorCode: {
35
37
  readonly EfirmaRequired: "efirma_required";
36
38
  /** No se pudo mandar el correo; el comprobante sí está timbrado. */
37
39
  readonly EmailFailed: "email_failed";
40
+ /** Ya hay un webhook con esa dirección en este modo; el mensaje dice cuál. Cámbielo en vez de crear otro. */
41
+ readonly EndpointExists: "endpoint_exists";
38
42
  /** La cuenta llegó al máximo de webhooks en este modo. */
39
43
  readonly EndpointLimit: "endpoint_limit";
44
+ /** Un campo de expand[] no existe en la respuesta, no es el id de otro objeto, o se pidieron demasiados (hasta 10 campos, 4 niveles). Vea Expandir objetos. */
45
+ readonly ExpandInvalid: "expand_invalid";
40
46
  /** Idempotency-Key es de 1 a 255 caracteres ASCII, sin acentos ni ñ: el id de su pedido o un UUID. */
41
47
  readonly IdempotencyKeyInvalid: "idempotency_key_invalid";
42
48
  /** Lo que timbra exige el encabezado Idempotency-Key (8 a 255 caracteres, uno nuevo por comprobante). Así un reintento nunca timbra dos veces. */
43
49
  readonly IdempotencyKeyMissing: "idempotency_key_missing";
44
50
  /** Esa Idempotency-Key ya se usó en las últimas 24 horas con otra solicitud (otra ruta u otro cuerpo). Use una nueva para cada operación distinta. */
45
51
  readonly IdempotencyKeyReused: "idempotency_key_reused";
46
- /** La cuenta no tiene timbres de producción. Compre un paquete en Desarrolladores › Timbres. En pruebas nunca pasa. Para enterarse antes, escuche balance.low o active la recarga automática. */
52
+ /** La cuenta no tiene timbres de producción: para timbrar, revisar RFC en las listas, consultar constancias o pedir descargas al SAT. Compre un paquete en Desarrolladores › Timbres. En pruebas nunca pasa. Para enterarse antes, escuche balance.low o active la recarga automática. */
47
53
  readonly InsufficientBalance: "insufficient_balance";
48
54
  /** Algo falló de nuestro lado. Repita la solicitud con la misma Idempotency-Key: nunca se timbra dos veces. Si sigue, escríbanos con el request_id. */
49
55
  readonly InternalError: "internal_error";
@@ -51,6 +57,8 @@ export declare const ErrorCode: {
51
57
  readonly InvalidApiKey: "invalid_api_key";
52
58
  /** El cuerpo no es un objeto JSON válido. */
53
59
  readonly InvalidJson: "invalid_json";
60
+ /** La respuesta no se pudo leer (api_error): no es el JSON de la API, sino la página de un proxy o de un portal de la red. status dice qué contestó. */
61
+ readonly InvalidResponse: "invalid_response";
54
62
  /** La factura no cumple una regla del SAT que Fiscalisto revisa antes de mandarla al PAC (uso contra régimen, totales, complementos…). No se usó ningún timbre. */
55
63
  readonly InvoiceInvalid: "invoice_invalid";
56
64
  /** Solo una factura de ingreso PUE vigente se marca pagada o por cobrar; una PPD se paga con su complemento de pago (type P). */
@@ -87,7 +95,7 @@ export declare const ErrorCode: {
87
95
  readonly ParameterInvalid: "parameter_invalid";
88
96
  /** Falta un campo obligatorio. param dice cuál. */
89
97
  readonly ParameterMissing: "parameter_missing";
90
- /** Mandó un campo que no existe (casi siempre un nombre mal escrito, como legalName en vez de legal_name). Nunca se ignora en silencio. */
98
+ /** Mandó un campo o un parámetro de la URL que no existe (casi siempre un nombre mal escrito, como legalName en vez de legal_name, o ?statuss= en vez de ?status=). Nunca se ignora en silencio. */
91
99
  readonly ParameterUnknown: "parameter_unknown";
92
100
  /** El recibo de nómina no se puede calcular o timbrar con esos datos (periodo, días, registro patronal del emisor…). */
93
101
  readonly PayrollInvalid: "payroll_invalid";
@@ -109,7 +117,7 @@ export declare const ErrorCode: {
109
117
  readonly RecurringNotDue: "recurring_not_due";
110
118
  /** La factura recurrente está en pausa: reanúdela con active: true para timbrarla. */
111
119
  readonly RecurringPaused: "recurring_paused";
112
- /** Otra solicitud con la misma Idempotency-Key sigue en proceso (409, con Retry-After). Repítala en un momento con la misma llave: contestará lo mismo. */
120
+ /** Otra solicitud con la misma Idempotency-Key sigue en proceso, o otra solicitud está cambiando el mismo objeto (dos actualizaciones del mismo cliente a la vez esperan su turno hasta 15 segundos) (409, con Retry-After). Repítala en un momento con la misma llave: contestará lo mismo. */
113
121
  readonly RequestInProgress: "request_in_progress";
114
122
  /** No existe un objeto con ese id (o es de otro emisor o del otro modo). */
115
123
  readonly ResourceMissing: "resource_missing";
@@ -123,8 +131,12 @@ export declare const ErrorCode: {
123
131
  readonly RouteNotFound: "route_not_found";
124
132
  /** No se pudo crear el entorno de prueba: falta su nombre o la cuenta ya tiene 25 (borre uno que ya no use). */
125
133
  readonly SandboxInvalid: "sandbox_invalid";
134
+ /** Las declaraciones de ese emisor se consultaron en el SAT hace menos de 10 minutos (cada consulta entra al SAT con su e.firma). Retry-After dice cuántos segundos faltan; lo que ya trajo está en GET /v1/sat_declarations. */
135
+ readonly SatRefreshTooSoon: "sat_refresh_too_soon";
126
136
  /** El SAT rechazó la solicitud de descarga. El mensaje trae su motivo, por ejemplo que ya se pidió el mismo periodo con los mismos filtros demasiadas veces (el SAT pone un límite de por vida). */
127
137
  readonly SatRequestRejected: "sat_request_rejected";
138
+ /** El SAT no contestó o no dejó entrar con la e.firma del emisor. El mensaje trae lo que dijo; no se usó ningún timbre. Reintente en 10 minutos. */
139
+ readonly SatUnavailable: "sat_unavailable";
128
140
  /** Demasiados timbres seguidos del mismo emisor. Espere lo que dice Retry-After; para muchas facturas use POST /v1/invoice_batches. */
129
141
  readonly StampRateLimit: "stamp_rate_limit";
130
142
  /** Esa tienda ya está conectada a este emisor. */
@@ -4,6 +4,8 @@
4
4
  * `if (error.code === ErrorCode.InvoiceRejected)`. Vea https://fiscalisto.com/docs/api/errores.
5
5
  */
6
6
  export const ErrorCode = {
7
+ /** No existe esa versión de la API (en Fiscalisto-Version o api_version). El mensaje dice cuáles hay; vea Versiones. */
8
+ ApiVersionInvalid: "api_version_invalid",
7
9
  /** El depósito no se puede conciliar, clasificar o reabrir así (ya está conciliado, las facturas son de otro cliente o una está cancelada…). El mensaje dice por qué. */
8
10
  BankTransactionInvalid: "bank_transaction_invalid",
9
11
  /** Una factura del lote no pasa la revisión; param dice cuál (invoices.3.items.0.unit_price). Ninguna del lote se timbró. */
@@ -36,15 +38,19 @@ export const ErrorCode = {
36
38
  EfirmaRequired: "efirma_required",
37
39
  /** No se pudo mandar el correo; el comprobante sí está timbrado. */
38
40
  EmailFailed: "email_failed",
41
+ /** Ya hay un webhook con esa dirección en este modo; el mensaje dice cuál. Cámbielo en vez de crear otro. */
42
+ EndpointExists: "endpoint_exists",
39
43
  /** La cuenta llegó al máximo de webhooks en este modo. */
40
44
  EndpointLimit: "endpoint_limit",
45
+ /** Un campo de expand[] no existe en la respuesta, no es el id de otro objeto, o se pidieron demasiados (hasta 10 campos, 4 niveles). Vea Expandir objetos. */
46
+ ExpandInvalid: "expand_invalid",
41
47
  /** Idempotency-Key es de 1 a 255 caracteres ASCII, sin acentos ni ñ: el id de su pedido o un UUID. */
42
48
  IdempotencyKeyInvalid: "idempotency_key_invalid",
43
49
  /** Lo que timbra exige el encabezado Idempotency-Key (8 a 255 caracteres, uno nuevo por comprobante). Así un reintento nunca timbra dos veces. */
44
50
  IdempotencyKeyMissing: "idempotency_key_missing",
45
51
  /** Esa Idempotency-Key ya se usó en las últimas 24 horas con otra solicitud (otra ruta u otro cuerpo). Use una nueva para cada operación distinta. */
46
52
  IdempotencyKeyReused: "idempotency_key_reused",
47
- /** La cuenta no tiene timbres de producción. Compre un paquete en Desarrolladores › Timbres. En pruebas nunca pasa. Para enterarse antes, escuche balance.low o active la recarga automática. */
53
+ /** La cuenta no tiene timbres de producción: para timbrar, revisar RFC en las listas, consultar constancias o pedir descargas al SAT. Compre un paquete en Desarrolladores › Timbres. En pruebas nunca pasa. Para enterarse antes, escuche balance.low o active la recarga automática. */
48
54
  InsufficientBalance: "insufficient_balance",
49
55
  /** Algo falló de nuestro lado. Repita la solicitud con la misma Idempotency-Key: nunca se timbra dos veces. Si sigue, escríbanos con el request_id. */
50
56
  InternalError: "internal_error",
@@ -52,6 +58,8 @@ export const ErrorCode = {
52
58
  InvalidApiKey: "invalid_api_key",
53
59
  /** El cuerpo no es un objeto JSON válido. */
54
60
  InvalidJson: "invalid_json",
61
+ /** La respuesta no se pudo leer (api_error): no es el JSON de la API, sino la página de un proxy o de un portal de la red. status dice qué contestó. */
62
+ InvalidResponse: "invalid_response",
55
63
  /** La factura no cumple una regla del SAT que Fiscalisto revisa antes de mandarla al PAC (uso contra régimen, totales, complementos…). No se usó ningún timbre. */
56
64
  InvoiceInvalid: "invoice_invalid",
57
65
  /** Solo una factura de ingreso PUE vigente se marca pagada o por cobrar; una PPD se paga con su complemento de pago (type P). */
@@ -88,7 +96,7 @@ export const ErrorCode = {
88
96
  ParameterInvalid: "parameter_invalid",
89
97
  /** Falta un campo obligatorio. param dice cuál. */
90
98
  ParameterMissing: "parameter_missing",
91
- /** Mandó un campo que no existe (casi siempre un nombre mal escrito, como legalName en vez de legal_name). Nunca se ignora en silencio. */
99
+ /** Mandó un campo o un parámetro de la URL que no existe (casi siempre un nombre mal escrito, como legalName en vez de legal_name, o ?statuss= en vez de ?status=). Nunca se ignora en silencio. */
92
100
  ParameterUnknown: "parameter_unknown",
93
101
  /** El recibo de nómina no se puede calcular o timbrar con esos datos (periodo, días, registro patronal del emisor…). */
94
102
  PayrollInvalid: "payroll_invalid",
@@ -110,7 +118,7 @@ export const ErrorCode = {
110
118
  RecurringNotDue: "recurring_not_due",
111
119
  /** La factura recurrente está en pausa: reanúdela con active: true para timbrarla. */
112
120
  RecurringPaused: "recurring_paused",
113
- /** Otra solicitud con la misma Idempotency-Key sigue en proceso (409, con Retry-After). Repítala en un momento con la misma llave: contestará lo mismo. */
121
+ /** Otra solicitud con la misma Idempotency-Key sigue en proceso, o otra solicitud está cambiando el mismo objeto (dos actualizaciones del mismo cliente a la vez esperan su turno hasta 15 segundos) (409, con Retry-After). Repítala en un momento con la misma llave: contestará lo mismo. */
114
122
  RequestInProgress: "request_in_progress",
115
123
  /** No existe un objeto con ese id (o es de otro emisor o del otro modo). */
116
124
  ResourceMissing: "resource_missing",
@@ -124,8 +132,12 @@ export const ErrorCode = {
124
132
  RouteNotFound: "route_not_found",
125
133
  /** No se pudo crear el entorno de prueba: falta su nombre o la cuenta ya tiene 25 (borre uno que ya no use). */
126
134
  SandboxInvalid: "sandbox_invalid",
135
+ /** Las declaraciones de ese emisor se consultaron en el SAT hace menos de 10 minutos (cada consulta entra al SAT con su e.firma). Retry-After dice cuántos segundos faltan; lo que ya trajo está en GET /v1/sat_declarations. */
136
+ SatRefreshTooSoon: "sat_refresh_too_soon",
127
137
  /** El SAT rechazó la solicitud de descarga. El mensaje trae su motivo, por ejemplo que ya se pidió el mismo periodo con los mismos filtros demasiadas veces (el SAT pone un límite de por vida). */
128
138
  SatRequestRejected: "sat_request_rejected",
139
+ /** El SAT no contestó o no dejó entrar con la e.firma del emisor. El mensaje trae lo que dijo; no se usó ningún timbre. Reintente en 10 minutos. */
140
+ SatUnavailable: "sat_unavailable",
129
141
  /** Demasiados timbres seguidos del mismo emisor. Espere lo que dice Retry-After; para muchas facturas use POST /v1/invoice_batches. */
130
142
  StampRateLimit: "stamp_rate_limit",
131
143
  /** Esa tienda ya está conectada a este emisor. */