Ir al contenido
tukontatukontaAPIv1.7.0

Ingresos

Los ingresos de la empresa: cada uno con su cliente, su número de documento, sus líneas y, si se quiere, sus vencimientos.

Listar ingresos

Sección titulada «Listar ingresos»
GET/incomes/

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

Parámetro Descripción
filter Número de documento completo.
customer_id id del cliente.
customer Parte de la razón social o del nombre comercial del cliente.
payment_status pending (pendiente de cobro) o paid (cobrado).
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/incomes/" \
  -H "X-API-KEY: $TUKONTA_API_KEY" \
  -H "Accept: application/json"
Ejemplo de respuestalo que devuelve la API

Notas:

  1. En el objeto del cliente, name, surname_1 y surname_2 solo aparecen si business_type es individual.
  2. income_type llega como product si la cuenta de ingreso es 7000000000 y como service si es 7050000000.
{
    "data": [
        {
            "id": "string",
            "company": "string",
            "customer": {
                "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",
            },
            "date": "string",
            "note": "string",
            "document_number": "string",
            "total_tax_base": number,
            "total_vat_quota": number,
            "total_surcharge_quota": number,
            "total_retention_quota": number,
            "total_amount": number,
            "invoice_lines": [
                {
                    "id": "string",
                    "amount": number,
                    "concept": "string",
                    "vat_rate": number,
                    "vat_quota": number,
                    "retention_rate": number,
                    "retention_quota": number,
                    "surcharge_rate": number,
                    "surcharge_quota": number,
                    "total_amount": number,
                    "income_type": "string",
                }
            ],
            "transactions": [
                {
                    "id": "string",
                    "date": "string",
                    "amount": number,
                    "charged": boolean,
                    "company_payment_method": "string",
                }
            ]
        }
    ],
    "pagination": {
        "total": number,
        "offset": number,
        "limit": number,
        "count": number,
        "hasMore": boolean
    }
}

Obtener 1 ingreso

Sección titulada «Obtener 1 ingreso»
GET/incomes/: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/incomes/ID_INGRESO" \
  -H "X-API-KEY: $TUKONTA_API_KEY" \
  -H "Accept: application/json"
Ejemplo de respuestalo que devuelve la API

Notas:

  1. En los objetos del cliente y de la empresa, name, surname_1 y surname_2 solo aparecen si business_type es individual.
  2. income_type llega como product si la cuenta de ingreso es 7000000000 y como service si es 7050000000.
{
    "id": "string",
    "company": {
        "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",
        "web": "string",
    },
    "customer": {
        "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",
    },
    "date": "string",
    "note": "string",
    "document_number": "string",
    "total_tax_base": number,
    "total_vat_quota": number,
    "total_surcharge_quota": number,
    "total_retention_quota": number,
    "total_amount": number,
    "invoice_lines": [
        {
            "id": "string",
            "amount": number,
            "concept": "string",
            "vat_rate": number,
            "vat_quota": number,
            "retention_rate": number,
            "retention_quota": number,
            "surcharge_rate": number,
            "surcharge_quota": number,
            "total_amount": number,
            "income_type": "string",
        }
    ],
    "transactions": [
        {
            "id": "string",
            "date": "string",
            "amount": number,
            "charged": boolean,
            "company_payment_method": "string",
        }
    ]
}

Crear ingreso

Sección titulada «Crear ingreso»
POST/incomes/

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

Campo Tipo Descripción
customer string id del cliente.
document_number string Número del documento.
date string Fecha del ingreso en formato yyyy-MM-dd.
invoice_lines array Array de líneas de ingreso. Al menos una.

Y los siguientes campos opcionales:

Campo Tipo Descripción
note string Nota del ingreso.
transactions array Array de vencimientos.
Ejemplo de envíolo que se manda a la API
Cuerpo de la petición
{
  "customer": "6972466e57588bd1d9bf38cb",
  "date": "2026-01-31",
  "document_number": "ING-2026-001",
  "note": "Ingreso creado desde public API",
  "invoice_lines": [
    {
      "concept": "Servicios de consultoria",
      "amount": 100,
      "vat_rate": 0.21,
      "retention_rate": 0,
      "income_type": "7050000000"
    }
  ]
}
Con curl
curl -X POST "https://api-sandbox.tukonta.com/v1/incomes/" \
  -H "X-API-KEY: $TUKONTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "customer": "6972466e57588bd1d9bf38cb",
  "date": "2026-01-31",
  "document_number": "ING-2026-001",
  "note": "Ingreso creado desde public API",
  "invoice_lines": [
    {
      "concept": "Servicios de consultoria",
      "amount": 100,
      "vat_rate": 0.21,
      "retention_rate": 0,
      "income_type": "7050000000"
    }
  ]
}'
Ejemplo de respuestalo que devuelve la API

