API da Sourced — Referência v1

API Pública Sourced v1

A API Sourced permite que sistemas ERP (como Calipso, SAP, JD Edwards) se integrem diretamente com a plataforma de compras da Sourced. Use-a para:

Enviar requisições de compra do seu ERP para o Sourced
Obter ordens de compra de volta no seu ERP após adjudicação
Verificar quais requisições já foram sincronizadas
Monitorar o status das suas requisições

A API segue as convenções REST, utiliza JSON para os corpos de solicitação e resposta, e se autentica via API keys.

Autenticação

Todos os endpoints (exceto health check) requerem uma API key enviada no header .

As API keys são criadas no painel de administração do Sourced em . Cada key é exibida apenas uma vez ao ser criada. Armazene-a com segurança.

Exemplo: Solicitação autenticada

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

Segurança: Trate sua API key como uma senha. Não a exponha em código do lado do cliente, repositórios públicos ou logs. Se comprometida, revogue-a imediatamente no painel de administração e crie uma nova.

URL Base

Ambiente	URL Base
Produção	https://api.gosourced.ai
Desenvolvimento	https://api-dev.gosourced.ai

Todos os endpoints são prefixados com .

Limites de taxa

Todos os endpoints são limitados a por endpoint. Exceder este limite retorna uma resposta .

Para operações em massa, use o endpoint de importação em lote () que aceita até 100 requisições por solicitação.

Erros

A API utiliza códigos de status HTTP padrão. Erros retornam um corpo JSON com um campo .

Formato de resposta de erro

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

Status	Significado
200	Sucesso
400	Solicitação inválida — erro de validação ou corpo malformado
401	Não autorizado — API key ausente ou inválida
404	Não encontrado — o recurso não existe ou não é acessível
422	Entidade não processável — o corpo da solicitação não passou na validação do esquema
429	Muitas solicitações — limite de taxa excedido
500	Erro interno do servidor — erro inesperado do nosso lado

Exemplos de erros

401 — API key inválida

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

422 — Erro de validação (ex: campo obrigatório ausente)

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

200 — Sucesso parcial (algumas requisições falharam)

