Versionamento da API

A API de Integrações usa versionamento via header customizado, garantindo que integrações existentes continuem funcionando quando novas versões forem lançadas.

Como usar

Envie o header api-version em suas requisições:

curl -H "Authorization: Bearer <token>" \
  -H "api-version: v1" \
  https://api.biterp.ai/products

Comportamento

Versões disponíveis

Boas práticas

1. Sempre envie o header: mesmo que a versão padrão funcione hoje, enviar explicitamente protege sua integração contra mudanças futuras
2. Teste antes de migrar: quando uma nova versão for lançada, teste sua integração antes de atualizar o header
3. Monitore deprecações: versões antigas serão depreciadas com antecedência

Exemplo de erro

Quando uma versão inválida é enviada, a resposta é 400 Bad Request com as versões aceitas:

{
    "status_code": 400,
    "message": "Invalid api-version. Accepted: v1. Current: v1",
    "error": "Bad Request"
}

Changelog (breaking changes em v1)

Mudanças de contrato na versão atual (v1) são documentadas aqui. Integrações que dependem de campos removidos devem buscar o dado no recurso dedicado (ex.: GET /customers/{id}).

2026-08 — customer embutido em orçamentos (GET /quotes, GET /quotes/{id})

O objeto customer aninhado nas respostas de listagem e detalhe de orçamentos foi reduzido para alinhar com pedidos de venda e notas: apenas identificação mínima do cliente, sem dados bancários, de contato ou de endereço.

Antes (~17 campos):

{
    "customer": {
        "id": "8f2c1e4a-9b3d-4c7e-a1f2-6d5b8e0c3a71",
        "type": "company",
        "tax_id": "12345678000195",
        "tax_id_type": "cnpj",
        "legal_name": "ACME Comércio Ltda",
        "trade_name": "ACME",
        "website": "https://acme.example",
        "address_line1": "Rua das Flores, 100",
        "address_line2": "Sala 12",
        "city": "São Paulo",
        "state": "SP",
        "postal_code": "01310100",
        "country_code": "BR",
        "is_blocked": false,
        "metadata": { "erp_code": "C-001" },
        "created_at": "2026-01-15T10:00:00.000Z",
        "updated_at": "2026-06-01T14:30:00.000Z"
    }
}

Depois (4 campos):

{
    "customer": {
        "id": "8f2c1e4a-9b3d-4c7e-a1f2-6d5b8e0c3a71",
        "legal_name": "ACME Comércio Ltda",
        "trade_name": "ACME",
        "tax_id": "12345678000195"
    }
}

Campos removidos do objeto embutido: type, tax_id_type, website, address_line1, address_line2, city, state, postal_code, country_code, is_blocked, metadata, created_at, updated_at.

O customer_id no corpo do orçamento não muda. Para o cadastro completo, use GET /customers/{id}. Detalhes no guia de orçamentos.