Notas:

  1. En los objetos del cliente y de la empresa, name, surname_1 y surname_2 solo aparecen si business_type es individual.
  2. income_type llega como product si la cuenta de ingreso es 7000000000 y como service si es 7050000000.
{
    "id": "string",
    "company": {
        "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",
        "web": "string",
    },
    "customer": {
        "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",
    },
    "date": "string",
    "note": "string",
    "document_number": "string",
    "total_tax_base": number,
    "total_vat_quota": number,
    "total_surcharge_quota": number,
    "total_retention_quota": number,
    "total_amount": number,
    "invoice_lines": [
        {
            "id": "string",
            "amount": number,
            "concept": "string",
            "vat_rate": number,
            "vat_quota": number,
            "retention_rate": number,
            "retention_quota": number,
            "surcharge_rate": number,
            "surcharge_quota": number,
            "total_amount": number,
            "income_type": "string",
        }
    ],
    "transactions": [
        {
            "id": "string",
            "date": "string",
            "amount": number,
            "charged": boolean,
            "company_payment_method": "string",
        }
    ]
}

Actualizar un ingreso

Sección titulada «Actualizar un ingreso»
PUT/incomes/:id

El cuerpo es igual que al crear un ingreso, con los mismos campos obligatorios. Si el ingreso está bloqueado (por ejemplo, porque ya se ha declarado), solo se aplican los vencimientos: lo demás no cambia. En las líneas (invoice_lines) y los vencimientos (transactions), para cambiar uno que ya existe se incluye su id, el que devuelve la API al consultar el ingreso; 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
{
  "customer": "6972466e57588bd1d9bf38cb",
  "date": "2026-01-31",
  "document_number": "ING-2026-001",
  "note": "Ingreso actualizado desde public API",
  "invoice_lines": [
    {
      "id": "674c98fda16dce6523336d88",
      "concept": "Servicios de consultoria actualizados",
      "amount": 125,
      "vat_rate": 0.21,
      "retention_rate": 0,
      "income_type": "7050000000"
    }
  ]
}
Con curl
curl -X PUT "https://api-sandbox.tukonta.com/v1/incomes/ID_INGRESO" \
  -H "X-API-KEY: $TUKONTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "customer": "6972466e57588bd1d9bf38cb",
  "date": "2026-01-31",
  "document_number": "ING-2026-001",
  "note": "Ingreso actualizado desde public API",
  "invoice_lines": [
    {
      "id": "674c98fda16dce6523336d88",
      "concept": "Servicios de consultoria actualizados",
      "amount": 125,
      "vat_rate": 0.21,
      "retention_rate": 0,
      "income_type": "7050000000"
    }
  ]
}'
Ejemplo de respuestalo que devuelve la API

Notas:

  1. En los objetos del cliente y de la empresa, name, surname_1 y surname_2 solo aparecen si business_type es individual.
  2. income_type llega como product si la cuenta de ingreso es 7000000000 y como service si es 7050000000.
{
    "id": "string",
    "company": {
        "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",
        "web": "string",
    },
    "customer": {
        "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",
    },
    "date": "string",
    "note": "string",
    "document_number": "string",
    "total_tax_base": number,
    "total_vat_quota": number,
    "total_surcharge_quota": number,
    "total_retention_quota": number,
    "total_amount": number,
    "invoice_lines": [
        {
            "id": "string",
            "amount": number,
            "concept": "string",
            "vat_rate": number,
            "vat_quota": number,
            "retention_rate": number,
            "retention_quota": number,
            "surcharge_rate": number,
            "surcharge_quota": number,
            "total_amount": number,
            "income_type": "string",
        }
    ],
    "transactions": [
        {
            "id": "string",
            "date": "string",
            "amount": number,
            "charged": boolean,
            "company_payment_method": "string",
        }
    ]
}

Líneas de ingreso invoice_lines

Sección titulada «Líneas de ingreso invoice_lines»

Campos obligatorios:

Campo Tipo Descripción
concept string Concepto de la línea de ingreso.
amount number Base imponible de la línea, con 2 decimales como máximo.
vat_rate number Porcentaje de IVA de la línea. Por ejemplo: para 21%, se indicará 0.21.
income_type string Código de la cuenta de ingreso según el listado de cuentas de ingreso.

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.

Eliminar un ingreso

Sección titulada «Eliminar un ingreso»
DELETE/incomes/: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 -X DELETE "https://api-sandbox.tukonta.com/v1/incomes/ID_INGRESO" \
  -H "X-API-KEY: $TUKONTA_API_KEY" \
  -H "Accept: application/json"
Copyright © GESFISER IBR, S.L. Todos los derechos reservados.Versión 1.7.0 · 11/11/2026