API de Sourced — Referencia v1

API Pública de Sourced v1

La API de Sourced permite que los sistemas ERP (como Calipso, SAP, JD Edwards) se integren directamente con la plataforma de compras de Sourced. Úsala para:

Enviar requisiciones de compra desde tu ERP a Sourced
Obtener órdenes de compra de vuelta en tu ERP una vez adjudicadas
Verificar qué requisiciones ya fueron sincronizadas
Monitorear el estado de tus requisiciones

La API sigue las convenciones REST, utiliza JSON para los cuerpos de solicitud y respuesta, y se autentica mediante API keys.

Autenticación

Todos los endpoints (excepto health check) requieren una API key enviada en el header .

Las API keys se crean en el panel de administración de Sourced en . Cada key se muestra solo una vez al crearla. Guardala de forma segura.

Ejemplo: Solicitud autenticada

curl -H "X-API-Key: sk_live_abc123..." \
  https://api.gosourced.ai/api/v1/requisitions

Seguridad: Tratá tu API key como una contraseña. No la expongas en código del lado del cliente, repositorios públicos o logs. Si se compromete, revocala inmediatamente desde el panel de administración y creá una nueva.

URL Base

Ambiente	URL Base
Producción	https://api.gosourced.ai
Desarrollo	https://api-dev.gosourced.ai

Todos los endpoints tienen el prefijo .

Límites de tasa

Todos los endpoints están limitados a por endpoint. Exceder este límite devuelve una respuesta .

Para operaciones masivas, usá el endpoint de importación por lotes () que acepta hasta 100 requisiciones por solicitud.

Errores

La API utiliza códigos de estado HTTP estándar. Los errores devuelven un cuerpo JSON con un campo .

Formato de respuesta de error

{
  "detail": "Invalid or revoked API key."
}

Estado	Significado
200	Éxito
400	Solicitud inválida — error de validación o cuerpo malformado
401	No autorizado — API key faltante o inválida
404	No encontrado — el recurso no existe o no es accesible
422	Entidad no procesable — el cuerpo de la solicitud no pasó la validación del esquema
429	Demasiadas solicitudes — límite de tasa excedido
500	Error interno del servidor — error inesperado de nuestro lado

Ejemplos de errores

401 — API key inválida

{
  "detail": "Invalid or revoked API key."
}

422 — Error de validación (ej: campo requerido faltante)

{
  "detail": [
    {
      "loc": ["body", "requisitions", 0, "items", 0, "quantity"],
      "msg": "Input should be greater than 0",
      "type": "greater_than"
    }
  ]
}

200 — Éxito parcial (algunas requisiciones fallaron)

{
  "success": false,
  "created_count": 2,
  "updated_count": 0,
  "skipped_count": 0,
  "error_count": 1,
  "errors": [
    {
      "index": 2,
      "external_id": "REQ-2026-0099",
      "error": "Failed to process requisition: duplicate external_line_id within items"
    }
  ],
  "requisition_ids": [1234, 1235]
}

Nota: el endpoint devuelve incluso con fallos parciales. Siempre verificá el campo y el array para detectar problemas por requisición.

Health Check

GET/api/v1/health

Verificar que la API esté accesible. No requiere autenticación.

Solicitud

curl https://api.gosourced.ai/api/v1/health

Respuesta — 200 OK

{
  "status": "ok",
  "api": "v1"
}

Importar requisiciones

POST/api/v1/requisitionsAPI Key requerida

Importar una o más requisiciones de compra desde tu ERP. Soporta importación por lotes de hasta 100 requisiciones por solicitud. Usa external_id para deduplicación.

Cuerpo de la solicitud

El cuerpo debe contener un array con 1 a 100 objetos de requisición.

Objeto Requisición

Campo	Tipo	Requerido	Descripción
external_id	string	requerido	ID único en tu ERP (clave de deduplicación). Máx 250 caracteres.
items	array	requerido	Items de línea (1-200 items). Ver esquema de Item abajo.
requester_name	string	opcional	Nombre de la persona solicitante. Máx 200 caracteres.
requester_email	string	opcional	Email del solicitante. Máx 200 caracteres.
description	string	opcional	Título o resumen de la requisición. Máx 500 caracteres.
comments	string	opcional	Instrucciones adicionales para compradores (HTML soportado). Máx 15.000 caracteres.
delivery_address	string	opcional	Dirección de entrega en texto libre. Máx 500 caracteres.
delivery_address_code	string	opcional	Código que coincide con una dirección configurada en Sourced. Máx 50 caracteres.
desired_delivery_lead_time_days	integer	opcional	Plazo de entrega deseado en días desde la confirmación de la OC. Se aplica como default a todos los items.
offer_deadline	datetime	opcional	Fecha límite para cotizaciones de proveedores (ISO 8601).
total_estimated_value	float	opcional	Valor total estimado. Se calcula automáticamente desde los items si se omite.
currency	string	opcional	Código de moneda (ej: "ARS", "USD"). Por defecto "ARS". Máx 10 caracteres.
department_code	string	opcional	Código de departamento/centro de costo (se compara con departamentos de Sourced). Máx 50 caracteres.
priority_level	string	opcional	Prioridad: "LOW", "MEDIUM", "HIGH" o "CRITICAL".
attachments	array	opcional	Archivos adjuntos (máx 20). Ver esquema de Adjunto abajo.
raw_data	object	opcional	JSON arbitrario de tu ERP, almacenado para trazabilidad.

