Factuarea API
Clients

Cercar un client per external ID

Cerca un client pel seu `external_id` (enviat al body JSON), la clau d'integració que el mapeja a un registre en un sistema de tercers (ERP/CRM/e-commerce). Diferent del `tax_id` fiscal. Retorna el client coincident o 404 si cap client fa servir aquest external_id dins de la teva empresa.

POST
/clients/find-by-external-id

Authorization

AuthorizationBearer <token>

A: header

Cos de la petició

application/json

Definicions de TypeScript

Usa el tipus request body a TypeScript.

Cos de la resposta

application/json

application/json

application/json

application/json

application/json

application/json

application/json

{
  "data": {
    "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01",
    "object": "client",
    "name": "Acme Corporation",
    "commercial_name": "Acme SL",
    "tax_id": "B12345678",
    "vat_id": "ESB12345678",
    "email": "billing@acme.com",
    "phone": "+34 600 123 456",
    "fax": "+34 91 123 45 68",
    "mobile": "+34 600 000 000",
    "website": "https://acme.com",
    "contact_person": "Juan García",
    "billing_emails": [
      "facturacion@acme.com",
      "contabilidad@acme.com"
    ],
    "address": {
      "line1": "Calle Mayor 1",
      "line2": "Edificio Central",
      "number": "42",
      "floor": "3",
      "door": "B",
      "staircase": "A",
      "postal_code": "28001",
      "city": "Madrid",
      "province": "Madrid",
      "country": "ES"
    },
    "coordinates": {
      "latitude": 39.4699,
      "longitude": -0.3763
    },
    "default_discount": 5,
    "default_vat_rate": 21,
    "default_retention_rate": 15,
    "is_surcharge_subject": false,
    "bank_accounts": [
      {
        "object": "bank_account",
        "iban": "ES7621000418401234567891",
        "bic": "CAIXESBBXXX",
        "is_default": true
      }
    ],
    "preferred_operation_regime": "general",
    "accumulate_347": true,
    "alternative_id": {
      "object": "alternative_id",
      "type": "tax_id_foreign",
      "value": "EU123456789",
      "country_code": "FR"
    },
    "payment_preferences": {
      "object": "payment_preferences",
      "method": "bank_transfer",
      "terms_days": 30
    },
    "dir3_accounting_office": "L01280796",
    "dir3_managing_body": "L01280796",
    "dir3_processing_unit": "L01280796",
    "external_id": "CRM-99",
    "notes": "Pago al contado.",
    "metadata": {
      "erp_code": "IVA-GEN",
      "ledger_account": "477000"
    },
    "is_active": true,
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "missing_api_key",
    "message": "No se ha proporcionado una API key válida en el header Authorization.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#missing_api_key",
    "request_id": "req_01HKQS5N8VR7QXJ9K3T6BWPMZA"
  }
}

{
  "error": {
    "type": "authorization_error",
    "code": "insufficient_scope",
    "message": "Esta API key no tiene el scope requerido para esta operación.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#insufficient_scope",
    "request_id": "req_01HKQS5NBC3P8M1KX4V7SLNHQD"
  }
}

{
  "error": {
    "type": "idempotency_error",
    "code": "idempotency_key_reused",
    "message": "La cabecera `Idempotency-Key` ya se usó con un body distinto. Usa una clave nueva o reenvía exactamente el mismo body.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#idempotency_key_reused",
    "request_id": "req_01HKQS5NHT9A4U7R2E3F8GZWTJ"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "El campo `name` es obligatorio y no puede estar vacío.",
    "param": "name",
    "doc_url": "https://docs.factuarea.com/guides/errors#parameter_invalid",
    "request_id": "req_01HKQS5NGS8Z3T6Q1D2E7FYVSI"
  }
}

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Has excedido el rate limit de 60 peticiones por minuto. Reintenta tras 30 segundos.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#rate_limit_exceeded",
    "request_id": "req_01HKQS5NKW1C6W9T4G5H0JBZVL"
  }
}

{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "Ha ocurrido un error inesperado. Si persiste, contacta con soporte adjuntando el request_id.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#internal_error",
    "request_id": "req_01HKQS5NLX2D7X0U5H6J1KCAWM"
  }
}

Elimina un client

Elimina un client. Retorna 422 si el client està referenciat per algun document (factura, pressupost, etc.).

Cercar un client per tax ID

Cerca un client pel seu identificador fiscal espanyol (NIF/CIF/NIE). Retorna el client coincident o 404 si cap client fa servir aquest tax_id dins de la teva empresa.