Responder las facturas de tus suplidores

Cuando un suplidor le emite una factura electrónica a tu negocio, Timbro la recibe. Tu sistema puede consultarla, compararla con la compra que registró y decirle al suplidor y a la DGII si el negocio la acepta o la rechaza. La DGII llama a esa respuesta aprobación comercial, y la API la llama commercialResponse.

Usa el SDK de facturación (@timbro/invoices o timbro-invoices) con una clave de API con acceso a Facturación. La clave determina el negocio y el modo, así que no los envíes como filtros.

Consulta las facturas pendientes

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"])

Compara el XML y los datos del suplidor con la compra que registró tu sistema antes de responder. Guarda el id de la factura recibida junto a esa compra.

Acepta o rechaza la factura

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"})

Para rechazarla, envía { decision: "rejected", motive: "El monto no coincide con la orden de compra" }. La respuesta comercial y su envío a la DGII tienen estados propios; consulta la factura recibida para saber si la DGII ya recibió tu respuesta.

Responder no registra la compra en tu contabilidad ni confirma que le pagaste al suplidor. Tu sistema sigue llevando esas tareas.

Con HTTP, usa GET /v1/received-documents?response=pending, GET /v1/received-documents/{receivedDocumentId} y GET /v1/received-documents/{receivedDocumentId}/files/xml. Responde con POST /v1/received-documents/{receivedDocumentId}/commercial-response y el cuerpo { "decision": "accepted" } o { "decision": "rejected", "motive": "..." }.