Integrações

API do Portugal Empresarial

Ligue o seu CRM, ERP ou folha de cálculo aos dados do Portugal Empresarial: diretório de empresas, oportunidades abertas, os pedidos de cotação da sua empresa, as propostas e as conexões. A API é REST, responde em JSON e está na versão 1.

Autenticação

Crie um token em Definições da conta › Tokens da API. O token só é mostrado uma vez: guarde-o num local seguro e nunca o publique.

Envie-o em todos os pedidos no cabeçalho Authorization, junto com Accept: application/json:

Authorization: Bearer 1|o-seu-token

Todos os tokens têm a permissão read (leitura). A permissão write (escrita no catálogo de produtos) só é dada quando a escolhe ao criar o token, e a escrita exige o papel de proprietário ou administrador da empresa (em qualquer plano; no Gratuito, dentro do limite do catálogo). Pode revogar um token a qualquer momento.

Endpoints

URL base: https://portugal-empresarial.pt/api/v1

GET /me

Utilizador do token e a empresa em nome da qual atua (com o papel na empresa).
GET /companies

Diretório de empresas, com pesquisa e filtros.

q

texto a pesquisar

setor

slug do setor

distrito

ex.: porto

verificadas

1 para só verificadas

por_pagina

1 a 50 (20 por omissão)
GET /companies/{slug}

Perfil público de uma empresa.
GET /rfqs

Pedidos de cotação abertos.

q

texto a pesquisar

setor

slug do setor

distrito

ex.: lisboa

por_pagina

1 a 50
GET /rfqs/{slug}

Detalhe de um pedido de cotação. O orçamento só aparece se for público ou se o pedido for da sua empresa.
GET /my/rfqs

Pedidos de cotação publicados pela sua empresa (todos os estados).

por_pagina

1 a 50
GET /my/rfqs/{slug}/proposals

Propostas recebidas num pedido da sua empresa. Só a empresa que publicou o pedido tem acesso.

por_pagina

1 a 50
GET /my/proposals

Propostas enviadas pela sua empresa, com o pedido de cotação associado.

por_pagina

1 a 50
GET /my/connections

Empresas com conexão B2B aceite com a sua empresa.

por_pagina

1 a 50
GET /my/offerings

Catálogo de produtos e serviços da sua empresa (todas as origens).

origem

manual, api, woocommerce, shopify…

external_id

o seu código interno

publicados

1 ou 0

por_pagina

1 a 50
GET /my/offerings/{id}

Um item do catálogo da sua empresa.
POST /my/offerings

Cria um item, ou atualiza o item da API com o mesmo external_id (201 criado, 200 atualizado). Permissão write.
PUT /my/offerings/{id}

Substitui um item criado pela API (o external_id não muda). Permissão write.
DELETE /my/offerings/{id}

Apaga um item criado pela API. Permissão write.
POST /my/offerings/bulk

Cria ou atualiza até 500 itens por pedido, pelo external_id, e opcionalmente despublica os que não vierem. Permissão write.

unpublish_missing

true para despublicar os itens da API que não foram enviados

sync_started_at

data ISO 8601 do início do envio, quando o catálogo vai em vários pedidos

Exemplos com curl

Os seus dados e a sua empresa:

curl https://portugal-empresarial.pt/api/v1/me \
  -H "Authorization: Bearer $PORTUGAL_EMPRESARIAL_TOKEN" \
  -H "Accept: application/json"

Empresas verificadas do distrito do Porto que mencionam "moldes":

curl "https://portugal-empresarial.pt/api/v1/companies?q=moldes&distrito=porto&verificadas=1" \
  -H "Authorization: Bearer $PORTUGAL_EMPRESARIAL_TOKEN" \
  -H "Accept: application/json"

Propostas recebidas num pedido de cotação da sua empresa:

curl https://portugal-empresarial.pt/api/v1/my/rfqs/paletes-eur-ab12cd/proposals \
  -H "Authorization: Bearer $PORTUGAL_EMPRESARIAL_TOKEN" \
  -H "Accept: application/json"

Enviar o catálogo de produtos

Mantenha o catálogo público da sua empresa (/produtos) igual ao do seu ERP ou loja. Cada item é identificado pelo seu código interno (external_id): se já existir é atualizado, senão é criado. Os itens criados no site ou por um conector automático nunca são alterados pela API.

