Empieza aquí

Crea tu cuenta en el sandbox, envía tu primera factura de prueba y descarga su PDF en cinco pasos.

Página de muestra

El sandbox público todavía no está abierto. Esta página muestra cómo funcionará cuando esté listo: las direcciones sandbox.trinity-soft.com y api-sandbox.trinity-soft.com aún no responden.

En el sandbox puedes probar la facturación electrónica sin pagar nada y sin tener un certificado digital. Tus facturas se envían al ambiente de habilitación (pruebas) de la DIAN, así que ves respuestas reales de la DIAN, pero las facturas no tienen validez fiscal.

Solo necesitas un correo electrónico y una forma de hacer peticiones HTTP: la terminal (cURL) o tu lenguaje de programación.

Crea tu cuenta

Entra a sandbox.trinity-soft.com y elige Crear cuenta.
Escribe tu correo y una contraseña.
Te llega un código a tu correo. Escríbelo para confirmar la cuenta.

Al entrar, tu cuenta ya tiene una empresa de pruebas lista para facturar. No tienes que configurar resolución, rango ni certificado: el sandbox usa un emisor de pruebas compartido.

Copia tu API key

En el panel, abre API keys y elige Crear API key. Cópiala y guárdala en un lugar seguro: solo se muestra una vez.

La API key va en el encabezado X-API-Key de cada petición. Trátala como una contraseña: no la pongas en el código ni en el navegador, y no la compartas. Si se filtra, revócala en el panel y crea otra.

En los ejemplos de esta guía, guárdala en una variable de entorno:

export TRIFACO_API_KEY="pega-aqui-tu-api-key"

Envía tu primera factura

Una factura necesita saber con qué rango de numeración se numera. Primero consulta tu rango con GET /v1/numbering-ranges y copia su id. Después envía la factura con POST /v1/invoices.

Cada envío lleva un encabezado Idempotency-Key: un texto único que tú eliges (de 8 a 128 caracteres). Si se corta la conexión y repites la petición con la misma clave, no se crea una factura duplicada.

API=https://api-sandbox.trinity-soft.com

# 1. Consulta tu rango de numeración
curl -s "$API/v1/numbering-ranges" -H "X-API-Key: $TRIFACO_API_KEY"

# 2. Envía la factura (cambia RANGO_ID por el id del paso anterior)
curl -s -X POST "$API/v1/invoices" \
  -H "X-API-Key: $TRIFACO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: mi-primera-factura-001" \
  -d '{
    "document_type": "invoice",
    "external_reference": "PEDIDO-001",
    "profile_id": "co-sale-cop-v1",
    "numbering_range_id": "RANGO_ID",
    "issued_at": "2026-09-16T10:00:00-05:00",
    "currency": "COP",
    "buyer": {
      "party_type": "person",
      "identification": { "type_code": "13", "number": "1000000000" },
      "name": "Cliente de prueba",
      "email": "cliente@example.com",
      "tax_registration": { "responsibility_codes": ["R-99-PN"], "tax_scheme_codes": ["01"] }
    },
    "lines": [{
      "id": "1",
      "description": "Servicio de prueba",
      "product_identification": { "scheme_code": "999", "value": "SERV-001" },
      "quantity": "1",
      "unit_code": "94",
      "unit_price": "10000.00",
      "price_base_quantity": "1",
      "net_amount": "10000.00",
      "adjustments": [],
      "taxes": [{ "code": "01", "rate": "19", "taxable_amount": "10000.00", "amount": "1900.00" }],
      "withholdings": []
    }],
    "adjustments": [],
    "tax_totals": [{ "code": "01", "rate": "19", "taxable_amount": "10000.00", "amount": "1900.00" }],
    "withholding_totals": [],
    "totals": {
      "line_extension_amount": "10000.00",
      "tax_exclusive_amount": "10000.00",
      "tax_inclusive_amount": "11900.00",
      "allowance_total_amount": "0.00",
      "charge_total_amount": "0.00",
      "prepaid_amount": "0.00",
      "payable_rounding_amount": "0.00",
      "payable_amount": "11900.00"
    },
    "payment": { "terms": "cash", "means_code": "10" }
  }'

La API responde 202 con el document_id de tu factura. 202 significa "recibida", no "aprobada por la DIAN": la factura se firma y se envía a la DIAN en segundo plano. Guarda el document_id para el siguiente paso.

¿Qué significa cada campo? Lo explicamos uno por uno en Crear una factura.

Consulta el resultado y el CUFE

Consulta la factura con GET /v1/documents/{id}, usando el document_id del paso anterior. Espera unos segundos entre consultas.

curl -s "$API/v1/documents/DOCUMENT_ID" -H "X-API-Key: $TRIFACO_API_KEY"

Fíjate en estos campos:

Campo	Qué te dice
`processing_status`	Si ya terminamos de procesarla. Cuando dice `completed`, ya hay respuesta.
`dian.status`	La respuesta de la DIAN: `validated` (aprobada), `rejected` (rechazada) o `pending` (esperando).
`dian.errors`	Si fue rechazada, aquí están los motivos.
`fiscal_identity.prefix` y `fiscal_identity.number`	El número que se le asignó a la factura, por ejemplo `SETP` `990001234`.
`fiscal_identity.unique_code`	El CUFE: el código único con el que la DIAN identifica la factura.

Si dian.status dice unknown, no vuelvas a enviar la factura: no sabemos todavía si la DIAN la recibió. Sigue consultando.

En lugar de consultar muchas veces, puedes pedir que te avisemos: mira Webhooks.

Descarga el PDF

Pide la lista de archivos de la factura con GET /v1/documents/{id}/artifacts. Busca el que tenga kind: pdf y status: available, y descárgalo con GET /v1/artifacts/{id}/content.

# Lista los archivos
curl -s "$API/v1/documents/DOCUMENT_ID/artifacts" -H "X-API-Key: $TRIFACO_API_KEY"

# Descarga el PDF (cambia ARTIFACT_ID por el id del archivo pdf)
curl -s "$API/v1/artifacts/ARTIFACT_ID/content" -H "X-API-Key: $TRIFACO_API_KEY" -o factura.pdf

En la misma lista está el XML firmado (kind: signed_xml) y la respuesta de la DIAN (kind: dian_response). Si un archivo aparece como pending, espera unos segundos y vuelve a consultar.

¿Y ahora qué?

Glosario: qué significan CUFE, rango, prefijo y los demás términos.
Crear una factura: todos los campos, con su explicación.
Errores: qué hacer cuando algo falla.