Ir al contenido
tukontatukontaAPIv1.7.0

Gastos

Los gastos de la empresa, con su proveedor, sus líneas y, si se quiere, su PDF y sus vencimientos.

Listar gastos

Sección titulada «Listar gastos»
GET/expenses/

Además de la paginación, admite estos filtros:

Parámetro Descripción
filter Parte del número del gasto.
provider_id id del proveedor.
provider_cif NIF del proveedor (completo).
provider Parte de la razón social o del nombre comercial del proveedor.
issued true para los gastos confirmados y false para los borradores.
payment_status pending (pendiente de pago) o paid (pagado).
min, max Importe total mínimo y máximo.
minDate, maxDate Fecha mínima y máxima, en formato yyyy-MM-dd. Envía las dos: si solo se indica una, se filtra únicamente ese día.
Ejemplo de envíolo que se manda a la API

Esta petición no lleva cuerpo: basta con la dirección y la clave de API.

Con curl
curl "https://api-sandbox.tukonta.com/v1/expenses/" \
  -H "X-API-KEY: $TUKONTA_API_KEY" \
  -H "Accept: application/json"
Ejemplo de respuestalo que devuelve la API
  • Respuesta: { "data": [ ... ], "pagination": { "total", "offset", "limit", "count", "hasMore" } }.
  • En cada gasto de la lista, company es el id de la empresa (texto) y en provider los campos de nombre siguen la misma regla que en customer de las facturas: solo aparecen si es individual.
  • Parámetro filter: busca por una parte del número de gasto, sin distinguir mayúsculas y minúsculas.

Obtener un gasto

Sección titulada «Obtener un gasto»
GET/expenses/:id
Ejemplo de envíolo que se manda a la API

Esta petición no lleva cuerpo: basta con la dirección y la clave de API.

Con curl
curl "https://api-sandbox.tukonta.com/v1/expenses/ID_GASTO" \
  -H "X-API-KEY: $TUKONTA_API_KEY" \
  -H "Accept: application/json"
Ejemplo de respuestalo que devuelve la API
  • company es el objeto completo de la empresa, como en el detalle de ingresos y facturas.
  • POST /expenses/ y PUT /expenses/:id devuelven lo mismo que GET /expenses/:id.
  • Las líneas no devuelven imputation, investment ni customs_vat: para actualizar el gasto hay que enviarlos de nuevo.
  • En los vencimientos, si está pagado se indica con paid.
{
    "id": "string",
    "company": {
        "id": "string",
        "cif": "string",
        "business_name": "string",
        "business_type": "string",
        "trade_name": "string",
        "address": "string",
        "postal_code": "string",
        "town": "string",
        "region": "string",
        "country_code": "string",
        "phone": "string",
        "email": "string",
        "web": "string"
    },
    "provider": {
        "id": "string",
        "cif": "string",
        "business_name": "string",
        "trade_name": "string",
        "name": "string",
        "surname_1": "string",
        "surname_2": "string",
        "business_type": "string",
        "address": "string",
        "postal_code": "string",
        "town": "string",
        "region": "string",
        "country_code": "string",
        "phone": "string",
        "email": "string"
    },
    "issued": boolean,
    "date": "string",
    "expense_number": "string",
    "note": "string",
    "total_tax_base": number,
    "total_vat_quota": number,
    "total_surcharge_quota": number,
    "total_retention_quota": number,
    "total_amount": number,
    "expense_lines": [
        {
            "id": "string",
            "concept": "string",
            "amount": number,
            "vat_rate": number,
            "vat_quota": number,
            "retention_rate": number,
            "retention_quota": number,
            "surcharge_rate": number,
            "surcharge_quota": number,
            "total_amount": number,
            "expense_type": "string"
        }
    ],
    "transactions": [
        {
            "id": "string",
            "date": "string",
            "amount": number,
            "paid": boolean
        }
    ]
}

Crear gasto

Sección titulada «Crear gasto»
POST/expenses/

El cuerpo de la petición debe contener los siguientes campos obligatorios:

Campo Tipo Descripción
provider string ID del proveedor.
issued boolean Indica si el gasto está confirmado o si se guarda como borrador.
date string Fecha del gasto en formato yyyy-MM-dd. También se acepta expense_date.
expense_number string Número del gasto o documento.
expense_lines array Array de líneas de gasto.

Y los siguientes campos opcionales:

Campo Tipo Descripción
note string Nota del gasto.
is_purchased_in_foreign_provider_country boolean Indica si la compra se ha realizado en el país extranjero del proveedor.
transactions array Array de vencimientos.

El campo attachments no se acepta. Para adjuntar el PDF, usa adjuntar un documento.

