Referência

Fornecedores

Os fornecedores a quem a empresa compra: a ficha e o número de contribuinte que as compras e o mapa de fornecedores usam.

Operação	O que faz
GET `/api/fornecedores`	Lista os fornecedores.
GET `/api/fornecedores/{id}`	A ficha de um fornecedor.
POST `/api/fornecedores`	Cria um fornecedor.
PUT `/api/fornecedores/{id}`	Actualiza a ficha de um fornecedor.
DELETE `/api/fornecedores/{id}`	Elimina um fornecedor da lista.

GET/api/fornecedores#

Lista os fornecedores.

Permissão Fornecedores.Ler

filtro procura no nome e no número de contribuinte. Com alteradoDesde (data e hora ISO 8601 em UTC) só vêm os criados ou alterados desde esse instante, por ordem de alteração, e os eliminados aparecem marcados (eliminado: true): ver Sincronização incremental.

A resposta é uma página: itens e proximoCursor. Ver Paginação.

Parâmetros

Nome	Onde	Tipo
`filtro`	na pesquisa	texto
`cursor`	na pesquisa	texto
`tamanho`	na pesquisa	número inteiro
`alteradoDesde`	na pesquisa	data e hora (ISO 8601)

Resposta (200 · JSON)

Campo	Tipo	Significado
`itens`	lista de objectos	Os registos desta página.
`itens[].id`	identificador (UUID)	Identificador único (UUID).
`itens[].nome`	texto	O nome.
`itens[].numeroContribuinte`	texto	O número de contribuinte (NIF).
`itens[].telefone`	texto	O telefone.
`itens[].alteradoEmUtc`	data e hora (ISO 8601)
`itens[].eliminado`	verdadeiro/falso
`proximoCursor`	texto ou nulo	O cursor da página seguinte; nulo quando não há mais. Ver Paginação.

Pedido

curl

curl 'https://<endereço-da-API>/api/fornecedores' \
  -H 'X-Api-Key: <a-sua-chave>'

GET/api/fornecedores/{id}#

A ficha de um fornecedor.

Permissão Fornecedores.Ler

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Resposta (200 · JSON)

Campo	Tipo	Significado
`id`	identificador (UUID)	Identificador único (UUID).
`nome`	texto	O nome.
`numeroContribuinte`	texto	O número de contribuinte (NIF).
`telefone`	texto	O telefone.
`municipioId`	identificador (UUID) ou nulo
`email`	texto ou nulo	O endereço de e-mail.
`endereco`	texto ou nulo	A morada.
`contacto`	texto ou nulo
`website`	texto ou nulo
`fax`	texto ou nulo
`codigoPostal`	texto ou nulo
`observacao`	texto ou nulo	O texto livre.
`nifEmAngola`	verdadeiro/falso
`pais`	texto ou nulo
`cidade`	texto ou nulo

Erros específicos

NAO_ENCONTRADO — além dos gerais.

Pedido

curl

curl 'https://<endereço-da-API>/api/fornecedores/<id>' \
  -H 'X-Api-Key: <a-sua-chave>'

POST/api/fornecedores#

Cria um fornecedor.

Permissão Fornecedores.Editar
Idempotência aceita Idempotency-Key

nome, numeroContribuinte, telefone e municipioId são obrigatórios (o município vem de GET /api/catalogos).

O número de contribuinte não pode repetir-se (erro DUPLICADO).

Corpo do pedido (JSON · CreateFornecedorCommand)

Campo	Tipo	Obrigatório	Significado
`nome`	texto	sim	O nome.
`numeroContribuinte`	texto	sim	O número de contribuinte (NIF).
`telefone`	texto	sim	O telefone.
`municipioId`	identificador (UUID) ou nulo
`email`	texto ou nulo		O endereço de e-mail.
`endereco`	texto ou nulo		A morada.
`contacto`	texto ou nulo
`website`	texto ou nulo
`fax`	texto ou nulo
`codigoPostal`	texto ou nulo
`observacao`	texto ou nulo		O texto livre.
`nifEmAngola`	verdadeiro/falso
`pais`	texto ou nulo
`cidade`	texto ou nulo

Resposta

Devolve 201 com { "id": "…" }.

Erros específicos

DUPLICADO · ERRO_DE_VALIDACAO — além dos gerais.

Pedido

curl

curl -X POST 'https://<endereço-da-API>/api/fornecedores' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Idempotency-Key: <um-GUID-novo>' \
  -H 'Content-Type: application/json' \
  -d '{
  "nome": "texto",
  "numeroContribuinte": "texto",
  "telefone": "texto"
}'

PUT/api/fornecedores/{id}#

Actualiza a ficha de um fornecedor.

Permissão Fornecedores.Editar

Substitui a ficha inteira: leia, altere e envie todos os campos.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Corpo do pedido (JSON · UpdateFornecedorRequest)

Campo	Tipo	Obrigatório	Significado
`nome`	texto	sim	O nome.
`numeroContribuinte`	texto	sim	O número de contribuinte (NIF).
`telefone`	texto	sim	O telefone.
`municipioId`	identificador (UUID) ou nulo
`email`	texto ou nulo		O endereço de e-mail.
`endereco`	texto ou nulo		A morada.
`contacto`	texto ou nulo
`website`	texto ou nulo
`fax`	texto ou nulo
`codigoPostal`	texto ou nulo
`observacao`	texto ou nulo		O texto livre.
`nifEmAngola`	verdadeiro/falso ou nulo
`pais`	texto ou nulo
`cidade`	texto ou nulo

Resposta

Devolve 204 sem corpo.

Pedido

curl

curl -X PUT 'https://<endereço-da-API>/api/fornecedores/<id>' \
  -H 'X-Api-Key: <a-sua-chave>' \
  -H 'Content-Type: application/json' \
  -d '{
  "nome": "texto",
  "numeroContribuinte": "texto",
  "telefone": "texto"
}'

DELETE/api/fornecedores/{id}#

Elimina um fornecedor da lista.

Permissão Fornecedores.Editar

As compras e os pagamentos já registados mantêm-se.

Parâmetros

Nome	Onde	Tipo	Obrigatório
`id`	no caminho	identificador (UUID)	sim

Resposta

Devolve 204 sem corpo.

Pedido

curl

curl -X DELETE 'https://<endereço-da-API>/api/fornecedores/<id>' \
  -H 'X-Api-Key: <a-sua-chave>'