Compras

Registra compras por el mismo camino que la pantalla Nueva compra: el gasto se contabiliza (y el kardex se mueve si hay inventario), una liquidación de compra se emite fiscalmente, y con "withhold": true se emite el comprobante de retención. Los listados y consultas son recursos JSON:API sobre el mismo registro.

El objeto `purchase` #

Atributos

country enum requerido

ECPE

currency string requerido

Moneda ISO 4217 ( USD en Ecuador, PEN en Perú).

environment enum requerido

Partición del dato: por una llave solo viaja production .

testproduction

grand_total string requerido

Importe total, como cadena decimal.

issue_date date requerido

Fecha de emisión (AAAA-MM-DD).

kind enum requerido

Tipo de documento de compra: factura de proveedor, liquidación o nota.

purchase_orderbillliquidacioncredit_notedebit_note

lines array requerido

Las líneas con su categoría de gasto y códigos de retención.

payment_methods array requerido

Códigos de forma de pago (SRI Tabla 24).

status enum requerido

Ciclo de vida: confirmed contabilizada · issued con liquidación emitida · withheld con retención emitida · void anulada.

draftapprovedconfirmedpending_approvalrejectedissuedwithheldvoid

supplier object requerido

El proveedor: identificación, nombre y correo.

tenant_slug string requerido

La organización dueña del libro.

total_tax string requerido

IVA de la compra, como cadena decimal.

total_withheld string requerido

Total retenido, como cadena decimal.

total_without_taxes string requerido

Subtotal sin impuestos, como cadena decimal.

access_key string

Clave de acceso de la liquidación emitida, si la compra es una liquidación.

approved_by_user_id uuid

book_id uuid

El libro contable dueño del registro — siempre el de tu llave.

electronic_document_id uuid

Id del comprobante propio (liquidación) en /documents , si se emitió.

import_ref string

journal_id uuid

El asiento contable que registró la compra.

notes string

Notas internas.

posted_at datetime

Momento de contabilización.

raised_by_user_id uuid

received_by_user_id uuid

source_authorization string

En notas: autorización de la factura modificada.

source_date date

En notas: fecha de la factura modificada.

source_id uuid

Id interno del documento de origen, si existe.

source_number string

En notas: la factura que la nota modifica.

supplier_authorization string

Autorización o clave de acceso del comprobante del proveedor.

supplier_doc_number string

Número del comprobante del proveedor — el sustento.

supplier_doc_type string

Código del tipo de documento del proveedor ( 01 factura).

supplier_notified_at datetime

tax_support string

Sustento tributario (código 00 – 09 , SRI Tabla 5).

transaction_type_key string

void_reason string

Motivo de anulación, si fue anulada.

warehouse_id uuid

withholding_access_key string

Clave de acceso de la retención emitida.

withholding_document_id uuid

Id del comprobante de retención emitido en /documents , si se emitió.

withholding_regime string

Régimen de retención aplicado, si el emisor tiene uno especial.

Filtrable por: access_keyapproved_by_user_idbook_idcountrycurrencyelectronic_document_idenvironmentgrand_totalidimport_refissue_datejournal_idkindnotesposted_atraised_by_user_idreceived_by_user_idsource_authorizationsource_datesource_idsource_numberstatussupplier_authorizationsupplier_doc_numbersupplier_doc_typesupplier_notified_attax_supporttenant_slugtotal_taxtotal_withheldtotal_without_taxestransaction_type_keyvoid_reasonwarehouse_idwithholding_access_keywithholding_document_idwithholding_regime

Ordenable por: access_keyapproved_by_user_idbook_idcountrycurrencyelectronic_document_idenvironmentgrand_totalidimport_refissue_datejournal_idkindnotesposted_atraised_by_user_idreceived_by_user_idsource_authorizationsource_datesource_idsource_numberstatussupplier_authorizationsupplier_doc_numbersupplier_doc_typesupplier_notified_attax_supporttenant_slugtotal_taxtotal_withheldtotal_without_taxestransaction_type_keyvoid_reasonwarehouse_idwithholding_access_keywithholding_document_idwithholding_regime

Registrar una compra#

POST /api/v1/purchases Bearer