Objeto Item

Campo	Tipo	Requerido	Descripción
description	string	requerido	Nombre o descripción del item. Máx 1.000 caracteres.
quantity	float	requerido	Cantidad requerida (debe ser > 0).
external_line_id	string	opcional	ID de línea en tu ERP (ej: "REQ-001-L10"). Se devuelve en las OC para trazabilidad. Máx 100 caracteres.
unit_of_measure	string	opcional	Código de UOM (ej: "KG", "EA", "LT", "M", "UN"). Se compara con el catálogo de tu org. Máx 50 caracteres.
target_price	float	opcional	Precio objetivo/presupuesto por unidad.
estimated_price	float	opcional	Precio total estimado para esta línea.
currency	string	opcional	Moneda para precios (ej: "ARS", "USD"). Máx 10 caracteres.
category	string	opcional	Categoría desde tu ERP. Máx 200 caracteres.
material_code	string	opcional	Código de material/parte en tu ERP (ej: código de material SAP). Máx 100 caracteres.
specifications	object	opcional	Especificaciones técnicas. Ver esquema de Especificaciones abajo.
desired_delivery_date	datetime	opcional	Fecha de entrega deseada para este item (ISO 8601, ej: "2026-05-15T00:00:00Z").
desired_delivery_lead_time_days	integer	opcional	Plazo de entrega deseado en días para esta línea. Sobreescribe el valor a nivel de cabecera.
detail	string	opcional	Notas adicionales para esta línea. Máx 1.000 caracteres.
raw_data	object	opcional	JSON arbitrario para este item.

Objeto Especificaciones

Campo	Tipo	Requerido	Descripción
manufacturer_code	string	opcional	Número de parte del fabricante (ej: "6ES7214-1AG40-0XB0"). Máx 100 caracteres.
manufacturer_name	string	opcional	Nombre del fabricante (ej: "Siemens"). Máx 200 caracteres.
manufacturer_description	string	opcional	Descripción del fabricante. Máx 500 caracteres.
buyer_code	string	opcional	Código interno en tu sistema (ej: "MAT-001234"). Máx 100 caracteres.
buyer_code_description	string	opcional	Descripción del código interno. Máx 500 caracteres.
buyer_code_system	string	opcional	Nombre del sistema de origen (ej: "SAP", "Calipso"). Máx 50 caracteres.
technical_specs	string	opcional	Especificaciones técnicas en texto libre (ej: "220V, 50Hz, IP55"). Máx 2.000 caracteres.
requirements	string	opcional	Requisitos adicionales (ej: "Certificación ISO 9001 requerida"). Máx 2.000 caracteres.

Objeto Adjunto

Campo	Tipo	Requerido	Descripción
url	string	requerido	URL públicamente accesible para descargar el archivo. Máx 2.000 caracteres.
filename	string	requerido	Nombre de archivo original (ej: "plano_motor.pdf"). Máx 255 caracteres.
description	string	opcional	Descripción del adjunto. Máx 500 caracteres.
file_type	string	opcional	Tipo MIME (se detecta automáticamente si no se proporciona). Máx 100 caracteres.

Lógica de deduplicación

Cada requisición se identifica por su (dentro del alcance de tu organización):

Nueva: Si no se encuentra una requisición existente, se crea una nueva con estado .
Actualizar: Si se encuentra una requisición existente con estado , se actualiza in-place (los items se reemplazan completamente).
Superseder: Si se encuentra una requisición existente con estado , se reactiva (vuelve a PENDING) con los nuevos datos.
Lanzada: Si la requisición ya fue lanzada como Solicitud de Compra (), la importación se rechaza. La PR activa no puede ser sobreescrita.
Descartada: Si la requisición fue descartada previamente (), se reactiva (vuelve a PENDING) con los nuevos datos. Útil cuando el ERP la cancela y luego la reenvía.

Solicitud — Ejemplo mínimo

curl -X POST https://api.gosourced.ai/api/v1/requisitions \
  -H "X-API-Key: sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "requisitions": [
      {
        "external_id": "REQ-2026-0042",
        "items": [
          {
            "description": "Bearing SKF 6205",
            "quantity": 10
          }
        ]
      }
    ]
  }'

Respuesta

ERPImportResult

Campo	Tipo	Requerido	Descripción
success	boolean	requerido	true si error_count es 0.
created_count	integer	requerido	Cantidad de nuevas requisiciones creadas.
updated_count	integer	requerido	Cantidad de requisiciones PENDING existentes actualizadas.
skipped_count	integer	requerido	Cantidad de requisiciones omitidas (actualmente siempre 0).
error_count	integer	requerido	Cantidad de requisiciones que fallaron al importar.
errors	array	requerido	Array de {index, external_id, error} para cada requisición fallida.
requisition_ids	array	requerido	IDs internos de Sourced de las requisiciones creadas/actualizadas.

Respuesta — 200 OK

{
  "success": true,
  "created_count": 1,
  "updated_count": 0,
  "skipped_count": 0,
  "error_count": 0,
  "errors": [],
  "requisition_ids": [1234]
}

Listar requisiciones

GET/api/v1/requisitionsAPI Key requerida

Obtener una lista paginada de tus requisiciones importadas. Solo devuelve requisiciones creadas a través de la API.

Parámetros de consulta

