Desarrolladores

Referencia de la API

Lea el estado de cumplimiento de sus proveedores desde sus propios sistemas, para que sus herramientas de adquisiciones y pagos puedan verificar VendMetric antes de actuar.

URL base y autenticación

Todos los puntos de acceso están bajo https://app.vendmetric.com/api/v1. Un administrador de la organización crea claves en Configuración; cada clave se muestra una sola vez. Envíela como un token Bearer. Cada respuesta está delimitada a la organización de la clave.

La API y los webhooks están incluidos en Professional y Enterprise, no en Starter. Las claves pueden recibir una fecha de vencimiento al crearlas, y el plan se verifica en cada solicitud, así que una clave deja de funcionar si el plan ya no incluye acceso a la API.

curl https://app.vendmetric.com/api/v1/vendors \
  -H "Authorization: Bearer vm_live_your_key_here"

Límites de velocidad: 60 solicitudes por minuto y 10,000 por día por clave. Exceder un límite devuelve HTTP 429 con un encabezado Retry-After. Las claves pueden revocarse en cualquier momento en Configuración.

Vencimiento y rotación de claves

Al crear una clave, usted elige cuánto tiempo vive: 24 horas, 30 días, 90 días, 1 año, o nunca. Las claves nuevas por defecto duran 90 días. Una clave que nunca vence sigue siendo válida hasta que alguien la revoque, incluso si se filtra en un registro o repositorio, así que prefiera una clave con fecha.

Notificamos a sus administradores siete días antes de que una clave venza. Las solicitudes con una clave vencida devuelven HTTP 401 con el código key_expired.

Para rotar sin tiempo de inactividad: cree la clave de reemplazo, despliéguela, confirme que el tráfico se ha movido, luego revoque la clave anterior.

Control de versiones

Cada clave está fijada a una versión con fecha, devuelta en cada respuesta en el encabezado VendMetric-API-Version. Su integración conserva el comportamiento contra el que fue construida; una clave nueva adopta la versión actual.

Agregamos puntos de acceso y campos de respuesta sin cambiar su versión, así que su cliente debe ignorar los campos que no reconozca. Cualquier cosa que pudiera romper una integración funcional, como eliminar un campo o endurecer un valor por defecto, se publica como una nueva versión con fecha. Cuando se retira una versión, verá encabezados Deprecation y Sunset por al menos 90 días antes.

Errores

Los errores devuelven un mensaje legible y un código estable sobre el cual ramificar.

{ "error": "API key expired. Create a new key in Settings, Developer.",
  "code": "key_expired" }

invalid_key (401): faltante, malformada, o revocada.
key_expired (401): la clave pasó su fecha de vencimiento.
plan_required (403): su plan no incluye esto.
rate_limited (429): vea Retry-After.
not_found (404): no existe tal registro en su organización.
invalid_request (400): se rechazó un parámetro; el mensaje lo nombra.

Listar proveedores

GET/vendors

Proveedores activos con estado de cumplimiento y puntaje, 50 por página por defecto, ordenados por nombre.

{
  "data": [
    {
      "id": "cmr...",
      "name": "Apex Electrical",
      "category": "Construction",
      "status": "ACTIVE",
      "compliance": "COMPLIANT",
      "vis_score": 96
    }
  ],
  "has_more": true,
  "next_cursor": "cmr..."
}

Devuelva next_cursor como cursor para recorrer páginas hasta que has_more sea falso.

limit: de 1 a 200, por defecto 50.
cursor: el next_cursor de la página anterior.
compliance: COMPLIANT, AT_RISK, NON_COMPLIANT, o PENDING.
status: ACTIVE, ONBOARDING, INVITED, SUSPENDED, o ARCHIVED. Los proveedores archivados se excluyen a menos que los solicite.
updated_since: ISO 8601; solo proveedores modificados desde entonces.

curl "https://app.vendmetric.com/api/v1/vendors?compliance=NON_COMPLIANT&limit=100" \
  -H "Authorization: Bearer vm_live_your_key_here"

Detalle de cumplimiento del proveedor

GET/vendors/{id}/compliance

El punto de acceso para llamar antes de pagarle a un proveedor: si está en cumplimiento, más cada requisito que aún necesita acción.

{
  "data": {
    "id": "cmr...",
    "name": "Apex Electrical",
    "compliance": "AT_RISK",
    "vis_score": 74,
    "is_compliant": false,
    "requirements": [
      {
        "document_type": "COI",
        "document_type_name": "Certificate of Insurance",
        "state": "EXPIRING_SOON",
        "days_until_expiration": 12,
        "expiration_date": "2026-07-30T00:00:00.000Z",
        "waived": false,
        "verification": null
      },
      {
        "document_type": "W9",
        "document_type_name": "W-9 Tax Form",
        "state": "SATISFIED",
        "days_until_expiration": null,
        "expiration_date": null,
        "waived": false,
        "verification": {
          "status": "MATCH",
          "checked_at": "2026-07-18T14:22:00.000Z"
        }
      }
    ],
    "action_needed": [ /* the requirements not yet satisfied */ ]
  }
}