Crea y confirma la compra en una llamada; idempotente por external_ref (mismo espacio de referencias que las facturas). Una falla fiscal posterior nunca deshace la compra contabilizada: la respuesta la nombra en warnings ( liquidacion_not_issued , withholding_not_issued ).

Content-Type: application/json

Cuerpo de la solicitud

supplier.identification string requerido

Cédula o RUC del proveedor.

supplier.name string requerido

Razón social del proveedor.

lines[] array requerido

Las líneas de la compra — al menos una.

lines[].description string requerido

Descripción de la línea.

lines[].unit_price decimal (string) requerido

Precio unitario sin impuestos.

kind string

Tipo de documento; por defecto "bill" (factura del proveedor).

billliquidacioncredit_notedebit_note

doc.number string

Número del comprobante del proveedor ( 001-001-000012345 ) — el sustento. No aplica a liquidaciones.

doc.authorization string

Autorización del comprobante del proveedor.

source.number string

Para notas de crédito/débito: la factura que modifica (requerido en notas).

source.authorization string

Autorización de la factura modificada.

source.date date

Fecha de la factura modificada.

tax_support string

Sustento tributario (código 00 – 09 ).

payment_method string

Código de forma de pago; por defecto "20" .

withhold boolean

Con true , emite el comprobante de retención tras registrar la compra.

external_ref string

Tu identificador de la operación — la clave de idempotencia.

order_id string (uuid)

La orden de compra que esta factura satisface. Hereda su flujo, aplica el control de copiado (no se factura más de lo pendiente) y la conciliación orden × recepción × factura — una diferencia responde 409 match_blocked sin registrar nada.

transaction_type string

Clave de un flujo de transacción del libro (compras). Un flujo restringido a puestos del espacio de trabajo no admite llaves de API.

issue_date date

Fecha de emisión (AAAA-MM-DD); por defecto hoy.

notes string

Notas internas de la compra.

lines[].quantity decimal (string)

Cantidad; por defecto "1" .

lines[].discount decimal (string)

Descuento en monto por línea.

lines[].iva string

Tarifa de IVA ( "15" , "5" , "0" ) o "exento" / "no_objeto" .

lines[].expense_category string

Categoría del gasto; decide la cuenta contable destino.

generalinventoryfixed_assettravelreimbursementinsurance

lines[].renta_code string

Código de retención de renta (SRI) para la línea.

lines[].iva_code string

Código de retención de IVA para la línea.

Devuelve · 201 con el objeto compra (o 200 si external_ref ya fue registrado). 422 validation_failed · 422 book_not_configured · 422 flow_refused · 409 match_blocked con differences (nada se registra) · 409 in_progress .

cURL

curl -X POST https://edge.datil.com/api/v1/purchases \
  -H "Authorization: Bearer $DATIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "external_ref": "compra-2049",
  "kind": "bill",
  "supplier": {
    "identification": "1790012345001",
    "name": "Proveedora Andina S.A."
  },
  "doc": {
    "number": "002-001-000012345",
    "authorization": "0307202601099234567800110010020000001231234567814"
  },
  "tax_support": "01",
  "withhold": true,
  "lines": [
    {
      "description": "Suministros de oficina",
      "quantity": "10",
      "unit_price": "12.50",
      "iva": "15",
      "expense_category": "general",
      "renta_code": "312"
    }
  ]
}'

Respuesta · 201

{
  "id": "4c8b2d6e-0a1f-4b3c-9e5d-7a9c1e3b5d7f",
  "kind": "bill",
  "status": "withheld",
  "environment": "production",
  "issue_date": "2026-07-03",
  "currency": "USD",
  "supplier": {
    "identification": "1790012345001",
    "name": "Proveedora Andina S.A."
  },
  "supplier_doc": {
    "type": "01",
    "number": "002-001-000012345",
    "authorization": "0307202601099234567800110010020000001231234567814"
  },
  "tax_support": "01",
  "payment_methods": [
    "20"
  ],
  "totals": {
    "without_taxes": "125.00",
    "tax": "18.75",
    "withheld": "1.25",
    "grand_total": "143.75"
  },
  "access_key": null,
  "electronic_document_id": null,
  "withholding": {
    "document_id": "2b4d6f8a-0c2e-4d5f-8b1a-3c5e7a9b1d3c",
    "access_key": "0307202607179000000000110010010000045671234567812"
  },
  "posted_at": "2026-07-03T14:07:00Z",
  "links": {
    "self": "/api/v1/purchases/4c8b2d6e-0a1f-4b3c-9e5d-7a9c1e3b5d7f",
    "withhold": "/api/v1/purchases/4c8b2d6e-0a1f-4b3c-9e5d-7a9c1e3b5d7f/withhold"
  }
}

