UEBON — Documentação da API

Introdução

Referência dos endpoints REST da Uebon. Prefixo comum: /api.

https://app.uebon.com/api

Fluxo recomendado: obter token → consultar tabelas gerais (séries, armazéns, tipos de documento) → criar ou pesquisar terceiros/artigos → emitir documento → obter PDF.

Secções

Autenticação — OAuth / Bearer token
Consulta v1 — account, options, IVA, terceiros, artigos
Escrita v1 — criar terceiros, artigos, documentos, PDF
Integração BI — exportação em massa (id encriptado da conta)

Autenticação

Endpoints protegidos exigem Authorization: Bearer {access_token}.

Obter token OAuth

O par client_id / client_secret é enviado pela Uebon ao activar o acesso API.

POST https://app.uebon.com/oauth/token
Content-Type: application/json

{
  "client_id": "{client_id}",
  "client_secret": "{client_secret}",
  "username": "[email protected]",
  "password": "sua_password",
  "grant_type": "password"
}

GET `/api/v1/auth/validate-token` auth

Confirma se o token é válido.

{ "data": "Token is valid" }

POST `/api/login`

POST `/api/v1/register`

Registo de nova conta.

GET `/api/v1/auth/user` auth

Utilizador autenticado.

POST `/api/v1/auth/logout` auth

Revoga o token actual.

GET `/api/user` auth

Dados do utilizador (alias).

Consulta autenticada (v1)

Tabelas gerais e referência da conta. Mesma lógica dos endpoints web.

Ir para: Conta Options Docs ref. Terceiros Artigos

GET `/api/v1/account`

Dados da conta (empresa, país, moeda, decimais). Equivalente a POST /account.

GET `/api/v1/options/{type}`

Séries, armazéns, pagamentos, etc. Equivalente a POST /options/{type}.

type	Descrição
`series`	Séries
`armazem`	Armazéns
`prazos_vencimento`	Prazos vencimento
`metodos_pagamento`	Pagamentos
`metodo_expedicao`	Expedição
`viaturas`	Viaturas
`impostos_taxas`	Impostos/taxas
`retencoes`	Retenções
`unidades_de_medida`	Unidades

GET https://app.uebon.com/api/v1/options/armazem
Authorization: Bearer {access_token}

GET `/api/v1/documents/types/{tipo}/{categoria?}`

Tipos de documento. tipo: venda, compra, stocks. categoria (opcional): documentos, guias…

GET https://app.uebon.com/api/v1/documents/types/venda/documentos
GET https://app.uebon.com/api/v1/documents/types/compra/documentos

GET `/api/v1/tax-rates/{country}` · `/api/v1/exemptions`

Taxas IVA (tax_info) e motivos de isenção.

GET https://app.uebon.com/api/v1/tax-rates/PT
GET https://app.uebon.com/api/v1/exemptions

GET `/api/v1/documents/last-date`

Data do último documento terminado (sequência temporal).

GET `/api/v1/clients` · `POST …/search` · `GET …/next-code`

Lista paginada (?page=1), pesquisa e código disponível.

POST https://app.uebon.com/api/v1/clients/search
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "search": "Empresa",
  "tipo": ["cliente", "ambos"],
  "visivel": true
}

GET `/api/v1/products` · `POST …/search` · `GET …/next-code`

Lista paginada (?page=1, ?armazem_id=1), pesquisa e código disponível.

Escrita autenticada (v1)

Criar terceiros, artigos e documentos; obter PDF. Respeita permissões da aplicação web.

POST `/api/v1/clients`

Cria terceiro. Equivalente a POST /clients/create.

Campo	Obr.	Descrição
`empresa`	sim	Denominação
`codigo`	sim	Código interno
`nif`	sim	NIF (mín. 5 chars)
`codigo_postal`	sim	Código postal
`tipo`	não	cliente \| fornecedor \| ambos

POST https://app.uebon.com/api/v1/clients
Authorization: Bearer {access_token}

{
  "empresa": "Empresa Exemplo Lda",
  "codigo": "CLI001",
  "nif": "123456789",
  "codigo_postal": "1000-001",
  "cidade": "Lisboa",
  "pais": "PT",
  "tipo": "cliente"
}

POST `/api/v1/products`

POST https://app.uebon.com/api/v1/products
Authorization: Bearer {access_token}

{
  "descricao": "Artigo exemplo",
  "tipo": "produto",
  "codigo": "ART001",
  "preco_sem_iva": 10.00,
  "iva": 5,
  "unidade_de_medida": 1
}

POST `/api/v1/documents`

Emite documento. Equivalente a POST /documents/create.

POST https://app.uebon.com/api/v1/documents
Authorization: Bearer {access_token}

{
  "client_id": 42,
  "serie_id": 1,
  "document_id": 3,
  "armazem_id": 1,
  "terminado": 1,
  "data": "2025-05-30 12:00:00",
  "total": 123.00,
  "products": [
    {
      "id": 10,
      "quantidade": 1,
      "valor": 100.00,
      "imposto": 5,
      "descricao": "Artigo exemplo"
    }
  ]
}

GET `/api/v1/documents/{id}/pdf`

PDF de impressão. Equivalente a GET /documents/open/{id}.

GET https://app.uebon.com/api/v1/documents/123/pdf
Authorization: Bearer {access_token}
Accept: application/pdf

Integração BI (leitura)

Exportação em massa sem token Bearer — usa {id} encriptado da conta. Limite: 10 req/min.

O {id} é fornecido no painel de integrações ou pelo suporte Uebon.

Artigos Terceiros Documentos

curl -s "https://app.uebon.com/api/bi/products/{id_encriptado}" -H "Accept: application/json"

GET `/api/bi/products/{id}`

Campo	Descrição
`id`	ID artigo
`codigo`	Código
`descricao`	Descrição
`tipo`	produto/serviço
`preco_sem_iva`	Preço s/ IVA
`preco_custo`	Custo
`iva`	Taxa IVA
`unidade_de_medida`	Unidade
`visivel`	Visível
`usado`	Usado em docs
`created`	Criação
`last_update`	Alteração

[
  {
    "id": 1,
    "codigo": "ART001",
    "descricao": "Artigo exemplo",
    "preco_sem_iva": "10.00",
    "tipo": "produto",
    "iva": "23"
  }
]

GET `/api/bi/entities/{id}`

Clientes, fornecedores (exclui Consumidor Final, Stock interno).

[
  {
    "id": 42,
    "codigo": "9876543210",
    "tipo": "cliente",
    "nif": "123456789",
    "nome": "Empresa Exemplo Lda",
    "morada": "Rua Principal, 1",
    "pais": "PT",
    "cidade": "Lisboa",
    "codigo_postal": "1000-001"
  }
]

GET `/api/bi/documents/{id}`

Documentos terminados e não anulados. entity_id = terceiro em /bi/entities.

[
  {
    "estado": "N",
    "entity_id": 42,
    "nome": "Fatura",
    "document_number": "FT 2025/1",
    "document_date": "2025-05-15",
    "net_total": "100.00",
    "total": "123.00"
  }
]

Respostas e erros

Código	Significado
200	Sucesso
401	Token em falta ou inválido
422	Validação falhou
429	Limite excedido (endpoints BI)

Usar Content-Type: application/json e Accept: application/json nos pedidos v1.