Ejemplo de envíolo que se manda a la API
Cuerpo de la petición: con vencimientos
{
  "provider": "68f8861a28e669be1f9905ff",
  "issued": true,
  "date": "2026-01-31",
  "expense_number": "EXP-2026-002",
  "note": "Gasto creado desde public API con vencimiento",
  "expense_lines": [
    {
      "concept": "Servicios profesionales",
      "amount": 100,
      "expense_type": "6290000000",
      "imputation": 1,
      "vat_rate": 0.21
    }
  ],
  "transactions": [
    {
      "date": "2026-02-15",
      "amount": 121,
      "paid": false
    }
  ]
}
Con curl: con vencimientos
curl -X POST "https://api-sandbox.tukonta.com/v1/expenses/" \
  -H "X-API-KEY: $TUKONTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "provider": "68f8861a28e669be1f9905ff",
  "issued": true,
  "date": "2026-01-31",
  "expense_number": "EXP-2026-002",
  "note": "Gasto creado desde public API con vencimiento",
  "expense_lines": [
    {
      "concept": "Servicios profesionales",
      "amount": 100,
      "expense_type": "6290000000",
      "imputation": 1,
      "vat_rate": 0.21
    }
  ],
  "transactions": [
    {
      "date": "2026-02-15",
      "amount": 121,
      "paid": false
    }
  ]
}'
Cuerpo de la petición
{
  "provider": "68f8861a28e669be1f9905ff",
  "issued": false,
  "date": "2026-01-31",
  "expense_number": "EXP-2026-001",
  "note": "Gasto creado desde public API",
  "expense_lines": [
    {
      "concept": "Servicios profesionales",
      "amount": 100,
      "expense_type": "6290000000",
      "imputation": 1,
      "vat_rate": 0.21
    }
  ]
}
Con curl
curl -X POST "https://api-sandbox.tukonta.com/v1/expenses/" \
  -H "X-API-KEY: $TUKONTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "provider": "68f8861a28e669be1f9905ff",
  "issued": false,
  "date": "2026-01-31",
  "expense_number": "EXP-2026-001",
  "note": "Gasto creado desde public API",
  "expense_lines": [
    {
      "concept": "Servicios profesionales",
      "amount": 100,
      "expense_type": "6290000000",
      "imputation": 1,
      "vat_rate": 0.21
    }
  ]
}'

Actualizar un gasto

Sección titulada «Actualizar un gasto»
PUT/expenses/:id

El cuerpo es igual que al crear un gasto, con los mismos campos obligatorios. El campo attachments tampoco se acepta en la actualización. Si el gasto está bloqueado (por ejemplo, porque ya se ha declarado), solo se aplican note y los vencimientos: lo demás no cambia. En las líneas (expense_lines) y los vencimientos (transactions), para cambiar uno que ya existe se incluye su id, el que devuelve la API al consultar el gasto; uno sin id se crea nuevo, y los que no se envíen se eliminan. Si no se envía transactions, los vencimientos se quedan como estaban.

Ejemplo de envíolo que se manda a la API
Cuerpo de la petición
{
  "provider": "68f8861a28e669be1f9905ff",
  "issued": false,
  "date": "2026-01-31",
  "expense_number": "EXP-2026-001",
  "note": "Gasto actualizado desde public API",
  "expense_lines": [
    {
      "id": "699e9c707a950a198431b340",
      "concept": "Servicios profesionales actualizados",
      "amount": 125,
      "expense_type": "6290000000",
      "imputation": 1,
      "vat_rate": 0.21
    }
  ],
  "transactions": [
    {
      "id": "699e9c707a950a198431b342",
      "date": "2026-02-15",
      "amount": 151.25,
      "paid": false
    }
  ]
}
Con curl
curl -X PUT "https://api-sandbox.tukonta.com/v1/expenses/ID_GASTO" \
  -H "X-API-KEY: $TUKONTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "provider": "68f8861a28e669be1f9905ff",
  "issued": false,
  "date": "2026-01-31",
  "expense_number": "EXP-2026-001",
  "note": "Gasto actualizado desde public API",
  "expense_lines": [
    {
      "id": "699e9c707a950a198431b340",
      "concept": "Servicios profesionales actualizados",
      "amount": 125,
      "expense_type": "6290000000",
      "imputation": 1,
      "vat_rate": 0.21
    }
  ],
  "transactions": [
    {
      "id": "699e9c707a950a198431b342",
      "date": "2026-02-15",
      "amount": 151.25,
      "paid": false
    }
  ]
}'
Cuerpo de la petición: gasto bloqueado
{
  "provider": "68f8861a28e669be1f9905ff",
  "issued": true,
  "date": "2026-01-31",
  "expense_number": "EXP-2026-001",
  "note": "Si el gasto está bloqueado, solo se actualizan la nota y los vencimientos",
  "expense_lines": [
    {
      "id": "699e9c707a950a198431b340",
      "concept": "Si el gasto está bloqueado, esta línea no cambia",
      "amount": 125,
      "expense_type": "6290000000",
      "imputation": 1,
      "vat_rate": 0.21
    }
  ]
}
Con curl: gasto bloqueado
curl -X PUT "https://api-sandbox.tukonta.com/v1/expenses/ID_GASTO" \
  -H "X-API-KEY: $TUKONTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "provider": "68f8861a28e669be1f9905ff",
  "issued": true,
  "date": "2026-01-31",
  "expense_number": "EXP-2026-001",
  "note": "Si el gasto está bloqueado, solo se actualizan la nota y los vencimientos",
  "expense_lines": [
    {
      "id": "699e9c707a950a198431b340",
      "concept": "Si el gasto está bloqueado, esta línea no cambia",
      "amount": 125,
      "expense_type": "6290000000",
      "imputation": 1,
      "vat_rate": 0.21
    }
  ]
}'