Emitir la retención#

POST /api/v1/purchases/:id/withhold Bearer

Emite (o reintenta) el comprobante de retención de una compra ya registrada — el mismo reintento que el botón Emitir retención del registro.

Content-Type: application/json

Parámetros

id uuid requerido

Id de la compra.

Devuelve · 200 con el objeto compra · 404 not_found · 422 withholding_failed .

cURL

curl -X POST https://edge.datil.com/api/v1/purchases/4c8b2d6e-0a1f-4b3c-9e5d-7a9c1e3b5d7f/withhold \
  -H "Authorization: Bearer $DATIL_API_KEY"

Respuesta · 200

{
  "id": "4c8b2d6e-0a1f-4b3c-9e5d-7a9c1e3b5d7f",
  "kind": "bill",
  "status": "withheld",
  "environment": "production",
  "issue_date": "2026-07-03",
  "currency": "USD",
  "supplier": {
    "identification": "1790012345001",
    "name": "Proveedora Andina S.A."
  },
  "supplier_doc": {
    "type": "01",
    "number": "002-001-000012345",
    "authorization": "0307202601099234567800110010020000001231234567814"
  },
  "tax_support": "01",
  "payment_methods": [
    "20"
  ],
  "totals": {
    "without_taxes": "125.00",
    "tax": "18.75",
    "withheld": "1.25",
    "grand_total": "143.75"
  },
  "access_key": null,
  "electronic_document_id": null,
  "withholding": {
    "document_id": "2b4d6f8a-0c2e-4d5f-8b1a-3c5e7a9b1d3c",
    "access_key": "0307202607179000000000110010010000045671234567812"
  },
  "posted_at": "2026-07-03T14:07:00Z",
  "links": {
    "self": "/api/v1/purchases/4c8b2d6e-0a1f-4b3c-9e5d-7a9c1e3b5d7f",
    "withhold": "/api/v1/purchases/4c8b2d6e-0a1f-4b3c-9e5d-7a9c1e3b5d7f/withhold"
  }
}

Listar compras#

GET /api/v1/purchases Bearer

Recurso JSON:API purchase , siempre acotado al libro de la llave por política del recurso.

Parámetros

filter[…] object

Filtra por atributo: filter[kind]=customer , u operadores anidados como filter[issue_date][greater_than]=2026-07-01 . Combinable con filter[and] / filter[or] .

sort string

Atributos separados por coma; prefijo - para descendente: sort=-issue_date .

page[limit] integer

Máximo de registros por página.

page[offset] integer

Desplazamiento desde el inicio del listado.

page[count] boolean

Con true , la respuesta incluye el total en meta.page.total .

fields[tipo] string

Atributos a devolver, separados por coma — el sparse fieldset de JSON:API.

Devuelve · 200 con data — lista de objetos purchase .

cURL

curl "https://edge.datil.com/api/v1/purchases?filter[status]=withheld&sort=-issue_date&page[limit]=20" \
  -H "Authorization: Bearer $DATIL_API_KEY"

Respuesta · 200

