From order to invoice

npm install @beel_es/sdk

import { BeeL, type RequestOptions } from '@beel_es/sdk';

export const beel = new BeeL({
  apiKey: process.env.BEEL_API_KEY!, // beel_sk_test_… in sandbox, beel_sk_live_… in production
  // baseUrl: process.env.MY_API_URL, // only for another environment or a proxy
  // Defaults: 3 automatic retries of 429, 5xx and network errors, reusing the call's
  // Idempotency-Key, so a retry never creates a second invoice.
});

// Every invoice call on this page passes it: no request can hang the integration.
export const REQUEST_TIMEOUT_MS = 20_000;
export const CALL: RequestOptions = { timeoutMs: REQUEST_TIMEOUT_MS }; // automatic retries included

// Once, at setup time: store the id in your configuration afterwards.
export async function findCompanyId(nif: string): Promise<string> {
  const { account_id } = await beel.catalogs.identity();
  const { companies } = await beel.account(account_id).companies.list({ search: nif });
  const company = companies.find((c) => c.nif === nif);
  if (!company?.id) throw new Error(`No company with NIF ${nif} in this account`);
  return company.id;
}

export const company = beel.company(process.env.BEEL_COMPANY_ID!);

import type {
  CompanyInvoicesResource,
  CompanyTaxConfigurationResource,
  CreateInvoiceOnceRequest,
  components,
} from '@beel_es/sdk';

type Schemas = components['schemas'];

// Requests and responses, generated from the OpenAPI contract.
export type Invoice = Schemas['Invoice'];
export type CreateInvoiceRequest = Schemas['CreateInvoiceRequest'];
export type OrderInvoice = CreateInvoiceOnceRequest; // STANDARD or SIMPLIFIED, external_ref required
export type InvoiceLine = CreateInvoiceRequest['lines'][number];
export type CreateCorrectiveInvoiceRequest = Schemas['CreateCorrectiveInvoiceRequest'];
export type ProcessingOptions = NonNullable<CreateInvoiceRequest['options']>;

// The recipient and how a foreign customer is identified.
export type Recipient = CreateInvoiceRequest['recipient']; // customer_id alone, or the data inline
export type AlternativeId = NonNullable<Schemas['AlternativeIdentifier']>; // { type, number, country_code? }
export type AlternativeIdType = AlternativeId['type']; // 'NIF_IVA' | 'OTHER_DOCUMENT' | 'PASSPORT' | …

// A line's taxes.
export type MainTax = Schemas['TaxInfo']; // { type: 'IVA' | …, percentage, regime_key? }
export type ExemptionReason = Schemas['ExemptionReason']; // 'EXENTA_ART_25' | 'NO_SUJETA_LOCALIZACION' | …
export type IrpfRate = Schemas['IrpfPercentage']; // 0 | 1 | 2 | … | 15 | 19 | 24

// Statuses and correctives.
export type InvoiceType = Schemas['InvoiceType']; // 'STANDARD' | 'SIMPLIFIED' | 'CORRECTIVE' | 'PROFORMA'
export type InvoiceStatus = Schemas['InvoiceStatus']; // 'DRAFT' | 'ISSUED' | … | 'RECTIFIED' | 'VOIDED'
export type SubmissionStatus = Schemas['VeriFactuSubmissionStatus']; // 'NOT_SUBMITTED' | 'PENDING' | …
export type RectificationType = Schemas['RectificationType']; // 'TOTAL' | 'PARTIAL'
export type RectificationCode = Schemas['VeriFactuRectificationCode']; // 'R1' … 'R5'

// What the SDK methods return.
export type InvoiceListQuery = NonNullable<Parameters<CompanyInvoicesResource['list']>[0]>;
export type InvoiceList = Awaited<ReturnType<CompanyInvoicesResource['list']>>; // { invoices, pagination }
export type Pagination = Schemas['Pagination']; // { current_page, total_pages, total_items, … }
// company.taxConfiguration.get(): default_irpf_rate, withholding_options.allowed_irpf_rates, …
export type TaxConfiguration = NonNullable<Awaited<ReturnType<CompanyTaxConfigurationResource['get']>>>;