{
  "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: o endpoint retorna mesmo com falhas parciais. Sempre verifique o campo e o array para detectar problemas por requisição.

Health Check

GET/api/v1/health

Verificar se a API está acessível. Não requer autenticação.

Solicitação

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

Resposta — 200 OK

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

Importar requisições

POST/api/v1/requisitionsAPI Key obrigatória

Importar uma ou mais requisições de compra do seu ERP. Suporta importação em lote de até 100 requisições por solicitação. Usa external_id para deduplicação.

Corpo da solicitação

O corpo deve conter um array com 1 a 100 objetos de requisição.

Objeto Requisição

Campo	Tipo	Obrigatório	Descrição
external_id	string	obrigatório	ID único no seu ERP (chave de deduplicação). Máx 250 caracteres.
items	array	obrigatório	Itens de linha (1-200 itens). Veja o esquema de Item abaixo.
requester_name	string	opcional	Nome da pessoa solicitante. Máx 200 caracteres.
requester_email	string	opcional	Email do solicitante. Máx 200 caracteres.
description	string	opcional	Título ou resumo da requisição. Máx 500 caracteres.
comments	string	opcional	Instruções adicionais para compradores (HTML suportado). Máx 15.000 caracteres.
delivery_address	string	opcional	Endereço de entrega em texto livre. Máx 500 caracteres.
delivery_address_code	string	opcional	Código correspondente a um endereço configurado no Sourced. Máx 50 caracteres.
desired_delivery_lead_time_days	integer	opcional	Prazo de entrega desejado em dias a partir da confirmação da OC. Aplicado como padrão a todos os itens.
offer_deadline	datetime	opcional	Data limite para cotações de fornecedores (ISO 8601).
total_estimated_value	float	opcional	Valor total estimado. Calculado automaticamente a partir dos itens se omitido.
currency	string	opcional	Código da moeda (ex: "ARS", "USD"). Padrão "ARS". Máx 10 caracteres.
department_code	string	opcional	Código de departamento/centro de custo (comparado com departamentos do Sourced). Máx 50 caracteres.
priority_level	string	opcional	Prioridade: "LOW", "MEDIUM", "HIGH" ou "CRITICAL".
attachments	array	opcional	Anexos de arquivo (máx 20). Veja o esquema de Anexo abaixo.
raw_data	object	opcional	JSON arbitrário do seu ERP, armazenado para rastreabilidade.

Objeto Item

Campo	Tipo	Obrigatório	Descrição
description	string	obrigatório	Nome ou descrição do item. Máx 1.000 caracteres.
quantity	float	obrigatório	Quantidade necessária (deve ser > 0).
external_line_id	string	opcional	ID de linha no seu ERP (ex: "REQ-001-L10"). Retornado nas OC para rastreabilidade. Máx 100 caracteres.
unit_of_measure	string	opcional	Código de UOM (ex: "KG", "EA", "LT", "M", "UN"). Comparado com o catálogo da sua org. Máx 50 caracteres.
target_price	float	opcional	Preço alvo/orçamento por unidade.
estimated_price	float	opcional	Preço total estimado para esta linha.
currency	string	opcional	Moeda para preços (ex: "ARS", "USD"). Máx 10 caracteres.
category	string	opcional	Categoria do seu ERP. Máx 200 caracteres.
material_code	string	opcional	Código de material/peça no seu ERP (ex: código de material SAP). Máx 100 caracteres.
specifications	object	opcional	Especificações técnicas. Veja o esquema de Especificações abaixo.
desired_delivery_date	datetime	opcional	Data de entrega desejada para este item (ISO 8601, ex: "2026-05-15T00:00:00Z").
desired_delivery_lead_time_days	integer	opcional	Prazo de entrega desejado em dias para esta linha. Sobrescreve o valor a nível de cabeçalho.
detail	string	opcional	Notas adicionais para esta linha. Máx 1.000 caracteres.
raw_data	object	opcional	JSON arbitrário para este item.

Objeto Especificações

Campo	Tipo	Obrigatório	Descrição
manufacturer_code	string	opcional	Número de peça do fabricante (ex: "6ES7214-1AG40-0XB0"). Máx 100 caracteres.
manufacturer_name	string	opcional	Nome do fabricante (ex: "Siemens"). Máx 200 caracteres.
manufacturer_description	string	opcional	Descrição do fabricante. Máx 500 caracteres.
buyer_code	string	opcional	Código interno no seu sistema (ex: "MAT-001234"). Máx 100 caracteres.
buyer_code_description	string	opcional	Descrição do código interno. Máx 500 caracteres.
buyer_code_system	string	opcional	Nome do sistema de origem (ex: "SAP", "Calipso"). Máx 50 caracteres.
technical_specs	string	opcional	Especificações técnicas em texto livre (ex: "220V, 50Hz, IP55"). Máx 2.000 caracteres.
requirements	string	opcional	Requisitos adicionais (ex: "Certificação ISO 9001 obrigatória"). Máx 2.000 caracteres.

Objeto Anexo

Campo	Tipo	Obrigatório	Descrição
url	string	obrigatório	URL publicamente acessível para baixar o arquivo. Máx 2.000 caracteres.
filename	string	obrigatório	Nome do arquivo original (ex: "plano_motor.pdf"). Máx 255 caracteres.
description	string	opcional	Descrição do anexo. Máx 500 caracteres.
file_type	string	opcional	Tipo MIME (detectado automaticamente se não fornecido). Máx 100 caracteres.

Lógica de deduplicação

Cada requisição é identificada pelo seu (dentro do escopo da sua organização):

Nova: Se nenhuma requisição existente for encontrada, uma nova é criada com status .
Atualizar: Se uma requisição existente com status for encontrada, ela é atualizada in-place (os itens são totalmente substituídos).
Superseder: Se uma requisição existente com status for encontrada, ela é reativada (volta para PENDING) com os novos dados.
Lançada: Se a requisição já foi lançada como Solicitação de Compra (), a importação é rejeitada. A PR ativa não pode ser sobrescrita.
Descartada: Se a requisição foi descartada anteriormente (), ela é reativada (volta para PENDING) com os novos dados. Útil quando o ERP a cancela e depois a reenvia.

Solicitação — Exemplo 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
          }
        ]
      }
    ]
  }'

