Ir al contenido
tukontatukontaAPIv1.7.0

Facturas

Las facturas de la empresa: borradores y facturas emitidas, que se envían a TicketBAI si la empresa está inscrita. También se puede descargar su PDF y enviarlas por email.

Listar facturas

Sección titulada «Listar facturas»
GET/invoices/

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

Parámetro Descripción
filter Número completo de la factura, con su serie. Por ejemplo: 626/2026.
customer id del cliente, o parte de su razón social o de su nombre comercial.
issued true para las facturas emitidas y false para los borradores.
payment_status pending (pendiente de cobro) o paid (cobrada).
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/invoices/" \
  -H "X-API-KEY: $TUKONTA_API_KEY" \
  -H "Accept: application/json"
Ejemplo de respuestalo que devuelve la API

Notas:

  1. income_type llega como product si la cuenta de ingreso es 7000000000 y como service si es 7050000000.
  2. En el objeto del cliente, name, surname_1 y surname_2 solo aparecen si business_type es individual.
  3. ticketbai_status solo aparece en facturas emitidas de empresas inscritas en TicketBAI: pending, accepted o not_sent (consulta «Emitir una factura con TicketBAI»).
{
    "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",
            },
            "description": "string",
            "issued": boolean,
            "date": "string",
            "note": "string",
            "footer": "string",
            "invoice_number": number,
            "serie": "string",
            "ticketbai_status": "string",
            "rectificative_invoice": {
                "id": "string",
                "invoice_number": number,
                "invoice_serie": "string",
                "date": "string",
                "total_tax_base": number,
                "total_vat_quota": number,
                "total_surcharge_quota": number,
                "total_retention_quota": number,
                "total_amount": number,
            },
            "total_tax_base": number,
            "total_vat_quota": number,
            "total_surcharge_quota": number,
            "total_retention_quota": number,
            "total_amount": number,
            "invoice_lines": [
                {
                    "id": "string",
                    "quantity": number,
                    "unit_price": number,
                    "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 factura

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

Notas:

  1. income_type llega como product si la cuenta de ingreso es 7000000000 y como service si es 7050000000.
  2. En los objetos del cliente y de la empresa, name, surname_1 y surname_2 solo aparecen si business_type es individual.
  3. ticketbai_status solo aparece en facturas emitidas de empresas inscritas en TicketBAI: pending, accepted o not_sent (consulta «Emitir una factura con TicketBAI»).
{
    "id": "string",
    "company": {
        "id": "string",
        "cif": "string",
        "business_name": "string",
        "name": "string",
        "surname_1": "string",
        "surname_2": "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",
    },
    "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",
    },
    "description": "string",
    "issued": boolean,
    "date": "string",
    "note": "string",
    "footer": "string",
    "invoice_number": number,
    "serie": "string",
    "ticketbai_status": "string",
    "rectificative_invoice": {
        "id": "string",
        "invoice_number": number,
        "invoice_serie": "string",
        "date": "string",
        "total_tax_base": number,
        "total_vat_quota": number,
        "total_surcharge_quota": number,
        "total_retention_quota": number,
        "total_amount": number,
    },
    "total_tax_base": number,
    "total_vat_quota": number,
    "total_surcharge_quota": number,
    "total_retention_quota": number,
    "total_amount": number,
    "invoice_lines": [
        {
            "id": "string",
            "quantity": number,
            "unit_price": number,
            "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",
        }
    ]
}

Obtener PDF de factura

Sección titulada «Obtener PDF de factura»
GET/invoices/:id/pdf

Devuelve el PDF asociado a la factura indicada por id.

Si la empresa está inscrita en TicketBAI, una factura emitida lleva el QR de TicketBAI, así que su PDF se hace cuando TicketBAI la confirma. Hasta entonces, normalmente unos minutos, la respuesta es 409 con el mensaje «El PDF estará disponible cuando Hacienda confirme la factura.».

El PDF se prepara justo después de crear, actualizar o emitir la factura. Si todavía no está preparado, la respuesta es 404: espera unos segundos y vuelve a pedirlo.

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/invoices/ID_FACTURA/pdf" \
  -H "X-API-KEY: $TUKONTA_API_KEY" \
  --output factura.pdf

Enviar factura por email

Sección titulada «Enviar factura por email»
POST/invoices/:id/email

Envía por email la factura indicada por id, con su PDF adjunto. También se pueden enviar borradores.

Requiere una clave de API con permiso de escritura. Si la factura no existe o pertenece a otra empresa, la respuesta es 404. Si la factura todavía no tiene PDF, la respuesta es 400. Si es una factura emitida que TicketBAI todavía no ha confirmado, la respuesta es 409 («La factura se podrá enviar cuando Hacienda la confirme.») y el email no cuenta para el límite diario.

El email sale de notificaciones@tukonta.com. Las respuestas del destinatario llegan al email de la empresa.

Todos los campos del cuerpo son opcionales. Si no se envía ninguno, el cuerpo puede ser {}:

Campo Tipo Descripción
to string Email del destinatario. Si no se indica, se usa el email del cliente de la factura. Si el cliente no tiene email, la respuesta es 400.
subject string Asunto del email. Si no se indica, se usa el asunto por defecto, en el idioma de facturación de la empresa.
body string Texto del email. Admite HTML. Si no se indica, se usa el texto por defecto, en el idioma de facturación de la empresa. Al final del texto siempre se añade el pie de tukonta.

La respuesta contiene:

Campo Tipo Descripción
to string Email al que se ha enviado.
message string Mensaje de confirmación del envío.

Cada empresa puede enviar como máximo 200 facturas por email al día desde la API (20 en el entorno de pruebas, donde llegan a tu correo y no al del cliente). El día cambia a medianoche, hora de España. Al superar el límite, la respuesta es 429. Los envíos que fallan no cuentan para el límite.

Ejemplo de envíolo que se manda a la API
Cuerpo de la petición
{
  "to": "cliente@example.com",
  "body": "Adjuntamos la factura solicitada."
}
Con curl
curl -X POST "https://api-sandbox.tukonta.com/v1/invoices/ID_FACTURA/email" \
  -H "X-API-KEY: $TUKONTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "cliente@example.com",
  "body": "Adjuntamos la factura solicitada."
}'

