El recurso contacts te permite gestionar los contactos de tu empresa: clientes, proveedores y empleados. Cada contacto puede tener uno o varios roles según la relación comercial que tengas con él.
Este artículo incluye ejemplos prácticos para los casos más comunes: clientes españoles (empresa y particular), clientes intracomunitarios (con validación VIES) y clientes extracomunitarios.
💡 Recomendación: Antes de empezar a desarrollar, te recomendamos crear un entorno de pruebas (sandbox) para hacer tus primeras llamadas sin afectar tus datos reales.
Endpoints disponibles
Método | Endpoint | Descripción |
GET | /{companyId}/contacts | Lista de contactos (con filtros y paginación) |
POST | /{companyId}/contacts | Crear un contacto |
GET | /{companyId}/contacts/{id} | Obtener un contacto por ID |
PUT | /{companyId}/contacts/{id} | Actualizar un contacto |
DELETE | /{companyId}/contacts/{id} | Eliminar un contacto |
PUT | /{companyId}/contacts/{id}/tags | Actualizar etiquetas del contacto |
Ejemplos de código
Los siguientes ejemplos muestran cómo crear contactos para diferentes casos de uso. Todos los ejemplos usan el método POST a /{companyId}/contacts.
Cliente español (empresa)
El caso más común: una empresa española identificada por su CIF.
curl -X POST \
-H "facturadirecta-api-key: TU_CLAVE_API" \
-H "Content-Type: application/json" \
-d '{
"content": {
"type": "contact",
"main": {
"name": "Cliente Empresa SL",
"fiscalId": "B12345674",
"currency": "EUR",
"country": "ES",
"address": "Pza Mayor, 4",
"zipcode": "49004",
"city": "Zamora",
"accounts": {
"client": "430000",
"clientCredit": "438000"
}
}
}
}' \
https://app.facturadirecta.com/api/TU_COMPANY_ID/contacts
Nota: FacturaDirecta valida automáticamente el formato del CIF español y asigna la posición fiscal correspondiente.
Cliente español (particular)
Para personas físicas con DNI/NIE. Usa el campo surname para los apellidos y marca endCustomer: true.
{
"content": {
"type": "contact",
"main": {
"name": "Pedro",
"surname": "García Gómez",
"fiscalId": "82931482Z",
"currency": "EUR",
"country": "ES",
"address": "Av. de Leopoldo Alas Clarín, 2",
"zipcode": "49018",
"city": "Zamora",
"endCustomer": true,
"accounts": {
"client": "430000",
"clientCredit": "438000"
}
}
}
}
Importante: El campo endCustomer: true indica que es un consumidor final. Esto afecta a cómo se genera el asiento contable y a algunos informes fiscales.
Cliente intracomunitario (UE)
Para clientes de otros países de la Unión Europea. Usa fiscalId con fiscalIdType: "02" (NIF-IVA intracomunitario) e incluye la validación VIES.
{
"content": {
"type": "contact",
"main": {
"name": "Google Ireland Limited",
"fiscalId": "IE6388047V",
"fiscalIdType": "02",
"vatEUValidation": {
"valid": true,
"date": "2026-01-15T10:30:00+01:00"
},
"currency": "EUR",
"country": "IE",
"address": "Gordon House, Barrow Street",
"city": "Dublin 4",
"accounts": {
"client": "430000",
"clientCredit": "438000"
}
}
}
}
Campos clave:
fiscalId: NIF intracomunitario con prefijo del país (ej: IE para Irlanda)fiscalIdType: "02": Indica que es un NIF-IVA intracomunitariovatEUValidation.valid: Resultado de la validación en VIESvatEUValidation.date: Fecha en que se realizó la validación
Nota: La validación VIES es obligatoria para aplicar la exención de IVA en operaciones intracomunitarias. Si no tienes la validación, incluye vatEUValidation.valid: false.
Cliente extracomunitario
Para clientes fuera de la Unión Europea. Puedes incluir el identificador fiscal del país de origen usando fiscalIdType: "06" (otro documento probatorio).
{
"content": {
"type": "contact",
"main": {
"name": "Mailgun Technologies",
"fiscalId": "12-3456789",
"fiscalIdType": "06",
"currency": "USD",
"country": "US",
"address": "535 Mission St., 14th Floor",
"zipcode": "94105",
"city": "San Francisco",
"region": "CA",
"accounts": {
"client": "430000",
"clientCredit": "438000"
}
}
}
}
Nota: Se recomienda usar los campos estructurados (address, zipcode, city, region) para la dirección de todos los contactos, incluyendo extranjeros.
Campos importantes
Estos son los campos más relevantes al crear o actualizar contactos:
Identificación
Campo | Tipo | Descripción |
name | string | Nombre fiscal (empresas) o nombre de pila (particulares) |
surname | string | Apellidos (solo para personas físicas) |
title | string | Nombre comercial o "mostrar como" (opcional) |
fiscalId | string | Identificador fiscal (CIF/NIF/NIE español, NIF intracomunitario, u otro) |
fiscalIdType | string | Tipo de identificador: NIF, 02 (intracomunitario), 03 (pasaporte), 04 (doc. oficial), 05 (certificado residencia), 06 (otro doc.), 07 (no censado) |
vatEU | string | OBSOLETO: Usar |
vatEUValidation | object | Resultado de validación VIES: |
endCustomer | boolean | Indica si es consumidor final (persona física) |
externalId | string | ID externo para integración con otros sistemas |
Dirección
Se recomienda usar los campos estructurados para todos los contactos, incluyendo extranjeros:
Campo | Tipo | Descripción |
country | string | Código de país ISO 3166-1 Alpha-2 (ej: ES, FR, US) |
address | string | Calle y número |
zipcode | string | Código postal |
city | string | Localidad |
region | string | Provincia o estado (código o nombre) |
fullAddress | string | Legacy: Dirección en texto libre. Se recomienda usar los campos estructurados |
Contabilidad
Campo | Tipo | Descripción |
currency | string | Moneda por defecto (ISO 4217: EUR, USD, etc.) |
accounts.client | string | Cuenta contable de cliente (ej: 430000) |
accounts.clientCredit | string | Cuenta de efectos comerciales a cobrar |
accounts.supplier | string | Cuenta contable de proveedor (ej: 400000) |
accounts.supplierCredit | string | Cuenta de efectos comerciales a pagar |
clientCode | string | Código interno de cliente |
providerCode | string | Código interno de proveedor |
Datos de contacto
Campo | Tipo | Descripción |
string | Email principal del contacto | |
phone | string | Teléfono principal |
website | string | Sitio web |
notes | string | Notas internas sobre el contacto |
Posiciones fiscales
FacturaDirecta asigna automáticamente la posición fiscal del contacto según:
País: España, UE o resto del mundo
Tipo de identificador: CIF (empresa) vs NIF/NIE (particular)
Validación VIES: Para operaciones intracomunitarias
Las posiciones fiscales determinan qué impuestos se aplican por defecto en las facturas:
Posición fiscal | Aplicación |
Nacional | IVA normal (21%, 10% o 4%) |
Intracomunitario | IVA exento (con NIF validado en VIES) |
Exportación | IVA exento (fuera de la UE) |
Canarias | IGIC en lugar de IVA |
Roles de contacto
Un contacto puede tener múltiples roles según tu relación comercial:
Cliente: Le emites facturas de venta
Proveedor: Te emite facturas de compra
Empleado: Registras sus nóminas
El rol se asigna automáticamente cuando usas el contacto en un documento (factura, gasto, nómina).
Errores comunes
Error: "Invalid fiscalId format"
El CIF/NIF/NIE no tiene un formato válido. Verifica:
CIF de empresa: letra + 8 dígitos (ej: B12345674)
NIF persona física: 8 dígitos + letra (ej: 82931482Z)
NIE: X/Y/Z + 7 dígitos + letra (ej: Y1234567X)
Error: "vatEU must include country prefix"
El NIF intracomunitario debe incluir el prefijo del país. Ejemplo: IE6388047V (no solo 6388047V).
Error: "Invalid country code"
Usa códigos de país ISO 3166-1 Alpha-2 de dos letras: ES, FR, DE, IT, US, etc.
Error: "name is required"
El campo name es obligatorio. Para personas físicas, indica el nombre de pila y usa surname para los apellidos.