{
  "data": [
    {
      "type": "purchase",
      "id": "4c8b2d6e-0a1f-4b3c-9e5d-7a9c1e3b5d7f",
      "attributes": {
        "country": "EC",
        "currency": "USD",
        "environment": "production",
        "grand_total": "143.75",
        "issue_date": "2026-07-03",
        "kind": "bill",
        "lines": [
          {
            "description": "Suministros de oficina",
            "quantity": "10.00",
            "unit_price": "12.50",
            "discount": "0.00",
            "expense_category": "general",
            "renta_withholding_code": "312"
          }
        ],
        "payment_methods": [
          "20"
        ],
        "status": "withheld",
        "supplier": {
          "identification": "1790012345001",
          "name": "Proveedora Andina S.A."
        },
        "tenant_slug": "acme",
        "total_tax": "18.75",
        "total_withheld": "1.25",
        "total_without_taxes": "125.00",
        "access_key": null,
        "approved_by_user_id": null,
        "book_id": "1d2f4b6a-8c0e-4a2b-9d3f-5e7a9c1b3d5f",
        "electronic_document_id": null,
        "import_ref": null,
        "journal_id": "6a1c3e5b-7d9f-4a2c-8e0b-2d4f6a8c0e2b",
        "notes": null,
        "posted_at": "2026-07-03T14:07:00Z",
        "raised_by_user_id": null,
        "received_by_user_id": null,
        "source_authorization": null,
        "source_date": null,
        "source_id": null,
        "source_number": null,
        "supplier_authorization": "0307202601099234567800110010020000001231234567814",
        "supplier_doc_number": "002-001-000012345",
        "supplier_doc_type": "01",
        "supplier_notified_at": null,
        "tax_support": "01",
        "transaction_type_key": null,
        "void_reason": null,
        "warehouse_id": null,
        "withholding_access_key": "0307202607179000000000110010010000045671234567812",
        "withholding_document_id": "2b4d6f8a-0c2e-4d5f-8b1a-3c5e7a9b1d3c",
        "withholding_regime": null
      }
    }
  ]
}

Consultar una compra#

GET /api/v1/purchases/:id Bearer

Un objeto purchase por id, del libro de la llave.

Parámetros

id uuid requerido

Id de la compra.

Devuelve · 200 con data · 404 .

cURL

curl "https://edge.datil.com/api/v1/purchases/4c8b2d6e-0a1f-4b3c-9e5d-7a9c1e3b5d7f" \
  -H "Authorization: Bearer $DATIL_API_KEY"

Respuesta · 200

{
  "data": {
    "type": "purchase",
    "id": "4c8b2d6e-0a1f-4b3c-9e5d-7a9c1e3b5d7f",
    "attributes": {
      "country": "EC",
      "currency": "USD",
      "environment": "production",
      "grand_total": "143.75",
      "issue_date": "2026-07-03",
      "kind": "bill",
      "lines": [
        {
          "description": "Suministros de oficina",
          "quantity": "10.00",
          "unit_price": "12.50",
          "discount": "0.00",
          "expense_category": "general",
          "renta_withholding_code": "312"
        }
      ],
      "payment_methods": [
        "20"
      ],
      "status": "withheld",
      "supplier": {
        "identification": "1790012345001",
        "name": "Proveedora Andina S.A."
      },
      "tenant_slug": "acme",
      "total_tax": "18.75",
      "total_withheld": "1.25",
      "total_without_taxes": "125.00",
      "access_key": null,
      "approved_by_user_id": null,
      "book_id": "1d2f4b6a-8c0e-4a2b-9d3f-5e7a9c1b3d5f",
      "electronic_document_id": null,
      "import_ref": null,
      "journal_id": "6a1c3e5b-7d9f-4a2c-8e0b-2d4f6a8c0e2b",
      "notes": null,
      "posted_at": "2026-07-03T14:07:00Z",
      "raised_by_user_id": null,
      "received_by_user_id": null,
      "source_authorization": null,
      "source_date": null,
      "source_id": null,
      "source_number": null,
      "supplier_authorization": "0307202601099234567800110010020000001231234567814",
      "supplier_doc_number": "002-001-000012345",
      "supplier_doc_type": "01",
      "supplier_notified_at": null,
      "tax_support": "01",
      "transaction_type_key": null,
      "void_reason": null,
      "warehouse_id": null,
      "withholding_access_key": "0307202607179000000000110010010000045671234567812",
      "withholding_document_id": "2b4d6f8a-0c2e-4d5f-8b1a-3c5e7a9b1d3c",
      "withholding_regime": null
    }
  }
}

El objeto purchase #

Registrar una compra#

Emitir la retención#

Listar compras#

Consultar una compra#

Cookies

El objeto `purchase` #