// Issue at once. Every other option defaults to false: no email is sent.
export const ISSUE_NOW: ProcessingOptions = { issue_directly: true };

import { company, CALL } from './client';
import type { Invoice, OrderInvoice } from './types';

/**
 * The invoice of one order, created at most once: `external_ref` is the order id.
 * Safe to call again after any error, and on every rerun of the batch.
 * The invoice returned may be one created earlier, VOIDED included: check its status.
 */
export function invoiceOrder(body: OrderInvoice): Promise<Invoice> {
  return company.invoices.createOnce(body, undefined, CALL);
}

import { BeeLApiError } from '@beel_es/sdk';

/** What to tell the shop when an order cannot be invoiced. */
export function explain(err: unknown): string {
  if (!(err instanceof BeeLApiError)) return 'No answer from BeeL.: try again later';
  // apiCode is the API's own error code; each fiscal one names the rule it enforces
  switch (err.apiCode) {
    case 'SIMPLIFIED_INVOICE_EXCEEDS_LEGAL_LIMIT':
      return 'Too large for a ticket: ask the customer for their fiscal data';
    case 'SIMPLIFICADA_FORBIDS_CROSS_BORDER':
      return 'A cross-border operation needs a standard invoice';
    default:
      return `${err.statusCode} ${err.apiCode}: ${err.message}`;
  }
}

/**
 * A corrective created earlier for this return, if any. createOnce does not create
 * correctives: give each one its own external_ref (the return id) and look it up first.
 */
export async function findCorrective(returnId: string): Promise<Invoice | undefined> {
  const { invoices } = await company.invoices.list({ external_ref: returnId }, CALL);
  return invoices.find((invoice) => invoice.type === 'CORRECTIVE');
}

// A Spanish business: legal name, NIF and fiscal address, sent inline.
// (A registered customer goes as `recipient: { customer_id }`, alone.)
const acme: Recipient = {
  legal_name: 'Acme Distribuciones SL',
  nif: 'B12345674',
  address: {
    street: 'Calle Mayor 1',
    postal_code: '28001',
    city: 'Madrid',
    province: 'Madrid',
    country_code: 'ES',
  },
  email: 'billing@acme.example',
};

// Your shop stores prices with VAT included: send what the customer paid per line.
export const vatIncluded: OrderInvoice = {
  type: 'STANDARD',
  external_ref: 'A-1001',
  recipient: acme,
  lines: [
    {
      description: 'Espresso machine',
      quantity: 2,
      total_including_tax: 605, // 2 × 302.50, VAT included
      main_tax: { type: 'IVA', percentage: 21, regime_key: '01' },
      irpf_rate: 0, // omitted, the line takes the company's default IRPF rate
    },
  ],
  options: ISSUE_NOW,
};

// Your shop stores net prices: send the unit price without VAT.
export const netPrice: OrderInvoice = {
  type: 'STANDARD',
  external_ref: 'A-1002',
  recipient: acme,
  lines: [
    {
      description: 'Espresso machine',
      quantity: 2,
      unit_price: 250, // without VAT; BeeL. computes base, VAT and totals
      main_tax: { type: 'IVA', percentage: 21, regime_key: '01' },
      irpf_rate: 0,
    },
  ],
  options: ISSUE_NOW,
};

// A consumer who gave no fiscal data: a simplified invoice (ticket), several VAT rates.
export const ticket: OrderInvoice = {
  type: 'SIMPLIFIED',
  external_ref: 'T-2001',
  recipient: {}, // no NIF and no alternative_id: an identified recipient needs STANDARD
  lines: [
    {
      description: 'Ground coffee 1 kg',
      quantity: 2,
      total_including_tax: 26.4,
      main_tax: { type: 'IVA', percentage: 10, regime_key: '01' },
    },
    {
      description: 'Milk frother',
      quantity: 1,
      total_including_tax: 48.4,
      main_tax: { type: 'IVA', percentage: 21, regime_key: '01' },
    },
  ],
  options: ISSUE_NOW,
};

