Ir al contenido
tukontatukontaAPIv1.7.0

Clientes

Los clientes de la empresa. Su id es el que se indica en customer al crear facturas e ingresos.

Listar clientes

Sección titulada «Listar clientes»
GET/customers/

Además de la paginación, admite este filtro:

Parámetro Descripción
filter Texto que se busca en el nombre, los apellidos, la razón social, el nombre comercial, el NIF, la dirección y los datos de contacto. No distingue mayúsculas.
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/customers/" \
  -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.
{
    "data": [
        {
            "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",
            "contact_person": "string",
            "phone": "string",
            "email": "string",
            "web": "string",
            "fax": "string",
            "personal_comment": "string"
        }
    ],
    "pagination": {
        "total": number,
        "offset": number,
        "limit": number,
        "count": number,
        "hasMore": boolean
    }
}

Obtener 1 cliente

Sección titulada «Obtener 1 cliente»
GET/customers/: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/customers/ID_CLIENTE" \
  -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.
{
    "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",
    "contact_person": "string",
    "phone": "string",
    "email": "string",
    "web": "string",
    "fax": "string",
    "personal_comment": "string",
    "has_surcharge": boolean,
}

Crear cliente

Sección titulada «Crear cliente»
POST/customers/

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

Campo Tipo Descripción
business_type string Tipo de cliente: individual (autónomo o particular) o company (empresa).
cif string NIF del cliente. Si no es válido o ya existe un cliente con el mismo NIF, no se podrá crear: la respuesta es 409.
trade_name string Nombre comercial.
business_name string Razón social. Obligatorio si business_type es company.
name string Nombre. Obligatorio si business_type es individual.
surname_1 string Primer apellido. Obligatorio si business_type es individual.
address string Dirección.
postal_code string Código postal.
town string Población.
country_code string Código del país. Se debe indicar el código del país en ISO 3166-1 (dos letras) según el siguiente listado: https://es.wikipedia.org/wiki/ISO_3166-2#Códigos_actuales.
region string Provincia. Si country_code es ES, se debe indicar el nombre de la provincia según el siguiente listado: https://es.wikipedia.org/wiki/Provincia_(Espa%C3%B1a)#Tabla_de_provincias.

Y los siguientes campos opcionales:

Campo Tipo Descripción
surname_2 string Segundo apellido.
contact_person string Persona de contacto.
phone string Teléfono.
email string Correo electrónico. Tiene que ser un email válido.
web string Página web.
fax string Fax.
personal_comment string Comentario personal.
has_surcharge boolean Indica si el cliente tiene recargo de equivalencia.
Ejemplo de envíolo que se manda a la API
Cuerpo de la petición: empresa
{
  "business_name": "Tech Solutions S.L.",
  "cif": "B12345674",
  "business_type": "company",
  "trade_name": "Tech Solutions",
  "address": "Calle Mayor 1",
  "postal_code": "48001",
  "town": "Bilbao",
  "region": "Bizkaia",
  "country_code": "ES",
  "contact_person": "Jane Doe",
  "phone": "+34944123456",
  "email": "contacto@example.com",
  "web": "https://example.com",
  "fax": "",
  "personal_comment": "Cliente creado desde public API",
  "has_surcharge": false
}
Con curl: empresa
curl -X POST "https://api-sandbox.tukonta.com/v1/customers/" \
  -H "X-API-KEY: $TUKONTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "business_name": "Tech Solutions S.L.",
  "cif": "B12345674",
  "business_type": "company",
  "trade_name": "Tech Solutions",
  "address": "Calle Mayor 1",
  "postal_code": "48001",
  "town": "Bilbao",
  "region": "Bizkaia",
  "country_code": "ES",
  "contact_person": "Jane Doe",
  "phone": "+34944123456",
  "email": "contacto@example.com",
  "web": "https://example.com",
  "fax": "",
  "personal_comment": "Cliente creado desde public API",
  "has_surcharge": false
}'
Cuerpo de la petición: persona física
{
  "business_type": "individual",
  "name": "Juan",
  "surname_1": "Garcia",
  "surname_2": "Lopez",
  "business_name": "Juan Garcia Lopez",
  "trade_name": "Juan Garcia",
  "cif": "12345678Z",
  "address": "Calle Gran Via 10",
  "postal_code": "28013",
  "town": "Madrid",
  "region": "Madrid",
  "country_code": "ES",
  "contact_person": "",
  "phone": "+34910123456",
  "email": "juan.garcia@example.com",
  "web": "",
  "fax": "",
  "personal_comment": "",
  "has_surcharge": false
}
Con curl: persona física
curl -X POST "https://api-sandbox.tukonta.com/v1/customers/" \
  -H "X-API-KEY: $TUKONTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "business_type": "individual",
  "name": "Juan",
  "surname_1": "Garcia",
  "surname_2": "Lopez",
  "business_name": "Juan Garcia Lopez",
  "trade_name": "Juan Garcia",
  "cif": "12345678Z",
  "address": "Calle Gran Via 10",
  "postal_code": "28013",
  "town": "Madrid",
  "region": "Madrid",
  "country_code": "ES",
  "contact_person": "",
  "phone": "+34910123456",
  "email": "juan.garcia@example.com",
  "web": "",
  "fax": "",
  "personal_comment": "",
  "has_surcharge": false
}'
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.
{
    "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",
    "contact_person": "string",
    "phone": "string",
    "email": "string",
    "web": "string",
    "fax": "string",
    "personal_comment": "string",
    "has_surcharge": boolean,
}