Crear factura

Sección titulada «Crear factura»
POST/invoices/

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

Campo Tipo Descripción
customer string id del cliente.
description string Descripción de la factura.
date string Fecha de la factura en formato yyyy-MM-dd.
invoice_lines array Array de líneas de factura. Al menos una.

Y los siguientes campos opcionales:

Campo Tipo Descripción
issued boolean Indica si se va a emitir la factura issued: true o si se va a guardar como borrador issued: false. Si la empresa está inscrita en TicketBAI, la fecha de la factura es igual o posterior a la fecha de inscripción y el campo issued: true, la factura se enviará a TicketBAI de forma automática. Si no se indica, la factura se guarda como borrador.
transactions array Array de vencimientos.
serie string Serie de la factura. Si no se proporciona, o es null, se usará la serie del año de la fecha de la factura. Si se proporciona, se debe indicar una serie que exista en la lista de series de la empresa. En un borrador no se guarda: indícala al emitirlo.
footer string Pie de página de la factura.
note string Nota de la factura.
rectificative_invoice string ID de la factura que se rectifica. Si se indica, la factura será rectificativa por diferencias de esa factura y en las líneas de factura se indicarán los importes que se corrigen. Si la factura original es de la serie IVA-OSS, en serie se debe indicar también una serie IVA-OSS.
Ejemplo de envíolo que se manda a la API
Cuerpo de la petición
{
  "customer": "6972466e57588bd1d9bf38cb",
  "description": "Factura creada desde public API",
  "issued": true,
  "date": "2026-02-06",
  "serie": "",
  "rectificative_invoice": "",
  "footer": "Texto legal o pie de factura",
  "note": "Nota interna de la factura",
  "invoice_lines": [
    {
      "quantity": 1,
      "concept": "Servicios de marketing",
      "unit_price": 100,
      "vat_rate": 0.21,
      "retention_rate": 0,
      "income_type": "7050000000"
    }
  ]
}
Con curl
curl -X POST "https://api-sandbox.tukonta.com/v1/invoices/" \
  -H "X-API-KEY: $TUKONTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "customer": "6972466e57588bd1d9bf38cb",
  "description": "Factura creada desde public API",
  "issued": true,
  "date": "2026-02-06",
  "serie": "",
  "rectificative_invoice": "",
  "footer": "Texto legal o pie de factura",
  "note": "Nota interna de la factura",
  "invoice_lines": [
    {
      "quantity": 1,
      "concept": "Servicios de marketing",
      "unit_price": 100,
      "vat_rate": 0.21,
      "retention_rate": 0,
      "income_type": "7050000000"
    }
  ]
}'
Ejemplo de respuestalo que devuelve la API