Campo	Tipo	Requerido	Descripción
page	integer	opcional	Número de página (por defecto: 1).
page_size	integer	opcional	Items por página, 1-100 (por defecto: 20).
status	string	opcional	Filtrar por estado: "PENDING", "LAUNCHED", "DISCARDED", "SUPERSEDED".

Solicitud

curl -H "X-API-Key: sk_live_abc123..." \
  "https://api.gosourced.ai/api/v1/requisitions?page=1&page_size=20&status=PENDING"

Respuesta — 200 OK

{
  "data": [
    {
      "id": 1234,
      "external_id": "REQ-2026-0042",
      "status": "PENDING",
      "requester_name": "Juan Pérez",
      "description": "Repuestos línea producción",
      "items": [...],
      "imported_at": "2026-03-07T14:30:00Z"
    }
  ],
  "total": 45,
  "page": 1,
  "page_size": 20,
  "has_more": true
}

Detalle de requisición

GET/api/v1/requisitions/{requisition_id}API Key requerida

Obtener una requisición individual por su ID interno de Sourced, incluyendo todos los items.

Solicitud

curl -H "X-API-Key: sk_live_abc123..." \
  https://api.gosourced.ai/api/v1/requisitions/1234

Devuelve el objeto completo de la requisición. Devuelve si no se encuentra o no pertenece a tu organización.

Verificar requisiciones existentes

POST/api/v1/requisitions/check-existingAPI Key requerida

Verificar qué external_ids ya existen en Sourced antes de importar. Útil para evitar llamadas innecesarias a la API.

Cuerpo de la solicitud

Campo	Tipo	Requerido	Descripción
external_ids	array	requerido	Lista de strings external_id a verificar (1-100 items).

Solicitud

curl -X POST https://api.gosourced.ai/api/v1/requisitions/check-existing \
  -H "X-API-Key: sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "external_ids": ["REQ-2026-0042", "REQ-2026-0043", "REQ-2026-0044"]
  }'

Respuesta — 200 OK

{
  "existing": ["REQ-2026-0042"],
  "not_found": ["REQ-2026-0043", "REQ-2026-0044"]
}

Cancelar requisición

POST/api/v1/requisitions/cancelAPI Key requerida

Cancelar una requisición PENDING enviando el external_id en el cuerpo del request.

Solo se pueden cancelar requisiciones con estado . Si la requisición ya fue lanzada como Solicitud de Compra, debe cancelarse dentro de Sourced.

Campo	Tipo	Requerido	Descripción
external_id	string	requerido	ID de la requisición en tu sistema externo (la misma que usaste al importar)
reason	string	opcional	Motivo de la cancelación (se almacena para auditoría)

Solicitud

curl -X POST https://api.gosourced.ai/api/v1/requisitions/cancel \
  -H "X-API-Key: sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "REQ-2026-0042",
    "reason": "Cancelado desde ERP"
  }'

Respuesta — 200 OK

{
  "status": "discarded",
  "external_id": "REQ-2026-0042"
}

Respuestas posibles:

discarded — La requisición fue descartada exitosamente.
already_discarded — La requisición ya estaba descartada (idempotente).
already_superseded — La requisición ya fue reemplazada por una versión más nueva.
La requisición ya fue lanzada — devuelve con detalles.
Requisición no encontrada — devuelve .

Listar órdenes de compra

GET/api/v1/purchase-ordersAPI Key requerida

Obtener órdenes de compra de tu organización. Soporta sincronización incremental a través del parámetro 'since'.

Parámetros de consulta

Campo	Tipo	Requerido	Descripción
page	integer	opcional	Número de página (por defecto: 1).
page_size	integer	opcional	Items por página, 1-100 (por defecto: 20).
status	string	opcional	Filtrar por estado: "DRAFT", "CREATED", "SENT", "CONFIRMED", "REJECTED", "CANCELLED".
since	datetime	opcional	Timestamp ISO 8601. Devuelve solo OC creadas o actualizadas después de esta fecha.
requisition_external_id	string	opcional	Filtrar por el external_id de la requisición original en tu ERP. Devuelve las OC que se generaron a partir de esa requisición.

Solicitud — Sincronización incremental

curl -H "X-API-Key: sk_live_abc123..." \
  "https://api.gosourced.ai/api/v1/purchase-orders?since=2026-03-01T00:00:00Z&status=CONFIRMED"

Respuesta — 200 OK

{
  "data": [
    {
      "id": 567,
      "code": "PO-2026-0089",
      "status": "CONFIRMED",
      "award_type": "FULL",
      "supplier_name": "Distribuidora Industrial SA",
      "supplier_id": 42,
      "supplier_external_id": "PROV-CAL-00123",
      "supplier_tax_id": "30712345678",
      "supplier_email": "ventas@distribuidora.com",
      "total_price": 285000.00,
      "currency": "ARS",
      "delivery_address": "Av. Corrientes 1234, CABA",
      "delivery_address_code": "001",
      "observations": "Entregar en horario de mañana. Coordinar con depósito.",
      "delivery_lead_time_days": 15,
      "expected_delivery_date": "2026-03-20T16:00:00Z",
      "payment_terms_code": "NET30",
      "awarded_at": "2026-03-05T16:00:00Z",
      "awarded_by_name": "Juan Pérez",
      "awarded_by_email": "juan.perez@empresa.com",
      "created_at": "2026-03-05T16:00:00Z",
      "updated_at": "2026-03-06T10:30:00Z",
      "purchase_request_id": 1234,
      "requisition_external_id": "REQ-2026-00142",
      "exchange_rate_data": {
        "date": "2026-03-05",
        "usdToArs": 1450.0,
        "arsToUsd": 0.00069
      },
      "total_nominal_savings": 15000.00,
      "total_real_savings": 8500.00,
      "savings_currency": "ARS",
      "items": [
        {
          "description": "Bearing SKF 6205",
          "quantity": 10,
          "unit_price": 28500.00,
          "total_price": 285000.00,
          "unit_of_measure": "UN",
          "currency": "ARS",
          "delivery_lead_time_days": 15,
          "expected_delivery_date": "2026-03-20T16:00:00Z",
          "external_line_id": "REQ-2026-0042-L10",
          "manufacturer_code": "6205-2RS"
        }
      ]
    }
  ],
  "total": 12,
  "page": 1,
  "page_size": 20,
  "has_more": false
}