const SIMPLIFIED_CAP = 3000; // SIM-001: never above, whatever the activity
const SIMPLIFIED_GENERAL_LIMIT = 400; // SIM-002: above it, only art. 4.2 activities (retail…)

type TicketDecision =
  | { issue: 'SIMPLIFIED' }
  | { issue: 'NONE'; reason: string; ask_customer_for: string[] };

/** Decide before sending: can this order be a ticket, or do you need the customer's data? */
export function ticketDecision(totalWithVat: number, art42Activity: boolean): TicketDecision {
  const needsData = { issue: 'NONE' as const, ask_customer_for: ['legal name', 'NIF', 'fiscal address'] };
  if (totalWithVat > SIMPLIFIED_CAP) {
    return { ...needsData, reason: `Total ${totalWithVat} € is above the simplified-invoice cap` };
  }
  if (totalWithVat > SIMPLIFIED_GENERAL_LIMIT && !art42Activity) {
    return { ...needsData, reason: `Total ${totalWithVat} € needs an art. 4.2 activity to go on a ticket` };
  }
  return { issue: 'SIMPLIFIED' };
}

// Service done on 23 September, paid and invoiced on 28 September.
export const lateInvoice: OrderInvoice = {
  type: 'STANDARD',
  external_ref: 'A-1003',
  operation_date: '2026-09-23', // the day of the service; issue_date is set by BeeL. when issued
  recipient: { customer_id: '4f244735-980b-8d9c-80e8-6331fa0b1958' },
  lines: [
    {
      description: 'Installation of the espresso machine',
      quantity: 1,
      unit_price: 90,
      main_tax: { type: 'IVA', percentage: 21, regime_key: '01' },
      irpf_rate: 0,
    },
  ],
  options: ISSUE_NOW,
};

// Paid 54.00 USD (VAT included). The API reads every amount as euros: convert first.
const paidUsd = 54;
const eurPerUsd = 0.92; // your rate for the day of the operation

const paidEur = Math.round(paidUsd * eurPerUsd * 100) / 100; // 49.68

export const usdOrder: OrderInvoice = {
  type: 'SIMPLIFIED',
  external_ref: 'U-3001',
  recipient: {},
  lines: [
    {
      description: 'Coffee subscription, 3 months',
      quantity: 1,
      total_including_tax: paidEur,
      main_tax: { type: 'IVA', percentage: 10, regime_key: '01' },
    },
  ],
  notes: `Paid ${paidUsd.toFixed(2)} USD. Exchange rate applied: ${eurPerUsd} EUR/USD.`,
  options: ISSUE_NOW,
};

// Goods shipped to a business in Ireland that gave its EU VAT number.
export const intraEuGoods: OrderInvoice = {
  type: 'STANDARD', // never SIMPLIFIED: rejected with SIMPLIFICADA_FORBIDS_CROSS_BORDER
  external_ref: 'E-4001',
  recipient: {
    legal_name: 'Example Trading Ltd',
    alternative_id: { type: 'NIF_IVA', number: 'IE6388047V', country_code: 'IE' },
    address: {
      street: 'Barrow Street 4',
      postal_code: 'D04 E5W5',
      city: 'Dublin',
      province: 'Dublin',
      country_code: 'IE',
    },
  },
  lines: [
    {
      description: 'Espresso machine (shipped from Madrid)',
      quantity: 10,
      unit_price: 250, // exempt: base = price, no VAT
      main_tax: { type: 'IVA', percentage: 0, regime_key: '01' },
      exemption_reason: 'EXENTA_ART_25', // intra-EU supply of goods (E5)
      irpf_rate: 0,
    },
  ],
  options: ISSUE_NOW,
};

// Remote support for a business in the United States (identified by its EIN).
export const nonEuServices: OrderInvoice = {
  type: 'STANDARD',
  external_ref: 'S-4003',
  recipient: {
    legal_name: 'Example Robotics Inc.',
    alternative_id: { type: 'OTHER_DOCUMENT', number: '12-3456789', country_code: 'US' },
    address: {
      street: '500 Market Street',
      postal_code: '94105',
      city: 'San Francisco',
      province: 'California',
      country_code: 'US',
    },
  },
  lines: [
    {
      description: 'Remote technical support, September',
      quantity: 1,
      unit_price: 1200,
      main_tax: { type: 'IVA', percentage: 0, regime_key: '01' },
      exemption_reason: 'NO_SUJETA_LOCALIZACION', // not subject: place of supply (N2)
      irpf_rate: 0,
    },
  ],
  options: ISSUE_NOW,
};

