Fornecedores

O recurso Fornecedores (/suppliers) mantém o cadastro de fornecedores do tenant. Ele é o espelho de Clientes: a mesma estrutura de pessoa física/jurídica, tax_id, contatos, dados bancários e extensões por país (br_data, us_data). Fornecedores são a ponta de origem do fluxo de compras — notas de compra e contas a pagar.

Permissão exigida: suppliers (ações create, read, update, delete).

Conceitos e campos-chave

A estrutura é idêntica à de clientes, com duas diferenças que valem atenção:

1. country_code é obrigatório e deve ser ISO2 (ex.: BR, US). Em clientes ele é opcional e aceita vários formatos; aqui é obrigatório e restrito ao código de duas letras.
2. Sem resolução de cidade/estado por texto. Fornecedores aceitam apenas city_id e state_id (IDs do catálogo, obtidos via Dados de referência) — não há campos city/state de texto livre.

O tax_id segue a mesma regra de Clientes: normalizado (pontuação ignorada) e sem validação de dígitos verificadores. Na resposta, o país vem como country_code (string), e city/state como objetos resolvidos.

Criar um fornecedor

curl -X POST https://api.biterp.ai/suppliers \
  -H "Authorization: Bearer sk_abc123_secretXYZ" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "company",
    "tax_id": "98.765.432/0001-10",
    "tax_id_type": "CNPJ",
    "legal_name": "Fornecedora Industrial S.A.",
    "trade_name": "FornInd",
    "country_code": "BR",
    "emails": ["compras@fornind.com.br"],
    "address_line1": "Rua da Indústria, 500",
    "postal_code": "04500-000",
    "state_id": 26,
    "city_id": 5270,
    "br_data": {
      "ie": "111222333444",
      "cnae_primary": "4671100",
      "pix_key": "98765432000110",
      "pix_key_type": "cnpj"
    }
  }'

state_id e city_id devem ser IDs reais do catálogo bitERP. Obtenha-os pelos endpoints de estados e cidades em Dados de referência.

Buscar fornecedores

Além da listagem paginada (GET /suppliers, com filtros e paginação):

Campos filtráveis em GET /suppliers: legal_name, trade_name, tax_id, type, city, state, country_code, is_active, reference_code, tags, created_at, updated_at. Ordenação por id, legal_name, trade_name, reference_code, created_at, updated_at.

Remover

DELETE /suppliers/{id} faz soft delete e responde 204 No Content.

Referência dos endpoints