Factuarea API
Proveedores

Buscar un proveedor por external ID

Busca un proveedor por su `external_id` (enviado en el body JSON), la clave de integración persistente que lo mapea a un registro en un sistema de terceros (ERP/CRM). Distinto del `tax_id` fiscal y del `Idempotency-Key` a nivel de petición. Devuelve el proveedor coincidente o 404 si ningún proveedor usa ese external_id dentro de tu empresa.

POST
/suppliers/find-by-external-id

Authorization

AuthorizationBearer <token>

En: header

Cuerpo de la petición

application/json

Definiciones de TypeScript

Usa el tipo request body en TypeScript.

Cuerpo de la respuesta

application/json

application/json

application/json

application/json

application/json

application/json

application/json

{
  "data": {
    "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a02",
    "object": "supplier",
    "name": "Distribuciones Ibéricas, S.L.",
    "business_name": "Distribuciones Ibéricas Sociedad Limitada",
    "commercial_name": "Distribuciones IB",
    "tax_id": "B87654321",
    "vat_id": "ESB87654321",
    "email": "facturacion@distribibericas.com",
    "phone": "+34 911 234 567",
    "fax": "+34 911 234 568",
    "mobile": "+34 600 234 567",
    "website": "https://distribibericas.com",
    "contact_person": "María López",
    "billing_emails": [
      "facturas@distribibericas.com",
      "contabilidad@distribibericas.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": 36.6954,
      "longitude": -4.4564
    },
    "iban": "ES9121000418450200051332",
    "bank_accounts": [
      {
        "object": "bank_account",
        "iban": "ES7621000418401234567891",
        "bic": "CAIXESBBXXX",
        "is_default": true
      }
    ],
    "default_taxes_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0f",
    "default_discount": 3,
    "default_vat_rate": 21,
    "default_retention_rate": 0,
    "is_surcharge_subject": false,
    "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
    },
    "external_id": "SUP-1",
    "notes": "Proveedor preferente de material de oficina.",
    "metadata": {
      "erp_code": "IVA-GEN",
      "ledger_account": "477000"
    },
    "is_active": true,
    "created_at": "2026-01-10T09:00:00Z",
    "updated_at": "2026-01-10T09:00: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 proveedor

Elimina un proveedor. Devuelve 422 si el proveedor está referenciado por alguna factura de compra.

Buscar un proveedor por tax ID

Busca un proveedor por su identificador fiscal español (NIF/CIF/NIE/VAT). Devuelve el proveedor coincidente o 404 si ningún proveedor usa ese tax_id dentro de tu empresa.