// A self-employed professional invoices consulting to a Spanish business,
// which withholds IRPF from the payment.
export const consulting: OrderInvoice = {
  type: 'STANDARD',
  external_ref: 'C-4002',
  recipient: { customer_id: '4f244735-980b-8d9c-80e8-6331fa0b1958' },
  lines: [
    {
      description: 'Consulting, 10 hours',
      quantity: 10,
      unit_price: 60,
      main_tax: { type: 'IVA', percentage: 21, regime_key: '01' },
      irpf_rate: 15, // per line; 0 on lines without withholding
    },
  ],
  options: ISSUE_NOW,
};
// Base 600.00 + VAT 126.00 = total 726.00 (the total AEAT receives).
// Withholding 90.00 → the customer pays 636.00.

// The IRPF rate a standard line gets when it omits irpf_rate, and the rates this issuer may use.
export async function irpfDefaults() {
  const config = await company.taxConfiguration.get();
  return {
    defaultRate: config?.default_irpf_rate, // undefined: the company has none
    allowed: config?.withholding_options?.allowed_irpf_rates ?? [],
  };
}

// A 10 % coupon on a product priced 24.20 € with 21 % VAT included.
// A declared total takes no discount, so send the net unit price and the coupon apart.
const priceWithVat = 24.2;
const vatRate = 21;
const unitPrice = Math.round((priceWithVat / (1 + vatRate / 100)) * 10_000) / 10_000; // 20.0000

export const withCoupon: OrderInvoice = {
  type: 'SIMPLIFIED',
  external_ref: 'P-4006',
  recipient: {},
  lines: [
    {
      description: 'Coffee grinder',
      quantity: 1,
      unit_price: unitPrice, // up to 4 decimals
      discount_percentage: 10, // coupon WELCOME10
      main_tax: { type: 'IVA', percentage: vatRate, regime_key: '01' },
    },
  ],
  options: ISSUE_NOW,
};
// Base 18.00 + VAT 3.78 = 21.78, the 24.20 price less 10 %.

// The customer returned the whole order A-1001: a TOTAL corrective, never a void.
export async function refundInFull(original: Invoice, returnId: string): Promise<Invoice> {
  const existing = await findCorrective(returnId);
  if (existing) return existing; // this return was already refunded

  const body: CreateCorrectiveInvoiceRequest = {
    rectification_type: 'TOTAL', // no `lines`: it takes back everything still invoiced
    rectification_code: original.type === 'SIMPLIFIED' ? 'R5' : 'R1',
    reason: 'Goods returned by the customer, order cancelled',
    circumstance_date: '2026-09-27', // the day of the return
    external_ref: returnId, // the id of the return, to find it again
    options: ISSUE_NOW,
  };
  return company.invoices.createCorrective(original.id, body, CALL);
}
// The original becomes VOIDED with void_cause TOTAL_CORRECTIVE; its record stays registered.

// One item of ticket T-2001 came back: an R5 PARTIAL corrective with the returned lines.
export async function refundLines(
  ticket: Invoice,
  returned: { description: string; quantity: number }[],
  returnId: string,
): Promise<Invoice> {
  const existing = await findCorrective(returnId);
  if (existing) return existing; // this return was already refunded

  const lines: CreateCorrectiveInvoiceRequest['lines'] = returned.map((item) => {
    const line = ticket.lines?.find((l) => l.description === item.description);
    if (!line) throw new Error(`"${item.description}" is not on ${ticket.invoice_number}`);
    return {
      description: `Return - ${item.description}`,
      quantity: -Math.abs(item.quantity), // negative: amounts taken back
      unit_price: line.unit_price, // the net unit price the ticket recorded
      discount_percentage: line.discount_percentage,
      main_tax: line.main_tax, // same rate as the original line
    };
  });

  const body: CreateCorrectiveInvoiceRequest = {
    rectification_type: 'PARTIAL',
    rectification_code: 'R5', // a simplified invoice is always corrected with R5
    reason: 'The customer returned one item of the ticket',
    circumstance_date: '2026-09-28',
    lines,
    external_ref: returnId,
    options: ISSUE_NOW,
  };
  return company.invoices.createCorrective(ticket.id, body, CALL);
}