Adjuntar un documento a un gasto ya creado

Sección titulada «Adjuntar un documento a un gasto ya creado»
POST/expenses/:id/attachment

Importante: el gasto tiene que estar creado previamente. Primero créalo con POST /expenses y después usa su id en esta petición.

Sube un PDF y lo vincula a un gasto que ya existe. No crea el gasto. También sirve para gastos creados antes.

Requiere una clave de API con permiso de escritura. La empresa es la asociada a la clave; no se envía en la petición. Si el gasto no existe o pertenece a otra empresa, la respuesta es 404.

El cuerpo es multipart/form-data con un único campo file:

Campo Tipo Descripción
file archivo PDF. El tamaño máximo es 5 MB.

Si el gasto ya tiene un documento, el nuevo archivo lo sustituye.

La respuesta contiene los datos del archivo:

Campo Tipo Descripción
id string ID del archivo.
file_name string Nombre original del archivo.
file_size string Tamaño formateado. Por ejemplo: 120.50 KB. No es el número de bytes.
mime_type string application/pdf.
Ejemplo de envíolo que se manda a la API

El cuerpo es multipart/form-data, con el PDF en el campo file.

Con curl
curl -X POST "https://api-sandbox.tukonta.com/v1/expenses/ID_GASTO/attachment" \
  -H "X-API-KEY: $TUKONTA_API_KEY" \
  -F "file=@factura.pdf"
Ejemplo de respuestalo que devuelve la API

multipart/form-data, campo file. Solo PDF, de 5 MB como máximo. Requiere una clave de API con permiso de escritura. La empresa es la de la clave. Si el gasto no existe o es de otra empresa, la respuesta es 404. Si el gasto ya tenía un documento, se sustituye.

file_size es un texto con el tamaño formateado, por ejemplo 120.50 KB.

{
  "id": "699e9c707a950a198431b343",
  "file_name": "factura.pdf",
  "file_size": "120.50 KB",
  "mime_type": "application/pdf"
}

Líneas de gasto expense_lines

Sección titulada «Líneas de gasto expense_lines»

Campos obligatorios:

Campo Tipo Descripción
concept string Concepto de la línea de gasto.
amount number Importe de la línea de gasto con 2 decimales.
expense_type string Código de la cuenta de gasto según el listado de cuentas de gasto.
imputation number Porcentaje de afectación. Por ejemplo: para 100%, se indicará 1.
vat_rate number Porcentaje de IVA. Por ejemplo: para 21%, se indicará 0.21.

Y los siguientes campos opcionales:

Campo Tipo Descripción
retention_rate number Porcentaje de retención. Por ejemplo: para 15%, se indicará 0.15.
surcharge_rate number Porcentaje de recargo. Por ejemplo: para 5%, se indicará 0.05.
investment boolean true si la línea corresponde a una inversión. Obligatorio true si expense_type empieza por 2; con las cuentas que empiezan por 5 o 6, false o sin indicar. Si no, la respuesta es 409.
customs_vat boolean Indica si corresponde a IVA de aduanas.

Eliminar un gasto

Sección titulada «Eliminar un gasto»
DELETE/expenses/:id

Un gasto bloqueado no se puede eliminar: la respuesta es 409.

Ejemplo de envíolo que se manda a la API

Esta petición no lleva cuerpo: basta con la dirección y la clave de API.

Con curl
curl -X DELETE "https://api-sandbox.tukonta.com/v1/expenses/ID_GASTO" \
  -H "X-API-KEY: $TUKONTA_API_KEY" \
  -H "Accept: application/json"
Ejemplo de respuestalo que devuelve la API 
{ "message": "Gasto eliminado correctamente." }
Copyright © GESFISER IBR, S.L. Todos los derechos reservados.Versión 1.7.0 · 11/11/2026