Resposta

ERPImportResult

Campo	Tipo	Obrigatório	Descrição
success	boolean	obrigatório	true se error_count for 0.
created_count	integer	obrigatório	Número de novas requisições criadas.
updated_count	integer	obrigatório	Número de requisições PENDING existentes atualizadas.
skipped_count	integer	obrigatório	Número de requisições ignoradas (atualmente sempre 0).
error_count	integer	obrigatório	Número de requisições que falharam ao importar.
errors	array	obrigatório	Array de {index, external_id, error} para cada requisição que falhou.
requisition_ids	array	obrigatório	IDs internos do Sourced das requisições criadas/atualizadas.

Resposta — 200 OK

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

Listar requisições

GET/api/v1/requisitionsAPI Key obrigatória

Obter uma lista paginada das suas requisições importadas. Retorna apenas requisições criadas via API.

Parâmetros de consulta

Campo	Tipo	Obrigatório	Descrição
page	integer	opcional	Número da página (padrão: 1).
page_size	integer	opcional	Itens por página, 1-100 (padrão: 20).
status	string	opcional	Filtrar por status: "PENDING", "LAUNCHED", "DISCARDED", "SUPERSEDED".

Solicitação

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

Resposta — 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
}

Detalhe da requisição

GET/api/v1/requisitions/{requisition_id}API Key obrigatória

Obter uma requisição individual pelo seu ID interno do Sourced, incluindo todos os itens.

Solicitação

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

Retorna o objeto completo da requisição. Retorna se não encontrada ou não pertencente à sua organização.

Verificar requisições existentes

POST/api/v1/requisitions/check-existingAPI Key obrigatória

Verificar quais external_ids já existem no Sourced antes de importar. Útil para evitar chamadas desnecessárias à API.

Corpo da solicitação

Campo	Tipo	Obrigatório	Descrição
external_ids	array	obrigatório	Lista de strings external_id para verificar (1-100 itens).

Solicitação

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"]
  }'

Resposta — 200 OK

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

Cancelar requisição

POST/api/v1/requisitions/cancelAPI Key obrigatória

Cancelar uma requisição PENDING enviando o external_id no corpo da requisição.

Apenas requisições com status podem ser canceladas. Se a requisição já foi lançada como Solicitação de Compra, deve ser cancelada dentro do Sourced.

Campo	Tipo	Obrigatório	Descrição
external_id	string	obrigatório	O ID da requisição no seu sistema externo (o mesmo usado na importação)
reason	string	opcional	Motivo do cancelamento (armazenado para auditoria)

Solicitação

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"
  }'

Resposta — 200 OK

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

Respostas possíveis:

discarded — A requisição foi descartada com sucesso.
already_discarded — A requisição já estava descartada (idempotente).
already_superseded — A requisição já foi substituída por uma versão mais nova.
A requisição já foi lançada — retorna com detalhes.
Requisição não encontrada — retorna .

Listar ordens de compra

GET/api/v1/purchase-ordersAPI Key obrigatória

Obter ordens de compra da sua organização. Suporta sincronização incremental através do parâmetro 'since'.

Parâmetros de consulta

Campo	Tipo	Obrigatório	Descrição
page	integer	opcional	Número da página (padrão: 1).
page_size	integer	opcional	Itens por página, 1-100 (padrão: 20).
status	string	opcional	Filtrar por status: "DRAFT", "CREATED", "SENT", "CONFIRMED", "REJECTED", "CANCELLED".
since	datetime	opcional	Timestamp ISO 8601. Retorna apenas OC criadas ou atualizadas após esta data.
requisition_external_id	string	opcional	Filtrar pelo external_id da requisição original no seu ERP. Retorna as OC geradas a partir dessa requisição.

Solicitação — Sincronização 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"

Resposta — 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
}

Detalhe da ordem de compra

GET/api/v1/purchase-orders/{po_id}API Key obrigatória

Obter uma ordem de compra individual pelo seu ID interno do Sourced, incluindo todos os itens de linha com rastreabilidade de volta ao seu ERP via external_line_id.