external_id: obrigatório, até 191 caracteres, único na sua empresa
title: obrigatório, até 150 caracteres
type: product (por omissão) ou service
description: texto até 5000 caracteres (o HTML é removido)
title_en, description_en: versão em inglês (opcional)
sku: referência, até 100 caracteres
price, currency: preço sem IVA em euros (currency só aceita EUR)
price_unit: ex.: unidade, hora, kg
availability: in_stock, on_order, unavailable
url: página do produto no seu site (https)
image_url: imagem JPG, PNG ou WebP até 2 MB num endereço https público; é descarregada em segundo plano
category: slug do setor (ex.: metalurgia)
published: false para esconder do catálogo público (true por omissão)

Enviar ou atualizar vários itens de uma vez:

curl -X POST https://portugal-empresarial.pt/api/v1/my/offerings/bulk \
  -H "Authorization: Bearer $PORTUGAL_EMPRESARIAL_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "external_id": "PAL-1200", "title": "Palete EUR 1200x800", "price": 12.5,
        "price_unit": "unidade", "availability": "in_stock", "sku": "PAL-1200",
        "url": "https://www.aminhaempresa.pt/paletes/eur",
        "image_url": "https://www.aminhaempresa.pt/img/palete.jpg" },
      { "external_id": "SRV-TRANSP", "title": "Transporte nacional", "type": "service" }
    ]
  }'

Resposta (o envio fica também no registo de sincronizações da empresa):

{ "data": { "run_id": 81, "received": 2, "created": 1, "updated": 1, "unchanged": 0,
  "unpublished": 0, "failed": 0, "skipped": 0, "errors": [],
  "limit": { "max_items": 25, "used": 12, "remaining": 13, "plan_limited": true },
  "items": [
    { "index": 0, "external_id": "PAL-1200", "status": "created" },
    { "index": 1, "external_id": "SRV-TRANSP", "status": "updated" }
  ] } }

Limite do catálogo: no plano Gratuito a empresa tem até 25 produtos e serviços no total (criados no site, importados por um conector e enviados pela API contam em conjunto); no Empresarial Pro é ilimitado. Os itens são tratados pela ordem em que os envia: os que já existem são sempre atualizados e os novos só são criados enquanto houver lugar. Os restantes vêm com o estado skipped e o motivo plan_limit (catalog_limit no máximo técnico de 10 000 itens), e o pedido responde 200 com o resumo. Num pedido de um só item (POST /my/offerings) sem lugar, a resposta é 422 com reason plan_limit.

{ "data": { "received": 30, "created": 25, "skipped": 5,
  "errors": ["5 produtos não importados: limite do plano Gratuito (25 produtos). ..."],
  "limit": { "max_items": 25, "used": 25, "remaining": 0, "plan_limited": true },
  "items": [ ..., { "index": 25, "external_id": "P-26", "status": "skipped", "reason": "plan_limit" }, ... ] } }

Estados possíveis de cada item: created, updated, unchanged, skipped (com reason plan_limit ou catalog_limit) e failed (com reason invalid ou duplicate e a mensagem).

Catálogo com mais de 500 itens: envie-o em vários pedidos com a mesma data de início e, no último, peça para despublicar o que não veio. Os itens despublicados não são apagados e voltam a aparecer se forem enviados de novo.

{ "items": [ ... últimos itens ... ],
  "unpublish_missing": true,
  "sync_started_at": "2026-10-09T08:00:00+01:00" }

Alterar ou apagar um item criado pela API:

curl -X PUT https://portugal-empresarial.pt/api/v1/my/offerings/123 \
  -H "Authorization: Bearer $PORTUGAL_EMPRESARIAL_TOKEN" -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Palete EUR 1200x800 (nova)", "price": 13.2, "availability": "on_order" }'

curl -X DELETE https://portugal-empresarial.pt/api/v1/my/offerings/123 \
  -H "Authorization: Bearer $PORTUGAL_EMPRESARIAL_TOKEN" -H "Accept: application/json"

Erros de validação respondem 422 com a lista dos campos (ex.: items.3.price). Sem a permissão write, sem o papel de proprietário ou administrador ou num item criado no site, a resposta é 403.

Respostas e paginação

As listas vêm paginadas: os resultados estão em data, e links e meta indicam a página atual, o total e os URLs da página seguinte e anterior (parâmetro page).

{
  "data": [{ "slug": "metalurgica-do-ave", "name": "Metalúrgica do Ave, Lda.", "nif": "509876543", "verified": true, ... }],
  "links": { "first": "...", "last": "...", "prev": null, "next": "...?page=2" },
  "meta": { "current_page": 1, "per_page": 20, "total": 134, ... }
}

Os campos privados nunca são devolvidos: orçamentos não públicos, links de acesso a eventos online, emails dos utilizadores de outras empresas e tokens.