Factuarea API
Proveedores

Crea un proveedor

Crea un nuevo proveedor para tu empresa. El objeto devuelto incluye el `uuid` generado.

POST
/suppliers

Authorization

AuthorizationBearer <token>

En: header

Parámetros de cabecera

Idempotency-Key?string

Clave única generada por el cliente para garantizar la idempotencia en los reintentos. Te permite reenviar de forma segura la misma petición: la primera respuesta se cachea y se devuelve sin volver a ejecutar la mutación. Es una cadena opaca para el servidor; cualquier valor único de hasta 64 caracteres es válido (UUID v7, UUID v4, ULID, nanoid, etc.). Se recomienda UUID v7 por coherencia con los identificadores de la API. La misma clave reutilizada con un body distinto devuelve 409 idempotency_key_reused.

Longitud1 <= length <= 64

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

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",
    "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,
    "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"
  }
}
{
  "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",
    "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,
    "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 varios proveedores de forma masiva

Elimina hasta 200 proveedores en una petición. Los proveedores con contratos asociados se reportan en failed junto con sus nombres visibles; los UUIDs de otros tenants se ignoran.

Elimina un proveedor

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