Solicitação

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

Procurando OCs pelo ID da requisição do seu sistema?

Este endpoint requer o ID interno do Sourced (). Se você precisa buscar ordens de compra usando o ID de requisição do seu ERP, use o endpoint com o query parameter :

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

Você também pode combinar com outros filtros: para filtrar por status da OC, para sincronização incremental, e / para paginação.

Objeto Ordem de Compra

Campo	Tipo	Obrigatório	Descrição
id	integer	obrigatório	ID interno da OC no Sourced.
code	string	obrigatório	Código legível da OC.
status	string	obrigatório	Status da OC: "DRAFT", "CREATED", "SENT", "CONFIRMED", "REJECTED", "CANCELLED".
award_type	string	opcional	Tipo de adjudicação: FULL (fornecedor único) ou PARTIAL (adjudicação dividida entre múltiplos fornecedores).
supplier_name	string	obrigatório	Nome do fornecedor.
supplier_id	integer	opcional	ID interno do fornecedor no Sourced.
total_price	float	opcional	Valor total da OC.
currency	string	opcional	Código da moeda.
delivery_address	string	opcional	Endereço de entrega.
delivery_address_code	string	opcional	Código do endereço de entrega da organização vinculado (ex. "001"). Use-o para mapear o destino no seu ERP. Null para endereços de texto livre sem registro vinculado.
observations	string	opcional	Comentários ou observações em texto livre inseridos pelo comprador na etapa de revisão pré-adjudicação. Usa as condições especiais cotadas pelo fornecedor quando o comprador não deixou nota. Null quando não há nenhuma.
delivery_lead_time_days	integer	opcional	Prazo de entrega em dias, conforme cotado pelo fornecedor a nível de cabeçalho. Quando o fornecedor cota prazos diferentes por linha, os itens podem ter valores distintos — use items[].delivery_lead_time_days para o valor por linha.
expected_delivery_date	datetime	opcional	Data de entrega calculada (awarded_at + delivery_lead_time_days). Null se faltar qualquer um dos dois. Para datas por linha use items[].expected_delivery_date.
payment_terms_code	string	opcional	Código das condições de pagamento.
awarded_at	datetime	opcional	Quando a OC foi adjudicada (ISO 8601).
awarded_by_name	string	opcional	Nome do usuário que adjudicou a OC.
awarded_by_email	string	opcional	Email do usuário que adjudicou a OC.
created_at	datetime	opcional	Timestamp de criação (ISO 8601).
updated_at	datetime	opcional	Timestamp da última atualização (ISO 8601).
purchase_request_id	integer	opcional	ID da solicitação de compra originária.
requisition_external_id	string	opcional	ID do documento de origem no seu ERP (ex. número de requisição em Calipso/SAP/JDE). Resolvido a partir da ERPRequisition de origem quando disponível; caso contrário, recorre ao external_id da PR. Pode ser uma lista separada por vírgulas quando uma única PR agrega múltiplas requisições de origem.
exchange_rate_data	object	opcional	Taxas de câmbio no momento do award. Formato: {"date": "2026-03-05", "usdToArs": 1450.0, "arsToUsd": 0.00069}. Null se não houver dados disponíveis.
total_nominal_savings	float	opcional	Economia nominal total vs preços históricos (sem ajuste por inflação).
total_real_savings	float	opcional	Economia real total vs preços históricos (ajustada por inflação).
savings_currency	string	opcional	Moeda dos valores de economia.
items	array	obrigatório	Itens de linha da OC. Veja o esquema de Item de OC abaixo.

Objeto Item de OC

Campo	Tipo	Obrigatório	Descrição
description	string	obrigatório	Descrição do item.
quantity	float	opcional	Quantidade pedida.
unit_price	float	opcional	Preço por unidade.
total_price	float	opcional	Preço total da linha (quantidade x preço unitário).
unit_of_measure	string	opcional	Unidade de medida.
currency	string	opcional	Código da moeda.
delivery_lead_time_days	integer	opcional	Prazo de entrega em dias para esta linha, conforme cotado pelo fornecedor. Itens diferentes da mesma OC podem ter prazos distintos.
expected_delivery_date	datetime	opcional	Data de entrega calculada para esta linha (PO.awarded_at + delivery_lead_time_days do item). Null se faltar qualquer um dos dois.
external_line_id	string	opcional	ID de linha original do seu ERP — use para vincular itens da OC às suas linhas de requisição.
manufacturer_code	string	opcional	Número de peça do fabricante.