NOT_SUBMITTED ──► PENDING ──► ACCEPTED
 (just issued)   (queued)  └► REJECTED

/** Issue every order first, then wait for AEAT on all of them together. */
export async function invoiceOrders(orderIds: string[]) {
  const issued: Invoice[] = [];
  const failed: { orderId: string; error: unknown }[] = [];

  for (const orderId of orderIds) {
    try {
      issued.push(await invoiceOrder(buildInvoice(orderId)));
    } catch (error) {
      failed.push({ orderId, error }); // see explain(): the other orders go on
    }
  }

  const { settled, pending } = await waitForAeat(issued);
  return {
    accepted: settled.filter((i) => i.verifactu?.submission_status === 'ACCEPTED'),
    rejected: settled.filter((i) => i.verifactu?.submission_status === 'REJECTED'), // read error_code / error_message
    notRegistered: settled.filter((i) => !i.verifactu?.enabled), // VeriFactu off for this NIF
    pending, // still NOT_SUBMITTED or PENDING: the verifactu.status.updated webhook reports them
    failed,
  };
}

export const AEAT_DEADLINE_MS = 120_000; // how long this run waits for AEAT, for the whole batch
export const AEAT_POLL_INTERVAL_MS = 5_000; // one round of list calls per tick

const WAITING: SubmissionStatus[] = ['NOT_SUBMITTED', 'PENDING'];

/**
 * Waits for AEAT on a whole batch at once, with one deadline. Returns the invoices
 * AEAT answered for (ACCEPTED or REJECTED) and the ones still waiting when the
 * deadline passed — those are not errors: the webhook will report them.
 */
export async function waitForAeat(issued: Invoice[]): Promise<{ settled: Invoice[]; pending: Invoice[] }> {
  const settled: Invoice[] = issued.filter((invoice) => !isWaiting(invoice));
  const pending = new Map(issued.filter(isWaiting).map((invoice) => [invoice.id, invoice]));
  const until = Date.now() + AEAT_DEADLINE_MS;
  const since = earliestIssueDate([...pending.values()]);

  while (pending.size > 0 && Date.now() < until) {
    await sleep(AEAT_POLL_INTERVAL_MS);
    // Two list calls per tick, whatever the batch size: what is still waiting since `since`.
    const stillWaiting = new Set<string>();
    for (const status of WAITING) {
      for (const invoice of await listAll(status, since)) stillWaiting.add(invoice.id);
    }
    // Whatever left those lists has an answer: read it once.
    for (const id of [...pending.keys()].filter((id) => !stillWaiting.has(id))) {
      const invoice = await company.invoices.get(id, CALL);
      if (isWaiting(invoice)) continue; // listed a moment before it moved
      settled.push(invoice);
      pending.delete(id);
    }
  }
  return { settled, pending: [...pending.values()] };
}

function isWaiting(invoice: Invoice): boolean {
  // No verifactu block, or enabled = false: never registered, nothing to wait for.
  if (!invoice.verifactu?.enabled) return false;
  const status = invoice.verifactu.submission_status;
  return status === undefined || WAITING.includes(status);
}

async function listAll(status: SubmissionStatus, since: string | undefined): Promise<Invoice[]> {
  const out: Invoice[] = [];
  for (let page = 1; ; page++) {
    const { invoices, pagination } = await company.invoices.list(
      { verifactu_status: status, date_from: since, limit: 100, page },
      CALL,
    );
    out.push(...invoices);
    if (page >= pagination.total_pages) return out;
  }
}

function earliestIssueDate(invoices: Invoice[]): string | undefined {
  const dates = invoices.map((invoice) => invoice.issue_date).filter((d): d is string => !!d);
  return dates.sort()[0];
}

const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));