Notas:

  1. income_type llega como product si la cuenta de ingreso es 7000000000 y como service si es 7050000000.
  2. En los objetos del cliente y de la empresa, name, surname_1 y surname_2 solo aparecen si business_type es individual.
  3. ticketbai_status solo aparece en facturas emitidas de empresas inscritas en TicketBAI: pending, accepted o not_sent (consulta «Emitir una factura con TicketBAI»).
{
    "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",
    },
    "description": "string",
    "issued": boolean,
    "date": "string",
    "note": "string",
    "footer": "string",
    "invoice_number": number,
    "serie": "string",
    "ticketbai_status": "string",
    "rectificative_invoice": {
        "id": "string",
        "invoice_number": number,
        "invoice_serie": "string",
        "date": "string",
        "total_tax_base": number,
        "total_vat_quota": number,
        "total_surcharge_quota": number,
        "total_retention_quota": number,
        "total_amount": number,
    },
    "total_tax_base": number,
    "total_vat_quota": number,
    "total_surcharge_quota": number,
    "total_retention_quota": number,
    "total_amount": number,
    "invoice_lines": [
        {
            "id": "string",
            "quantity": number,
            "unit_price": number,
            "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",
        }
    ]
}

Emitir una factura con TicketBAI

Sección titulada «Emitir una factura con TicketBAI»

Al emitir una factura (issued: true) de una empresa inscrita en TicketBAI, la factura se envía a Hacienda en la misma petición, y el código de la respuesta indica cómo ha ido:

  • Si Hacienda la acepta, la respuesta es 200 con la factura emitida.

  • Si Hacienda la rechaza, no responde o está en mantenimiento, la respuesta es 409 con message, que explica qué ha pasado y qué hacer, y la factura (invoice) guardada como borrador; su número queda libre. Por ejemplo:

    {
        "message": "Hacienda no ha respondido a tiempo y no ha recibido la factura. Se ha guardado como borrador; vuelve a emitirla en unos minutos.",
        "invoice": { "id": "6af45a44067c61650602f6f9", "issued": false }
    }

  • Si no se sabe si Hacienda la ha recibido, la respuesta es 409 con ticketbai_pending: true y la factura (invoice) ya emitida, con su número. Tukonta sigue comprobándola y reenviándola hasta que Hacienda la confirme; no la vuelvas a enviar. Por ejemplo:

    {
        "message": "La factura 626/2026 está emitida, pero Hacienda todavía no la ha confirmado. Hasta que la confirme no se pueden emitir más facturas; suele tardar unos minutos.",
        "ticketbai_pending": true,
        "invoice": { "id": "6af45a44067c61650602f6f9", "issued": true, "invoice_number": 626, "ticketbai_status": "pending" }
    }

Mientras una factura de la empresa esté pendiente de confirmar, no se puede emitir ninguna otra: emitir una factura (o pasar un borrador a emitida) responde 409 con un mensaje que indica qué factura se está confirmando. Los borradores se pueden seguir guardando. Así la numeración de las facturas es siempre correlativa y sin huecos.

Las facturas emitidas de una empresa inscrita en TicketBAI llevan ticketbai_status, que dice en qué punto están con Hacienda. Los borradores, las facturas de antes de la inscripción y las de empresas que no están en TicketBAI no lo llevan.

Valor Qué significa
pending Enviada, pero Hacienda todavía no la ha confirmado. Hasta que la confirme no se pueden emitir más facturas.
accepted Hacienda la ha recibido y aceptado.
not_sent Emitida, pero no consta que se haya enviado a Hacienda.

Si al emitir la respuesta lleva ticketbai_pending: true, consulta la factura con GET /invoices/:id pasados unos minutos: cuando Hacienda la confirme, ticketbai_status será accepted. La factura no incluye el identificador ni el QR de TicketBAI: el QR va en el PDF (GET /invoices/:id/pdf).

Actualizar una factura

Sección titulada «Actualizar una factura»
PUT/invoices/:id

Los campos son los mismos que al crear una factura. Lo que se puede cambiar depende de cómo esté la factura:

  • Borrador: hay que enviar siempre customer, description e invoice_lines; si falta alguno, la respuesta es 409. Con issued: true se emite, igual que al crearla.
  • Emitida: basta con enviar lo que cambia. No se pueden enviar serie ni date, aunque no cambien: la respuesta es 409.
  • Bloqueada (por ejemplo, enviada a TicketBAI o ya declarada): solo se pueden cambiar note y transactions.

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 la factura; 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",
  "description": "Factura actualizada desde public API",
  "issued": false,
  "date": "2026-02-06",
  "serie": "",
  "rectificative_invoice": "",
  "footer": "Texto legal o pie de factura actualizado",
  "note": "Nota interna actualizada",
  "invoice_lines": [
    {
      "id": "674c98fda16dce6523336d88",
      "quantity": 1,
      "concept": "Servicios de marketing actualizados",
      "unit_price": 125,
      "vat_rate": 0.21,
      "retention_rate": 0,
      "income_type": "7050000000"
    }
  ]
}
Con curl
curl -X PUT "https://api-sandbox.tukonta.com/v1/invoices/ID_FACTURA" \
  -H "X-API-KEY: $TUKONTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "customer": "6972466e57588bd1d9bf38cb",
  "description": "Factura actualizada desde public API",
  "issued": false,
  "date": "2026-02-06",
  "serie": "",
  "rectificative_invoice": "",
  "footer": "Texto legal o pie de factura actualizado",
  "note": "Nota interna actualizada",
  "invoice_lines": [
    {
      "id": "674c98fda16dce6523336d88",
      "quantity": 1,
      "concept": "Servicios de marketing actualizados",
      "unit_price": 125,
      "vat_rate": 0.21,
      "retention_rate": 0,
      "income_type": "7050000000"
    }
  ]
}'
Ejemplo de respuestalo que devuelve la API