Sobre datas e prazos de entrega

O prazo de entrega existe em dois níveis: a nível de cabeçalho (reflete o prazo geral cotado pelo fornecedor) e a nível de linha (preciso por item). Quando o fornecedor cota prazos diferentes por linha, prefira o valor por linha.
é um campo calculado: . O Sourced calcula; o fornecedor não envia uma data diretamente.
Se for null, também será null. Isso normalmente significa que o fornecedor não incluiu o prazo na cotação.

Atualizar status da ordem de compra

POST/api/v1/purchase-orders/{po_id}/statusAPI Key obrigatória

Atualizar o status de uma ordem de compra para refletir seu progresso no seu sistema externo (ERP).

Transições de status permitidas:

De	Para	Significado
DRAFT	CREATED	A OC foi criada no seu ERP.
CREATED	CONFIRMED	A OC foi totalmente aprovada no seu ERP.
DRAFT	CONFIRMED	Atalho quando não é necessário o passo intermediário.
DRAFT	REJECTED	A OC foi rejeitada no seu ERP. A PR é reaberta no Sourced.
CREATED	REJECTED	A OC foi rejeitada no seu ERP após ter sido criada. A PR é reaberta no Sourced.
DRAFT / CREATED / SENT / CONFIRMED	CANCELLED	A compra não vai acontecer. A OC é cancelada e a PR também — nada é reaberto. Use REJECTED se a necessidade ainda existir e você quiser readjudicar.

Campo	Tipo	Obrigatório	Descrição
status	string	obrigatório	Status destino: CREATED (OC criada no seu ERP), CONFIRMED (OC aprovada no seu ERP), REJECTED (OC rejeitada, reabre a PR) ou CANCELLED (compra cancelada, cancela a OC e a PR).
external_id	string	opcional	Número ou código da OC no seu ERP (ex: OC-CAL-00045678). Armazenado para rastreabilidade.
notes	string	opcional	Notas opcionais sobre a mudança de status.

Solicitação

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"
  }'

Resposta — 200 OK

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

Listar fornecedores

GET/api/v1/suppliersAPI Key obrigatória

Listar os fornecedores da sua organização. Use ?has_erp_code=false para encontrar fornecedores sem mapear. Use ?detail=full para contatos, categorias e cobertura.

Parâmetros de consulta

Campo	Tipo	Obrigatório	Descrição
page	integer	opcional	Número da página (padrão: 1).
page_size	integer	opcional	Resultados por página (1-200, padrão: 50).
search	string	opcional	Buscar por nome, nome personalizado, email, CNPJ/CUIT ou código ERP.
erp_code	string	opcional	Filtrar por código ERP exato.
has_erp_code	boolean	opcional	true = apenas mapeados ao ERP, false = apenas sem mapear.
detail	string	opcional	Use 'full' para incluir contatos, categorias e cobertura.

Solicitação

# 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"

Resposta — 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
}

Criar fornecedor

POST/api/v1/suppliersAPI Key obrigatória

Criar um fornecedor para sua organização. Pelo menos um de tax_id ou erp_code é obrigatório. Pelo menos um contato com papel 'sales' é obrigatório. Se já existir um fornecedor global com o mesmo CNPJ/CUIT, ele é reutilizado e vinculado à sua organização.

Corpo da solicitação

