Quickstart

Issue your first DIAN sales invoice with AdapterDian and follow it until the tax authority validates it.

Before you start

An API key issued by Piensa IT. See Authentication.
An authorized numbering range. If you have more than one active range for the same document type, see Numbering ranges.

Sandbox or production is decided by the key

The provider environment travels with your API key, not with the request. There is no header or parameter to switch it: ask for sandbox credentials to try things out.

Issue a sales invoice

Send the customer, the items and the payment details. Every issuing POST requires an Idempotency-Key header of at least 8 characters.

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

The adapter validates the issuing rules, calculates totals and the rounding adjustment, and queues the document. It answers 202 Accepted before the provider responds:

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

Check the status

The final status is queried separately, with the 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"

Wait for status to be validated (accepted by the DIAN) or rejected. A validated document may still carry warnings from the tax authority: they are not a rejection, but they point at master data worth fixing. See Document lifecycle.

Download the PDF

Once the document has a DIAN number, download its representation as pdf, xml, attached-xml (includes the authority’s response) or zip (the package that would go by email):

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"

Before it has a number, this returns 409 naming the current status.