Detalle de orden de compra

GET/api/v1/purchase-orders/{po_id}API Key requerida

Obtener una orden de compra individual por su ID interno de Sourced, incluyendo todos los items con trazabilidad hacia tu ERP via external_line_id.

Solicitud

curl -H "X-API-Key: sk_live_abc123..." \
  https://api.gosourced.ai/api/v1/purchase-orders/567

¿Buscás OCs por el ID de requisición de tu sistema?

Este endpoint requiere el ID interno de Sourced (). Si necesitás buscar órdenes de compra usando el ID de requisición de tu ERP, usá el endpoint con el query parameter :

GET /api/v1/purchase-orders?requisition_external_id=YOUR-REQ-ID

También podés combinarlo con otros filtros: para filtrar por estado de la OC, para sincronización incremental, y / para paginación.

Objeto Orden de Compra

Campo	Tipo	Requerido	Descripción
id	integer	requerido	ID interno de OC en Sourced.
code	string	requerido	Código de OC legible.
status	string	requerido	Estado de la OC: "DRAFT", "CREATED", "SENT", "CONFIRMED", "REJECTED", "CANCELLED".
award_type	string	opcional	Tipo de adjudicación: FULL (proveedor único) o PARTIAL (adjudicación dividida entre múltiples proveedores).
supplier_name	string	requerido	Nombre del proveedor.
supplier_id	integer	opcional	ID interno del proveedor en Sourced.
total_price	float	opcional	Valor total de la OC.
currency	string	opcional	Código de moneda.
delivery_address	string	opcional	Dirección de entrega.
delivery_address_code	string	opcional	Código de la dirección de entrega de la organización vinculada (ej. "001"). Usalo para mapear el destino contra tu ERP. Null para direcciones de texto libre sin registro vinculado.
observations	string	opcional	Comentarios u observaciones en texto libre que el comprador cargó en el paso de revisión pre-adjudicación. Usa las condiciones especiales cotizadas por el proveedor si el comprador no dejó nota. Null cuando no hay ninguna.
delivery_lead_time_days	integer	opcional	Plazo de entrega en días, según lo cotizado por el proveedor a nivel cabecera. Cuando el proveedor cotiza distintos plazos por línea, los items pueden tener valores diferentes — usá items[].delivery_lead_time_days para el valor por línea.
expected_delivery_date	datetime	opcional	Fecha de entrega calculada (awarded_at + delivery_lead_time_days). Null si falta cualquiera de los dos. Para fechas por línea usá items[].expected_delivery_date.
payment_terms_code	string	opcional	Código de condiciones de pago.
awarded_at	datetime	opcional	Cuándo se adjudicó la OC (ISO 8601).
awarded_by_name	string	opcional	Nombre del usuario que adjudicó la OC.
awarded_by_email	string	opcional	Email del usuario que adjudicó la OC.
created_at	datetime	opcional	Timestamp de creación (ISO 8601).
updated_at	datetime	opcional	Timestamp de última actualización (ISO 8601).
purchase_request_id	integer	opcional	ID de la solicitud de compra originante.
requisition_external_id	string	opcional	ID del documento origen en tu ERP (ej. número de requisición en Calipso/SAP/JDE). Se resuelve desde la ERPRequisition de origen cuando existe; si no, cae al external_id de la PR. Puede ser una lista separada por comas cuando una sola PR agrupa varias requisiciones origen.
exchange_rate_data	object	opcional	Tipos de cambio al momento del award. Formato: {"date": "2026-03-05", "usdToArs": 1450.0, "arsToUsd": 0.00069}. Null si no hay datos disponibles.
total_nominal_savings	float	opcional	Ahorro nominal total vs precios históricos (sin ajuste por inflación).
total_real_savings	float	opcional	Ahorro real total vs precios históricos (ajustado por inflación).
savings_currency	string	opcional	Moneda de los montos de ahorro.
items	array	requerido	Items de línea de la OC. Ver esquema de Item de OC abajo.

Objeto Item de OC

Campo	Tipo	Requerido	Descripción
description	string	requerido	Descripción del item.
quantity	float	opcional	Cantidad ordenada.
unit_price	float	opcional	Precio por unidad.
total_price	float	opcional	Precio total de la línea (cantidad x precio unitario).
unit_of_measure	string	opcional	Unidad de medida.
currency	string	opcional	Código de moneda.
delivery_lead_time_days	integer	opcional	Plazo de entrega en días para esta línea, según lo cotizado por el proveedor. Items distintos de una misma OC pueden tener plazos diferentes.
expected_delivery_date	datetime	opcional	Fecha de entrega calculada para esta línea (PO.awarded_at + delivery_lead_time_days del item). Null si falta cualquiera de los dos.
external_line_id	string	opcional	ID de línea original de tu ERP — usalo para vincular items de la OC con tus líneas de requisición.
manufacturer_code	string	opcional	Número de parte del fabricante.