El campo de verificación

Cada requisito lleva un objeto de verificación cuando su documento que lo satisface ha sido revisado contra una fuente autoritativa (los ID fiscales de W-9 primero), o null cuando no se ha ejecutado tal verificación. Es evidencia para su decisión, nunca una barrera: un requisito puede estar satisfecho sin verificación, y un resultado de verificación nunca cambia el estado de un documento por sí solo.

MATCH: el nombre y el ID fiscal se confirmaron contra la fuente.
MISMATCH: la fuente reporta que los valores no coinciden. Solo una discrepancia confirmada devuelve esto; trátelo como una señal para revisar el archivo, no un rechazo automático.
REVIEW: la fuente devolvió un resultado parcial o ambiguo (por ejemplo una casi coincidencia en el nombre, o un candidato difuso en una lista de vigilancia) que una persona debería confirmar. No es una aprobación ni un fallo confirmado.
PENDING: una verificación asíncrona está en progreso (por ejemplo una consulta al registro estatal). Vuelva a consultar, o suscríbase al webhook document.approved; el campo se resuelve a uno de los estados anteriores.
UNAVAILABLE: la verificación no pudo completarse (no hay ID fiscal presente, o no se pudo contactar a la fuente). Un error del proveedor nunca se reporta como una discrepancia.

checked_at es la marca de tiempo de la verificación más reciente. Si aplica ID fiscales verificados por fuente en su bloqueo de pagos, requiera verification.status === "MATCH" en el requisito relevante además de is_compliant.

Garantías de proveedor

GET/vendors/{id}/warranties

Las garantías que su organización tiene con un proveedor, la de vencimiento más próximo primero. Deliberadamente separado del punto de acceso de cumplimiento: una garantía es cobertura que usted posee, así que nunca afecta is_compliant ni el puntaje del proveedor. Úselo para alimentar sistemas de activos, mantenimiento o adquisiciones que necesiten saber cuándo termina la cobertura.

{
  "data": {
    "vendor_id": "cmr...",
    "vendor_name": "Apex Electrical",
    "warranties": [
      {
        "reference": "V#-2107",
        "covered_item": "Rooftop HVAC units, Building A",
        "provider": "Trane",
        "start_date": "2025-09-02T00:00:00.000Z",
        "expiration_date": "2027-09-01T00:00:00.000Z",
        "days_until_expiration": 410,
        "status": "ACTIVE",
        "coverage_value": 85000,
        "terms": "Parts and labor, quarterly maintenance required."
      }
    ]
  }
}

status es uno de ACTIVE, EXPIRING_SOON, EXPIRED, CLAIMED, o VOID. Un proveedor sin garantías devuelve una lista vacía. El seguimiento de garantías es una función del plan Professional: en planes sin ella, el punto de acceso devuelve HTTP 403 con una explicación en lugar de un resultado vacío.

Resumen de la organización

GET/organization/summary

Conteos de la cartera y puntaje promedio, para un panel de resumen.

{
  "data": {
    "vendors_total": 42,
    "by_compliance": { "COMPLIANT": 33, "AT_RISK": 6, "NON_COMPLIANT": 2, "PENDING": 1 },
    "average_vis": 88
  }
}

Webhooks

En lugar de consultar repetidamente, registre un punto de acceso https en Configuración y reciba un POST firmado en el momento en que algo cambie. Eventos disponibles:

vendor.compliance_changed
document.approved
document.expired
vendor.joined

Cada entrega lleva un encabezado X-VendMetric-Event y un encabezado X-VendMetric-Signature con la forma sha256=<hex>, un HMAC-SHA256 del cuerpo exacto de la solicitud usando el secreto de firma de su punto de acceso (mostrado una sola vez cuando agrega el punto de acceso). Verifíquelo antes de confiar en una carga útil:

// Node.js
import crypto from "crypto";

function verify(rawBody, signatureHeader, secret) {
  const expected =
    "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signatureHeader),
    Buffer.from(expected),
  );
}

Las entregas fallidas se reintentan; un punto de acceso que falla repetidamente se deshabilita y se notifica a su equipo. Use "Enviar prueba" en Configuración para confirmar que su receptor funciona.

Siguiente: bloquee pagos a proveedores según el cumplimiento →