Campo	Tipo	Obrigatório	Descrição
name	string	obrigatório	Nome do fornecedor para sua organização.
tax_id	string	opcional	CNPJ, CUIT, RUT, etc. Pelo menos um de tax_id ou erp_code é obrigatório.
erp_code	string	opcional	Código do fornecedor no seu ERP. Pelo menos um de tax_id ou erp_code é obrigatório.
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 (ex: AR, BR, US).
city	string	opcional	Cidade do fornecedor.
address	string	opcional	Endereço completo.
state_code	string	opcional	Estado/província (ex: SP, RJ).
website	string	opcional	Site do fornecedor.
contacts	array	obrigatório	Lista de contatos. Pelo menos um com papel 'sales' é obrigatório.
contacts[].name	string	obrigatório	Nome do contato.
contacts[].email	string	obrigatório	Email do contato.
contacts[].phone	string	opcional	Telefone (opcional).
contacts[].role	string	obrigatório	Papel: SALES ou LOGISTICS.
contacts[].is_primary	boolean	opcional	true se for o contato principal (padrão: false).

Solicitação

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"
      }
    ]
  }'

Resposta — 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": []
}

Referência de esquemas

Referência rápida de todos os esquemas de solicitação/resposta usados nos endpoints.

Status de requisição

Status	Descrição
PENDING	Importada, aguardando revisão de um comprador no Sourced.
LAUNCHED	O comprador lançou a requisição como Solicitação de Compra.
DISCARDED	A requisição foi descartada manualmente.
SUPERSEDED	Uma versão mais nova foi importada com o mesmo external_id.

Status de ordem de compra

Status	Descrição
DRAFT	OC criada no Sourced, pendente de sincronização com o ERP externo.
CREATED	OC criada no ERP externo, pendente de aprovação.
CONFIRMED	OC totalmente aprovada no ERP externo.
REJECTED	OC rejeitada no ERP externo. A PR associada é reaberta automaticamente.
CANCELLED	Compra cancelada. A OC é cancelada e a PR associada também — nada é reaberto.

Em breve serão adicionados estados adicionais como RECEIVED (mercadoria recebida), INVOICED (faturada), entre outros, para refletir o ciclo de vida completo da ordem de compra.

Códigos de referência

Catálogos de moedas e tipos de pagamento aceitos pela API. Use-os para mapear esses valores com os códigos equivalentes no seu ERP.

Moedas

O Sourced não usa um enum fechado de moedas: qualquer código ISO 4217 válido de 3 letras é aceito. As moedas mais utilizadas pelos nossos clientes são:

Código	Moeda
ARS	Peso argentino
USD	Dólar americano
EUR	Euro
BRL	Real brasileiro

Envie o código ISO 4217 diretamente no campo currency (ex: "currency": "EUR"). O Sourced o persiste como está e o devolve igual nas respostas.

Tipos de pagamento (payment_terms_code)

Catálogo global de condições de pagamento disponíveis no Sourced. Use o código (coluna Code) no campo payment_terms_code da PO. O campo type indica a natureza do pagamento: IMMEDIATE (no recebimento), ADVANCE (antecipado), NET_DAYS (a X dias da fatura).

Código	Nome	Tipo	Dias	Descrição
COD	Cash On Delivery	IMMEDIATE	0	Pagamento contra entrega
IMM	Immediate Payment	IMMEDIATE	0	Pagamento imediato / À vista
ADV100	Advance Payment	ADVANCE	0	Pagamento antecipado 100%
ADV50	Advance 50%	ADVANCE	0	Pagamento antecipado de 50%
NET7	Net 7 Days	NET_DAYS	7	Pagamento em 7 dias da data da fatura
NET10	Net 10 Days	NET_DAYS	10	Pagamento em 10 dias da data da fatura
NET15	Net 15 Days	NET_DAYS	15	Pagamento em 15 dias da data da fatura
NET20	Net 20 Days	NET_DAYS	20	Pagamento em 20 dias da data da fatura
NET21	Net 21 Days	NET_DAYS	21	Pagamento em 21 dias da data da fatura
NET30	Net 30 Days	NET_DAYS	30	Pagamento em 30 dias da data da fatura
EOM30	End of Month + 30	NET_DAYS	30	Pagamento no fim do mês mais 30 dias
NET35	Net 35 Days	NET_DAYS	35	Pagamento em 35 dias da data da fatura
NET40	Net 40 Days	NET_DAYS	40	Pagamento em 40 dias da data da fatura
NET45	Net 45 Days	NET_DAYS	45	Pagamento em 45 dias da data da fatura
NET60	Net 60 Days	NET_DAYS	60	Pagamento em 60 dias da data da fatura
NET75	Net 75 Days	NET_DAYS	75	Pagamento em 75 dias da data da fatura
NET90	Net 90 Days	NET_DAYS	90	Pagamento em 90 dias da data da fatura