Sobre fechas y plazos de entrega

El plazo de entrega existe a dos niveles: a nivel cabecera (refleja el plazo general que cotizó el proveedor) y a nivel línea (preciso por item). Cuando el proveedor cotiza distintos plazos por línea, conviene usar el valor por línea.
es un campo calculado: . Lo computa Sourced; no es un dato que el proveedor envíe directamente.
Si viene null, también lo hará . Esto suele significar que el proveedor no incluyó el plazo en su cotización.

Actualizar estado de orden de compra

POST/api/v1/purchase-orders/{po_id}/statusAPI Key requerida

Actualizar el estado de una orden de compra para reflejar su progreso en tu sistema externo (ERP).

Transiciones de estado permitidas:

Desde	Hacia	Significado
DRAFT	CREATED	La OC fue creada en tu ERP.
CREATED	CONFIRMED	La OC fue aprobada completamente en tu ERP.
DRAFT	CONFIRMED	Atajo cuando no necesitás el paso intermedio.
DRAFT	REJECTED	La OC fue rechazada en tu ERP. La PR se reabre en Sourced.
CREATED	REJECTED	La OC fue rechazada en tu ERP después de haber sido creada. La PR se reabre en Sourced.
DRAFT / CREATED / SENT / CONFIRMED	CANCELLED	La compra se cayó. La OC se cancela y la PR también — no se reabre nada. Usá REJECTED si la necesidad sigue vigente y querés re-adjudicar.

Campo	Tipo	Requerido	Descripción
status	string	requerido	Estado destino: CREATED (OC creada en tu ERP), CONFIRMED (OC aprobada en tu ERP), REJECTED (OC rechazada, reabre la PR) o CANCELLED (compra caída, cancela la OC y la PR).
external_id	string	opcional	Número o código de la OC en tu ERP (ej: OC-CAL-00045678). Se guarda para trazabilidad.
notes	string	opcional	Notas opcionales sobre el cambio de estado.

Solicitud

curl -X POST https://api.gosourced.ai/api/v1/purchase-orders/567/status \
  -H "X-API-Key: sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "status": "CREATED",
    "external_id": "OC-CAL-00045678",
    "notes": "Creada en Calipso"
  }'

Respuesta — 200 OK

{
  "status": "created",
  "po_id": 567,
  "code": "PO-A1B2C3D4"
}

Listar proveedores

GET/api/v1/suppliersAPI Key requerida

Listar los proveedores de tu organización. Usa ?has_erp_code=false para encontrar proveedores sin mapear al ERP. Usa ?detail=full para obtener contactos, categorías y cobertura.

Parámetros de consulta

Campo	Tipo	Requerido	Descripción
page	integer	opcional	Número de página (default: 1).
page_size	integer	opcional	Resultados por página (1-200, default: 50).
search	string	opcional	Buscar por nombre, nombre personalizado, email, CUIT/CNPJ o código ERP.
erp_code	string	opcional	Filtrar por código ERP exacto.
has_erp_code	boolean	opcional	true = solo mapeados al ERP, false = solo sin mapear.
detail	string	opcional	Usar 'full' para incluir contactos, categorías y cobertura.

Solicitud

# Light (default)
curl -H "X-API-Key: sk_live_abc123..." \
  "https://api.gosourced.ai/api/v1/suppliers?has_erp_code=false"

# Full detail
curl -H "X-API-Key: sk_live_abc123..." \
  "https://api.gosourced.ai/api/v1/suppliers?search=30712345678&detail=full"

Respuesta — 200 OK

// Light response
{
  "data": [
    {
      "id": 42,
      "name": "Distribuidora Industrial SA",
      "email": "ventas@distribuidora.com",
      "tax_id": "30712345678",
      "country_code": "AR",
      "city": "Buenos Aires",
      "is_active": true,
      "is_preferred": true,
      "erp_code": "PROV-CAL-00123",
      "erp_type": "SAP_B1"
    }
  ],
  "total": 85,
  "page": 1,
  "page_size": 50,
  "has_more": true
}

