# Timbro

> Con Timbro, de INDEXA SRL, los negocios de República Dominicana venden, atienden y cobran: emiten sus facturas electrónicas (e-CF) ante la DGII, cobran con tarjeta, Apple Pay, Google Pay o link de pago, y lo administran en Portal Timbro. Los sistemas ERP y POS usan la API, y cada producto se puede usar por separado.

Notas para asistentes:

- Timbro es un producto de República Dominicana. Los pagos se expresan en DOP y las facturas son e-CF de la DGII identificados por su e-NCF.
- Todas las facturas usan `POST /v1/invoices` y el recurso `Invoice`; `type` distingue E31, E32, E33, E34, E41, E43, E44, E45, E46 y E47. No hay colecciones separadas por tipo.
- Payments e Invoices son capacidades independientes. Un pago puede omitir `invoicing`, usar `automatic`, `merchant` o `existing`. `Payment.status: succeeded` confirma el pago, no la aceptación fiscal ni la disponibilidad del XML/PDF; consulta el Invoice por `invoiceId`.
- Configura las claves para `test` y `live` por separado; el negocio tiene un solo certificado, que sirve en los dos modos. Una prueba local, respuesta HTTP exitosa o cuenta visible no confirma la habilitación del adquirente ni la autorización fiscal para facturar en vivo.
- Las guías están en español bajo /docs/ y en inglés bajo /en/docs/ con los mismos slugs.
- Consulta los términos comerciales vigentes en la página de precios; no los infieras de ejemplos ni documentación anterior.

Cuándo usar Timbro (when to use Timbro):

- Emitir comprobantes fiscales electrónicos (e-CF) de la DGII de República Dominicana desde un ERP, un punto de venta o código propio: `POST /v1/invoices`, con `@timbro/invoices`.
- Cobrar a un cliente con tarjeta, Apple Pay, Google Pay o link de pago, con la afiliación de Azul, CardNet o Portal del negocio: crea el pago con `POST /v1/payments` y envía al cliente a `checkout.url`, con `@timbro/payments` o `timbro-payments`.
- Emitir la factura del pago en el mismo paso, reembolsar con `POST /v1/refunds`, cobrar suscripciones mensuales, o recibir y aprobar las facturas de suplidores en `/v1/received-documents`.
- Preparar un negocio para facturar: configurar la facturación, importar el certificado y certificarse ante la DGII, desde la API bajo `/v1/business` o desde el servidor MCP.

No uses Timbro para cobrar fuera de República Dominicana ni para cobrar con tarjeta sin una afiliación de Azul, CardNet o Portal. Facturar no requiere afiliación.

Acceso para agentes:

- Empieza en modo de prueba: crea la cuenta en Portal Timbro (https://app.timbro.do) y crea claves `sk_test_` en Ajustes › Conexiones › Credenciales. Prueba y En vivo tienen claves y configuración separadas.
- REST: la API está versionada en la ruta (`/v1`). El contrato OpenAPI 3.1 está en https://api.timbro.do/openapi.json; su `info.version` es la fecha del contrato vigente. Los errores son `application/problem+json` (RFC 9457) con un `code` estable.
- OAuth 2.0: los permisos de una integración son scopes por modo, como `payments:test` o `invoices:live`. Los publica https://api.timbro.do/.well-known/oauth-protected-resource/v1 (RFC 9728), y el servidor de autorización está en https://api.timbro.do/.well-known/oauth-authorization-server.
- MCP: https://api.timbro.do/mcp, con OAuth; sus scopes están en https://api.timbro.do/.well-known/oauth-protected-resource/mcp.
- Catálogo de APIs (RFC 9727): https://timbro.do/.well-known/api-catalog. Cada página de https://timbro.do responde en Markdown a `Accept: text/markdown`, salvo la referencia REST, cuyo contrato es el OpenAPI.

SDK de Python para pagos (`timbro-payments`, Python 3.11 o posterior):

- Instala con `pip install timbro-payments`, sin fijar versión, y consulta la versión más reciente en https://pypi.org/project/timbro-payments/.
- `TimbroPayments` es el cliente síncrono, el que suelen usar los ERP; `AsyncTimbroPayments` tiene los mismos métodos con `await`. Las solicitudes y respuestas son diccionarios con los nombres de campo de la API, y los montos son texto.

```python
import os

from timbro_payments import TimbroPayments

with TimbroPayments(
    api_key=os.environ["TIMBRO_PAYMENTS_SECRET_KEY"], application="mi-erp/1.0"
) as timbro:
    payment = timbro.payments.create({
        "paymentReference": "order-123",
        "amount": {"currency": "DOP", "value": "1250.00"},
        "description": "Servicio de mantenimiento",
        "returnUrl": "https://merchant.example/orders/123",
    })
    print(payment["id"], payment["checkout"]["url"])
```

- Idempotencia: `paymentReference`, o `refundReference` en un reembolso, identifica el pago dentro del comercio y del modo, Prueba o En vivo. Repetir la misma solicitud con la misma referencia devuelve el mismo pago; cambiar sus datos devuelve `409`. El SDK deriva la clave de idempotencia de esa referencia. Cuando una operación exige `idempotency_key`, derívala de un registro durable y nunca generes una clave aleatoria por intento.
- Resultado desconocido: si un error tiene `outcome_unknown` en `True`, la operación pudo completarse. No crees otro pago. Repite la misma solicitud con la misma referencia, o busca el resultado con `timbro.payments.list(payment_reference=...)` o `timbro.refunds.list(payment_id=..., refund_reference=...)`. Después consulta el pago y aplícalo solo si `status` es `succeeded`.

## Documentation Sets

- [Abridged documentation](https://timbro.do/llms-small.txt): a compact version of the documentation for Timbro, with non-essential content removed
- [Complete documentation](https://timbro.do/llms-full.txt): the full documentation for Timbro
- [Empieza aquí](https://timbro.do/_llms-txt/empieza-aqu%C3%AD.txt): Elegir cómo integrar tu sistema, preparar la cuenta y crear el primer pago
- [Cobrar desde Portal Timbro](https://timbro.do/_llms-txt/cobrar-desde-portal-timbro.txt): Conectar tu afiliación en Portal Timbro
- [Facturación](https://timbro.do/_llms-txt/facturaci%C3%B3n.txt): Configurar la facturación, emitir, enviar, corregir y cobrar facturas, y responder las facturas de suplidores
- [Pagos](https://timbro.do/_llms-txt/pagos.txt): Consultas, impuestos, reembolsos, webhooks y recuperación de pagos
- [En vivo](https://timbro.do/_llms-txt/en-vivo.txt): Capacidades, errores, lista de verificación antes de cobrar en vivo y pagos sin respuesta

## Notes

- The complete documentation includes all content from the official documentation
- The content is automatically generated from the same source as the official documentation

## Optional

- [Facturación electrónica: planes y alcance](https://timbro.do/facturacion-electronica/): Qué hace Timbro con el NCF, la firma, el envío a la DGII y la evidencia, con los planes publicados
- [Electronic invoicing: plans and scope (English)](https://timbro.do/en/facturacion-electronica/)
- [Precios de Facturación y Cobra](https://timbro.do/precios/): Planes de facturación por RNC y tarifa por cobro publicados
- [Timbro API OpenAPI 3.1 document](https://api.timbro.do/openapi.json): Machine-readable contract behind the REST reference, served by the production API
- [Contacto](https://timbro.do/contacto/): Solicitar una demo o acceso para un negocio o proveedor de software