Respond to your suppliers' invoices

When a supplier issues an e-invoice to your business, Timbro receives it. Your system can retrieve it, compare it with the purchase it recorded, and tell the supplier and the DGII whether the business accepts or rejects it. The DGII calls that response commercial approval, and the API calls it commercialResponse.

Use the invoicing SDK (@timbro/invoices or timbro-invoices) with an API key with Invoicing access. The key determines the business and the mode, so do not send them as filters.

Retrieve the pending invoices

TypeScript

import { createTimbroInvoices } from "@timbro/invoices";

const timbro = createTimbroInvoices({ apiKey: process.env.TIMBRO_INVOICES_API_KEY! });
const pending = await timbro.receivedDocuments.list({ response: "pending", limit: 20 });
const summary = pending.data[0];
const received = summary ? await timbro.receivedDocuments.retrieve(summary.id) : undefined;
if (received) {
  const xml = await timbro.receivedDocuments.downloadXml(received.id);
}

Python

import os

from timbro_invoices import TimbroInvoices

timbro = TimbroInvoices(api_key=os.environ["TIMBRO_INVOICES_API_KEY"])
pending = timbro.received_documents.list(response="pending", limit=20)
received = (
    timbro.received_documents.retrieve(pending["data"][0]["id"]) if pending["data"] else None
)
if received is not None:
    received_xml = timbro.received_documents.download_xml(received["id"])

Before responding, compare the XML and the supplier’s data with the purchase your system recorded. Store the received invoice’s id with that purchase.

Accept or reject the invoice

TypeScript

if (received?.commercialResponse.status === "pending") {
  const reviewed = await timbro.receivedDocuments.respond(received.id, { decision: "accepted" });
}

Python

if received is not None and received["commercialResponse"]["status"] == "pending":
    reviewed = timbro.received_documents.respond(received["id"], {"decision": "accepted"})

To reject it, send { decision: "rejected", motive: "The amount does not match the purchase order" }. The commercial response and its submission to the DGII have their own statuses; retrieve the received invoice to learn whether the DGII already received your response.

Responding does not record the purchase in your accounting or confirm that you paid the supplier. Your system still handles those tasks.

With HTTP, use GET /v1/received-documents?response=pending, GET /v1/received-documents/{receivedDocumentId}, and GET /v1/received-documents/{receivedDocumentId}/files/xml. Respond with POST /v1/received-documents/{receivedDocumentId}/commercial-response and the body { "decision": "accepted" } or { "decision": "rejected", "motive": "..." }.