// Full response (?detail=full)
{
  "data": [
    {
      "id": 42,
      "name": "Distribuidora Industrial SA",
      "email": "ventas@distribuidora.com",
      "tax_id": "30712345678",
      "country_code": "AR",
      "city": "Buenos Aires",
      "is_active": true,
      "is_preferred": true,
      "erp_code": "PROV-CAL-00123",
      "erp_type": "SAP_B1",
      "address": "Av. Corrientes 1234",
      "state_code": "CABA",
      "website": "https://distribuidora.com",
      "description": "Distribuidor de insumos industriales",
      "tax_regime": null,
      "employee_count": "50+",
      "years_in_business": "5+",
      "performance_score": 4.2,
      "reliability_score": 4.5,
      "quality_score": 4.0,
      "contacts": [
        {
          "name": "Juan Pérez",
          "email": "juan@distribuidora.com",
          "phone": "+54 11 5555-1234",
          "role": "SALES",
          "is_primary": true
        }
      ],
      "categories": [
        { "id": 15, "code": "IND-001", "name": "Insumos Industriales", "level": "LEVEL_1" }
      ],
      "coverage": [
        { "country": "Argentina", "province": null, "is_nationwide": true }
      ]
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 50,
  "has_more": false
}

Crear proveedor

POST/api/v1/suppliersAPI Key requerida

Crear un proveedor para tu organización. Al menos uno de tax_id o erp_code es obligatorio. Se requiere al menos un contacto con rol 'sales'. Si ya existe un proveedor global con el mismo CUIT, se reutiliza y se vincula a tu organización.

Cuerpo de la solicitud

Campo	Tipo	Requerido	Descripción
name	string	requerido	Nombre del proveedor para tu organización.
tax_id	string	opcional	CUIT, CNPJ, RUT, etc. Al menos uno de tax_id o erp_code es obligatorio.
erp_code	string	opcional	Código del proveedor en tu ERP. Al menos uno de tax_id o erp_code es obligatorio.
erp_type	string	opcional	Tipo de ERP (SAP_B1, JDE, ORACLE_CLOUD, etc.).
country_code	string	opcional	Código de país ISO 3166-1 (ej: AR, BR, US).
city	string	opcional	Ciudad del proveedor.
address	string	opcional	Dirección completa.
state_code	string	opcional	Estado/provincia (ej: CABA, SP).
website	string	opcional	Sitio web del proveedor.
contacts	array	requerido	Lista de contactos. Al menos uno con rol 'sales' es obligatorio.
contacts[].name	string	requerido	Nombre del contacto.
contacts[].email	string	requerido	Email del contacto.
contacts[].phone	string	opcional	Teléfono (opcional).
contacts[].role	string	requerido	Rol: SALES o LOGISTICS.
contacts[].is_primary	boolean	opcional	true si es el contacto principal (default: false).

Solicitud

curl -X POST https://api.gosourced.ai/api/v1/suppliers \
  -H "X-API-Key: sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Distribuidora Industrial SA",
    "tax_id": "30712345678",
    "erp_code": "PROV-CAL-00123",
    "erp_type": "SAP_B1",
    "country_code": "AR",
    "city": "Buenos Aires",
    "address": "Av. Corrientes 1234",
    "contacts": [
      {
        "name": "Juan Pérez",
        "email": "juan@distribuidora.com",
        "phone": "+54 11 5555-1234",
        "role": "SALES",
        "is_primary": true
      },
      {
        "name": "María García",
        "email": "maria@distribuidora.com",
        "role": "LOGISTICS"
      }
    ]
  }'

Respuesta — 200 OK

// 201 Created
{
  "id": 42,
  "name": "Distribuidora Industrial SA",
  "email": null,
  "tax_id": "30712345678",
  "country_code": "AR",
  "city": "Buenos Aires",
  "is_active": true,
  "is_preferred": false,
  "erp_code": "PROV-CAL-00123",
  "erp_type": "SAP_B1",
  "address": "Av. Corrientes 1234",
  "state_code": null,
  "website": null,
  "description": null,
  "tax_regime": null,
  "employee_count": null,
  "years_in_business": null,
  "performance_score": null,
  "reliability_score": null,
  "quality_score": null,
  "contacts": [
    {
      "name": "Juan Pérez",
      "email": "juan@distribuidora.com",
      "phone": "+54 11 5555-1234",
      "role": "SALES",
      "is_primary": true
    },
    {
      "name": "María García",
      "email": "maria@distribuidora.com",
      "phone": null,
      "role": "LOGISTICS",
      "is_primary": false
    }
  ],
  "categories": [],
  "coverage": []
}

Referencia de esquemas

Referencia rápida de todos los esquemas de solicitud/respuesta usados en los endpoints.

Estados de requisición

Estado	Descripción
PENDING	Importada, esperando revisión de un comprador en Sourced.
LAUNCHED	El comprador lanzó la requisición como Solicitud de Compra.
DISCARDED	La requisición fue descartada manualmente.
SUPERSEDED	Se importó una versión más nueva con el mismo external_id.

Estados de orden de compra

Estado	Descripción
DRAFT	OC creada en Sourced, pendiente de sincronización al ERP.
CREATED	OC creada en el ERP externo, pendiente de aprobación.
CONFIRMED	OC aprobada completamente en el ERP externo.
REJECTED	OC rechazada en el ERP externo. La PR asociada se reabre automáticamente.
CANCELLED	Compra caída. La OC se cancela y la PR asociada también — nada se reabre.

Próximamente se agregarán estados adicionales como RECEIVED (mercadería recepcionada), INVOICED (facturada), entre otros, para reflejar el ciclo de vida completo de la orden de compra.

Códigos de referencia

Catálogos de monedas y tipos de pago aceptados por la API. Usalos para mapear estos valores con los códigos equivalentes en tu ERP.

Monedas

Sourced no usa un enum cerrado de monedas: cualquier código ISO 4217 válido de 3 letras es aceptado. Las monedas más utilizadas por nuestros clientes son:

Código	Moneda
ARS	Peso argentino
USD	Dólar estadounidense
EUR	Euro
BRL	Real brasileño

Mandá el código ISO 4217 directamente en el campo currency (ej: "currency": "EUR"). Sourced lo persiste tal cual y lo devuelve igual en las respuestas.

Tipos de pago (payment_terms_code)

Catálogo global de condiciones de pago disponibles en Sourced. Usá el código (columna Code) en el campo payment_terms_code de la PO. El campo type indica la naturaleza del pago: IMMEDIATE (al recibir), ADVANCE (anticipado), NET_DAYS (a X días de la factura).

Código	Nombre	Tipo	Días	Descripción
COD	Cash On Delivery	IMMEDIATE	0	Pago contra entrega
IMM	Immediate Payment	IMMEDIATE	0	Pago inmediato / Contado
ADV100	Advance Payment	ADVANCE	0	Pago por adelantado 100%
ADV50	Advance 50%	ADVANCE	0	Pago por adelantado del 50%
NET7	Net 7 Days	NET_DAYS	7	Pago a 7 días de la fecha de factura
NET10	Net 10 Days	NET_DAYS	10	Pago a 10 días de la fecha de factura
NET15	Net 15 Days	NET_DAYS	15	Pago a 15 días de la fecha de factura
NET20	Net 20 Days	NET_DAYS	20	Pago a 20 días de la fecha de factura
NET21	Net 21 Days	NET_DAYS	21	Pago a 21 días de la fecha de factura
NET30	Net 30 Days	NET_DAYS	30	Pago a 30 días de la fecha de factura
EOM30	End of Month + 30	NET_DAYS	30	Pago a fin de mes más 30 días
NET35	Net 35 Days	NET_DAYS	35	Pago a 35 días de la fecha de factura
NET40	Net 40 Days	NET_DAYS	40	Pago a 40 días de la fecha de factura
NET45	Net 45 Days	NET_DAYS	45	Pago a 45 días de la fecha de factura
NET60	Net 60 Days	NET_DAYS	60	Pago a 60 días de la fecha de factura
NET75	Net 75 Days	NET_DAYS	75	Pago a 75 días de la fecha de factura
NET90	Net 90 Days	NET_DAYS	90	Pago a 90 días de la fecha de factura

El catálogo es global a toda la plataforma y rara vez cambia. Si necesitás un código adicional para tu integración, contactanos.

Unidades de medida

Códigos de unidad de medida aceptados en items de requisiciones. Se envían en el campo unit_of_measure.

Código	Unidad
EA	Unidad
PCS	Piezas
KG	Kilogramo
G	Gramo
LB	Libra
OZ	Onza
M	Metro
CM	Centímetro
MM	Milímetro
IN	Pulgada
FT	Pie
YD	Yarda
L	Litro
ML	Mililitro
GAL	Galón
QT	Cuarto de galón
PT	Pinta
FL_OZ	Onza líquida
M2	Metro cuadrado
CM2	Centímetro cuadrado
FT2	Pie cuadrado
IN2	Pulgada cuadrada
YD2	Yarda cuadrada
M3	Metro cúbico
CM3	Centímetro cúbico
FT3	Pie cúbico
IN3	Pulgada cúbica
YD3	Yarda cúbica
BOX	Caja
CASE	Caja/Estuche
PACK	Paquete
SET	Juego
KIT	Kit
BUNDLE	Manojo
ROLL	Rollo
SHEET	Hoja/Lámina
PALLET	Paleta
DRUM	Tambor/Bidón
BAG	Bolsa
BOTTLE	Botella
CEN	Centena

Si enviás una unidad no reconocida, se almacena tal cual. Recomendamos usar los códigos estándar para que la IA pueda normalizar correctamente las cotizaciones de proveedores.

Flujo de integración

Patrón de integración típico para una sincronización ERP programada (ej: cron job cada 15 minutos):

Recopilar nuevas requisiciones del ERP

Consultar tu ERP por requisiciones aprobadas que aún no fueron sincronizadas con Sourced.

Verificar existentes (opcional)

Llamar a POST /requisitions/check-existing con external_ids para filtrar requisiciones ya sincronizadas.

Importar requisiciones

Llamar a POST /requisitions con el lote de requisiciones nuevas/actualizadas. Guardar los requisition_ids devueltos.

Consultar órdenes de compra nuevas

Llamar a GET /purchase-orders?since={last_sync_timestamp}&status=DRAFT para obtener OC nuevas. Crear la OC en tu ERP y llamar a POST /purchase-orders/{id}/status con {"status": "CREATED"}.

Confirmar OC aprobadas

Cuando la OC se apruebe en tu ERP, llamar a POST /purchase-orders/{id}/status con {"status": "CONFIRMED"} para cerrar el ciclo.

Pseudocódigo — Cron job de sincronización

# Step 1: Get pending requisitions from ERP
ERP_REQS=$(query_erp_pending_requisitions)

# Step 2: Check which ones already exist in Sourced
EXISTING=$(curl -s -X POST \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{"external_ids": $ERP_REQ_IDS}" \
  https://api.gosourced.ai/api/v1/requisitions/check-existing)

# Step 3: Import only new requisitions
NEW_REQS=$(filter_not_found $ERP_REQS $EXISTING)
curl -s -X POST \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{"requisitions": $NEW_REQS}" \
  https://api.gosourced.ai/api/v1/requisitions

# Step 4: Pull new POs since last sync
POS=$(curl -s \
  -H "X-API-Key: $API_KEY" \
  "https://api.gosourced.ai/api/v1/purchase-orders?since=$LAST_SYNC&status=DRAFT")

# Step 5: Create POs in ERP and update status
for PO in $POS; do
  create_po_in_erp $PO
  curl -s -X POST \
    -H "X-API-Key: $API_KEY" \
    -H "Content-Type: application/json" \
    -d "{"status": "CREATED", "external_id": "$ERP_PO_NUMBER"}" \
    "https://api.gosourced.ai/api/v1/purchase-orders/$PO_ID/status"
done

# Step 6: When PO is approved in ERP, confirm it
curl -s -X POST \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "CONFIRMED"}' \
  "https://api.gosourced.ai/api/v1/purchase-orders/$PO_ID/status"

Ejemplo completo

Una solicitud de importación realista con todos los campos disponibles:

Solicitud de importación completa

curl -X POST https://api.gosourced.ai/api/v1/requisitions \
  -H "X-API-Key: sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "requisitions": [
      {
        "external_id": "CAL-REQ-2026-0042",
        "description": "Repuestos bomba centrífuga Planta Norte",
        "requester_name": "Carlos Rodríguez",
        "requester_email": "carlos.rodriguez@empresa.com",
        "comments": "Urgente: bomba fuera de servicio desde 03/03. <b>Necesitamos entrega express.</b>",
        "delivery_address": "Av. Industrial 4500, Parque Industrial Pilar, Buenos Aires",
        "delivery_address_code": "PLANTA-NORTE",
        "desired_delivery_lead_time_days": 7,
        "offer_deadline": "2026-03-10T18:00:00Z",
        "total_estimated_value": 1250000.00,
        "currency": "ARS",
        "department_code": "MANT-001",
        "priority_level": "HIGH",
        "items": [
          {
            "external_line_id": "CAL-REQ-2026-0042-L10",
            "description": "Sello mecánico para bomba centrífuga KSB ETA 50-200",
            "quantity": 2,
            "unit_of_measure": "UN",
            "target_price": 185000.00,
            "estimated_price": 370000.00,
            "currency": "ARS",
            "category": "Repuestos Bombas",
            "material_code": "MAT-BOM-0234",
            "desired_delivery_lead_time_days": 10,
            "detail": "Sello tipo cartucho, material: carburo de silicio / carburo de silicio",
            "specifications": {
              "manufacturer_code": "KSB-SEAL-50200",
              "manufacturer_name": "KSB",
              "manufacturer_description": "Mechanical seal for ETA 50-200 centrifugal pump",
              "buyer_code": "MAT-BOM-0234",
              "buyer_code_description": "Sello mecánico bomba KSB ETA 50-200",
              "buyer_code_system": "Calipso",
              "technical_specs": "Diámetro eje: 35mm, Material caras: SiC/SiC, Elastómeros: Viton",
              "requirements": "Debe incluir certificado de calidad. Preferencia por repuesto original KSB."
            }
          },
          {
            "external_line_id": "CAL-REQ-2026-0042-L20",
            "description": "Rodamiento SKF 6310-2RS",
            "quantity": 4,
            "unit_of_measure": "UN",
            "target_price": 45000.00,
            "currency": "ARS",
            "category": "Rodamientos",
            "material_code": "MAT-ROD-0089",
            "specifications": {
              "manufacturer_code": "6310-2RS1",
              "manufacturer_name": "SKF",
              "technical_specs": "50x110x27mm, sellado ambos lados, grasa estándar"
            }
          },
          {
            "external_line_id": "CAL-REQ-2026-0042-L30",
            "description": "Aceite lubricante ISO VG 68",
            "quantity": 20,
            "unit_of_measure": "LT",
            "target_price": 5500.00,
            "currency": "ARS",
            "category": "Lubricantes",
            "specifications": {
              "technical_specs": "Aceite mineral ISO VG 68, índice de viscosidad > 95"
            }
          }
        ],
        "attachments": [
          {
            "url": "https://erp.empresa.com/files/plano-bomba-eta-50-200.pdf",
            "filename": "plano_bomba_KSB_ETA_50-200.pdf",
            "description": "Plano de despiece bomba KSB ETA 50-200",
            "file_type": "application/pdf"
          }
        ],
        "raw_data": {
          "calipso_doc_type": "SOL",
          "calipso_doc_number": "0042",
          "calipso_branch": "001",
          "approved_by": "María González",
          "cost_center": "CC-MANT-NORTE"
        }
      }
    ]
  }'

