Primeros pasos

Emite tu primera factura de venta DIAN con AdapterDian y síguela hasta que la autoridad tributaria la valide.

Antes de empezar

Una API Key emitida por Piensa IT. Ver Autenticación.
Un rango de numeración autorizado. Si tienes más de un rango activo para el mismo tipo de documento, ver Rangos de numeración.

Sandbox o producción lo decide la llave

El ambiente del proveedor viaja con tu API Key, no con la petición. No hay cabecera ni parámetro para cambiarlo: pide credenciales de sandbox para probar.

Emite una factura de venta

Envía el cliente, los ítems y los medios de pago. Todo POST que emite exige la cabecera Idempotency-Key, de al menos 8 caracteres.

POST /invoices/v1/sales-invoices

curl -X POST https://adapterdian.piensait.com/functions/v1/invoices/v1/sales-invoices \
  -H "Authorization: Bearer $ADAPTERDIAN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d @factura.json

const res = await fetch("https://adapterdian.piensait.com/functions/v1/invoices/v1/sales-invoices", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ADAPTERDIAN_API_KEY}`,
    // Save it with your order: a retry must reuse the same key.
    "Idempotency-Key": order.invoiceKey,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(invoice),
});
const { transaction_id, status, totals } = await res.json(); // 202 Accepted

{
  "customer": {
    "identification_document_code": "31",
    "identification": "123456789",
    "legal_organization": "legal_entity",
    "company": "Alan company name",
    "email": "[email protected]",
    "municipality_code": "68679"
  },
  "items": [
    {
      "code_reference": "PROD-000A",
      "name": "Producto A",
      "quantity": "1.00",
      "price": "10000.00",
      "unit_measure_code": "94",
      "standard_code": "999",
      "taxes": [
        {
          "code": "01",
          "rate": "19.00"
        }
      ]
    },
    {
      "code_reference": "PROD-000B",
      "name": "Producto B",
      "quantity": "3.00",
      "price": "20000.00",
      "unit_measure_code": "94",
      "standard_code": "999",
      "taxes": [
        {
          "code": "01",
          "rate": "19.00"
        }
      ]
    }
  ],
  "payment_details": [
    {
      "payment_form": "cash",
      "payment_method_code": "42",
      "reference_code": "pago-001",
      "amount": "83300.00"
    }
  ]
}

El adaptador valida las reglas de emisión, calcula los totales y el ajuste de redondeo, y encola el documento. Responde 202 Accepted antes de que el proveedor conteste:

202 Accepted

{
  "transaction_id": "91003243-14b6-4bed-9fd7-…",
  "status": "pending",
  "deduplicated": false,
  "totals": {
    "gross_amount": "70000.00",
    "discount_amount": "0.00",
    "taxable_amount": "70000.00",
    "tax_amount": "13300.00",
    "withholding_amount": "0.00",
    "total": "83300.00"
  },
  "cash_rounding_amount": "0.00"
}

Consulta el estado

El estado final se consulta aparte, con el transaction_id:

GET /invoices/v1/sales-invoices/{id}

curl https://adapterdian.piensait.com/functions/v1/invoices/v1/sales-invoices/$TRANSACTION_ID \
  -H "Authorization: Bearer $ADAPTERDIAN_API_KEY"

Espera a que status sea validated (aceptada por la DIAN) o rejected. Un documento validado puede traer warnings de la autoridad tributaria: no son un rechazo, pero señalan datos maestros que conviene corregir. Ver Ciclo de vida del documento.

Descarga el PDF

Cuando el documento ya tiene número DIAN, descarga su representación como pdf, xml, attached-xml (incluye la respuesta de la autoridad) o zip (el paquete que iría por correo):

GET /invoices/v1/sales-invoices/{id}/pdf

curl -OJ https://adapterdian.piensait.com/functions/v1/invoices/v1/sales-invoices/$TRANSACTION_ID/pdf \
  -H "Authorization: Bearer $ADAPTERDIAN_API_KEY"

Antes de tener número responde 409 nombrando el estado actual.