Actualizar un cliente

Sección titulada «Actualizar un cliente»
PUT/customers/:id

El cuerpo es igual que al crear un cliente, con los mismos campos obligatorios: envía siempre el cliente completo. Si no se envía business_type, se toma company. Si el NIF no es válido o ya existe otro cliente con el mismo NIF, no se podrá actualizar (409). Si el cliente tiene facturas o ingresos, has_surcharge no se puede cambiar: envía el valor que ya tiene.

Ejemplo de envíolo que se manda a la API
Cuerpo de la petición
{
  "business_name": "Tech Solutions Updated S.L.",
  "cif": "B12345674",
  "business_type": "company",
  "trade_name": "Tech Solutions Updated",
  "address": "Calle Mayor 2",
  "postal_code": "48001",
  "town": "Bilbao",
  "region": "Bizkaia",
  "country_code": "ES",
  "contact_person": "Jane Doe",
  "phone": "+34944123456",
  "email": "contacto.updated@example.com",
  "web": "https://example.com",
  "fax": "",
  "personal_comment": "Cliente actualizado desde public API",
  "has_surcharge": false
}
Con curl
curl -X PUT "https://api-sandbox.tukonta.com/v1/customers/ID_CLIENTE" \
  -H "X-API-KEY: $TUKONTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "business_name": "Tech Solutions Updated S.L.",
  "cif": "B12345674",
  "business_type": "company",
  "trade_name": "Tech Solutions Updated",
  "address": "Calle Mayor 2",
  "postal_code": "48001",
  "town": "Bilbao",
  "region": "Bizkaia",
  "country_code": "ES",
  "contact_person": "Jane Doe",
  "phone": "+34944123456",
  "email": "contacto.updated@example.com",
  "web": "https://example.com",
  "fax": "",
  "personal_comment": "Cliente actualizado desde public API",
  "has_surcharge": false
}'
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.
{
    "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",
    "contact_person": "string",
    "phone": "string",
    "email": "string",
    "web": "string",
    "fax": "string",
    "personal_comment": "string",
    "has_surcharge": boolean,
}

Eliminar un cliente

Sección titulada «Eliminar un cliente»
DELETE/customers/:id

Requiere una clave de API con permiso de escritura. Si el cliente tiene facturas o ingresos, aunque sean borradores o estén eliminados, no se puede eliminar: la respuesta es 409. 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/customers/ID_CLIENTE" \
  -H "X-API-KEY: $TUKONTA_API_KEY" \
  -H "Accept: application/json"
Ejemplo de respuestalo que devuelve la API 
{ "message": "Cliente eliminado correctamente." }
Copyright © GESFISER IBR, S.L. Todos los derechos reservados.Versión 1.7.0 · 11/11/2026