Notas:

  1. income_type llega como product si la cuenta de ingreso es 7000000000 y como service si es 7050000000.
  2. En los objetos del cliente y de la empresa, name, surname_1 y surname_2 solo aparecen si business_type es individual.
  3. ticketbai_status solo aparece en facturas emitidas de empresas inscritas en TicketBAI: pending, accepted o not_sent (consulta «Emitir una factura con TicketBAI»).
{
    "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",
    },
    "description": "string",
    "issued": boolean,
    "date": "string",
    "note": "string",
    "footer": "string",
    "invoice_number": number,
    "serie": "string",
    "ticketbai_status": "string",
    "rectificative_invoice": {
        "id": "string",
        "invoice_number": number,
        "invoice_serie": "string",
        "date": "string",
        "total_tax_base": number,
        "total_vat_quota": number,
        "total_surcharge_quota": number,
        "total_retention_quota": number,
        "total_amount": number,
    },
    "total_tax_base": number,
    "total_vat_quota": number,
    "total_surcharge_quota": number,
    "total_retention_quota": number,
    "total_amount": number,
    "invoice_lines": [
        {
            "id": "string",
            "quantity": number,
            "unit_price": number,
            "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",
        }
    ]
}

Eliminar una factura

Sección titulada «Eliminar una factura»
DELETE/invoices/:id

Elimina un borrador. Requiere una clave de API con permiso de escritura.

Una factura emitida no se puede eliminar, ni tampoco una bloqueada o ya eliminada: la respuesta es 409 con el motivo. Si no existe o es de otra empresa, la respuesta es 404.

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/invoices/ID_FACTURA" \
  -H "X-API-KEY: $TUKONTA_API_KEY" \
  -H "Accept: application/json"
Ejemplo de respuestalo que devuelve la API 
{ "message": "Factura eliminada correctamente." }

Deshacer una factura

Sección titulada «Deshacer una factura»
PUT/invoices/:id/undo

Devuelve una factura emitida a borrador y deja libre su número, para corregirla y volver a emitirla. Requiere una clave de API con permiso de escritura. La respuesta es la factura, ya como borrador.

Solo se puede deshacer la última factura de su serie en ese año. Una factura enviada a TicketBAI o ya declarada no se puede deshacer: 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 PUT "https://api-sandbox.tukonta.com/v1/invoices/ID_FACTURA/undo" \
  -H "X-API-KEY: $TUKONTA_API_KEY" \
  -H "Accept: application/json"
Ejemplo de respuestalo que devuelve la API

Devuelve la factura, ya como borrador (issued: false), con el mismo formato que GET /invoices/:id.

Líneas de factura invoice_lines

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

Campos obligatorios:

Campo Tipo Descripción
quantity number Cantidad de la línea de factura.
concept string Concepto de la línea de factura.
unit_price number Precio unitario de la línea de factura con 2 decimales.
vat_rate number Porcentaje de IVA de la línea de factura. Por ejemplo: para 21%, se indicará 0.21.
income_type string Si es un servicio, se indicará 7050000000. Si es un producto, se indicará 7000000000.

Y los siguientes campos opcionales:

Campo Tipo Descripción
retention_rate number Porcentaje de retención de la línea de factura. Por ejemplo: para 15%, se indicará 0.15. Al emitir la factura (issued: true) solo se admiten 0, 0.01, 0.02, 0.07, 0.15, 0.19 y 0.24; con otro tipo, la API responde con un error 409 que indica la línea. No se aplica a los borradores ni a los planes Tukonta y Tukonta anual.
surcharge_rate number Porcentaje de recargo de la línea de factura. Por ejemplo: para 5%, se indicará 0.05.
Copyright © GESFISER IBR, S.L. Todos los derechos reservados.Versión 1.7.0 · 11/11/2026