Respuesta — 200 OK

{
  "success": true,
  "created_count": 1,
  "updated_count": 0,
  "skipped_count": 0,
  "error_count": 0,
  "errors": [],
  "requisition_ids": [1234]
}

Documentación API

API Pública de Sourced v1

Autenticación

URL Base

Límites de tasa

Errores

Ejemplos de errores

Health Check

Importar requisiciones

Cuerpo de la solicitud

Objeto Requisición

Objeto Item

Objeto Especificaciones

Objeto Adjunto

Lógica de deduplicación

Respuesta

ERPImportResult

Listar requisiciones

Parámetros de consulta

Detalle de requisición

Verificar requisiciones existentes

Cuerpo de la solicitud

Cancelar requisición

Respuestas posibles:

Listar órdenes de compra

Parámetros de consulta

Detalle de orden de compra

Objeto Orden de Compra

Objeto Item de OC

Actualizar estado de orden de compra

Listar proveedores

Parámetros de consulta

Crear proveedor

Cuerpo de la solicitud

Referencia de esquemas

Estados de requisición

Estados de orden de compra

Códigos de referencia

Monedas

Tipos de pago (payment_terms_code)

Unidades de medida

Flujo de integración

Recopilar nuevas requisiciones del ERP

Verificar existentes (opcional)

Importar requisiciones

Consultar órdenes de compra nuevas

Confirmar OC aprobadas

Ejemplo completo