Documentos de Venda
As rotas aqui descritas permitem gerir todos os processos relativos a documentos de venda: orçamentos, faturas-proforma, guias, faturas e notas.
Criação do Documento de Venda
1. Criação do cabeçalho
Para dar início à criação de um documento comercial, começa-se pelo cabeçalho. Isto é realizado através de uma solicitação POST usando cURL, onde é necessário incluir um token de acesso (access_token
), e o conteúdo (payload JSON
) que detalha as especificações do documento, incluindo o tipo de documento (fatura, fatura simplificada, fatura-recibo), informação sobre o cliente (novo ou existente), condições de pagamento, detalhes sobre o IVA, entre outros atributos opcionais.
2. Adição de Linhas
Após a criação do cabeçalho, é possível adicionar uma ou mais linhas ao documento. Este passo permite detalhar os produtos ou serviços que estão sendo transacionados.
3. Finalização do Documento
O documento pode ser finalizado após a adição de todas as informações necessárias. Uma vez finalizado, o documento não pode ser alterado ou eliminado, apenas anulado se necessário.
Cada passo é crucial para assegurar que o documento comercial seja criado de forma precisa e conforme as necessidades do usuário. A atenção aos detalhes durante o processo de criação e finalização é fundamental para a integridade do documento.
1. Criar Cabeçalho de Documento de Venda
No pedido acima, o access_token é o token de acesso válido devolvido pelo serviço de OAuth. O payload JSON a enviar contém a seguinte informação:
Nota 1 - A série associada ao documento tem já que existir, e o seu "id" interno pode ser obtido por um:
Nota 2 - Se o cliente for identificado pelo seu "id" interno tem já que existir, e o seu "id" interno pode ser obtido por um:
Nota 3 - São também suportados dois "países" adicionais: "PT-AC" (Portugal, Açores) e "PT-MA" (Portugal, Madeira). Os países disponíveis podem ser consultados por um GET /countries, ou um em particular por um:
Nota 4 - O "id" interno da conta bancária da empresa deve ser obtido por um:
Nota 5 - O "id" interno da conta de caixa da empresa deve ser obtido por um
Nota 6 - O "id" interno do motivo de isenção deve ser obtido por um
Nota 7 - O "id" interno da moeda deve ser obtido por um
2. Criação da(s) linha(s)
Após a criação do documento, é possível personalizar as linhas do mesmo para detalhar produtos, serviços, ou outros descritores específicos. As linhas podem ser configuradas para refletir várias especificidades fiscais e comerciais, incluindo a opção de adicionar linhas apenas descritivas, com ou sem valor associado.
As linhas podem referenciar três tipos de itens: produtos, serviços ou descritores (juros, imobilizado, impostos especiais...). Para cada um destes o payload é ligeiramente diferente, e cada um será descrito de seguida.
No pedido mencionado acima, o access_token
representa o token de acesso validado pelo serviço de OAuth. O payload JSON a ser enviado contém informações distintas para um produto, um serviço ou um descritor, conforme será detalhado nas etapas seguintes.ccc
2.1. Criar Linha de Documento de Venda para um Produto
2.2. Criar Linha de Documento de Venda para um Serviço
2.3. Criar Linha de Documento de Venda para um Descritor
2.5. Criar Linha de Documento de Venda para uma Descrição Sem Valor
Para o caso particular de uma linha de descrição sem valor, este payload contém a seguinte informação:
3. Finalização do documento
Após todas as linhas criadas, e se não houver mais nenhuma alteração ao documento, este pode ser finalizado.
Após a finalização, a alteração ou eliminação do cabeçalho e das linhas deixa de ser possível, assim como a criação de linhas adicionais.
No pedido acima, o access_token é o token de acesso válido devolvido pelo serviço de OAuth e o id do documento é o "id" interno do documento (cabeçalho) é o devolvido no campo "id" da resposta ao seu pedido de criação (ver ponto 1. Criação do cabeçalho). O payload JSON a enviar contém a seguinte informação:
Este pedido é equivalente ao pedido de alteração do cabeçalho do documento (ver Alteração do cabeçalho do documento). Por isso, a finalização do documento — que é a alteração do atributo "status" do cabeçalho — pode ser realizada juntamente com a alteração de outros atributos ou relações do cabeçalho, num único pedido.
Alteração do Documento de Venda
Enquanto o documento não for finalizado, tanto o seu cabeçalho como qualquer uma das suas linhas podem ser alteradas a qualquer momento. Além disso, qualquer uma das linhas pode ser eliminada (ver Eliminação de uma linha), e novas linhas criadas e adicionadas (ver 2. Criação da(s) linha(s)).
Atualizar Linha de Documento de Venda
O exemplo de payload acima deve por isso ser ajustado consoante se trate da alteração duma linha de produto, de serviço, de descritor ou de descrição. É ainda possível alterar o tipo de linha (de uma linha de serviço para uma de produto, por exemplo).
O access_token é o token de acesso válido devolvido pelo serviço de OAuth.
O id da linha é o "id" interno da linha do documento, devolvido no campo "id" da resposta ao seu pedido de criação (ver ponto 2. Criação da(s) linha(s) )
A informação que pode ser enviada no pedido de alteração da linha do documento é equivalente à que é obtida após criação ou obtenção de Documentos de Venda.
Por favor, note que alguns atributos podem estar marcados como null
, o que significa que não foram fornecidos valores para esses atributos no JSON.
Nota 1 - O "id"
interno do documento, associado ao cabeçalho, corresponde ao "id" fornecido na resposta ao pedido de criação desse cabeçalho. Consulte a secção #id-1.-criacao-do-cabecalho para mais detalhes.
Nota 2 - O item (serviço, produto ou descritor) já deve existir, e o seu "id"
interno pode ser obtido por um
Nota 3 - Além de "PT" (Portugal Continental), são também suportadas as regiões autónomas de IVA "PT-AC" (Açores) e "PT-MA" (Madeira).
Para consultar os regimes de IVA no âmbito do OSS, é importante notar que os códigos de região correspondem aos códigos dos países. Estes códigos podem ser obtidos através do seguinte pedido:
Nota 4 - A unidade de medida deve existir previamente, e seu identificador "id"
interno pode ser obtido através de um
Nota 5 - O "id" interno da taxa de IVA deve ser obtido por um
Remover Linha de Documento de Venda
No pedido acima, o access_token é o token de acesso válido devolvido pelo serviço de OAuth e o id da linha é o "id" interno da linha do documento, devolvido no campo "id" da resposta ao seu pedido de criação (ver ponto 2. Criação da(s) linha(s)).
Anulação do documento
Após a sua finalização, o documento deixa de poder ser eliminado, podendo apenas ser anulado.
No pedido acima, o access_token é o token de acesso válido devolvido pelo serviço de OAuth e o id do documento é o "id" interno do documento (cabeçalho) é o devolvido no campo "id" da resposta ao seu pedido de criação (ver ponto 1. Criação do cabeçalho). O payload JSON a enviar contém a seguinte informação:
Após a sua anulação, o documento deixa de poder ser alterado. Esta operação é irreversível.
Remover Documento de Venda
Enquanto estiver em preparação, o documento pode ser eliminado.
Após a finalização, a sua eliminação — assim como a sua alteração — deixa de ser possível. Para saber mais consulte: 3. Finalização do documento
No pedido acima, o access_token é o token de acesso válido devolvido pelo serviço de OAuth e o id do documento é o "id" interno do documento (cabeçalho) é o devolvido no campo "id" da resposta ao seu pedido de criação (ver ponto 1. Criação do cabeçalho).
Esta operação é irreversível.
Last updated