O catálogo é global em toda a plataforma e raramente muda. Se você precisar de um código adicional para sua integração, entre em contato.

Unidades de medida

Códigos de unidade de medida aceitos em itens de requisições. Enviados no campo unit_of_measure.

Código	Unidade
EA	Unidade
PCS	Peças
KG	Quilograma
G	Grama
LB	Libra
OZ	Onça
M	Metro
CM	Centímetro
MM	Milímetro
IN	Polegada
FT	Pé
YD	Jarda
L	Litro
ML	Mililitro
GAL	Galão
QT	Quarto de galão
PT	Pinta
FL_OZ	Onça líquida
M2	Metro quadrado
CM2	Centímetro quadrado
FT2	Pé quadrado
IN2	Polegada quadrada
YD2	Jarda quadrada
M3	Metro cúbico
CM3	Centímetro cúbico
FT3	Pé cúbico
IN3	Polegada cúbica
YD3	Jarda cúbica
BOX	Caixa
CASE	Caixa/Estojo
PACK	Pacote
SET	Jogo
KIT	Kit
BUNDLE	Fardo
ROLL	Rolo
SHEET	Folha/Lâmina
PALLET	Palete
DRUM	Tambor/Barril
BAG	Saco
BOTTLE	Garrafa
CEN	Centena

Se você enviar uma unidade não reconhecida, ela é armazenada como está. Recomendamos usar os códigos padrão para que a IA possa normalizar corretamente as cotações dos fornecedores.

Fluxo de integração

Padrão de integração típico para uma sincronização ERP agendada (ex: cron job a cada 15 minutos):

Coletar novas requisições do ERP

Consultar seu ERP por requisições aprovadas que ainda não foram sincronizadas com o Sourced.

Verificar existentes (opcional)

Chamar POST /requisitions/check-existing com external_ids para filtrar requisições já sincronizadas.

Importar requisições

Chamar POST /requisitions com o lote de requisições novas/atualizadas. Armazenar os requisition_ids retornados.

Consultar novas ordens de compra

Chamar GET /purchase-orders?since={last_sync_timestamp}&status=DRAFT para obter OC novas. Criar a OC no seu ERP e chamar POST /purchase-orders/{id}/status com {"status": "CREATED"}.

Confirmar OCs aprovadas

Quando a OC for aprovada no seu ERP, chamar POST /purchase-orders/{id}/status com {"status": "CONFIRMED"} para fechar o ciclo.

Pseudocódigo — Cron job de sincronização

# 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"

Exemplo completo

Uma solicitação de importação realista com todos os campos disponíveis preenchidos:

Solicitação de importação 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"
        }
      }
    ]
  }'

Resposta — 200 OK

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

Documentação API

API Pública Sourced v1

Autenticação

URL Base

Limites de taxa

Erros

Exemplos de erros

Health Check

Importar requisições

Corpo da solicitação

Objeto Requisição

Objeto Item

Objeto Especificações

Objeto Anexo

Lógica de deduplicação

Resposta

ERPImportResult

Listar requisições

Parâmetros de consulta

Detalhe da requisição

Verificar requisições existentes

Corpo da solicitação

Cancelar requisição

Respostas possíveis:

Listar ordens de compra

Parâmetros de consulta

Detalhe da ordem de compra

Objeto Ordem de Compra

Objeto Item de OC

Atualizar status da ordem de compra

Listar fornecedores

Parâmetros de consulta

Criar fornecedor

Corpo da solicitação

Referência de esquemas

Status de requisição

Status de ordem de compra

Códigos de referência

Moedas

Tipos de pagamento (payment_terms_code)

Unidades de medida

Fluxo de integração

Coletar novas requisições do ERP

Verificar existentes (opcional)

Importar requisições

Consultar novas ordens de compra

Confirmar OCs aprovadas

Exemplo completo