# Table of Contents - [Introdução | TOConline - Documentação API](#introdu-o-toconline-documenta-o-api) - [Setup do Postman | TOConline - Documentação API](#setup-do-postman-toconline-documenta-o-api) - [Autenticação Simplificada | TOConline - Documentação API](#autentica-o-simplificada-toconline-documenta-o-api) - [Empresa | TOConline - Documentação API](#empresa-toconline-documenta-o-api) - [Características dos pedidos | TOConline - Documentação API](#caracter-sticas-dos-pedidos-toconline-documenta-o-api) - [Autenticação Detalhada | TOConline - Documentação API](#autentica-o-detalhada-toconline-documenta-o-api) - [Vendas | TOConline - Documentação API](#vendas-toconline-documenta-o-api) - [Descarregar PDF de Recibo | TOConline - Documentação API](#descarregar-pdf-de-recibo-toconline-documenta-o-api) - [Vendas | TOConline - Documentação API](#vendas-toconline-documenta-o-api) - [Compras | TOConline - Documentação API](#compras-toconline-documenta-o-api) - [Versões Anteriores | TOConline - Documentação API](#vers-es-anteriores-toconline-documenta-o-api) - [Descarregar PDF de Documentos de Venda | TOConline - Documentação API](#descarregar-pdf-de-documentos-de-venda-toconline-documenta-o-api) - [Comunicação de documentos à AT | TOConline - Documentação API](#comunica-o-de-documentos-at-toconline-documenta-o-api) - [Compras | TOConline - Documentação API](#compras-toconline-documenta-o-api) - [Descarregar PDF de Pagamentos | TOConline - Documentação API](#descarregar-pdf-de-pagamentos-toconline-documenta-o-api) - [Comunicação de documentos à AT | TOConline - Documentação API](#comunica-o-de-documentos-at-toconline-documenta-o-api) - [Descarregar PDF de Documentos de Compra | TOConline - Documentação API](#descarregar-pdf-de-documentos-de-compra-toconline-documenta-o-api) - [Envio de Recibos por email | TOConline - Documentação API](#envio-de-recibos-por-email-toconline-documenta-o-api) - [Envio de Documentos por email | TOConline - Documentação API](#envio-de-documentos-por-email-toconline-documenta-o-api) - [Documentos de Compra | TOConline - Documentação API](#documentos-de-compra-toconline-documenta-o-api) - [Documentos de Série | TOConline - Documentação API](#documentos-de-s-rie-toconline-documenta-o-api) - [Pagamentos | TOConline - Documentação API](#pagamentos-toconline-documenta-o-api) - [APIs Auxiliares | TOConline - Documentação API](#apis-auxiliares-toconline-documenta-o-api) - [Produtos e Serviços | TOConline - Documentação API](#produtos-e-servi-os-toconline-documenta-o-api) - [Países | TOConline - Documentação API](#pa-ses-toconline-documenta-o-api) - [Unidade Monetária | TOConline - Documentação API](#unidade-monet-ria-toconline-documenta-o-api) - [Recibos de Venda | TOConline - Documentação API](#recibos-de-venda-toconline-documenta-o-api) - [Unidades de Medida | TOConline - Documentação API](#unidades-de-medida-toconline-documenta-o-api) - [Categorias de Despesa | TOConline - Documentação API](#categorias-de-despesa-toconline-documenta-o-api) - [Documentos de Venda | TOConline - Documentação API](#documentos-de-venda-toconline-documenta-o-api) - [Documentos Retificativos | TOConline - Documentação API](#documentos-retificativos-toconline-documenta-o-api) - [Família de Itens | TOConline - Documentação API](#fam-lia-de-itens-toconline-documenta-o-api) - [Recibos de Venda | TOConline - Documentação API](#recibos-de-venda-toconline-documenta-o-api) - [Caixa Associada | TOConline - Documentação API](#caixa-associada-toconline-documenta-o-api) - [Descritores de Taxa | TOConline - Documentação API](#descritores-de-taxa-toconline-documenta-o-api) - [Contas Bancárias | TOConline - Documentação API](#contas-banc-rias-toconline-documenta-o-api) - [Pagamentos | TOConline - Documentação API](#pagamentos-toconline-documenta-o-api) - [Taxas | TOConline - Documentação API](#taxas-toconline-documenta-o-api) - [Clientes, Morada e E-mail | TOConline - Documentação API](#clientes-morada-e-e-mail-toconline-documenta-o-api) - [Fornecedores, Morada e E-mail | TOConline - Documentação API](#fornecedores-morada-e-e-mail-toconline-documenta-o-api) - [Documentos de Compra | TOConline - Documentação API](#documentos-de-compra-toconline-documenta-o-api) - [Documentos de Venda | TOConline - Documentação API](#documentos-de-venda-toconline-documenta-o-api) - [Email Protection | Cloudflare](#email-protection-cloudflare) --- # Introdução | TOConline - Documentação API Esta página fornece informações essenciais para começar a trabalhar com a API referenciada, utilizando duas ferramentas-chave: Swagger e Postman. * **Swagger**: A documentação da API está disponível em OpenAPI e pode ser acessada através do link fornecido. Swagger auxilia na visualização e no download da documentação da API. * **Postman**: Oferece uma maneira eficiente de realizar chamadas à API, simplificando a gestão de autenticação. Existem instruções fornecidas para importar um arquivo de configuração pronto no Postman, facilitando a configuração inicial. ### [hashtag](https://api-docs.toconline.pt/#openapi) Swagger OpenAPI é atualmente o método standard de documentar APIs. Como tal, temos disponível no seguinte link, a documentação da referenciada API, em OpenAPI. Link para visualizar e descarregar OpenAPI: [https://app.swaggerhub.com/apis/toconline.pt/toc-online\_open\_api/1.0.0app.swaggerhub.comchevron-right](https://app.swaggerhub.com/apis/toconline.pt/toc-online_open_api/1.0.0) [https://app.swaggerhub.com/apis/toconline.pt/toc-online\_open\_api/1.0.0arrow-up-right](https://app.swaggerhub.com/apis/toconline.pt/toc-online_open_api/1.0.0) ### [hashtag](https://api-docs.toconline.pt/#postman) Postman Para facilitar o processo de configuração, disponibilizamos um arquivo pronto para importação no Postman. Este procedimento resume-se em dois passos simples: 1. Acesse a página de credenciais da API para obter o arquivo de configuração. Ele é fornecido via e-mail ao integrador escolhido. 2. Navegue até **Empresa > Dados API**, no nosso produto, para acessar e baixar o arquivo mencionado. [NextSetup do Postmanchevron-right](https://api-docs.toconline.pt/setup-do-postman) Last updated 1 year ago --- # Setup do Postman | TOConline - Documentação API #### [hashtag](https://api-docs.toconline.pt/setup-do-postman#configuracao-de-acesso-a-api) Configuração de Acesso à API Para configurar o acesso à AP, siga os passos abaixo: 1. Acesse o menu `Empresa > Dados API`. Esta opção está disponível somente para os administradores da empresa. 2. Insira o nome e o e-mail do integrador responsável pela conexão com a API. Após a conclusão destes passos, o integrador receberá um e-mail contendo: * Um link temporário para consulta e edição das credenciais de acesso à API. * Um ficheiro necessário para a utilização com o Postman. **Setup Postman** Após acessar a página de downloads do Postman em [https://www.postman.com/downloads/arrow-up-right](https://www.postman.com/downloads/) e concluir a instalação do software, na página inicial, selecione a opção "**Importar**" para prosseguir. ![](https://api-docs.toconline.pt/~gitbook/image?url=https%3A%2F%2F1863668386-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fk7sif7BY0rPzivMcj1HB%252Fuploads%252Fl2NS4hxLu1BnVFOrwVMo%252FClicar%2520em%2520import.png%3Falt%3Dmedia%26token%3D75ee7a58-5c51-4196-99e7-718f422a56c7&width=768&dpr=4&quality=100&sign=a2b29bfa&sv=2) A partir deste ponto, deverá importar o ficheiro descarregado na página de credenciais da API. Com este ficheiro importado, deverá ter uma nova coleção aberta, com os possíveis pedidos à API disponibilizados. ![](https://api-docs.toconline.pt/~gitbook/image?url=https%3A%2F%2F1863668386-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fk7sif7BY0rPzivMcj1HB%252Fuploads%252F1HWhhiHdCPH4RBj7zczb%252FFicheiro%2520importado.png%3Falt%3Dmedia%26token%3Dbedf14ad-f0b3-4d37-9733-38f6d58ee14a&width=768&dpr=4&quality=100&sign=6d0a6cce&sv=2) Antes de realizar qualquer pedido, é necesário realizar a autenticação. Para o efeito, deve clicar em Open APIDe seguida, deve clicar em "autenticação". ![](https://api-docs.toconline.pt/~gitbook/image?url=https%3A%2F%2F1863668386-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fk7sif7BY0rPzivMcj1HB%252Fuploads%252FQrhKfJsMQbdiYwSh0GmE%252FClicado%2520em%2520Authorization.png%3Falt%3Dmedia%26token%3D0e783ea2-d443-40f5-b0fc-42773177855b&width=768&dpr=4&quality=100&sign=824dff2d&sv=2) Daqui, deverá ter todos os campos como mostrado na imagem, ir ao final da página e clicar em "Gerar novo token de acesso". Este processo irá abrir uma página no seu browser, que deverá ativar um pop-up. Caso este pop-up não surja, deverá garantir que não tem a opção de 'permitir pop-ups' desativada. Quando o pop-up surjir, deverá clicar na checkbox que surge no popup, antes de confirmar a operação. ![](https://api-docs.toconline.pt/~gitbook/image?url=https%3A%2F%2F1863668386-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fk7sif7BY0rPzivMcj1HB%252Fuploads%252FAhUF1UL0QTTca4issk36%252FClicar%2520em%2520get%2520access%2520token.png%3Falt%3Dmedia%26token%3D41362950-2852-46af-824b-82739439f0df&width=768&dpr=4&quality=100&sign=177b57a3&sv=2) Para finalizar, voltar ao início da página, e selecionar o token gerado. ![](https://api-docs.toconline.pt/~gitbook/image?url=https%3A%2F%2F1863668386-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fk7sif7BY0rPzivMcj1HB%252Fuploads%252Fn6Bfx16RuJbpXuYgVMtJ%252FSelecionar%2520o%2520Token%2520Gerado.png%3Falt%3Dmedia%26token%3D55e14dd6-17b0-4a7a-af83-ba2f6db0da66&width=768&dpr=4&quality=100&sign=cd88c00a&sv=2) **Pedidos à API** A partir deste ponto, todos os passos estão concluidos para a experimentação com a API. De modo a enviar um pedido à API, deve selecionar o pedido que quer enviar, na barra lateral esquerda. ![](https://api-docs.toconline.pt/~gitbook/image?url=https%3A%2F%2F1863668386-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fk7sif7BY0rPzivMcj1HB%252Fuploads%252FjJVI1ubwG3vK4Q4Jrypl%252FSelecionar%2520a%2520barra%2520lateral%2520esquerda.png%3Falt%3Dmedia%26token%3D6401d8b4-4dfb-4c9f-ad99-f5df2d5b80c3&width=768&dpr=4&quality=100&sign=b533217&sv=2) Aberto o pedido, pode editar os parâmetros que deseja enviar, e enviar o pedido utilizando o botão "enviar". A resposta do pedido irá surgir na caixa "Resposta" ![](https://api-docs.toconline.pt/~gitbook/image?url=https%3A%2F%2F1863668386-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fk7sif7BY0rPzivMcj1HB%252Fuploads%252FmrJygqqRZgr56V5iAzSG%252FClicar%2520em%2520Send.png%3Falt%3Dmedia%26token%3D59284010-492f-4edd-b92d-42914d953bf8&width=768&dpr=4&quality=100&sign=3f5d62fc&sv=2) [PreviousIntroduçãochevron-left](https://api-docs.toconline.pt/) [NextAutenticação Simplificadachevron-right](https://api-docs.toconline.pt/autenticacao-simplificada) Last updated 1 year ago sun-brightdesktopmoon sun-brightdesktopmoon --- # Autenticação Simplificada | TOConline - Documentação API circle-info A presente página apresenta uma versão simplificada do processo de autenticação. Caso este não seja suficiente para a sua aplicação, ou encontre algum erro, ou dificuldade, consulte: [Autenticação Detalhada](https://api-docs.toconline.pt/autenticacao-detalhada) ### [hashtag](https://api-docs.toconline.pt/autenticacao-simplificada#passo-1-obtencao-das-credenciais-de-acesso-a-nossa-api-comercial) Passo 1: Obtenção das credenciais de acesso à nossa API comercial Neste passo, deverão ser obtidos os seguintes dados, necessários para que possam aceder à nossa API comercial: > * Identificador (a que chamamos "`OAUTH_CLIENT_ID`", ou simplesmente "`client_id`", nos exemplos posteriores) > > * Segredo (a que chamamos "`OAUTH_CLIENT_SECRET`", ou simplesmente "`secret`", nos exemplos posteriores) > > * Endereço de autenticação por OAuth (a que chamamos "`OAUTH_URL`" nos exemplos posteriores) > > * Endereço de acesso à API (a que chamamos "`API_URL`" nos exemplos posteriores) > Os quatro dados de acesso acima indicados são todos obtidos directamente da empresa à qual se pretende aceder via API. Para os obter, deverá fazer o seguinte: 1. Entrar na empresa com uma conta de Empresário ![](https://api-docs.toconline.pt/~gitbook/image?url=https%3A%2F%2F1863668386-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fk7sif7BY0rPzivMcj1HB%252Fuploads%252Ff2fnGF2J5L1yaB6hzE8c%252FEntrar%2520em%2520empresa.png%3Falt%3Dmedia%26token%3D562dbe04-931b-4bb9-8f72-9e68e1911f2d&width=768&dpr=4&quality=100&sign=295dc67&sv=2) 1. Aceder através do menu à opção Empresa > Configurações > Dados API ![](https://api-docs.toconline.pt/~gitbook/image?url=https%3A%2F%2F1863668386-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fk7sif7BY0rPzivMcj1HB%252Fuploads%252FtxLM4S05keSbdJavmn9a%252FMenu%253EEmpresa.png%3Falt%3Dmedia%26token%3Dc3d6a695-7463-4a10-8c29-d8c48594940e&width=768&dpr=4&quality=100&sign=f68c93ee&sv=2) 1. Introduzir os dados do integrador, que irá receber os dados de acesso à API através de um link temporário, de 72h. 1. Abrir o link de acesso enviado no email ![](https://api-docs.toconline.pt/~gitbook/image?url=https%3A%2F%2F1863668386-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fk7sif7BY0rPzivMcj1HB%252Fuploads%252FCCLcQCEoXy8AzsVWvqih%252FMenu%253EDadosApi.png%3Falt%3Dmedia%26token%3D64d46540-5ed0-4b2e-93e0-7c5a8f8f1df1&width=768&dpr=4&quality=100&sign=bebc7d7c&sv=2) ### [hashtag](https://api-docs.toconline.pt/autenticacao-simplificada#passo-2-obtencao-do-authorization_code) Passo 2: Obtenção do _authorization\_code_ circle-info #### [hashtag](https://api-docs.toconline.pt/autenticacao-simplificada#caso-esteja-a-utilizar-postman-devera-desativar-a-opcao-automatically-follow-redirects-nas-definicoe) Caso esteja a utilizar Postman, deverá desativar a opção "Automatically follow redirects", nas definições do pedido Neste passo, deverá ser feito um pedido GET ao endereço OAUTH\_URL/auth com: Na query do Url, os **parâmetros**: > * `client_id=OAUTH_CLIENT_ID` > > * `redirect_uri=OAUTH_REDIRECT_URL` > > * `response_type=code` > > * `scope=commercial` > Nos **headers**, o seguinte: > * `Content-Type: application/json` > O exemplo seguinte ilustra o pedido feito no terminal, usando o curl: A resposta esperada é como a seguinte: Utilizando o authorization\_code recebido na resposta, deverá seguir o próximo passo ### [hashtag](https://api-docs.toconline.pt/autenticacao-simplificada#passo-3-obtencao-do-access_code) Passo 3: Obtenção do access\_code Neste passo, deverá ser feito um pedido POST ao endereço OAUTH\_URL/token com: 1. No body do pedido, os parâmetros: > * grant\_type=authorization\_code > > * code= o "authorization\_code" obtido do passo anterior. > > * scope=commercial > 1. Nos headers, os seguinte: > * Content-Type: application/x-www-form-urlencoded > > * Accept: application/json > > * Authorization: o texto "Basic", seguido dum espaço, seguido dum texto formado pela concatenação do "client\_id", seguido de ':', seguido do "secret", tudo codificado em base 64. Por exemplo, se o "client\_id" fosse "test" e o "secret" fosse "abcdef", o valor deste header seria "Basic dGVzdDphYmNkZWY=", sendo "dGVzdDphYmNkZWY=" o texto "test:abcdef" em base 64. > O exemplo seguinte ilustra o pedido feito no terminal, usando o curl: A resposta esperada é como a seguinte: Daqui, tem então o access\_token necessário para a utilização da API, referenciado nas restantes páginas de pedidos de exemplo [PreviousSetup do Postmanchevron-left](https://api-docs.toconline.pt/setup-do-postman) [NextAutenticação Detalhadachevron-right](https://api-docs.toconline.pt/autenticacao-detalhada) Last updated 1 year ago * [Passo 1: Obtenção das credenciais de acesso à nossa API comercial](https://api-docs.toconline.pt/autenticacao-simplificada#passo-1-obtencao-das-credenciais-de-acesso-a-nossa-api-comercial) * [Passo 2: Obtenção do authorization\_code](https://api-docs.toconline.pt/autenticacao-simplificada#passo-2-obtencao-do-authorization_code) * [Passo 3: Obtenção do access\_code](https://api-docs.toconline.pt/autenticacao-simplificada#passo-3-obtencao-do-access_code) sun-brightdesktopmoon Copy curl -v -H 'Content-Type: application/json' \ '/auth?client_id=\ &redirect_uri=http://127.0.0.1:4080/oauth/callback\ &response_type=code&scope=commercial' Copy GET /oauth/auth?client_id HTTP/1.1 &redirect_uri=http://127.0.0.1:4080/oauth/callback &response_type=code&scope=commercial HTTP/1.1 > Accept: */* > Content-Type: application/json > < HTTP/1.1 302 Moved Temporarily < Content-Type: text/html < Location: http://127.0.0.1:4080/oauth/callback? code= Copy curl -v -X POST -H 'Content-Type: application/x-www-form-urlencoded'\ -H 'Accept: application/json'\ -H 'Authorization: Basic ' \ -d 'grant_type=authorization_code&\ code=&scope=commercial' \ '/token' Copy POST /oauth/token HTTP/1.1 Content-Type: application/x-www-form-urlencoded > Accept: application/json > Authorization: Basic dGVzdHM6ZWJhOTI3NjM3MzRlN2MwMg== > < HTTP/1.1 200 OK < Content-Type: application/json;charset=utf-8 < {"access_token":"10dc1d36e24b790540d087ea238ec345abd1a02daa73ae45a09", "expires_in":7890000, "refresh_token":"f71824c9e4675a8aa9661f18ae5341e977d37", "token_type":"Bearer"} sun-brightdesktopmoon --- # Empresa | TOConline - Documentação API [Clientes, Morada e E-mailchevron-right](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email) [Fornecedores, Morada e E-mailchevron-right](https://api-docs.toconline.pt/apis/empresa/fornecedores) [Produtos e Serviçoschevron-right](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos) [PreviousCaracterísticas dos pedidoschevron-left](https://api-docs.toconline.pt/caracteristicas-dos-pedidos) [NextClientes, Morada e E-mailchevron-right](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email) Last updated 1 year ago sun-brightdesktopmoon sun-brightdesktopmoon --- # Características dos pedidos | TOConline - Documentação API Nas seguintes páginas são exemplificados alguns dos pedidos mais comuns à API. Estes estão subdivididos em diferentes áreas. #### [hashtag](https://api-docs.toconline.pt/caracteristicas-dos-pedidos#pre-requesitos-para-a-realizacao-de-qualquer-um-dos-pedidos) Pré-requesitos para a realização de qualquer um dos pedidos: * Um acesso autenticado à empresa de trabalho, via OAuth (o modo de autenticação está documentado na página anterior * A empresa de trabalho deverá ter uma licença de GC activa, excepto para os GET, que serão autorizados mesmo quando a licença expira #### [hashtag](https://api-docs.toconline.pt/caracteristicas-dos-pedidos#conteudos-dos-headers-comuns-a-todos-os-pedidos) Conteúdos dos Headers, comuns a todos os pedidos > * `Content-Type: application/vnd.api+json` > > * `Accept: application/json` > > * `Authorization`: Bearer (token de acesso válido devolvido pelo serviço de OAuth) > #### [hashtag](https://api-docs.toconline.pt/caracteristicas-dos-pedidos#filtro-de-parametros) Filtro de parâmetros: De momento não estão disponíveis rotas que cubram todo o tipo de informação que está disponível através do software. No entanto, muitos recursos que não têm uma rota dedicada podem ser acedidos por outras rotas, utilizando os filtros de parâmetros. Por exemplo, apesar de não existir nenhuma rota para documentos de venda pendentes, existe uma rota de documentos de venda. Estes documentos contém um atributo de valor pendente. Como tal, é possível obter apenas os documentos com valor pendente, da seguinte forma: [hashtag](https://api-docs.toconline.pt/caracteristicas-dos-pedidos#obter-documentos-de-compra) Obter Documentos de Compra ------------------------------------------------------------------------------------------------------------------------------- `GET` `/api/commercial_sales_documents` #### [hashtag](https://api-docs.toconline.pt/caracteristicas-dos-pedidos#path-parameters) Path Parameters Name Type Description page\[size\] String 10 filter String "documents.pending\_total>0" De notar que deverá indicar o tipo de documento no atributo que procura filtrar. Neste caso, deverá ser documents.pending\_total. > commercial\_sales\_documents -> **documents** > > commercial\_sales\_receipts -> **receipts** > > commercial\_purchases\_documents -> **purchases\_documents** > > commercial\_purchases\_payments -> **payments** Da mesma forma, poderá filtrar, por exemplo, pela data. [hashtag](https://api-docs.toconline.pt/caracteristicas-dos-pedidos#obter-linha-de-documento-de-compras) Obter Linha de Documento de Compras ------------------------------------------------------------------------------------------------------------------------------------------------- `GET` `/api/commercial_sales_document_lines` #### [hashtag](https://api-docs.toconline.pt/caracteristicas-dos-pedidos#path-parameters-1) Path Parameters Name Type Description page\[size\] String 10 filter String "document\_lines.created\_at>'2022-01-01'::date" Deverá também indicar o tipo de linhas de documento pelo qual está a filtrar, tal como na lista acima. De seguida está um exemplo de como poderá realizar um pedido utilizando este filtro É recomendável utilizar paginação, caso haja um grande número de resultados para ser apresentado [PreviousAutenticação Detalhadachevron-left](https://api-docs.toconline.pt/autenticacao-detalhada) [NextEmpresachevron-right](https://api-docs.toconline.pt/apis/empresa) Last updated 1 year ago * [Obter Documentos de Compra](https://api-docs.toconline.pt/caracteristicas-dos-pedidos#obter-documentos-de-compra) * [Obter Linha de Documento de Compras](https://api-docs.toconline.pt/caracteristicas-dos-pedidos#obter-linha-de-documento-de-compras) sun-brightdesktopmoon Copy curl -v -X GET -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer ' '/v1/commercial_sales_documents?filter="document_lines.created_at>'2022-01-01'::date"' sun-brightdesktopmoon --- # Autenticação Detalhada | TOConline - Documentação API Para utilizar a nossa API através do Postman, é necessário seguir o processo de autenticação descrito nesta página para obter a chave de acesso. Depois de adquirida, essa chave pode ser introduzida no Postman como parâmetro de autenticação Bearer Token nas solicitações à nossa API. Isso permite testar facilmente os endpoints da API e interagir com o nosso sistema de forma programática durante o desenvolvimento e testes. Ao conectar a nossa API com o Postman, siga os seguintes passos interligados à autenticação: 1. **Obtenha a chave de acesso** seguindo o processo de autenticação descrito anteriormente. Esta etapa envolverá fornecer credenciais necessárias para acessar a nossa API comercial. 2. **Configure o Postman** para usar esta chave de acesso. No Postman, vá até as configurações de autenticação da requisição que você está criando e selecione o tipo de autenticação como "Bearer Token". 3. **Insira a chave de acesso** no campo disponível após selecionar o tipo de autenticação como Bearer Token. Certifique-se de que a chave de acesso obtida não é de serviços externos como Google, mas sim obtida diretamente conforme o nosso processo de autenticação. Seguindo esses passos, você poderá utilizar o Postman para testar e interagir com nossa API de forma segura e eficiente, garantindo que todos os pedidos estejam devidamente autenticados. [hashtag](https://api-docs.toconline.pt/autenticacao-detalhada#passo-1-obtencao-das-credenciais-de-acesso-a-nossa-api-comercial) Passo 1: Obtenção das credenciais de acesso à nossa API comercial ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Neste passo, deverão ser obtidos os seguintes dados, necessários para que possam aceder à nossa API comercial: > * Identificador (a que chamamos "OAUTH\_CLIENT\_ID", ou simplesmente "client\_id", nos exemplos posteriores) > > * Segredo (a que chamamos "OAUTH\_CLIENT\_SECRET", ou simplesmente "secret", nos exemplos posteriores) > > * Endereço de autenticação por OAuth (a que chamamos "OAUTH\_URL" nos exemplos posteriores) > > * Endereço de acesso à API (a que chamamos "API\_URL" nos exemplos posteriores) > Os três primeiros são requisitos para a autenticação (via OAuth) na API, juntamente com um outro, o endereço de retorno a que chamamos "OAUTH\_REDIRECT\_URL" nos exemplos posteriores e no exemplo em Ruby que foi enviado. O quarto é o endereço base de todos os pedidos feitos à API.O endereço de retorno, OAUTH\_REDIRECT\_URL, vem pré-fixado pelo nosso serviço de OAuth, e é o endereço "[https://oauth.pstmn.io/v1/callbackarrow-up-right](https://oauth.pstmn.io/v1/callback) ". Os quatro dados de acesso acima indicados são todos obtidos directamente da empresa à qual se pretende aceder via API. Para os obter, ou alterar o endereço de redirect, deverá fazer o seguinte: 1. Entrar na empresa com uma conta de Empresário ![](https://api-docs.toconline.pt/~gitbook/image?url=https%3A%2F%2F1863668386-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fk7sif7BY0rPzivMcj1HB%252Fuploads%252Ff2fnGF2J5L1yaB6hzE8c%252FEntrar%2520em%2520empresa.png%3Falt%3Dmedia%26token%3D562dbe04-931b-4bb9-8f72-9e68e1911f2d&width=768&dpr=4&quality=100&sign=295dc67&sv=2) 1. Aceder através do menu à opção Empresa > Configurações > Dados API ![](https://api-docs.toconline.pt/~gitbook/image?url=https%3A%2F%2F1863668386-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fk7sif7BY0rPzivMcj1HB%252Fuploads%252FtxLM4S05keSbdJavmn9a%252FMenu%253EEmpresa.png%3Falt%3Dmedia%26token%3Dc3d6a695-7463-4a10-8c29-d8c48594940e&width=768&dpr=4&quality=100&sign=f68c93ee&sv=2) 1. Introduzir os dados do integrador, que irá receber os dados de acesso à API através de um link temporário, de 72h. 1. Abrir o link de acesso enviado no email ![](https://api-docs.toconline.pt/~gitbook/image?url=https%3A%2F%2F1863668386-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fk7sif7BY0rPzivMcj1HB%252Fuploads%252FCCLcQCEoXy8AzsVWvqih%252FMenu%253EDadosApi.png%3Falt%3Dmedia%26token%3D64d46540-5ed0-4b2e-93e0-7c5a8f8f1df1&width=768&dpr=4&quality=100&sign=bebc7d7c&sv=2) [hashtag](https://api-docs.toconline.pt/autenticacao-detalhada#passo-2-autenticacao-no-nosso-servico-de-oauth-e-obtencao-do-token-de-acesso-a-api) Passo 2: Autenticação no nosso serviço de OAuth e obtenção do token de acesso à API ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Antes de poder aceder à API, o utilizador deverá autenticar-se no nosso serviço de OAuth e obter um token de acesso, chamado a partir de agora "access token", executando os passos seguintes. Esses passos, e um exemplo de código (Ruby) a executar, são também demonstrados no exemplo enviado.De acordo com as especificações do OAuth, a obtenção do código de acesso é feita em dois passos: ### [hashtag](https://api-docs.toconline.pt/autenticacao-detalhada#passo-2.1-obtencao-de-um-codigo-de-autorizacao-authorization_code) Passo 2.1: Obtenção de um código de autorização ("authorization\_code") Neste passo, deverá ser feito um pedido GET ao endereço OAUTH\_URL/auth com: 1. Na query do Url, os parâmetros: > * `client_id=OAUTH_CLIENT_ID`\- este é o primeiro dado dos quatro obtidos no [Passo 1: Obtenção das credenciais de acesso à nossa API comercial](https://api-docs.toconline.pt/autenticacao-detalhada#passo-1-obtencao-das-credenciais-de-acesso-a-nossa-api-comercial) > > * `redirect_uri=OAUTH_REDIRECT_URL` - salvo alteração posterior, é o endereço fixo indicado no passo 1. > > * `response_type=code` > > * `scope=commercial` > 1. Nos headers, os seguinte: > `Content-Type: application/json` circle-info Nota: Caso esteja a usar **Postman**, deverá ir a settings e desativar o campo '**Automatically follow redirects**'. O resultado, na consola, irá conter o _code_ necessário O exemplo seguinte ilustra o pedido feito no terminal, usando o curl: A resposta esperada é como a seguinte: Ou seja, a resposta esperada é um status 302 (Moved Temporarily) e deve conter um header chamado "Location" no qual se encontra o parâmetro "code" com o valor do código de autorização ("authorization\_code"). Enquanto o utilizador não implementar um diferente deste, que exista e possa efectivamente ser chamado (ver o passo 1 para como fazê-lo), o pedido efectuado, que responde com um status 302, não deverá prosseguir com o _redirect_ solicitado pela resposta.A única forma de responder a esse pedido é a de ignorar esse _redirect_, não chamando a “Location” devolvida, e simplesmente obter o código de autorização ("authorization\_code”) directamente do header “Location” da resposta.A forma de ignorar o _redirect_ depende do cliente Http utilizado, e terá que ser vista e implementada caso a caso. No caso do curl, que usámos nos exemplos anteriormente enviados, os _redirect_ são ignorados por omissão, só sendo executados se se utilizar a opção “-L”.Quando for configurado um "`OAUTH_REDIRECT_URL`" diferente (ver o passo 1 para como fazê-lo), então será feito um pedido a esse endereço, de onde poderá também ser obtido o "authorization\_code", que é enviado a esse endereço como o parâmetro "code" do Url. ### [hashtag](https://api-docs.toconline.pt/autenticacao-detalhada#passo-2.2-obtencao-de-um-token-de-acesso-a-api-access_token-e-de-um-codigo-de-actualizacao-deste-ref) Passo 2.2: Obtenção de um token de acesso à API ("access\_token") e de um código de actualização deste ("refresh\_token") Neste passo, deverá ser feito um pedido POST ao endereço OAUTH\_URL/token com: 1. No **body** do pedido, uma query "Url-encoded" com os parâmetros: > * `grant_type=authorization_code` > > * `code=authorization_code` - obtido do passo anterior. > > * `scope=commercial` > 1. Nos **headers**, os seguinte: > * `Content-Type: application/x-www-form-urlencoded` > > * `Accept: application/json` > > * `Authorization`: o texto "Basic", seguido dum espaço, seguido dum texto formado pela concatenação do "client\_id", seguido de ':', seguido do "secret", tudo codificado em base 64. Por exemplo, se o "client\_id" fosse "test" e o "secret" fosse "abcdef", o valor deste header seria "Basic dGVzdDphYmNkZWY=", sendo "dGVzdDphYmNkZWY=" o texto "test:abcdef" em base 64. > O exemplo seguinte ilustra o pedido feito no terminal, usando o curl: A resposta esperada é como a seguinte: Ou seja, a resposta esperada é um status 200 (OK) e um JSON no qual se encontra o parâmetro "`access_token`" e o "`refresh_token`". O "`access_token`" e o "`refresh_token`" deverão ser guardados para uso posterior. O "access\_token" terá que ser enviado (ver Passo 3) em TODOS os pedidos de acesso à API, tendo a validade definida no parâmetro "expires\_in" (em s) da resposta anterior. Após este tempo, os pedidos à API começarão a devolver um erro 401 (Unauthorized), e terá que ser pedido um novo "access\_token" (repetindo os passos 2.1 e 2.2) ou renovado o existente usando o "refresh\_token" (executando o passo 2.3). ### [hashtag](https://api-docs.toconline.pt/autenticacao-detalhada#passo-2.3-actualizacao-do-token-de-acesso-a-api-access_token-depois-deste-expirado-usando-o-codigo-d) Passo 2.3: Actualização do token de acesso à API ("access\_token") depois deste expirado, usando o código de actualização ("refresh\_token") obtido em 2.2 Neste passo, deverá ser feito um pedido POST ao endereço OAUTH\_URL/token com: 1. No body do pedido, uma query "Url-encoded" com os parâmetros: > * `grant_type=refresh_token` > > * `refresh_token=refresh_token` obtido do passo anterior, que deve ser guardado para esse efeito. > > * `scope=commercial` > 1. Nos headers, os seguinte: > * `Content-Type: application/x-www-form-urlencoded` > > * `Accept: application/json` > > * `Authorization`: o texto "Basic", seguido dum espaço, seguido dum texto formado pela concatenação do "client\_id", seguido de ':', seguido do "secret", tudo codificado em base 64. Por exemplo, se o "client\_id" fosse "test" e o "secret" fosse "abcdef", o valor deste header seria "`Basic dGVzdDphYmNkZWY=`", sendo "dGVzdDphYmNkZWY=" o texto "test:abcdef" em base 64. > O exemplo seguinte ilustra o pedido feito no terminal, usando o curl: A resposta esperada é como a seguinte: Ou seja, a resposta esperada é um status 200 (OK) e um JSON no qual se encontra o (novo) parâmetro "access\_token" e o (novo) "refresh\_token".O novo "access\_token" e o novo "refresh\_token", tal como no passo 2.2, deverão ser guardados para uso posterior. ### [hashtag](https://api-docs.toconline.pt/autenticacao-detalhada#passo-3-acesso-autenticado-a-api-comercial-usando-o-access_token-obtido-de-2.2-e-guardado) Passo 3: Acesso autenticado à API comercial, usando o "access\_token" obtido de 2.2 e guardado Todos os pedidos à API, cujos endereços são os documentados em [https://toconline.gitbook.io/documentacao-apiarrow-up-right](https://app.gitbook.com/s/yOlkai8btiTTydekYpN2) , são feitos para o endereço "API\_URL" seguido do nome do recurso. Além disso, todos os pedidos deverão conter obrigatoriamente os seguintes headers: > * `Content-Type: application/vnd.api+json` > > * `Accept: application/json` > > * `Authorization`: o texto "Bearer", seguido dum espaço, seguido do "access\_token" obtido do passo 2.2. > Os parâmetros adicionais a passar na query (no caso de GET) ou no body dos pedidos são os especificados pelo padrão JSONAPI, a que a nossa API obedece, e que estão documentados em [jsonapi.orgarrow-up-right](http://jsonapi.org/) . Como exemplo, indica-se um pedido GET ao recurso "commercial\_sales\_documents" (documentos de venda), paginado para devolver apenas os 5 primeiros registos. A resposta esperada, neste caso, é como a seguinte: Ou seja, e se não ocorrer nenhum erro (como o tentar uma consulta a algo que não existe, ou criar um registo com valores incorrectos), a resposta esperada é um status 200 (OK) e um JSON, no formato JSONAPI, contendo o registo ou os registos devolvidos (no caso dos GET), criados (POST) ou alterados (PATCH).Como se disse no passo 2.2, se o pedido devolver um status 401 (Unauthorized), provavelmente o "access\_token" já expirou, e terá que ser actualizado, ou pedido um novo efectuando novamente o passo 2. [PreviousAutenticação Simplificadachevron-left](https://api-docs.toconline.pt/autenticacao-simplificada) [NextCaracterísticas dos pedidoschevron-right](https://api-docs.toconline.pt/caracteristicas-dos-pedidos) Last updated 1 year ago * [Passo 1: Obtenção das credenciais de acesso à nossa API comercial](https://api-docs.toconline.pt/autenticacao-detalhada#passo-1-obtencao-das-credenciais-de-acesso-a-nossa-api-comercial) * [Passo 2: Autenticação no nosso serviço de OAuth e obtenção do token de acesso à API](https://api-docs.toconline.pt/autenticacao-detalhada#passo-2-autenticacao-no-nosso-servico-de-oauth-e-obtencao-do-token-de-acesso-a-api) * [Passo 2.1: Obtenção de um código de autorização ("authorization\_code")](https://api-docs.toconline.pt/autenticacao-detalhada#passo-2.1-obtencao-de-um-codigo-de-autorizacao-authorization_code) * [Passo 2.2: Obtenção de um token de acesso à API ("access\_token") e de um código de actualização deste ("refresh\_token")](https://api-docs.toconline.pt/autenticacao-detalhada#passo-2.2-obtencao-de-um-token-de-acesso-a-api-access_token-e-de-um-codigo-de-actualizacao-deste-ref) * [Passo 2.3: Actualização do token de acesso à API ("access\_token") depois deste expirado, usando o código de actualização ("refresh\_token") obtido em 2.2](https://api-docs.toconline.pt/autenticacao-detalhada#passo-2.3-actualizacao-do-token-de-acesso-a-api-access_token-depois-deste-expirado-usando-o-codigo-d) * [Passo 3: Acesso autenticado à API comercial, usando o "access\_token" obtido de 2.2 e guardado](https://api-docs.toconline.pt/autenticacao-detalhada#passo-3-acesso-autenticado-a-api-comercial-usando-o-access_token-obtido-de-2.2-e-guardado) sun-brightdesktopmoon Copy curl -v -H 'Content-Type: application/json' \ '/auth?client_id=\ &redirect_uri=http://127.0.0.1:4080/oauth/callback\ &response_type=code&scope=commercial' Copy GET /oauth/auth?client_id HTTP/1.1 &redirect_uri=http://127.0.0.1:4080/oauth/callback &response_type=code&scope=commercial HTTP/1.1 > Accept: */* > Content-Type: application/json > < HTTP/1.1 302 Moved Temporarily < Content-Type: text/html < Location: http://127.0.0.1:4080/oauth/callback? code= Copy curl -v -X POST -H 'Content-Type: application/x-www-form-urlencoded'\ -H 'Accept: application/json'\ -H 'Authorization: Basic ' \ -d 'grant_type=authorization_code&\ code=&scope=commercial' \ '/token' Copy POST /oauth/token HTTP/1.1 > Content-Type: application/x-www-form-urlencoded > Accept: application/json > Authorization: Basic dGVzdHM6ZWJhOTI3NjM3MzRlN2MwMg== > < HTTP/1.1 200 OK < Content-Type: application/json;charset=utf-8 < {"access_token":"10dc1d36e24b790540d087ea238ec345abd1a02daa73ae45a09", "expires_in":7890000, "refresh_token":"f71824c9e4675a8aa9661f18ae5341e977d37", "token_type":"Bearer"} Copy curl -v -X POST -H 'Content-Type: application/x-www-form-urlencoded'\ -H 'Accept: application/json'\ -H 'Authorization: Basic '\ -d 'grant_type=refresh_token&refresh_token=&scope=commercial' \ '/token' Copy POST /oauth/token HTTP/1.1 Content-Type: application/x-www-form-urlencoded Accept: application/json Authorization: Basic dGVzdHM6ZWJhOTI3NjM3MzRlN2MwMg== < HTTP/1.1 200 OK < Content-Type: application/json;charset=utf-8 < {"access_token":"b5604dacd4257355cb3692c79fe39490429b", "expires_in":7890000, "refresh_token":"47d3362c1394d8b230b399bd9ecad80b07dfb74b5e1d5ac", "token_type":"Bearer"} Copy curl -v -H 'Content-Type: application/vnd.api+json' \ -H 'Accept: application/json'\ -H 'Authorization: Bearer ' \ '/commercial_sales_documents?page[size]=5' Copy GET /commercial_sales_documents?page[size]=5 HTTP/1.1 Content-Type: application/vnd.api+json Accept: application/json Authorization: Bearer HTTP/1.1 200 OK Content-Type: application/vnd.api+json;charset=utf-8 {"data":[{"type":"commercial_sales_documents","id":"...","attributes":{...}}, ...]} sun-brightdesktopmoon --- # Vendas | TOConline - Documentação API [Documentos de Vendachevron-right](https://api-docs.toconline.pt/apis/vendas/documentos-de-venda) [Descarregar PDF de Documentos de Vendachevron-right](https://api-docs.toconline.pt/apis/vendas/descarregar-pdf-de-documentos-de-venda) [Descarregar PDF de Recibochevron-right](https://api-docs.toconline.pt/apis/vendas/descarregar-pdf-de-recibo) [Comunicação de documentos à ATchevron-right](https://api-docs.toconline.pt/apis/vendas/comunicacao-de-documentos-a-at) [Recibos de Vendachevron-right](https://api-docs.toconline.pt/apis/vendas/recibos-de-venda) [Envio de Documentos por emailchevron-right](https://api-docs.toconline.pt/apis/vendas/envio-de-documentos-por-email) [Envio de Recibos por emailchevron-right](https://api-docs.toconline.pt/apis/vendas/envio-de-recibos-por-email) [PreviousProdutos e Serviçoschevron-left](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos) [NextDocumentos de Vendachevron-right](https://api-docs.toconline.pt/apis/vendas/documentos-de-venda) Last updated 1 year ago sun-brightdesktopmoon sun-brightdesktopmoon --- # Descarregar PDF de Recibo | TOConline - Documentação API ### [hashtag](https://api-docs.toconline.pt/apis/vendas/descarregar-pdf-de-recibo#obter-caminho-para-ficheiro) Obter Caminho para Ficheiro circle-exclamation Para um documento ser descarregado, o mesmo deve estar com um estado (status) de finalizado (status = 1) . De modo a descarregar o PDF de um documento, deverá realizar um pedido à seguinte rota: GET Copy /api/url_for_print/?filter[type]=Document&filter[copies]=1 circle-info Para obter o id do Documento de Compra pretendido (document\_id) poderá consultar: [Documentos de Compra](https://api-docs.toconline.pt/apis/compras/documentos-de-compra#obter-todos-os-documentos-de-compra-finalizados) Tal como nos restantes pedidos especificados anteriormente, o corresponde ao token de acesso válido devolvido pelo serviço de OAuth ### [hashtag](https://api-docs.toconline.pt/apis/vendas/descarregar-pdf-de-recibo#descarregar-ficheiro) Descarregar Ficheiro Utilizando a resposta recebida, deverá concatenar os atributos: scheme + "://" + host + path, e irá obter o link através do qual a transferência é imediata. Neste caso, seria: GET Copy /public-file/path_to_file [PreviousDescarregar PDF de Documentos de Vendachevron-left](https://api-docs.toconline.pt/apis/vendas/descarregar-pdf-de-documentos-de-venda) [NextComunicação de documentos à ATchevron-right](https://api-docs.toconline.pt/apis/vendas/comunicacao-de-documentos-a-at) Last updated 1 year ago * [Obter Caminho para Ficheiro](https://api-docs.toconline.pt/apis/vendas/descarregar-pdf-de-recibo#obter-caminho-para-ficheiro) * [Descarregar Ficheiro](https://api-docs.toconline.pt/apis/vendas/descarregar-pdf-de-recibo#descarregar-ficheiro) sun-brightdesktopmoon sun-brightdesktopmoon --- # Vendas | TOConline - Documentação API [Documentos de Vendachevron-right](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/documentos-de-venda) [Recibos de Vendachevron-right](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/recibos-de-venda) [PreviousVersões Anterioreschevron-left](https://api-docs.toconline.pt/apis/versoes-anteriores) [NextDocumentos de Vendachevron-right](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/documentos-de-venda) Last updated 1 year ago sun-brightdesktopmoon sun-brightdesktopmoon --- # Compras | TOConline - Documentação API [Documentos de Comprachevron-right](https://api-docs.toconline.pt/apis/compras/documentos-de-compra) [Descarregar PDF de Documentos de Comprachevron-right](https://api-docs.toconline.pt/apis/compras/descarregar-pdf-de-documentos-de-compra) [Comunicação de documentos à ATchevron-right](https://api-docs.toconline.pt/apis/compras/comunicacao-de-documentos-a-at) [Pagamentoschevron-right](https://api-docs.toconline.pt/apis/compras/pagamentos) [PreviousEnvio de Recibos por emailchevron-left](https://api-docs.toconline.pt/apis/vendas/envio-de-recibos-por-email) [NextDocumentos de Comprachevron-right](https://api-docs.toconline.pt/apis/compras/documentos-de-compra) Last updated 1 year ago sun-brightdesktopmoon sun-brightdesktopmoon --- # Versões Anteriores | TOConline - Documentação API [Vendaschevron-right](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas) [Compraschevron-right](https://api-docs.toconline.pt/apis/versoes-anteriores/compras) [PreviousComunicação de documentos à ATchevron-left](https://api-docs.toconline.pt/apis/compras/comunicacao-de-documentos-a-at) [NextVendaschevron-right](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas) Last updated 1 year ago sun-brightdesktopmoon sun-brightdesktopmoon --- # Descarregar PDF de Documentos de Venda | TOConline - Documentação API ### [hashtag](https://api-docs.toconline.pt/apis/vendas/descarregar-pdf-de-documentos-de-venda#obter-caminho-para-ficheiro) Obter Caminho para Ficheiro circle-exclamation Para um documento ser descarregado, o mesmo deve estar com um estado (status) de finalizado (status = 1) . ### [hashtag](https://api-docs.toconline.pt/apis/vendas/descarregar-pdf-de-documentos-de-venda#get-api-url_for_print-salesdocumentid) Descarregar PDF de Documentos de Venda get {{base\_url}}/api/url\_for\_print/{salesDocumentId} Descarregar PDF de Documentos de Venda chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Path parameters salesDocumentIdstringRequired Id do documento de venda Example: `10` Query parameters filter\[type\]stringOptional Tipo do documento a imprimir (Document = Documento de venda) Example: `Document` Responses chevron-right 200 Descarregar PDF de Documentos de Venda / Descarregar PDF de Documentos de Venda application/json Headersobject Show Headersplus Responseobject Show propertiesplus get /api/url\_for\_print/{salesDocumentId} HTTPchevron-down HTTPcURLJavaScriptPython Test it 200 Descarregar PDF de Documentos de Venda / Descarregar PDF de Documentos de Venda circle-info Para obter o id do Documento de Compra pretendido (document\_id) poderá consultar: [Documentos de Compra](https://api-docs.toconline.pt/apis/compras/documentos-de-compra#obter-todos-os-documentos-de-compra-finalizados) Tal como nos restantes pedidos especificados anteriormente, o corresponde ao token de acesso válido devolvido pelo serviço de OAuth ### [hashtag](https://api-docs.toconline.pt/apis/vendas/descarregar-pdf-de-documentos-de-venda#descarregar-ficheiro) Descarregar Ficheiro Utilizando a resposta recebida, deverá concatenar os atributos: scheme + "://" + host + path, e irá obter o link através do qual a transferência é imediata. Neste caso, seria: [PreviousRecibos de Vendachevron-left](https://api-docs.toconline.pt/apis/vendas/recibos-de-venda) [NextDescarregar PDF de Recibochevron-right](https://api-docs.toconline.pt/apis/vendas/descarregar-pdf-de-recibo) Last updated 1 year ago * [Obter Caminho para Ficheiro](https://api-docs.toconline.pt/apis/vendas/descarregar-pdf-de-documentos-de-venda#obter-caminho-para-ficheiro) * [GETDescarregar PDF de Documentos de Venda](https://api-docs.toconline.pt/apis/vendas/descarregar-pdf-de-documentos-de-venda#get-api-url_for_print-salesdocumentid) * [Descarregar Ficheiro](https://api-docs.toconline.pt/apis/vendas/descarregar-pdf-de-documentos-de-venda#descarregar-ficheiro) sun-brightdesktopmoon Copy GET /api/url_for_print/{salesDocumentId} HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Accept: */* Copy { "data": { "attributes": { "url": { "host": "integration.toconline.pt", "path": "/public-file/eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJleHAiOjIwODgwOTYyMDksImlhdCI6MTcwOTY2NDIwOSwibmJmIjoxNzA5NjY0MjA5LCJhcmNoaXZlIjp7ImlkIjoiY1dQSUxkVlkyIiwiZW50aXR5X2lkIjoiODAwMDAwMDQ2In19.herbicMeAYAzFgcb22h9uUZDugfYiGCYokXakor3nIVSo2psCyZLvN9Ps1vH4SUTkfe4cW0mWuOveujHnNby7fA4JoOvoqZX18vw1hRrmPANtW8n3yg62sjiw6PWR7WIMgXPPdXQbS8peHHTo5E6i2qSd16a40mzarSEbc3y8TRppjr1NpKTVyZKL6eWT9Av7xk23X4M-AHOxZzmgsyFA4RVr2ggk_Fqdj1eFbBobvC8y0-dtckvOzS7_ihjaLUTReBCT9Ic-cVV0LrwpIXYEa6nKHG_r3Pzdw2K_jesJHGGDQjgbQEXvKBAu8vOJhoFCRuGpdZTG9H02pdaCFGRWA", "port": 443, "scheme": "https" } }, "id": "10", "type": "url_for_print" } } Endpoint Copy https://app.toconline.pt/api/url_for_print/?filter[type]=Document&filter[copies]=1 Copy https://app.toconline.pt/public-file/path_to_file sun-brightdesktopmoon --- # Comunicação de documentos à AT | TOConline - Documentação API [hashtag](https://api-docs.toconline.pt/apis/vendas/comunicacao-de-documentos-a-at#pedir-comunicacao-de-documentos) Pedir comunicação de documentos -------------------------------------------------------------------------------------------------------------------------------------------------------- Pode enviar 3 tipos de documentos à Autoridade Tributária: * _sales\_document_: documentos de venda * _shipment\_document_: guias * _purchases\_shipment\_document_: guias de devolução a fornecedor De modo a comunicar um documento, deverá realizar um pedido POST, para o endpoint: _send\_document\_at\_webservice_ [hashtag](https://api-docs.toconline.pt/apis/vendas/comunicacao-de-documentos-a-at#comunicacao-de-documentos) Comunicação de documentos -------------------------------------------------------------------------------------------------------------------------------------------- `PATCH` `/send_document_at_webservice` #### [hashtag](https://api-docs.toconline.pt/apis/vendas/comunicacao-de-documentos-a-at#request-body) Request Body Name Type Description data\* object 200: OK Copy { data: { type: 'send_document_at_webservice', id: '', attributes: { communication_status: , communication_code: , communication_message: } } } O payload a utilizar para a comunicação é o seguinte: circle-info "entity\_username" -> Nome de utilizador usado para acesso ao Portal das finanças. "entity\_password" -> Palavra-passe usada para acesso ao Portal das Finanças. A resposta ao pedido trará informação sobre o sucesso/insucesso da operação no seguinte formato: O campo _communication\_code_ terá o código de comunicação à Autoridade Tributária no caso do documento comunicado ter sido uma guia (vendas ou compras). [PreviousDescarregar PDF de Recibochevron-left](https://api-docs.toconline.pt/apis/vendas/descarregar-pdf-de-recibo) [NextEnvio de Documentos por emailchevron-right](https://api-docs.toconline.pt/apis/vendas/envio-de-documentos-por-email) Last updated 1 year ago * [Pedir comunicação de documentos](https://api-docs.toconline.pt/apis/vendas/comunicacao-de-documentos-a-at#pedir-comunicacao-de-documentos) * [Comunicação de documentos](https://api-docs.toconline.pt/apis/vendas/comunicacao-de-documentos-a-at#comunicacao-de-documentos) sun-brightdesktopmoon Copy curl -v -X POST -H 'Content-Type: application/vnd.api+json'\ -H 'Accept: application/json'\ -H 'Authorization: Bearer '\ -d '' '/send_document_at_webservice' Payload Copy { "data": { "type": "send_document_at_webservice", "id": 2, "attributes": { "document_type": "", "entity_username": "", "entity_password": "" } } } Response Copy { "data": { "id": "", "type": "send_document_at_webservice", "attributes": { "communication_message": "", "communication_code": "", "communication_status": "", } } } sun-brightdesktopmoon --- # Compras | TOConline - Documentação API [Documentos de Comprachevron-right](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/documentos-de-compra) [Pagamentoschevron-right](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/pagamentos) [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/compras#undefined) -------------------------------------------------------------------------------------- [PreviousRecibos de Vendachevron-left](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/recibos-de-venda) [NextDocumentos de Comprachevron-right](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/documentos-de-compra) Last updated 1 year ago sun-brightdesktopmoon sun-brightdesktopmoon --- # Descarregar PDF de Pagamentos | TOConline - Documentação API ### [hashtag](https://api-docs.toconline.pt/apis/compras/descarregar-pdf-de-pagamentos#obter-caminho-para-ficheiro) Obter Caminho para Ficheiro circle-exclamation Para um documento ser descarregado, o mesmo deve estar com um estado (status) de finalizado (status = 1) . De modo a descarregar o PDF de um documento, deverá realizar um pedido à seguinte rota: GET Copy https://app.toconline.pt/api/url_for_print/?filter[type]=PurchasesDocument&filter[copies]=1 circle-info Para obter o id do Documento de Compra pretendido (document\_id) poderá consultar: [Documentos de Compra](https://api-docs.toconline.pt/apis/compras/documentos-de-compra#obter-todos-os-documentos-de-compra-finalizados) Tal como nos restantes pedidos especificados anteriormente, o corresponde ao token de acesso válido devolvido pelo serviço de OAuth ### [hashtag](https://api-docs.toconline.pt/apis/compras/descarregar-pdf-de-pagamentos#descarregar-ficheiro) Descarregar Ficheiro Utilizando a resposta recebida, deverá concatenar os atributos: scheme + "://" + host + path, e irá obter o link através do qual a transferência é imediata. Neste caso, seria: GET Copy https://app.toconline.pt/public-file/path_to_file [PreviousDescarregar PDF de Documentos de Comprachevron-left](https://api-docs.toconline.pt/apis/compras/descarregar-pdf-de-documentos-de-compra) [NextComunicação de documentos à ATchevron-right](https://api-docs.toconline.pt/apis/compras/comunicacao-de-documentos-a-at) Last updated 1 year ago * [Obter Caminho para Ficheiro](https://api-docs.toconline.pt/apis/compras/descarregar-pdf-de-pagamentos#obter-caminho-para-ficheiro) * [Descarregar Ficheiro](https://api-docs.toconline.pt/apis/compras/descarregar-pdf-de-pagamentos#descarregar-ficheiro) sun-brightdesktopmoon sun-brightdesktopmoon --- # Comunicação de documentos à AT | TOConline - Documentação API [hashtag](https://api-docs.toconline.pt/apis/compras/comunicacao-de-documentos-a-at#pedir-comunicacao-de-documentos) Pedir comunicação de documentos --------------------------------------------------------------------------------------------------------------------------------------------------------- Pode enviar 3 tipos de documentos à Autoridade Tributária: * _sales\_document_: documentos de venda * _shipment\_document_: guias * _purchases\_shipment\_document_: guias de devolução a fornecedor De modo a comunicar um documento, deverá realizar um pedido POST, para o endpoint: _send\_document\_at\_webservice_ [hashtag](https://api-docs.toconline.pt/apis/compras/comunicacao-de-documentos-a-at#comunicacao-de-documentos) Comunicação de documentos --------------------------------------------------------------------------------------------------------------------------------------------- `PATCH` `/send_document_at_webservice` #### [hashtag](https://api-docs.toconline.pt/apis/compras/comunicacao-de-documentos-a-at#request-body) Request Body Name Type Description data\* object 200: OK Copy { data: { type: 'send_document_at_webservice', id: '', attributes: { communication_status: , communication_code: , communication_message: } } } O payload a utilizar para a comunicação é o seguinte: circle-info "entity\_username" -> Nome de utilizador usado para acesso ao Portal das finanças. "entity\_password" -> Palavra-passe usada para acesso ao Portal das Finanças. A resposta ao pedido trará informação sobre o sucesso/insucesso da operação no seguinte formato: O campo _communication\_code_ terá o código de comunicação à Autoridade Tributária no caso do documento comunicado ter sido uma guia (vendas ou compras). [PreviousDescarregar PDF de Pagamentoschevron-left](https://api-docs.toconline.pt/apis/compras/descarregar-pdf-de-pagamentos) [NextVersões Anterioreschevron-right](https://api-docs.toconline.pt/apis/versoes-anteriores) Last updated 1 year ago * [Pedir comunicação de documentos](https://api-docs.toconline.pt/apis/compras/comunicacao-de-documentos-a-at#pedir-comunicacao-de-documentos) * [Comunicação de documentos](https://api-docs.toconline.pt/apis/compras/comunicacao-de-documentos-a-at#comunicacao-de-documentos) sun-brightdesktopmoon Copy curl -v -X POST -H 'Content-Type: application/vnd.api+json'\ -H 'Accept: application/json'\ -H 'Authorization: Bearer '\ -d '' '/send_document_at_webservice' Payload Copy { "data": { "type": "send_document_at_webservice", "id": 2, "attributes": { "document_type": "", "entity_username": "", "entity_password": "" } } } Response Copy { "data": { "id": "", "type": "send_document_at_webservice", "attributes": { "communication_message": "", "communication_code": "", "communication_status": "", } } } sun-brightdesktopmoon --- # Descarregar PDF de Documentos de Compra | TOConline - Documentação API ### [hashtag](https://api-docs.toconline.pt/apis/compras/descarregar-pdf-de-documentos-de-compra#obter-caminho-para-ficheiro) Obter Caminho para Ficheiro circle-exclamation Para um documento ser descarregado, o mesmo deve estar com um estado (status) de finalizado (status = 1) . De modo a descarregar o PDF de um documento, deverá realizar um pedido à seguinte rota: ### [hashtag](https://api-docs.toconline.pt/apis/compras/descarregar-pdf-de-documentos-de-compra#get-api-url_for_print-purchasesdocumentid) Descarregar PDF de Documentos de Compra get {{base\_url}}/api/url\_for\_print/{purchasesDocumentId} Descarregar PDF de Documentos de Compra chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Path parameters purchasesDocumentIdstringRequired Id do documento de compra Example: `10` Query parameters filter\[type\]stringOptional Tipo do documento a imprimir (PurchasesDocument = Documento de compra) Example: `PurchasesDocument` Responses chevron-right 200Success No content get /api/url\_for\_print/{purchasesDocumentId} HTTPchevron-down HTTPcURLJavaScriptPython Test it 200Success No content circle-info Para obter o id do Documento de Compra pretendido (document\_id) poderá consultar: [Documentos de Compra](https://api-docs.toconline.pt/apis/compras/documentos-de-compra#obter-todos-os-documentos-de-compra-finalizados) Tal como nos restantes pedidos especificados anteriormente, o corresponde ao token de acesso válido devolvido pelo serviço de OAuth ### [hashtag](https://api-docs.toconline.pt/apis/compras/descarregar-pdf-de-documentos-de-compra#descarregar-ficheiro) Descarregar Ficheiro Utilizando a resposta recebida, deverá concatenar os atributos: scheme + "://" + host + path, e irá obter o link através do qual a transferência é imediata. Neste caso, seria: [PreviousPagamentoschevron-left](https://api-docs.toconline.pt/apis/compras/pagamentos) [NextDescarregar PDF de Pagamentoschevron-right](https://api-docs.toconline.pt/apis/compras/descarregar-pdf-de-pagamentos) Last updated 1 year ago * [Obter Caminho para Ficheiro](https://api-docs.toconline.pt/apis/compras/descarregar-pdf-de-documentos-de-compra#obter-caminho-para-ficheiro) * [GETDescarregar PDF de Documentos de Compra](https://api-docs.toconline.pt/apis/compras/descarregar-pdf-de-documentos-de-compra#get-api-url_for_print-purchasesdocumentid) * [Descarregar Ficheiro](https://api-docs.toconline.pt/apis/compras/descarregar-pdf-de-documentos-de-compra#descarregar-ficheiro) sun-brightdesktopmoon Copy GET /api/url_for_print/{purchasesDocumentId} HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Accept: */* GET Copy https://app.toconline.pt/public-file/path_to_file sun-brightdesktopmoon --- # Envio de Recibos por email | TOConline - Documentação API ### [hashtag](https://api-docs.toconline.pt/apis/vendas/envio-de-recibos-por-email#patch-api-email-document) Envio de Documentos por email patch {{base\_url}}/api/email/document Envio de Documentos por email chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Body application/jsonchevron-down application/json dataobjectOptional Show propertiesplus Responses chevron-right 200Success No content patch /api/email/document HTTPchevron-down HTTPcURLJavaScriptPython Envio de Documentos por emailchevron-down Envio de Documentos por emailEnvio de Recibos por email Test it 200Success No content Copy curl -v -X POST -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer ' -d '' '/email/document/' No pedido acima, o _access\_token_ é o _token_ de acesso válido devolvido pelo serviço de OAuth e o _id do documento ou recibo_ é o "id" interno do documento ou do recibo (cabeçalho), o devolvido no campo "id" da resposta ao seu pedido de criação. O _payload_ JSON a enviar contém a seguinte informação: Payload Copy { "data": { "type": "email/document", // [OBRIGATÓRIO] "id": "", // [OBRIGATÓRIO] Este "id" é o devolvido na resposta ao pedido de criação do cabeçalho do documento ou do recibo, ver acima "attributes": { "type": "Receipt", // [OBRIGATÓRIO "Receipt" para recibos\ "to_email": "[email protected]", // [OPCIONAL] Por omissão é o endereço de email do cliente; se não existir tem que ser indicado. Podem ser vários, separados por ,\ "from_email": "[email protected]", // [OPCIONAL] Por omissão é o endereço no-reply de email do sistema (TOConline, Business...)\ "from_name": "Nome do remetente", // [OPCIONAL]\ "subject": "Assunto da mensagem" // [OPCIONAL] Por omissão é o assunto padrão do sistema ("(Nome da empresa) enviou-lhe um documento/recibo através do (TOConline, Business...)")\ }\ }\ }\ \ [PreviousEnvio de Documentos por emailchevron-left](https://api-docs.toconline.pt/apis/vendas/envio-de-documentos-por-email)\ [NextCompraschevron-right](https://api-docs.toconline.pt/apis/compras)\ \ Last updated 1 year ago\ \ sun-brightdesktopmoon\ \ Copy\ \ PATCH /api/email/document HTTP/1.1\ Host: {{base_url}}\ Authorization: Bearer YOUR_OAUTH2_TOKEN\ Content-Type: application/json\ Accept: */*\ Content-Length: 226\ \ {\ "data": {\ "attributes": {\ "from_email": "[email protected]",\ "from_name": "Nome do remetente",\ "subject": "Assunto da mensagem",\ "to_email": "[email protected]",\ "type": "Document"\ },\ "id": 3,\ "type": "email/document"\ }\ }\ \ Exemplo de Response\ \ Copy\ \ {\ "success": true,\ "to_addresses": "[email protected]"\ }\ \ sun-brightdesktopmoon --- # Envio de Documentos por email | TOConline - Documentação API ### [hashtag](https://api-docs.toconline.pt/apis/vendas/envio-de-documentos-por-email#patch-api-email-document) Envio de Documentos por email patch {{base\_url}}/api/email/document Envio de Documentos por email chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Body application/jsonchevron-down application/json dataobjectOptional Show propertiesplus Responses chevron-right 200Success No content patch /api/email/document HTTPchevron-down HTTPcURLJavaScriptPython Envio de Documentos por emailchevron-down Envio de Documentos por emailEnvio de Recibos por email Test it 200Success No content Copy curl -v -X PATCH -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer ' -d '' '/email/document/' No pedido acima, o _access\_token_ é o _token_ de acesso válido devolvido pelo serviço de OAuth e o _id do documento ou recibo_ é o "id" interno do documento ou do recibo (cabeçalho), o devolvido no campo "id" da resposta ao seu pedido de criação. O _payload_ JSON a enviar contém a seguinte informação: Payload Copy { "data": { "type": "email/document", // [OBRIGATÓRIO] "id": "", // [OBRIGATÓRIO] Este "id" é o devolvido na resposta ao pedido de criação do cabeçalho do documento ou do recibo, ver acima "attributes": { "type": "Document|Receipt", // [OPCIONAL] Por omissão "Document": "Document" para documentos de venda, "Receipt" para recibos "to_email": "[email protected]", // [OPCIONAL] Por omissão é o endereço de email do cliente; se não existir tem que ser indicado. Podem ser vários, separados por , "from_email": "[email protected]", // [OPCIONAL] Por omissão é o endereço no-reply de email do sistema (TOConline, Business...) "from_name": "Nome do remetente", // [OPCIONAL] "subject": "Assunto da mensagem" // [OPCIONAL] Por omissão é o assunto padrão do sistema ("(Nome da empresa) enviou-lhe um documento/recibo através do (TOConline, Business...)") } } } [PreviousComunicação de documentos à ATchevron-left](https://api-docs.toconline.pt/apis/vendas/comunicacao-de-documentos-a-at) [NextEnvio de Recibos por emailchevron-right](https://api-docs.toconline.pt/apis/vendas/envio-de-recibos-por-email) Last updated 1 year ago sun-brightdesktopmoon Copy PATCH /api/email/document HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Content-Type: application/json Accept: */* Content-Length: 226 { "data": { "attributes": { "from_email": "[email protected]", "from_name": "Nome do remetente", "subject": "Assunto da mensagem", "to_email": "[email protected]", "type": "Document" }, "id": 3, "type": "email/document" } } Exemplo de Response Copy { "success": true, "to_addresses": "[email protected]" } sun-brightdesktopmoon --- # Documentos de Compra | TOConline - Documentação API Os documentos de compra na versão v1 da API têm a mesma estrutura anteriormente descrita para a v0: são compostos por um cabeçalho e uma ou mais linhas. Nesta nova versão, é possível criar ambos num só pedido, descrito de seguida. [hashtag](https://api-docs.toconline.pt/apis/compras/documentos-de-compra#criar-documento-de-compra) Criar Documento de Compra ----------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://api-docs.toconline.pt/apis/compras/documentos-de-compra#post-api-v1-commercial_purchases_documents) Criar Cabeçalho de Documentos de Compra post {{base\_url}}/api/v1/commercial\_purchases\_documents Criar Cabeçalho de Documentos de Compra chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Body application/jsonchevron-down application/json currency\_conversion\_ratenumberOptionalExample: `1.21` currency\_idnumberOptionalExample: `1` currency\_iso\_codestringOptionalExample: `USD` datestringOptionalExample: `2023-01-01` document\_series\_idnumberOptionalExample: `1` document\_typestringOptionalExample: `FC` due\_datestringOptionalExample: `2023-02-01` external\_referencestringOptionalExample: `Referência do documento externo` linesobject\[\]OptionalExample: `[{"item_id":2,"item_type":"Product","tax_id":1,"unit_of_measure_id":2}]` Show propertiesplus notesstringOptionalExample: `Notas ao documento` retention\_totalnumberOptionalExample: `9.99` retention\_typestringOptionalExample: `TD` settlement\_expressionstringOptionalExample: `7.5` supplier\_address\_detailstringOptionalExample: `Morada do fornecedor` supplier\_business\_namestringOptionalExample: `Nome do fornecedor` supplier\_citystringOptionalExample: `Cidade/Localidade do fornecedor` supplier\_countrystringOptionalExample: `PT` supplier\_idnumberOptionalExample: `1` supplier\_postcodestringOptionalExample: `0000-000` supplier\_tax\_registration\_numberstringOptionalExample: `999999990` tax\_exemption\_reason\_idnumberOptionalExample: `1` vat\_included\_pricesbooleanOptionalExample: `false` Responses chevron-right 200Success No content post /api/v1/commercial\_purchases\_documents HTTPchevron-down HTTPcURLJavaScriptPython Test it 200Success No content O _payload_ JSON a enviar contém a seguinte informação: circle-info **Nota 1:** A série associada ao documento tem já que existir, e o seu "id" interno pode ser obtido por um circle-info Nota 2: Se o fornecedor for identificado pelo seu "id" interno tem já que existir, e o seu "id" interno pode ser obtido por um circle-info **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 circle-info **Nota 4**: O "id" interno do motivo de isenção deve ser obtido por um circle-info **Nota 5**: O "id" interno da moeda deve ser obtido por um circle-info Nota 6: O item (produto ou categoria de despesas) tem já que existir, e o seu "id" interno pode ser obtido por um circle-info **Nota 7**: A unidade de medida tem já que existir, e o seu "id" interno pode ser obtido por um circle-info **Nota 8:** O "id" interno da taxa de IVA deve ser obtido por um [hashtag](https://api-docs.toconline.pt/apis/compras/documentos-de-compra#alteracao-do-documento-de-compra) Alteração do Documento de Compra ------------------------------------------------------------------------------------------------------------------------------------------------- triangle-exclamation Após a criação de um documento de compra este fica automaticamente finalizado, se pretender criar documentos sem finalizar pode consultar a versão anterior desta API: [Documentos de Compra](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/documentos-de-compra) Quando um documento é criado em um estado finalizado, torna-se impossível executar as seguintes operações em documentos de compra: * Finalização do Documento de Compra * Anulação do Documento de Compra * AtualizarDocumento de Compra * Eliminação do Documento de Compra [hashtag](https://api-docs.toconline.pt/apis/compras/documentos-de-compra#consulta-do-documento) Consulta do documento --------------------------------------------------------------------------------------------------------------------------- Os documentos podem ser consultados a qualquer altura, antes ou depois de finalizados, e mesmo depois de anulados. ### [hashtag](https://api-docs.toconline.pt/apis/compras/documentos-de-compra#get-api-v1-commercial_purchases_documents) Obter Todos os Documentos de Compra Finalizados get {{base\_url}}/api/v1/commercial\_purchases\_documents Obter Todos os Documentos de Compra Finalizados chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Query parameters filter\[status\]stringOptional @@@@@@@@@ Example: `1` Responses chevron-right 200Success No content get /api/v1/commercial\_purchases\_documents HTTPchevron-down HTTPcURLJavaScriptPython Test it 200Success No content [PreviousCompraschevron-left](https://api-docs.toconline.pt/apis/compras) [NextPagamentoschevron-right](https://api-docs.toconline.pt/apis/compras/pagamentos) Last updated 1 year ago * [Criar Documento de Compra](https://api-docs.toconline.pt/apis/compras/documentos-de-compra#criar-documento-de-compra) * [POSTCriar Cabeçalho de Documentos de Compra](https://api-docs.toconline.pt/apis/compras/documentos-de-compra#post-api-v1-commercial_purchases_documents) * [Alteração do Documento de Compra](https://api-docs.toconline.pt/apis/compras/documentos-de-compra#alteracao-do-documento-de-compra) * [Consulta do documento](https://api-docs.toconline.pt/apis/compras/documentos-de-compra#consulta-do-documento) * [GETObter Todos os Documentos de Compra Finalizados](https://api-docs.toconline.pt/apis/compras/documentos-de-compra#get-api-v1-commercial_purchases_documents) sun-brightdesktopmoon Copy POST /api/v1/commercial_purchases_documents HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Content-Type: application/json Accept: */* Content-Length: 722 { "currency_conversion_rate": 1.21, "currency_id": 1, "currency_iso_code": "USD", "date": "2023-01-01", "document_series_id": 1, "document_type": "FC", "due_date": "2023-02-01", "external_reference": "Referência do documento externo", "lines": [\ {\ "item_id": 2,\ "item_type": "Product",\ "tax_id": 1,\ "unit_of_measure_id": 2\ }\ ], "notes": "Notas ao documento", "retention_total": 9.99, "retention_type": "TD", "settlement_expression": "7.5", "supplier_address_detail": "Morada do fornecedor", "supplier_business_name": "Nome do fornecedor", "supplier_city": "Cidade/Localidade do fornecedor", "supplier_country": "PT", "supplier_id": 1, "supplier_postcode": "0000-000", "supplier_tax_registration_number": "999999990", "tax_exemption_reason_id": 1, "vat_included_prices": false } Copy { // Identificação do documento "document_type": "FC|DSP", // [OBRIGATÓRIO] Tipo de documento. "FC": fatura, "DSP": fatura de despesas. "date": "2023-01-01", // [OPCIONAL] Data do documento; por omissão, a data do pedido. // [OPCIONAL] Identificação da série do documento. Por omissão, aplicam-se as regras configuradas na empresa para escolha da série. // Se a série for indicada, usar apenas um dos dois campos seguintes (o "id" ou o prefixo). Se se indicarem os dois, então devem ser consistentes. "document_series_id": 1, // [OPCIONAL] Identificador interno da série. Ver NOTA 1 abaixo. "document_series_prefix": "Prefixo da série", // [OPCIONAL] Em alternativa ao campo "document_series_id". // [OPCIONAL] Identificação do fornecedor. Por omissão, é o fornecedor indiferenciado (NIF "999999990"). // Se o fornecedor for indicado, usar apenas um dos dois campos seguintes (o "id" ou o NIF). Se se indicarem os dois, então devem ser consistentes. "supplier_id": 1, // [OPCIONAL] Identificador interno do fornecedor. Ver NOTA 2. "supplier_tax_registration_number": "999999990", // [OPCIONAL] NIF do fornecedor. se o fornecedor com o NIF indicado não existir, será criado automaticamente. Se o país ("supplier_country") for Portugal ("PT", "PT-AC" ou "PT-MA"), deve ser um NIF português válido. // [OPCIONAL] Os atributos seguintes são usados na criação do fornecedor, se não existir ainda. // Se o fornecedor já existir, são guardados no documento, mas a ficha do fornecedor não é actualizada. "supplier_business_name": "Nome do fornecedor", // [OBRIGATÓRIO] caso o fornecedor ainda não exista e tenha que ser criado. [OPCIONAL] nos outros casos, a não ser que exista mais do que um fornecedor com o NIF indicado, usando-se então o nome para o identificar. "supplier_address_detail": "Morada do fornecedor", // [OPCIONAL] "supplier_postcode": "0000-000", // [OPCIONAL] Código postal do fornecedor, no formato 0000-000. "supplier_city": "Cidade/Localidade do fornecedor", // [OPCIONAL] "supplier_country": "PT", // [OPCIONAL] País do fornecedor. Por omissão, "PT"; é o código ISO alpha-2 do país do fornecedor (vd. https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2; ver também a NOTA 3. // [OPCIONAL] Condições de pagamento "due_date": "2023-02-01", // [OPCIONAL] Data de vencimento; por omissão, a data do documento, ou a referente ao prazo de pagamento configurado no fornecedor, se o fornecedor tiver configurado um prazo de pagamento. "settlement_expression": "7.5", // [OPCIONAL] Desconto no cabeçalho, em percentagem; são suportados descontos compostos, como "3+5" // [OPCIONAL] IVA "vat_included_prices": false, // [OPCIONAL] Os preços nas linhas são com IVA incluído? Por omissão, não (false). "tax_exemption_reason_id": 1, // Motivo de isenção de IVA. [OBRIGATÓRIO] apenas se o documento tiver pelo menos uma linha isenta de IVA. Não deve ser indicado nos restantes casos. Ver NOTA 4. // [OPCIONAL] Moeda. Por omissão, "EUR". // Se a moeda for indicada, usar apenas um dos dois campos seguintes (o "id" ou o código ISO). Se se indicarem os dois, então devem ser consistentes. "currency_id": 1, // [OPCIONAL] Identificador interno da moeda. Ver NOTA 5. "currency_iso_code": "USD", // [OPCIONAL] É o código ISO da moeda do documento (vd. https://en.wikipedia.org/wiki/ISO_4217). "currency_conversion_rate": 1.21, // [OMITIDO] se a moeda for "EUR". [OBRIGATÓRIO] nos restantes casos; é a taxa de conversão para EUR (1 EUR = n USD|...). // [OPCIONAL] Retenção "retention_total": 9.99, // [OPCIONAL] Valor total de retenção. "retention_type": "TD|TI|C|P|CPS|O", // [OPCIONAL] Tipo de retenção. TD: Trabalho dependente, TI: Trabalho independente, C: Capitais, P: Prediais, CPS: Comissões e Prestações de Serviços, O: Outros. Por omissão, "TD". // [OPCIONAL] Outras informações "notes": "Notas ao documento", // [OPCIONAL] "external_reference": "Referência do documento externo", // [OPCIONAL] // [OBRIGATÓRIO] Linhas do documento "lines": [\ {\ // [OPCIONAL] Identificação do item. Se nada for indicado, assume-se uma linha apenas de descrição.\ "item_type": "Product|Purchases::ExpenseCategory", // [OPCIONAL] Tipo de item: "Product": produto, "Purchases::ExpenseCategory": categoria de despesas. Por omissão fica vazio (linha de descrição).\ // Se o item for indicado, usar apenas um dos dois campos seguintes (o "id" ou o código). Se se indicarem os dois, então devem ser consistentes entre si, e consistentes com o "item_type".\ "item_id": 1, // [OPCIONAL] Identificador interno do item. Ver NOTA 6.\ "item_code": "Código do produto/categoria de despesas", // [OPCIONAL] Já tem que existir o produto/categoria de despesas com este código. Por omissão, é usado o item identificado pelo campo "item_id". Se nada for indicado, assume-se uma linha apenas de descrição.\ "description": "Descrição da linha", // [OPCIONAL] Por omissão é usada a descrição associada ao item, se este for indicado. [OBRIGATÓRIO] Para uma linha apenas de descrição.\ \ // [OPCIONAL] Unidade de medida. Por omissão é a configurada no item (se for produto), ou a por omissão na empresa.\ // Se a unidade de medida for indicada, usar apenas um dos dois campos seguintes (o "id" ou o código). Se se indicarem os dois, então devem ser consistentes entre si.\ "unit_of_measure_id": 1, // [OPCIONAL] Identificador interno da unidade de medida. Ver NOTA 7.\ "unit_of_measure": "Unidade de medida", // [OPCIONAL] Por omissão é a configurada no item (se for produto), ou a por omissão na empresa.\ // Quantidades e valores. [OBRIGATÓRIO] Para linhas de descrição valorizadas.\ "quantity": 1, // [OPCIONAL] Por omissão 1, se não for uma linha de descrição valorizada. [OBRIGATÓRIO] Para uma linha de descrição valorizada.\ "unit_price": 9.99, // [OPCIONAL] Se for indicado um produto. Por omissão é usado o PVP associado ao produto. [OBRIGATÓRIO] Para uma linha de categoria de despesas ou de descrição valorizada.\ "settlement_expression": "3", // [OPCIONAL] Desconto de linha, em percentagem; são suportados descontos compostos, como "3+5".\ \ // [OPCIONAL] IVA. Por omissão é aplicado o IVA associado ao item, ou à taxa normal, na região onde a empresa está localizada.\ // Se a taxa de IVA for indicada, usar apenas ou o campo "id" ou um ou mais dos três campos seguintes. Se se indicarem todos os campos, então devem ser consistentes entre si.\ "tax_id": 1, // [OPCIONAL] Identificador interno da taxa de IVA. Ver NOTA 8.\ "tax_code": "NOR|INT|RED|ISE", // [OPCIONAL] Por omissão é usado o tipo de IVA associado ao item, ou "NOR" se nenhum associado. Os tipos de IVA suportados são "NOR" (normal), "INT" (intermédio), "RED" (reduzido), "ISE" (isento).\ "tax_percentage": 22, // [OPCIONAL] Percentagem de IVA a usar: serve para indicar uma taxa de outra região (se o campo "tax_country_region" não for indicado) ou uma taxa antiga, já não em vigor.\ "tax_country_region": "PT-MA" // [OPCIONAL] Região do IVA. Por omissão (e se o campo "tax_percentage" não for indicado) aplica-se a taxa de IVA da região onde a empresa está localizada.\ },\ // Outras linhas, se existirem\ ...\ ] } Copy GET /commercial_document_series?filter[document_type]= &filter[prefix]= Copy GET /suppliers?filter[tax_registration_number]= Copy GET /countries?filter[iso_alpha_2]=PT| Copy GET /tax_exemption_reasons?filter[code]=M07| Copy GET /currencies?filter[iso_code]=USD| Copy GET /products?filter[item_code]= ou GET /expense_categories?filter[accounting_number]= Copy GET /units_of_measure?filter[unit_of_measure]= Copy GET /taxes?filter[tax_code]=NOR|&filter[tax_country_region]=PT| ou GET /taxes?filter[tax_code]= &filter[tax_country_region]= &filter[tax_percentage]= Copy GET /api/v1/commercial_purchases_documents HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Accept: */* sun-brightdesktopmoon --- # Documentos de Série | TOConline - Documentação API ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/documentos-de-serie#obter-todos-os-documentos-de-serie) Obter Todos os Documentos de Série ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/documentos-de-serie#get-api-commercial_document_series) Obter Documentos de Série com filtro get {{base\_url}}/api/commercial\_document\_series Obter Documentos de Série com filtro chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Query parameters filter\[document\_type\]stringOptionalExample: `FT` filter\[prefix\]stringOptionalExample: `2023` filter\[number\]stringOptionalExample: `13` Responses chevron-right 200 Sucesso application/json Headersobject Show Headersplus Responseobject Show propertiesplus get /api/commercial\_document\_series HTTPchevron-down HTTPcURLJavaScriptPython Test it 200 Sucesso ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/documentos-de-serie#obter-documentos-de-serie-com-filtro) Obter Documentos de Série com Filtro [PreviousCategorias de Despesachevron-left](https://api-docs.toconline.pt/apis/apis-auxiliares/categorias-de-despesa) Last updated 1 year ago * [Obter Todos os Documentos de Série](https://api-docs.toconline.pt/apis/apis-auxiliares/documentos-de-serie#obter-todos-os-documentos-de-serie) * [GETObter Documentos de Série com filtro](https://api-docs.toconline.pt/apis/apis-auxiliares/documentos-de-serie#get-api-commercial_document_series) * [Obter Documentos de Série com Filtro](https://api-docs.toconline.pt/apis/apis-auxiliares/documentos-de-serie#obter-documentos-de-serie-com-filtro) sun-brightdesktopmoon Copy GET /api/commercial_document_series HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Accept: */* Copy { "data": [\ {\ "attributes": {\ "active": true,\ "activity_code": null,\ "address_id": null,\ "allow_mb_reference": false,\ "at_status": "active",\ "at_status_date": null,\ "at_type": "normal",\ "atcud_prefix": "THIS_IS_FAKE",\ "bank_account_id": null,\ "broker_edi": null,\ "cashed_vat": false,\ "communication_date": null,\ "company_id": 800000046,\ "copies": 1,\ "created_at": "2023-04-27 11:26:40.38374",\ "data": {},\ "description": null,\ "direct_debit": false,\ "document_series_id": null,\ "document_theme_id": null,\ "document_type": "FT",\ "electronic_invoice": false,\ "external_registration": false,\ "hidden": false,\ "is_default": false,\ "is_edi": false,\ "manual_registration": false,\ "number": 13,\ "observations": null,\ "oss_country_id": null,\ "oss_tax_defaults": [],\ "prefix": "2023",\ "render_banks_data": false,\ "render_banks_data_fr": false,\ "updated_at": "2024-03-04 16:51:35.941381",\ "vat_included_prices": false\ },\ "id": "72",\ "relationships": {\ "company": {\ "data": {\ "id": "800000046",\ "type": "current_company"\ }\ }\ },\ "type": "commercial_document_series"\ }\ ] } GET Copy {{base_url}}/api/commercial_document_series?filter[document_type]=FT&filter[prefix]=2023&filter[number]=3 sun-brightdesktopmoon --- # Pagamentos | TOConline - Documentação API Os pagamentos seguem a mesma estrutura anteriormente definida: São compostos por um cabeçalho, e linhas. Nesta nova versão, é possível criar ambas as componentes num só pedido, descrito de seguida. ### [hashtag](https://api-docs.toconline.pt/apis/compras/pagamentos#criacao-de-cabecalhos-e-linhas) Criar Cabeçalho de sPagamento Os detalhes do pedido POST para a criação de recibos estão descritos de seguida, em formato OpenAPI, e em cURL. ### [hashtag](https://api-docs.toconline.pt/apis/compras/pagamentos#post-api-v1-commercial_purchases_payments) Criar Cabeçalho de Pagamentos post {{base\_url}}/api/v1/commercial\_purchases\_payments Criar Cabeçalho de Pagamentos chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Body application/jsonchevron-down application/json cash\_account\_idnumberOptionalExample: `2` check\_numberany | nullableOptional company\_idnumberOptionalExample: `800000046` country\_idnumberOptionalExample: `1` currency\_conversion\_ratenumberOptionalExample: `1` currency\_idnumberOptionalExample: `1` datestringOptionalExample: `2024-02-29` document\_series\_idnumberOptionalExample: `12` gross\_totalnumberOptionalExample: `11.3` internal\_observationsstringOptionalExample: `Comentário interno` net\_totalnumberOptionalExample: `0` observationsstringOptionalExample: `Comentários visíveis` payment\_mechanismstringOptionalExample: `MO` supplier\_idnumberOptionalExample: `9` third\_party\_idany | nullableOptional third\_party\_typeany | nullableOptional Responses chevron-right 200Success No content post /api/v1/commercial\_purchases\_payments HTTPchevron-down HTTPcURLJavaScriptPython Test it 200Success No content Este pedido permite criar um pagamento, e respetivas linhas, em simultâneo. Neste, o payload JSON deverá vir no seguinte formato [hashtag](https://api-docs.toconline.pt/apis/compras/pagamentos#anulacao-de-um-documento-caso-seja-preciso) Anulação de um Pagamento ----------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://api-docs.toconline.pt/apis/compras/pagamentos#patch-api-v1-commercial_purchases_documents-id-void) Anular Documentos de Compra patch {{base\_url}}/api/v1/commercial\_purchases\_documents/{id}/void Anular Documentos de Compra chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Path parameters idstringRequiredExample: `41` Responses chevron-right 200Success No content patch /api/v1/commercial\_purchases\_documents/{id}/void HTTPchevron-down HTTPcURLJavaScriptPython Test it 200Success No content [hashtag](https://api-docs.toconline.pt/apis/compras/pagamentos#atualizar-pagamento) Atualizar Pagamento ------------------------------------------------------------------------------------------------------------- O seguinte pedido pode ser realizado, após a criação do documento, e permite alterar informações sobre o documento. A estrutura do payload é a mesma do POST de criação. Neste, deverá enviar no id do pedido o id do documento a alterar. Os atributos enviados no body irão substituir os guardados no momento, e cada linha enviada dentro de lines irá substituir os dados guardados na linha com id especificado em payment\_line\_id ### [hashtag](https://api-docs.toconline.pt/apis/compras/pagamentos#patch-api-commercial_purchases_payments-id) Atualizar Pagamento patch {{base\_url}}/api/commercial\_purchases\_payments/{id} Atualizar Pagamento chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Path parameters idstringRequired TODO Example: `4` Body application/jsonchevron-down application/json dataobjectOptional Show propertiesplus Responses chevron-right 200Success No content patch /api/commercial\_purchases\_payments/{id} HTTPchevron-down HTTPcURLJavaScriptPython Test it 200Success No content [hashtag](https://api-docs.toconline.pt/apis/compras/pagamentos#adicao-de-linhas) Adicionar Linhas ao Pagamento -------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://api-docs.toconline.pt/apis/compras/pagamentos#post-api-commercial_purchases_payment_lines) Adicionar Linha a Pagamentos post {{base\_url}}/api/commercial\_purchases\_payment\_lines Adicionar Linha a Pagamentos chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Body application/jsonchevron-down application/json dataobjectOptional Show propertiesplus Responses chevron-right 200Success No content post /api/commercial\_purchases\_payment\_lines HTTPchevron-down HTTPcURLJavaScriptPython Adicionar Linha a Pagamentoschevron-down Adicionar Linha a PagamentosCriar Linhas de Pagamento Test it 200Success No content circle-info NOTA: É na linha que se indica qual o documento de compra (FC ou DSP) a pagar. Se necessário, podem criar-se mais do que uma linha (e nesse caso o pagamento é feito de uma só vez para todos os documentos) [hashtag](https://api-docs.toconline.pt/apis/compras/pagamentos#remocao-de-linhas) Remover Linhas de Pagamento ------------------------------------------------------------------------------------------------------------------- Do mesmo modo, caso pretenda remover linhas de um documento, pode utilizar a seguinte rota, onde apenas tem de indicar o id da linha a remover, no path. ### [hashtag](https://api-docs.toconline.pt/apis/compras/pagamentos#delete-api-commercial_purchases_payment_lines) Remover Linhas de Pagamento delete {{base\_url}}/api/commercial\_purchases\_payment\_lines Remover Linhas de Pagamento chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Responses chevron-right 200Success No content delete /api/commercial\_purchases\_payment\_lines HTTPchevron-down HTTPcURLJavaScriptPython Test it 200Success No content [hashtag](https://api-docs.toconline.pt/apis/compras/pagamentos#consultar-documento) Obter Pagamento por Id ---------------------------------------------------------------------------------------------------------------- Por fim, se pretender obter informações sobre um dado documento, pode utilizar a seguinte rota, onde deverá especificar o id do documento a analisar no path. ### [hashtag](https://api-docs.toconline.pt/apis/compras/pagamentos#get-api-commercial_purchases_payments-id) Obter Pagamento por Id get {{base\_url}}/api/commercial\_purchases\_payments/{id} Obter Pagamento por Id chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Path parameters idstringRequired TODO Example: `4` Responses chevron-right 200Success No content get /api/commercial\_purchases\_payments/{id} HTTPchevron-down HTTPcURLJavaScriptPython Test it 200Success No content [hashtag](https://api-docs.toconline.pt/apis/compras/pagamentos#consultar-documento-1) Obter Todos os Pagamentos --------------------------------------------------------------------------------------------------------------------- [PreviousDocumentos de Comprachevron-left](https://api-docs.toconline.pt/apis/compras/documentos-de-compra) [NextDescarregar PDF de Documentos de Comprachevron-right](https://api-docs.toconline.pt/apis/compras/descarregar-pdf-de-documentos-de-compra) Last updated 1 year ago * [Criar Cabeçalho de sPagamento](https://api-docs.toconline.pt/apis/compras/pagamentos#criacao-de-cabecalhos-e-linhas) * [POSTCriar Cabeçalho de Pagamentos](https://api-docs.toconline.pt/apis/compras/pagamentos#post-api-v1-commercial_purchases_payments) * [Anulação de um Pagamento](https://api-docs.toconline.pt/apis/compras/pagamentos#anulacao-de-um-documento-caso-seja-preciso) * [PATCHAnular Documentos de Compra](https://api-docs.toconline.pt/apis/compras/pagamentos#patch-api-v1-commercial_purchases_documents-id-void) * [Atualizar Pagamento](https://api-docs.toconline.pt/apis/compras/pagamentos#atualizar-pagamento) * [PATCHAtualizar Pagamento](https://api-docs.toconline.pt/apis/compras/pagamentos#patch-api-commercial_purchases_payments-id) * [Adicionar Linhas ao Pagamento](https://api-docs.toconline.pt/apis/compras/pagamentos#adicao-de-linhas) * [POSTAdicionar Linha a Pagamentos](https://api-docs.toconline.pt/apis/compras/pagamentos#post-api-commercial_purchases_payment_lines) * [Remover Linhas de Pagamento](https://api-docs.toconline.pt/apis/compras/pagamentos#remocao-de-linhas) * [DELETERemover Linhas de Pagamento](https://api-docs.toconline.pt/apis/compras/pagamentos#delete-api-commercial_purchases_payment_lines) * [Obter Pagamento por Id](https://api-docs.toconline.pt/apis/compras/pagamentos#consultar-documento) * [GETObter Pagamento por Id](https://api-docs.toconline.pt/apis/compras/pagamentos#get-api-commercial_purchases_payments-id) * [Obter Todos os Pagamentos](https://api-docs.toconline.pt/apis/compras/pagamentos#consultar-documento-1) sun-brightdesktopmoon Copy POST /api/v1/commercial_purchases_payments HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Content-Type: application/json Accept: */* Content-Length: 374 { "cash_account_id": 2, "check_number": null, "company_id": 800000046, "country_id": 1, "currency_conversion_rate": 1, "currency_id": 1, "date": "2024-02-29", "document_series_id": 12, "gross_total": 11.3, "internal_observations": "Comentário interno", "net_total": 0, "observations": "Comentários visíveis", "payment_mechanism": "MO", "supplier_id": 9, "third_party_id": null, "third_party_type": null } Copy curl -v -X POST -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer ' -d '' '/v1/commercial_purchases_payments' Copy { "id":2, "lines": [\ {\ "payment_id": 2,\ "payable_type": "Purchases::Document",\ "payable_id": 2,\ "paid_value": 200,\ "settlement_percentage": 1.0,\ "cashed_vat_amount": null,\ "gross_total": 9.65,\ "settlement_amount": 0.0,\ "net_total": 5.0,\ "retention_total": 0.0,\ }\ ] } Copy PATCH /api/v1/commercial_purchases_documents/{id}/void HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Accept: */* Copy PATCH /api/commercial_purchases_payments/{id} HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Content-Type: application/json Accept: */* Content-Length: 411 { "data": { "attributes": { "check_number": null, "currency_conversion_rate": 1, "date": "2024-02-29", "deleted": false, "document_no": "PF 2023/2", "document_series_id": 12, "gross_total": 0, "internal_observations": "Comentário interno", "net_total": 0, "observations": "Comentários visíveis", "payment_mechanism": "MO", "standalone": true, "third_party_id": null, "third_party_type": "" }, "id": "4", "type": "commercial_purchases_payments" } } Copy POST /api/commercial_purchases_payment_lines HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Content-Type: application/json Accept: */* Content-Length: 163 { "data": { "attributes": { "paid_value": 50, "payable_id": 2, "payable_type": "Purchases::Document", "settlement_percentage": 3 }, "type": "commercial_purchases_payment_lines" } } Payload Copy { "data": { "type": "commercial_purchases_payment_lines", "attributes": { "payable_id": "", "payable_type": "Purchases::Document", //"payment_id": "" "paid_value": 50, // Valor total a pagar (não é necessário pagar a totalidade do documento, ou pode pagar-se mais do que um documento) // Indicar o atributo seguinte apenas se existir desconto no pagamento (3%, neste exemplo) "settlement_percentage": 3 } } } Copy DELETE /api/commercial_purchases_payment_lines HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Accept: */* Copy GET /api/commercial_purchases_payments/{id} HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Accept: */* sun-brightdesktopmoon --- # APIs Auxiliares | TOConline - Documentação API [Descritores de Taxachevron-right](https://api-docs.toconline.pt/apis/apis-auxiliares/descritores-de-taxa) [Família de Itenschevron-right](https://api-docs.toconline.pt/apis/apis-auxiliares/familia-de-itens) [Paíseschevron-right](https://api-docs.toconline.pt/apis/apis-auxiliares/paises) [Unidades de Medidachevron-right](https://api-docs.toconline.pt/apis/apis-auxiliares/unidades-de-medida) [Contas Bancáriaschevron-right](https://api-docs.toconline.pt/apis/apis-auxiliares/contas-bancarias) [Caixa Associadachevron-right](https://api-docs.toconline.pt/apis/apis-auxiliares/caixa-associada) [Unidade Monetáriachevron-right](https://api-docs.toconline.pt/apis/apis-auxiliares/unidade-monetaria) [Taxaschevron-right](https://api-docs.toconline.pt/apis/apis-auxiliares/taxas) [Categorias de Despesachevron-right](https://api-docs.toconline.pt/apis/apis-auxiliares/categorias-de-despesa) [Documentos de Sériechevron-right](https://api-docs.toconline.pt/apis/apis-auxiliares/documentos-de-serie) [PreviousPagamentoschevron-left](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/pagamentos) [NextDescritores de Taxachevron-right](https://api-docs.toconline.pt/apis/apis-auxiliares/descritores-de-taxa) Last updated 1 year ago sun-brightdesktopmoon sun-brightdesktopmoon --- # Produtos e Serviços | TOConline - Documentação API [hashtag](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#produtos) Produtos ------------------------------------------------------------------------------------------------ ### [hashtag](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#obter-produtos) Obter Produtos De modo a obter informações sobre um dado produto, poderá realizar o seguinte pedido `GET` `/products` #### [hashtag](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#path-parameters) Path Parameters Name Type Description filter\[item\_code\] String 200: OK Toda a informação sobre o produto Copy { // Response } Neste, pode não indicar nenhum filtro, e obter todos os produtos disponíveis, ou então filtrar por qualquer um dos campos disponíveis, tal como no exemplo dado, e seguindo as convenções JSONAPI chevron-rightExemplo de Response[hashtag](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#exemplo-de-response) Copy { "data": [\ {\ "type": "products",\ "id": "2",\ "attributes": {\ "item_code": "100",\ "item_description": "Isto é uma breve descrição",\ "sales_price": 2.0,\ "sales_price_includes_vat": false,\ "tax_code": "INT",\ "applied_tax_code": "INT",\ "notes": "Isto são notas de produtos",\ "is_merchandise": null,\ "location_in_warehouse": null,\ "sales_price_2": 4.0,\ "sales_price_3": null,\ "purchase_price": 5.0,\ "ean_barcode": "553214",\ "financial_cost": 2.0,\ "transport_cost": 1.0,\ "other_cost": 0.0,\ "customs_cost": 10.0,\ "estimated_total_cost": 18.0,\ "product_inventory_type": "P",\ "accounting_number": null,\ "service_group": null,\ "is_active": true,\ "sales_price_vat_display": 2.26,\ "sales_price_2_vat_display": 4.52,\ "sales_price_3_vat_display": null,\ "applied_tax_exemption_reason_id": null\ },\ "relationships": {\ "applied_tax_exemption_reason": {\ "data": null\ },\ "company": {\ "data": {\ "type": "current_company",\ "id": "800000046"\ }\ },\ "item_families": {\ "data": {\ "type": "item_families",\ "id": "3"\ }\ },\ "tax_exemption_reasons": {\ "data": null\ },\ "unit_of_measure": {\ "data": {\ "type": "units_of_measure",\ "id": "5"\ }\ }\ }\ }\ ] } ### [hashtag](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#undefined-1) ### [hashtag](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#criar-produtos) Criar Produtos ### [hashtag](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#post-api-products) Criar Produto post {{base\_url}}/api/products Criar Produto chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Body application/jsonchevron-down application/json dataobjectOptional Show propertiesplus Responses chevron-right 200 Sucesso application/json Headersobject Show Headersplus Responseobject Show propertiesplus post /api/products HTTPchevron-down HTTPcURLJavaScriptPython Test it 200 Sucesso No pedido acima, o corresponde ao token de acesso válido devolvido pelo serviço de OAuth, e o deverá ter o seguinte formato: Payload Response ### [hashtag](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#undefined-3) [hashtag](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#servicos) Serviços ------------------------------------------------------------------------------------------------ ### [hashtag](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#criar-servicos) Criar Serviços No pedido acima, o corresponde ao token de acesso válido devolvido pelo serviço de OAuth, e o deverá ter o seguinte formato ### [hashtag](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#post-api-services) Criar Serviço post {{base\_url}}/api/services Criar Serviço chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Body application/jsonchevron-down application/json dataobject\[\]OptionalExample: `[{"attributes":{"customs_cost":0,"ean_barcode":"","estimated_total_cost":0,"financial_cost":0,"item_code":"333333","item_description":"Serviço NOR","other_cost":0,"purchase_price":0,"sales_price":10,"sales_price_2":20,"sales_price_3":30,"transport_cost":0,"type":"Service"},"type":"services"}]` Show propertiesplus Responses chevron-right 200 Sucesso application/json Headersobject Show Headersplus Responseobject Show propertiesplus post /api/services HTTPchevron-down HTTPcURLJavaScriptPython Test it 200 Sucesso ### [hashtag](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#undefined-4) ### [hashtag](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#obter-todos-os-servicos) Obter Todos os Serviços `GET` `/services` #### [hashtag](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#path-parameters-1) Path Parameters Name Type Description filter\[item\_code\] String 200: OK Toda a informação sobre o serviço ### [hashtag](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#undefined-6) ### [hashtag](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#obter-servico) Obter Serviço De modo a obter informações sobre um dado serviço, poderá realizar o seguinte pedido ### [hashtag](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#get-api-services) Obter Todos os Serviços get {{base\_url}}/api/services Obter Todos os Serviços chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Responses chevron-right 200 Sucesso application/json Headersobject Show Headersplus Responseobject Show propertiesplus get /api/services HTTPchevron-down HTTPcURLJavaScriptPython Test it 200 Sucesso [hashtag](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#undefined-7) ----------------------------------------------------------------------------------------- * * * ### [hashtag](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#associar-familias-de-itens-a-produtos) Associar Famílias de Itens a Produtos circle-info Já teve de ser criado previamente uma Família de Itens. Pode consultar mais em: [Família de Itens](https://api-docs.toconline.pt/apis/apis-auxiliares/familia-de-itens) ### [hashtag](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#patch-api-products) Atualizar Produto patch {{base\_url}}/api/products Atualizar Produto chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Body application/jsonchevron-down application/json dataobjectOptional Show propertiesplus Responses chevron-right 200Success No content patch /api/products HTTPchevron-down HTTPcURLJavaScriptPython Test it 200Success No content Payload Response ### [hashtag](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#associar-familias-de-itens-a-servicos) Associar Famílias de Itens a Serviços circle-info Já teve de ser criado previamente uma Família de Itens. Pode consultar mais em: [Família de Itens](https://api-docs.toconline.pt/apis/apis-auxiliares/familia-de-itens) ### [hashtag](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#patch-api-services) Atualizar Serviço patch {{base\_url}}/api/services Atualizar Serviço chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Body application/jsonchevron-down application/json dataobjectOptional Show propertiesplus Responses chevron-right 200Success No content patch /api/services HTTPchevron-down HTTPcURLJavaScriptPython Test it 200Success No content Payload Response [hashtag](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#undefined-10) ------------------------------------------------------------------------------------------ ### [hashtag](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#associar-unidades-de-medida-a-produtos) Associar Unidades de Medida a Produtos circle-info Já teve de ser criado previamente uma Unidade de Medida. Pode consultar mais em: [Unidades de Medida](https://api-docs.toconline.pt/apis/apis-auxiliares/unidades-de-medida) ### [hashtag](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#patch-api-products-1) Atualizar Produto patch {{base\_url}}/api/products Atualizar Produto chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Body application/jsonchevron-down application/json dataobjectOptional Show propertiesplus Responses chevron-right 200Success No content patch /api/products HTTPchevron-down HTTPcURLJavaScriptPython Test it 200Success No content Payload Response ### [hashtag](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#associar-unidades-de-medida-a-servicos) Associar Unidades de Medida a Serviços ### [hashtag](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#patch-api-products-2) Atualizar Produto patch {{base\_url}}/api/products Atualizar Produto chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Body application/jsonchevron-down application/json dataobjectOptional Show propertiesplus Responses chevron-right 200Success No content patch /api/products HTTPchevron-down HTTPcURLJavaScriptPython Test it 200Success No content Payload Response [PreviousFornecedores, Morada e E-mailchevron-left](https://api-docs.toconline.pt/apis/empresa/fornecedores) [NextVendaschevron-right](https://api-docs.toconline.pt/apis/vendas) Last updated 1 year ago * [Produtos](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#produtos) * [Obter Produtos](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#obter-produtos) * [](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#undefined-1) * [Criar Produtos](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#criar-produtos) * [POSTCriar Produto](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#post-api-products) * [](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#undefined-3) * [Serviços](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#servicos) * [Criar Serviços](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#criar-servicos) * [POSTCriar Serviço](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#post-api-services) * [](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#undefined-4) * [Obter Todos os Serviços](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#obter-todos-os-servicos) * [](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#undefined-6) * [Obter Serviço](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#obter-servico) * [GETObter Todos os Serviços](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#get-api-services) * [](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#undefined-7) * [Associar Famílias de Itens a Produtos](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#associar-familias-de-itens-a-produtos) * [PATCHAtualizar Produto](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#patch-api-products) * [Associar Famílias de Itens a Serviços](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#associar-familias-de-itens-a-servicos) * [PATCHAtualizar Serviço](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#patch-api-services) * [](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#undefined-10) * [Associar Unidades de Medida a Produtos](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#associar-unidades-de-medida-a-produtos) * [PATCHAtualizar Produto](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#patch-api-products-1) * [Associar Unidades de Medida a Serviços](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#associar-unidades-de-medida-a-servicos) * [PATCHAtualizar Produto](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#patch-api-products-2) sun-brightdesktopmoon Copy POST /api/products HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Content-Type: application/json Accept: */* Content-Length: 209 { "data": { "attributes": { "item_code": 777777, "item_description": "Product with a family", "item_family_id": 4, "sales_price": 100, "sales_price_includes_vat": false, "tax_code": "NOR", "type": "Product" }, "type": "products" } } Copy { "data": { "attributes": { "accounting_number": null, "applied_tax_code": "NOR", "applied_tax_exemption_reason_id": null, "customs_cost": 0, "ean_barcode": null, "estimated_total_cost": 0, "financial_cost": 0, "is_active": true, "is_merchandise": null, "item_code": "777777", "item_description": "Product with a family", "location_in_warehouse": null, "notes": null, "other_cost": 0, "product_inventory_type": null, "purchase_price": null, "sales_price": 100, "sales_price_2": null, "sales_price_2_vat_display": null, "sales_price_3": null, "sales_price_3_vat_display": null, "sales_price_includes_vat": false, "sales_price_vat_display": 123, "service_group": null, "tax_code": "NOR", "transport_cost": 0 }, "id": "21", "relationships": { "applied_tax_exemption_reason": { "data": null }, "company": { "data": { "id": "800000046", "type": "current_company" } }, "item_families": { "data": { "id": "4", "type": "item_families" } }, "tax_exemption_reasons": { "data": null }, "unit_of_measure": { "data": { "id": "2", "type": "units_of_measure" } } }, "type": "products" }, "meta": { "observed": { "scalar": 1 } } } Payload Copy { "data": { "type": "products", // [OBRIGATÓRIO] "attributes": { "type": "Product", // [OBRIGATÓRIO] "item_code": "PTEST", // [OBRIGATÓRIO] "item_description": "Test product", // [OBRIGATÓRIO] "sales_price": 100, // [OPCIONAL] "sales_price_includes_vat": false, // [OPCIONAL] Por omissão, false; true, se o preço de venda do produto incluir IVA "tax_code": "NOR" // [OPCIONAL] Os tipos de IVA suportados são "NOR" (normal), "INT" (intermédio), "RED" (reduzido), "ISE" (isento) } } } Response Copy { "meta": { "observed": { "scalar": 1 } }, "data": { "type": "products", "id": "3", "attributes": { "item_code": "PTEST", "item_description": "Test product", "sales_price": 100, "sales_price_includes_vat": false, "tax_code": "NOR", "applied_tax_code": "NOR", "notes": null, "is_merchandise": null, "location_in_warehouse": null, "sales_price_2": null, "sales_price_3": null, "purchase_price": null, "ean_barcode": null, "financial_cost": 0.0, "transport_cost": 0.0, "other_cost": 0.0, "customs_cost": 0.0, "estimated_total_cost": 0.0, "product_inventory_type": null, "accounting_number": null, "service_group": null, "is_active": true, "sales_price_vat_display": 123.00, "sales_price_2_vat_display": null, "sales_price_3_vat_display": null, "applied_tax_exemption_reason_id": null }, "relationships": { "applied_tax_exemption_reason": { "data": null }, "company": { "data": { "type": "current_company", "id": "800000046" } }, "item_families": { "data": null }, "tax_exemption_reasons": { "data": null }, "unit_of_measure": { "data": { "type": "units_of_measure", "id": "2" } } } } } Copy { "data": { "type": "services", // [OBRIGATÓRIO] "attributes": { "type": "Service", // [OBRIGATÓRIO] "item_code": "STEST", // [OBRIGATÓRIO] "item_description": "Test service", // [OBRIGATÓRIO] "sales_price": 100, // [OPCIONAL] "sales_price_includes_vat": false, // [OPCIONAL] Por omissão, false; true, se o preço de venda do produto incluir IVA "tax_code": "NOR" // [OPCIONAL] Os tipos de IVA suportados são "NOR" (normal), "INT" (intermédio), "RED" (reduzido), "ISE" (isento) } } } Copy POST /api/services HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Content-Type: application/json Accept: */* Content-Length: 303 { "data": [\ {\ "attributes": {\ "customs_cost": 0,\ "ean_barcode": "",\ "estimated_total_cost": 0,\ "financial_cost": 0,\ "item_code": "333333",\ "item_description": "Serviço NOR",\ "other_cost": 0,\ "purchase_price": 0,\ "sales_price": 10,\ "sales_price_2": 20,\ "sales_price_3": 30,\ "transport_cost": 0,\ "type": "Service"\ },\ "type": "services"\ }\ ] } Copy { "data": [\ {\ "attributes": {\ "accounting_number": null,\ "applied_tax_code": null,\ "applied_tax_exemption_reason_id": null,\ "customs_cost": 0,\ "ean_barcode": "",\ "estimated_total_cost": 0,\ "financial_cost": 0,\ "is_active": true,\ "is_merchandise": null,\ "item_code": "333333",\ "item_description": "Serviço NOR",\ "location_in_warehouse": null,\ "notes": null,\ "other_cost": 0,\ "product_inventory_type": null,\ "purchase_price": 0,\ "sales_price": 10,\ "sales_price_2": 20,\ "sales_price_2_vat_display": null,\ "sales_price_3": 30,\ "sales_price_3_vat_display": null,\ "sales_price_includes_vat": null,\ "sales_price_vat_display": null,\ "service_group": null,\ "tax_code": null,\ "transport_cost": 0\ },\ "id": "19",\ "relationships": {\ "applied_tax_exemption_reason": {\ "data": null\ },\ "company": {\ "data": {\ "id": "800000046",\ "type": "current_company"\ }\ },\ "item_families": {\ "data": null\ },\ "tax_exemption_reasons": {\ "data": null\ },\ "unit_of_measure": {\ "data": {\ "id": "2",\ "type": "units_of_measure"\ }\ }\ },\ "type": "services"\ }\ ], "meta": { "observed": { "scalar": 1 } } } Copy { // Response } Copy GET /api/services HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Accept: */* Copy { "data": [\ {\ "attributes": {\ "accounting_number": null,\ "applied_tax_code": "NOR",\ "applied_tax_exemption_reason_id": null,\ "customs_cost": 0,\ "ean_barcode": "",\ "estimated_total_cost": 0,\ "financial_cost": 0,\ "is_active": true,\ "is_merchandise": null,\ "item_code": "54321",\ "item_description": "Serviço1",\ "location_in_warehouse": null,\ "notes": "Notas de Serviço",\ "other_cost": 0,\ "product_inventory_type": null,\ "purchase_price": 0,\ "sales_price": 10,\ "sales_price_2": 20,\ "sales_price_2_vat_display": 24.6,\ "sales_price_3": 30,\ "sales_price_3_vat_display": 36.9,\ "sales_price_includes_vat": false,\ "sales_price_vat_display": 12.3,\ "service_group": "G1",\ "tax_code": "NOR",\ "transport_cost": 0\ },\ "id": "7",\ "relationships": {\ "applied_tax_exemption_reason": {\ "data": null\ },\ "company": {\ "data": {\ "id": "800000046",\ "type": "current_company"\ }\ },\ "item_families": {\ "data": {\ "id": "4",\ "type": "item_families"\ }\ },\ "tax_exemption_reasons": {\ "data": null\ },\ "unit_of_measure": {\ "data": {\ "id": "5",\ "type": "units_of_measure"\ }\ }\ },\ "type": "services"\ }\ ] } Copy PATCH /api/products HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Content-Type: application/json Accept: */* Content-Length: 71 { "data": { "attributes": { "item_family_id": 4 }, "id": "6", "type": "products" } } Payload Copy { "data": { "type": "products", "id": "6", "attributes": { "item_family_id": 4 } } } Response Copy { "meta": { "observed": { "scalar": 1 } }, "data": { "type": "products", "id": "6", "attributes": { "item_code": "123456", "item_description": "Test product with family", "sales_price": 100, "sales_price_includes_vat": false, "tax_code": "NOR", "applied_tax_code": "NOR", "notes": null, "is_merchandise": null, "location_in_warehouse": null, "sales_price_2": null, "sales_price_3": null, "purchase_price": null, "ean_barcode": null, "financial_cost": 0.0, "transport_cost": 0.0, "other_cost": 0.0, "customs_cost": 0.0, "estimated_total_cost": 0.0, "product_inventory_type": null, "accounting_number": null, "service_group": null, "is_active": true, "sales_price_vat_display": 123.00, "sales_price_2_vat_display": null, "sales_price_3_vat_display": null, "applied_tax_exemption_reason_id": null }, "relationships": { "applied_tax_exemption_reason": { "data": null }, "company": { "data": { "type": "current_company", "id": "800000046" } }, "item_families": { "data": { "type": "item_families", "id": "4" } }, "tax_exemption_reasons": { "data": null }, "unit_of_measure": { "data": { "type": "units_of_measure", "id": "2" } } } } Copy PATCH /api/services HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Content-Type: application/json Accept: */* Content-Length: 71 { "data": { "attributes": { "item_family_id": 4 }, "id": "7", "type": "services" } } Payload Copy { "data": { "type": "services", "id": "7", "attributes": { "item_family_id": 4 } } } Response Copy { "meta": { "observed": { "scalar": 1 } }, "data": { "type": "services", "id": "7", "attributes": { "item_code": "54321", "item_description": "Serviço1", "sales_price": 10.0, "sales_price_includes_vat": false, "tax_code": "NOR", "applied_tax_code": "NOR", "notes": "Notas de Serviço", "is_merchandise": null, "location_in_warehouse": null, "sales_price_2": 20.0, "sales_price_3": 30.0, "purchase_price": 0.0, "ean_barcode": "", "financial_cost": 0.0, "transport_cost": 0.0, "other_cost": 0.0, "customs_cost": 0.0, "estimated_total_cost": 0.0, "product_inventory_type": null, "accounting_number": null, "service_group": "G1", "is_active": true, "sales_price_vat_display": 12.30, "sales_price_2_vat_display": 24.60, "sales_price_3_vat_display": 36.90, "applied_tax_exemption_reason_id": null }, "relationships": { "applied_tax_exemption_reason": { "data": null }, "company": { "data": { "type": "current_company", "id": "800000046" } }, "item_families": { "data": { "type": "item_families", "id": "4" } }, "tax_exemption_reasons": { "data": null }, "unit_of_measure": { "data": { "type": "units_of_measure", "id": "5" } } } } } Copy PATCH /api/products HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Content-Type: application/json Accept: */* Content-Length: 71 { "data": { "attributes": { "item_family_id": 4 }, "id": "6", "type": "products" } } PATCH Copy https://api/v1.toconline.com/api/products Payload Copy { "data": { "type": "products", "id": "6", "attributes": { "item_family_id": 4 } } } Response Copy { "meta": { "observed": { "scalar": 1 } }, "data": { "type": "products", "id": "6", "attributes": { "item_code": "123456", "item_description": "Test product with family", "sales_price": 100, "sales_price_includes_vat": false, "tax_code": "NOR", "applied_tax_code": "NOR", "notes": null, "is_merchandise": null, "location_in_warehouse": null, "sales_price_2": null, "sales_price_3": null, "purchase_price": null, "ean_barcode": null, "financial_cost": 0.0, "transport_cost": 0.0, "other_cost": 0.0, "customs_cost": 0.0, "estimated_total_cost": 0.0, "product_inventory_type": null, "accounting_number": null, "service_group": null, "is_active": true, "sales_price_vat_display": 123.00, "sales_price_2_vat_display": null, "sales_price_3_vat_display": null, "applied_tax_exemption_reason_id": null }, "relationships": { "applied_tax_exemption_reason": { "data": null }, "company": { "data": { "type": "current_company", "id": "800000046" } }, "item_families": { "data": { "type": "item_families", "id": "4" } }, "tax_exemption_reasons": { "data": null }, "unit_of_measure": { "data": { "type": "units_of_measure", "id": "2" } } } } Copy PATCH /api/products HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Content-Type: application/json Accept: */* Content-Length: 71 { "data": { "attributes": { "item_family_id": 4 }, "id": "6", "type": "products" } } PATCH Copy https://api/v1.toconline.com/api/services Payload Copy { "data": { "type": "service", "id": "6", "attributes": { "item_family_id": 4 } } } Response Copy { "meta": { "observed": { "scalar": 1 } }, "data": { "type": "services", "id": "7", "attributes": { "item_code": "54321", "item_description": "Serviço1", "sales_price": 10.0, "sales_price_includes_vat": false, "tax_code": "NOR", "applied_tax_code": "NOR", "notes": "Notas de Serviço", "is_merchandise": null, "location_in_warehouse": null, "sales_price_2": 20.0, "sales_price_3": 30.0, "purchase_price": 0.0, "ean_barcode": "", "financial_cost": 0.0, "transport_cost": 0.0, "other_cost": 0.0, "customs_cost": 0.0, "estimated_total_cost": 0.0, "product_inventory_type": null, "accounting_number": null, "service_group": "G1", "is_active": true, "sales_price_vat_display": 12.30, "sales_price_2_vat_display": 24.60, "sales_price_3_vat_display": 36.90, "applied_tax_exemption_reason_id": null }, "relationships": { "applied_tax_exemption_reason": { "data": null }, "company": { "data": { "type": "current_company", "id": "800000046" } }, "item_families": { "data": { "type": "item_families", "id": "4" } }, "tax_exemption_reasons": { "data": null }, "unit_of_measure": { "data": { "type": "units_of_measure", "id": "5" } } } } } sun-brightdesktopmoon --- # Países | TOConline - Documentação API ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/paises#obter-todos-os-paises) Obter Todos os Países ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/paises#get-api-countries) Obter Todos os Países get {{base\_url}}/api/countries Obter Todos os Países chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Query parameters filter\[iso\_alpha\_2\]stringOptionalExample: `PT` Responses chevron-right 200 / Sucesso Headersobject Show Headersplus get /api/countries HTTPchevron-down HTTPcURLJavaScriptPython Test it 200 / Sucesso No content GET Copy https://api/v1.toconline.com/api/coutries chevron-rightExemplo de Response[hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/paises#exemplo-de-response) ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/paises#obter-pais-por-codigo-de-pais) Obter País por Código de País Endpoint Response circle-info ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/paises#obter-todos-os-paises-oss) Obter Todos os Países OSS ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/paises#get-api-oss_countries) Obter Todos os Países OSS get {{base\_url}}/api/oss\_countries Obter Todos os Países OSS chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Responses chevron-right 200 Sucesso application/json Headersobject Show Headersplus Responseobject Show propertiesplus get /api/oss\_countries HTTPchevron-down HTTPcURLJavaScriptPython Test it 200 Sucesso chevron-rightExemplo de Response[hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/paises#exemplo-de-response-1) [PreviousFamília de Itenschevron-left](https://api-docs.toconline.pt/apis/apis-auxiliares/familia-de-itens) [NextUnidades de Medidachevron-right](https://api-docs.toconline.pt/apis/apis-auxiliares/unidades-de-medida) Last updated 1 year ago * [Obter Todos os Países](https://api-docs.toconline.pt/apis/apis-auxiliares/paises#obter-todos-os-paises) * [GETObter Todos os Países](https://api-docs.toconline.pt/apis/apis-auxiliares/paises#get-api-countries) * [Obter País por Código de País](https://api-docs.toconline.pt/apis/apis-auxiliares/paises#obter-pais-por-codigo-de-pais) * [Obter Todos os Países OSS](https://api-docs.toconline.pt/apis/apis-auxiliares/paises#obter-todos-os-paises-oss) * [GETObter Todos os Países OSS](https://api-docs.toconline.pt/apis/apis-auxiliares/paises#get-api-oss_countries) sun-brightdesktopmoon Copy GET /api/countries HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Accept: */* Copy { "data": [\ {\ "type": "countries",\ "id": "1",\ "attributes": {\ "default_name": "Portugal - Continente",\ "iso_alpha_2": "PT",\ "iso_alpha_3": "PRT",\ "tax_country_region": "PT"\ }\ },\ {\ "type": "countries",\ "id": "2",\ "attributes": {\ "default_name": "Portugal - Madeira",\ "iso_alpha_2": "PT-MA",\ "iso_alpha_3": "PRT",\ "tax_country_region": "PT-MA"\ }\ },\ (...)\ ] } } Endpoint Copy https://api/v1.toconline.com/api/coutries?filter[iso_alpha_2]= Endpooint Copy https://api/v1.toconline.com/api/coutries?filter[iso_alpha_2]=PT Copy { "data": [\ {\ "type": "countries",\ "id": "1",\ "attributes": {\ "default_name": "Portugal - Continente",\ "iso_alpha_2": "PT",\ "iso_alpha_3": "PRT",\ "tax_country_region": "PT"\ }\ }\ ] } Copy => "iso_alpha_2" Copy GET /api/oss_countries HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Accept: */* Copy { "data": [\ {\ "attributes": {\ "default_name": "Luxembourg",\ "iso_alpha_2": "LU",\ "iso_alpha_3": "LUX",\ "tax_country_region": "LU"\ },\ "id": "234",\ "type": "oss_countries"\ },\ {\ "attributes": {\ "default_name": "Austria",\ "iso_alpha_2": "AT",\ "iso_alpha_3": "AUT",\ "tax_country_region": "AT"\ },\ "id": "235",\ "type": "oss_countries"\ },\ {\ "attributes": {\ "default_name": "Malta",\ "iso_alpha_2": "MT",\ "iso_alpha_3": "MLT",\ "tax_country_region": "MT"\ },\ "id": "21",\ "type": "oss_countries"\ },\ {\ "attributes": {\ "default_name": "Romania",\ "iso_alpha_2": "RO",\ "iso_alpha_3": "ROU",\ "tax_country_region": "RO"\ },\ "id": "230",\ "type": "oss_countries"\ },\ {\ "attributes": {\ "default_name": "Latvia",\ "iso_alpha_2": "LV",\ "iso_alpha_3": "LVA",\ "tax_country_region": "LV"\ },\ "id": "79",\ "type": "oss_countries"\ },\ {\ "attributes": {\ "default_name": "Poland",\ "iso_alpha_2": "PL",\ "iso_alpha_3": "POL",\ "tax_country_region": "PL"\ },\ "id": "27",\ "type": "oss_countries"\ },\ {\ "attributes": {\ "default_name": "Bulgaria",\ "iso_alpha_2": "BG",\ "iso_alpha_3": "BGR",\ "tax_country_region": "BG"\ },\ "id": "170",\ "type": "oss_countries"\ },\ {\ "attributes": {\ "default_name": "Germany",\ "iso_alpha_2": "DE",\ "iso_alpha_3": "DEU",\ "tax_country_region": "DE"\ },\ "id": "19",\ "type": "oss_countries"\ },\ {\ "attributes": {\ "default_name": "Sweden",\ "iso_alpha_2": "SE",\ "iso_alpha_3": "SWE",\ "tax_country_region": "SE"\ },\ "id": "151",\ "type": "oss_countries"\ },\ {\ "attributes": {\ "default_name": "Greece",\ "iso_alpha_2": "GR",\ "iso_alpha_3": "GRC",\ "tax_country_region": "EL"\ },\ "id": "196",\ "type": "oss_countries"\ },\ {\ "attributes": {\ "default_name": "Denmark",\ "iso_alpha_2": "DK",\ "iso_alpha_3": "DNK",\ "tax_country_region": "DK"\ },\ "id": "25",\ "type": "oss_countries"\ },\ {\ "attributes": {\ "default_name": "Netherlands",\ "iso_alpha_2": "NL",\ "iso_alpha_3": "NLD",\ "tax_country_region": "NL"\ },\ "id": "52",\ "type": "oss_countries"\ },\ {\ "attributes": {\ "default_name": "Slovenia",\ "iso_alpha_2": "SI",\ "iso_alpha_3": "SVN",\ "tax_country_region": "SI"\ },\ "id": "246",\ "type": "oss_countries"\ },\ {\ "attributes": {\ "default_name": "Finland",\ "iso_alpha_2": "FI",\ "iso_alpha_3": "FIN",\ "tax_country_region": "FI"\ },\ "id": "117",\ "type": "oss_countries"\ },\ {\ "attributes": {\ "default_name": "Hungary",\ "iso_alpha_2": "HU",\ "iso_alpha_3": "HUN",\ "tax_country_region": "HU"\ },\ "id": "100",\ "type": "oss_countries"\ },\ {\ "attributes": {\ "default_name": "Czech Republic",\ "iso_alpha_2": "CZ",\ "iso_alpha_3": "CZE",\ "tax_country_region": "CZ"\ },\ "id": "212",\ "type": "oss_countries"\ },\ {\ "attributes": {\ "default_name": "Ireland",\ "iso_alpha_2": "IE",\ "iso_alpha_3": "IRL",\ "tax_country_region": "IE"\ },\ "id": "164",\ "type": "oss_countries"\ },\ {\ "attributes": {\ "default_name": "Slovakia",\ "iso_alpha_2": "SK",\ "iso_alpha_3": "SVK",\ "tax_country_region": "SK"\ },\ "id": "237",\ "type": "oss_countries"\ },\ {\ "attributes": {\ "default_name": "France",\ "iso_alpha_2": "FR",\ "iso_alpha_3": "FRA",\ "tax_country_region": "FR"\ },\ "id": "107",\ "type": "oss_countries"\ },\ {\ "attributes": {\ "default_name": "Italy",\ "iso_alpha_2": "IT",\ "iso_alpha_3": "ITA",\ "tax_country_region": "IT"\ },\ "id": "205",\ "type": "oss_countries"\ },\ {\ "attributes": {\ "default_name": "Estonia",\ "iso_alpha_2": "EE",\ "iso_alpha_3": "EST",\ "tax_country_region": "EE"\ },\ "id": "250",\ "type": "oss_countries"\ },\ {\ "attributes": {\ "default_name": "Monaco",\ "iso_alpha_2": "MC",\ "iso_alpha_3": "MCO",\ "tax_country_region": "MC"\ },\ "id": "204",\ "type": "oss_countries"\ },\ {\ "attributes": {\ "default_name": "Lithuania",\ "iso_alpha_2": "LT",\ "iso_alpha_3": "LTU",\ "tax_country_region": "LT"\ },\ "id": "59",\ "type": "oss_countries"\ },\ {\ "attributes": {\ "default_name": "Belgium",\ "iso_alpha_2": "BE",\ "iso_alpha_3": "BEL",\ "tax_country_region": "BE"\ },\ "id": "55",\ "type": "oss_countries"\ },\ {\ "attributes": {\ "default_name": "Spain",\ "iso_alpha_2": "ES",\ "iso_alpha_3": "ESP",\ "tax_country_region": "ES"\ },\ "id": "232",\ "type": "oss_countries"\ },\ {\ "attributes": {\ "default_name": "Cyprus",\ "iso_alpha_2": "CY",\ "iso_alpha_3": "CYP",\ "tax_country_region": "CY"\ },\ "id": "94",\ "type": "oss_countries"\ },\ {\ "attributes": {\ "default_name": "Croatia",\ "iso_alpha_2": "HR",\ "iso_alpha_3": "HRV",\ "tax_country_region": "HR"\ },\ "id": "122",\ "type": "oss_countries"\ }\ ] } GET Copy https://api/v1.toconline.com/api/coutries Copy { "data": [\ {\ "type": "countries",\ "id": "1",\ "attributes": {\ "default_name": "Portugal - Continente",\ "iso_alpha_2": "PT",\ "iso_alpha_3": "PRT",\ "tax_country_region": "PT"\ }\ },\ {\ "type": "countries",\ "id": "2",\ "attributes": {\ "default_name": "Portugal - Madeira",\ "iso_alpha_2": "PT-MA",\ "iso_alpha_3": "PRT",\ "tax_country_region": "PT-MA"\ }\ },\ (...)\ ] } } sun-brightdesktopmoon --- # Unidade Monetária | TOConline - Documentação API ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/unidade-monetaria#obter-todas-as-unidades-monetarias) Obter Todas as Unidades Monetárias ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/unidade-monetaria#get-api-currencies) Obter Todas as Unidades Monetárias get {{base\_url}}/api/currencies Obter Todas as Unidades Monetárias chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Responses chevron-right 200Success No content get /api/currencies HTTPchevron-down HTTPcURLJavaScriptPython Test it 200Success No content ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/unidade-monetaria#obter-unidade-monetaria-por-id) Obter Unidade Monetária por Id ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/unidade-monetaria#get-api-currencies-currencyid) Obter Todas as Unidade Monetária por Id get {{base\_url}}/api/currencies/{currencyId} Obter Todas as Unidade Monetária por Id chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Path parameters currencyIdstringRequired Id da unidade monetária Example: `2` Responses chevron-right 200 Sucesso application/json Headersobject Show Headersplus Responseobject Show propertiesplus get /api/currencies/{currencyId} HTTPchevron-down HTTPcURLJavaScriptPython Test it 200 Sucesso [PreviousCaixa Associadachevron-left](https://api-docs.toconline.pt/apis/apis-auxiliares/caixa-associada) [NextTaxaschevron-right](https://api-docs.toconline.pt/apis/apis-auxiliares/taxas) Last updated 1 year ago * [Obter Todas as Unidades Monetárias](https://api-docs.toconline.pt/apis/apis-auxiliares/unidade-monetaria#obter-todas-as-unidades-monetarias) * [GETObter Todas as Unidades Monetárias](https://api-docs.toconline.pt/apis/apis-auxiliares/unidade-monetaria#get-api-currencies) * [Obter Unidade Monetária por Id](https://api-docs.toconline.pt/apis/apis-auxiliares/unidade-monetaria#obter-unidade-monetaria-por-id) * [GETObter Todas as Unidade Monetária por Id](https://api-docs.toconline.pt/apis/apis-auxiliares/unidade-monetaria#get-api-currencies-currencyid) sun-brightdesktopmoon Copy GET /api/currencies HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Accept: */* Copy GET /api/currencies/{currencyId} HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Accept: */* Copy { "data": { "attributes": { "iso_code": "USD", "symbol": "$" }, "id": "2", "relationships": { "country": { "data": { "id": "2", "type": "countries" } } }, "type": "currencies" } } sun-brightdesktopmoon --- # Recibos de Venda | TOConline - Documentação API [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/recibos-de-venda#criacao-de-recibos) Criação de recibos ----------------------------------------------------------------------------------------------------------------------------------- Cada recibo é constituído por: 1. Um cabeçalho 2. Uma ou mais linhas O recibo não possui um estado "em preparação". Um recibo pode ser (3.) anulado. ### [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/recibos-de-venda#id-1.-criar-cabecalho-do-recibo-de-venda) 1\. Criar Cabeçalho do Recibo de Venda circle-exclamation Já tem de exisitir um **Documento de Venda Finalizado** Para mais informações consulte: [3\. Finalização do documento](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/documentos-de-venda#id-3.-finalizacao-do-documento) Os detalhes do pedido POST para a criação de recibos estão descritos de seguida, em formato OpenAPI, e em cURL. ### [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/recibos-de-venda#post-api-commercial_sales_receipts) Criar Cabeçalho de Recibo de Venda post {{base\_url}}/api/commercial\_sales\_receipts Criar Cabeçalho de Recibo de Venda chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Body application/jsonchevron-down application/json dataobjectOptional Show propertiesplus Responses chevron-right 200Success No content post /api/commercial\_sales\_receipts HTTPchevron-down HTTPcURLJavaScriptPython Test it 200Success No content No pedido acima, o corresponde ao token de acesso válido devolvido pelo serviço de OAuth, e o deverá ter o seguinte formato circle-info Para saber como obter mais informação de como obter o id dos Documentos de Série poderá consultar: [Documentos de Série](https://api-docs.toconline.pt/apis/apis-auxiliares/documentos-de-serie) circle-info Para saber como obter mais informação de como obter o id da Conta Bancária poderá consultar: [Contas Bancárias](https://api-docs.toconline.pt/apis/apis-auxiliares/contas-bancarias) circle-info Para saber como obter mais informação de como obter o id da Conta de Caixa Associada poderá consultar: [Caixa Associada](https://api-docs.toconline.pt/apis/apis-auxiliares/caixa-associada) Payload Response circle-exclamation Após criar o cabeçalho, a resposta TEM QUE ser consultada para obtenção do identificador interno ("id") do recibo criado. Este identificador será necessário para a criação de todas as linhas. circle-exclamation Quando um documento é finalizado este vai gerar um número do documento com a estrutura \[TIPO ANO/NUMERO\] através deste poderá executar um filtro nos documentos de série para encontrar o seu documento. circle-info **Nota 1:** A série associada ao recibo tem já que existir, e o seu "id" interno deve ser obtido por um circle-info **Nota 2:** O "id" interno da conta bancária da empresa deve ser obtido por um circle-info **Nota 3:** O "id" interno da conta de caixa da empresa deve ser obtido por um ### [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/recibos-de-venda#id-2.-criar-linha-do-documento-de-venda) 2\. Criar Linha do Documento de Venda: Os detalhes do pedido POST para a criação de recibos estão descritos de seguida, em formato OpenAPI, e em cURL. ### [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/recibos-de-venda#post-api-commercial_sales_receipt_lines) Adicionar Linha a Recibo de Venda post {{base\_url}}/api/commercial\_sales\_receipt\_lines Adicionar Linha a Recibo de Venda chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Body application/jsonchevron-down application/json dataobjectOptional Show propertiesplus Responses chevron-right 200Success No content post /api/commercial\_sales\_receipt\_lines HTTPchevron-down HTTPcURLJavaScriptPython Test it 200Success No content No pedido acima, o corresponde ao token de acesso válido devolvido pelo serviço de OAuth, e o deverá ter o seguinte formato circle-info **Nota 1:** O "id" interno do documento (fatura, nota) a receber deve ser obtido por um\\ ### [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/recibos-de-venda#id-3.-anular-recibo-de-venda) 3\. Anular Recibo de Venda Os detalhes do pedido POST para a criação de recibos estão descritos de seguida, em formato OpenAPI, e em cURL. ### [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/recibos-de-venda#patch-api-v1-commercial_sales_receipts-salesreceiptid-void) Anular Recibo de Venda patch {{base\_url}}/api/v1/commercial\_sales\_receipts/{salesReceiptId}/void Anular Recibo de Venda chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Path parameters salesReceiptIdstringRequired Responses chevron-right 200Success No content patch /api/v1/commercial\_sales\_receipts/{salesReceiptId}/void HTTPchevron-down HTTPcURLJavaScriptPython Test it 200Success No content No pedido acima, o corresponde ao token de acesso válido devolvido pelo serviço de OAuth, e o deverá ter o seguinte formato Payload Response circle-info **Nota 1:** O "id" interno do recibo a anular pode ser obtido por um circle-check É na linha do recibo que se indica qual o documento (FT, ou outro) que foi pago. Se necessário, pode criar-se mais do que uma linha (e nesse caso o recibo é emitido de uma só vez para todos os documentos referenciados) [PreviousDocumentos de Vendachevron-left](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/documentos-de-venda) [NextCompraschevron-right](https://api-docs.toconline.pt/apis/versoes-anteriores/compras) Last updated 1 year ago * [Criação de recibos](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/recibos-de-venda#criacao-de-recibos) * [1\. Criar Cabeçalho do Recibo de Venda](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/recibos-de-venda#id-1.-criar-cabecalho-do-recibo-de-venda) * [POSTCriar Cabeçalho de Recibo de Venda](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/recibos-de-venda#post-api-commercial_sales_receipts) * [2\. Criar Linha do Documento de Venda:](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/recibos-de-venda#id-2.-criar-linha-do-documento-de-venda) * [POSTAdicionar Linha a Recibo de Venda](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/recibos-de-venda#post-api-commercial_sales_receipt_lines) * [3\. Anular Recibo de Venda](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/recibos-de-venda#id-3.-anular-recibo-de-venda) * [PATCHAnular Recibo de Venda](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/recibos-de-venda#patch-api-v1-commercial_sales_receipts-salesreceiptid-void) sun-brightdesktopmoon Copy POST /api/commercial_sales_receipts HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Content-Type: application/json Accept: */* Content-Length: 161 { "data": { "attributes": { "date": "2025-06-01", "document_series_id": 66, "gross_total": 10, "net_total": 20, "payment_mechanism": "MO" }, "type": "commercial_sales_receipts" } } Copy curl -v -X POST -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer ' -d '' '/commercial_sales_receipts' Payload Copy { "data": { "type": "commercial_sales_receipts", // [OBRIGATÓRIO] "attributes": { "date": "2020-06-01", // [OPCIONAL] Data do recibo; por omissão, a data do pedido "payment_mechanism": "MO", // [OPCIONAL] Meios de pagamento aceites: "MO": Numerário, "CH": Cheque, "DC": Cartão de débito, "CC": Cartão de crédito, "TR": Transferência bancária, "DDA": Débito direto autorizado, "MB": Referências de pagamento Multibanco. "document_series_id": , // [OPCIONAL] Série de recibos associada. Não precisa de ser indicada; por omissão o recibo é criado na série por omissão associada ao tipo de documento. Vd. Nota 1 "bank_account_id": ,// [OPCIONAL] Conta bancária da empresa para onde o recebimento é feito. Usado apenas quando o meio de pagamento é "DC", "CC", "TR" ou "DDA", e apenas se for necessário indicar uma conta bancária específica. Vd. Nota 2 "cash_account_id": // [OPCIONAL] Conta de caixa da empresa para onde o recebimento é feito. Usado apenas quando o meio de pagamento é "MO", e apenas se for necessário indicar uma conta de caixa específica. Vd. Nota3 } } } Copy { "data": { "type": "commercial_sales_receipts", "id": "6", "attributes": { "date": "2020-06-01", "document_no": "RC 2023/5", "document_series_id": 66, "payment_mechanism": "MO", "gross_total": 0, "net_total": 0, "third_party_type": "", "third_party_id": null, "check_number": null, "currency_conversion_rate": 1, "internal_observations": null, "observations": null, "standalone": null, "saft_import_id": null, "deleted": false, "manual_registration_type": null, "manual_registration_series": null, "manual_registration_number": null, "created_at": "2024-02-26 11:31:37.827953", "updated_at": "2024-02-26 11:31:37.827953" }, "relationships": { "bank_accounts": { "data": null }, "cash_accounts": { "data": null }, "commercial_document_series": { "data": { "type": "commercial_document_series", "id": "66" } }, "company": { "data": { "type": "current_company", "id": "800000046" } }, "country": { "data": null }, "currency": { "data": null }, "customer": { "data": null }, "lines": { "data": [] }, "user": { "data": { "type": "current_company_users", "id": "800000863" } } } } } Copy GET /commercial_document_series?filter[document_type]=o tipo de documento> &filter[prefix]=&filter[number]= Copy GET /company_bank_accounts?filter[iban]= ou GET /company_bank_accounts?filter[name]= Copy GET /cash_accounts?filter[name]= Copy POST /api/commercial_sales_receipt_lines HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Content-Type: application/json Accept: */* Content-Length: 285 { "data": { "attributes": { "cashed_vat_amount": null, "gross_total": 10.69, "net_total": 9.27, "receipt_id": 13, "receivable_id": 12, "receivable_type": "Document", "received_value": 10.69, "retention_total": 0.72, "settlement_amount": 0, "settlement_percentage": 0 }, "type": "commercial_sales_receipt_lines" } } Copy curl -v -X POST -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer ' -d '' '/commercial_sales_receipt_lines' Payload Copy { "data": { "type": "commercial_sales_receipt_lines", // [OBRIGATÓRIO] "attributes": { "receivable_type": "Document", // [OBRIGATÓRIO] "receivable_id": "", // [OBRIGATÓRIO] Vd. Nota 1 "received_value": 50, // [OBRIGATÓRIO] Valor total a receber (não é necessário receber a totalidade do documento, pode fazer-se um recebimento parcial) "settlement_percentage": "3" // [OPCIONAL] Desconto de pagamento, em percentagem; são suportados descontos compostos, como "3+5" "receipt_id" : "" // [OBRIGATÓRIO] Recibo a que esta linha pertence. Este "id" é o devolvido na resposta ao pedido de criação do cabeçalho, ver acima } } } Copy GET /commercial_sales_documents?filter[document_no]= Copy PATCH /api/v1/commercial_sales_receipts/{salesReceiptId}/void HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Accept: */* Copy curl -v -X PATCH -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer ' -d '' '/commercial_sales_receipts/' Copy { "data": { "type": "commercial_sales_receipts", "id": "3", //id do recibo de venda pretendido "attributes": { "deleted": true } } } Copy { "data": { "type": "commercial_sales_receipts", "id": "3", "attributes": { "date": "2020-06-01", "document_no": "RC 2023/2", "document_series_id": 66, "payment_mechanism": "MO", "gross_total": 0, "net_total": 0, "third_party_type": null, "third_party_id": null, "check_number": null, "currency_conversion_rate": 1, "internal_observations": null, "observations": null, "standalone": null, "saft_import_id": null, "deleted": true, "manual_registration_type": null, "manual_registration_series": null, "manual_registration_number": null, "created_at": "2024-02-23 15:34:36.778593", "updated_at": "2024-02-27 12:52:10.462666" }, "relationships": { "bank_accounts": { "data": null }, "cash_accounts": { "data": null }, "commercial_document_series": { "data": { "type": "commercial_document_series", "id": "66" } }, "company": { "data": { "type": "current_company", "id": "800000046" } }, "country": { "data": null }, "currency": { "data": null }, "customer": { "data": null }, "lines": { "data": [] }, "user": { "data": { "type": "current_company_users", "id": "800000863" } } } } } Copy GET /commercial_sales_receipts?filter[document_no]= sun-brightdesktopmoon --- # Unidades de Medida | TOConline - Documentação API ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/unidades-de-medida#criar-unidade-de-medida) Criar Unidade de Medida ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/unidades-de-medida#post-api-units_of_measure) Criar Unidades de Medida post {{base\_url}}/api/units\_of\_measure Criar Unidades de Medida chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Body application/jsonchevron-down application/json dataobjectOptional Show propertiesplus Responses chevron-right 200 Criar Unidades de Medida application/json Headersobject Show Headersplus Responseobject Show propertiesplus post /api/units\_of\_measure HTTPchevron-down HTTPcURLJavaScriptPython Test it 200 Criar Unidades de Medida Payload Response Payload Copy { "data": { "type": "units_of_measure", "attributes": { "unit_of_measure": "Anos de Luz", "is_default": false } } } Response Copy { "data": { "type": "units_of_measure", "id": "9", "attributes": { "unit_of_measure": "Anos de Luz", "is_default": false }, "relationships": { "company": { "data": { "type": "current_company", "id": "800000046" } } } } } ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/unidades-de-medida#undefined-1) ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/unidades-de-medida#obter-todas-as-unidade-de-medida) Obter Todas as Unidade de Medida ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/unidades-de-medida#get-api-units_of_measure) Obter Todas as Unidades de Medida get {{base\_url}}/api/units\_of\_measure Obter Todas as Unidades de Medida chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Query parameters filter\[unit\_of\_measure\]stringOptionalExample: `horas` Responses chevron-right 200 / Sucesso Headersobject Show Headersplus get /api/units\_of\_measure HTTPchevron-down HTTPcURLJavaScriptPython Test it 200 / Sucesso No content chevron-rightExemplo de Response [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/unidades-de-medida#exemplo-de-response) ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/unidades-de-medida#undefined-2) ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/unidades-de-medida#remover-unidades-de-medida) Remover Unidades de Medida ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/unidades-de-medida#delete-api-units_of_measure-unitsofmeasureid) Remover Unidades de Medida delete {{base\_url}}/api/units\_of\_measure/{unitsOfMeasureId} Remover Unidades de Medida chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Path parameters unitsOfMeasureIdstringRequired Id da unidade de medida Example: `10` Responses chevron-right 200 Sucesso application/json Headersobject Show Headersplus Responseobject Show propertiesplus delete /api/units\_of\_measure/{unitsOfMeasureId} HTTPchevron-down HTTPcURLJavaScriptPython Test it 200 Sucesso chevron-rightExemplo de Response[hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/unidades-de-medida#exemplo-de-response-1) [PreviousPaíseschevron-left](https://api-docs.toconline.pt/apis/apis-auxiliares/paises) [NextContas Bancáriaschevron-right](https://api-docs.toconline.pt/apis/apis-auxiliares/contas-bancarias) Last updated 1 year ago * [Criar Unidade de Medida](https://api-docs.toconline.pt/apis/apis-auxiliares/unidades-de-medida#criar-unidade-de-medida) * [POSTCriar Unidades de Medida](https://api-docs.toconline.pt/apis/apis-auxiliares/unidades-de-medida#post-api-units_of_measure) * [](https://api-docs.toconline.pt/apis/apis-auxiliares/unidades-de-medida#undefined-1) * [Obter Todas as Unidade de Medida](https://api-docs.toconline.pt/apis/apis-auxiliares/unidades-de-medida#obter-todas-as-unidade-de-medida) * [GETObter Todas as Unidades de Medida](https://api-docs.toconline.pt/apis/apis-auxiliares/unidades-de-medida#get-api-units_of_measure) * [](https://api-docs.toconline.pt/apis/apis-auxiliares/unidades-de-medida#undefined-2) * [Remover Unidades de Medida](https://api-docs.toconline.pt/apis/apis-auxiliares/unidades-de-medida#remover-unidades-de-medida) * [DELETERemover Unidades de Medida](https://api-docs.toconline.pt/apis/apis-auxiliares/unidades-de-medida#delete-api-units_of_measure-unitsofmeasureid) sun-brightdesktopmoon Copy POST /api/units_of_measure HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Content-Type: application/json Accept: */* Content-Length: 99 { "data": { "attributes": { "is_default": false, "unit_of_measure": "Anos Luz" }, "type": "units_of_measure" } } Copy { "data": { "attributes": { "is_default": false, "unit_of_measure": "Anos Luz" }, "id": "11", "relationships": { "company": { "data": { "id": "800000046", "type": "current_company" } } }, "type": "units_of_measure" } } Copy GET /api/units_of_measure HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Accept: */* GET Copy https://api/v1.toconline.com/api/units_of_measure Copy { "data": [\ {\ "type": "units_of_measure",\ "id": "6",\ "attributes": {\ "unit_of_measure": "horas",\ "is_default": false\ },\ "relationships": {\ "company": {\ "data": {\ "type": "current_company",\ "id": "800000046"\ }\ }\ }\ },\ {\ "type": "units_of_measure",\ "id": "5",\ "attributes": {\ "unit_of_measure": "Kg",\ "is_default": false\ },\ "relationships": {\ "company": {\ "data": {\ "type": "current_company",\ "id": "800000046"\ }\ }\ }\ },\ {\ "type": "units_of_measure",\ "id": "4",\ "attributes": {\ "unit_of_measure": "Lt",\ "is_default": false\ },\ "relationships": {\ "company": {\ "data": {\ "type": "current_company",\ "id": "800000046"\ }\ }\ }\ },\ {\ "type": "units_of_measure",\ "id": "3",\ "attributes": {\ "unit_of_measure": "m",\ "is_default": false\ },\ "relationships": {\ "company": {\ "data": {\ "type": "current_company",\ "id": "800000046"\ }\ }\ }\ },\ {\ "type": "units_of_measure",\ "id": "2",\ "attributes": {\ "unit_of_measure": "un",\ "is_default": true\ },\ "relationships": {\ "company": {\ "data": {\ "type": "current_company",\ "id": "800000046"\ }\ }\ }\ },\ {\ "type": "units_of_measure",\ "id": "9",\ "attributes": {\ "unit_of_measure": "Anos de Luz",\ "is_default": false\ },\ "relationships": {\ "company": {\ "data": {\ "type": "current_company",\ "id": "800000046"\ }\ }\ }\ }\ ] } Copy DELETE /api/units_of_measure/{unitsOfMeasureId} HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Accept: */* Copy { "meta": {} } DELETE Copy https://api/v1.toconline.com/api/units_of_measure/{id} Copy { "meta": {} } sun-brightdesktopmoon --- # Categorias de Despesa | TOConline - Documentação API ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/categorias-de-despesa#obter-todas-as-categorias-de-despesa) Obter Todas as Categorias de Despesa ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/categorias-de-despesa#get-api-expense_categories) Obter Todas as Categorias de Despesa get {{base\_url}}/api/expense\_categories Obter Todas as Categorias de Despesa chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Responses chevron-right 200Success No content get /api/expense\_categories HTTPchevron-down HTTPcURLJavaScriptPython Test it 200Success No content ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/categorias-de-despesa#obter-categorias-de-despesa-por-id) Obter Categorias de Despesa por Id ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/categorias-de-despesa#get-api-expense_categories-id) Obter Categorias de Despesa por Id get {{base\_url}}/api/expense\_categories/{id} Obter Categorias de Despesa por Id chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Path parameters idstringRequiredExample: `2` Responses chevron-right 200 Sucesso application/json Headersobject Show Headersplus Responseobject Show propertiesplus get /api/expense\_categories/{id} HTTPchevron-down HTTPcURLJavaScriptPython Test it 200 Sucesso [PreviousTaxaschevron-left](https://api-docs.toconline.pt/apis/apis-auxiliares/taxas) [NextDocumentos de Sériechevron-right](https://api-docs.toconline.pt/apis/apis-auxiliares/documentos-de-serie) Last updated 1 year ago * [Obter Todas as Categorias de Despesa](https://api-docs.toconline.pt/apis/apis-auxiliares/categorias-de-despesa#obter-todas-as-categorias-de-despesa) * [GETObter Todas as Categorias de Despesa](https://api-docs.toconline.pt/apis/apis-auxiliares/categorias-de-despesa#get-api-expense_categories) * [Obter Categorias de Despesa por Id](https://api-docs.toconline.pt/apis/apis-auxiliares/categorias-de-despesa#obter-categorias-de-despesa-por-id) * [GETObter Categorias de Despesa por Id](https://api-docs.toconline.pt/apis/apis-auxiliares/categorias-de-despesa#get-api-expense_categories-id) sun-brightdesktopmoon Copy GET /api/expense_categories HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Accept: */* Copy GET /api/expense_categories/{id} HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Accept: */* Copy { "data": { "attributes": { "accounting_number": "241", "accounting_suffix": "241", "categories_count": 0, "company_id": 800000046, "created_at": "2023-04-27 11:26:41", "enumerations_expense_category_grouping_id": null, "enumerations_profit_and_losses_category_id": null, "help": null, "is_deletable": false, "is_editable": false, "is_main": true, "is_ready": null, "name": "Impostos Sobre o Rendimento", "parent_expense_category_id": null, "tax_code": "NOR", "tax_deductibility": 100, "updated_at": "2023-04-27 11:26:41" }, "id": "2", "relationships": { "company": { "data": { "id": "800000046", "type": "current_company" } }, "parent_expense_category": { "data": null } }, "type": "expense_categories" } } sun-brightdesktopmoon --- # Documentos de Venda | TOConline - Documentação API [hashtag](https://api-docs.toconline.pt/apis/vendas/documentos-de-venda#criar-documento-de-venda) Criar Documento de Venda ------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://api-docs.toconline.pt/apis/vendas/documentos-de-venda#post-api-v1-commercial_sales_documents) Criar Documento de Venda post {{base\_url}}/api/v1/commercial\_sales\_documents Criar Documento de Venda chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Body application/jsonchevron-down application/json apply\_retention\_when\_paidbooleanOptionalExample: `true` currency\_conversion\_ratenumberOptionalExample: `1.21` currency\_iso\_codestringOptionalExample: `EUR` customer\_address\_detailstringOptionalExample: `Praceta da Liberdade n5` customer\_business\_namestringOptionalExample: `Ricardo Ribeiro` customer\_citystringOptionalExample: `Lisboa` customer\_countrystringOptionalExample: `PT` customer\_postcodestringOptionalExample: `1000-101` customer\_tax\_registration\_numberstringOptionalExample: `229659179` datestringOptionalExample: `2023-01-01` document\_typestringOptionalExample: `FT` due\_datestringOptionalExample: `2023-02-01` external\_referencestringOptionalExample: `Referência do documento externo` finalizenumberOptionalExample: `0` linesobject\[\]OptionalExample: `[{}]` notesstringOptionalExample: `Notas ao documento` operation\_countrystringOptionalExample: `PT-MA` payment\_mechanismstringOptionalExample: `MO` retentionnumberOptionalExample: `7.5` retention\_typestringOptionalExample: `IRS` settlement\_expressionstringOptionalExample: `7.5` vat\_included\_pricesbooleanOptionalExample: `false` Responses chevron-right 200Success No content post /api/v1/commercial\_sales\_documents HTTPchevron-down HTTPcURLJavaScriptPython Test it 200Success No content #### [hashtag](https://api-docs.toconline.pt/apis/vendas/documentos-de-venda#cabecalho-documentos-de-venda) Cabeçalho Documentos de Venda Atributo Descrição Obrigatório document\_type Tipo de documento. "FT": fatura, "FS": fatura simplificada, "FR": fatura-recibo. Sim date Data do documento. Por omissão, a data do pedido. Não document\_series\_id Identificador interno da série. Não document\_series\_prefix Prefixo da série. Não customer\_id Identificador interno do cliente. Não customer\_tax\_registration\_number NIF do cliente. Não customer\_business\_name Nome do cliente. Sim customer\_address\_detail Morada do cliente. Não customer\_postcode Código postal do cliente, no formato 0000-000. Não customer\_city Cidade/Localidade do cliente. Não customer\_country País do cliente. Por omissão, "PT". Não due\_date Data de vencimento. Por omissão, a data do documento, ou a referente ao prazo de pagamento configurado no cliente. Não settlement\_expression Desconto no cabeçalho, em percentagem. São suportados descontos compostos, como "3+5". Não payment\_mechanism Modo de pagamento. Não bank\_account\_id Identificador interno da conta bancária da empresa para onde o recebimento é feito. Não cash\_account\_id Identificador interno da conta de caixa da empresa para onde o recebimento é feito. Não vat\_included\_prices Os preços nas linhas são com IVA incluído? Por omissão, não (false). Não tax\_exemption\_reason\_id Motivo de isenção de IVA. Não operation\_country A região de operação para efeitos de IVA. Não currency\_id Identificador interno da moeda. Não currency\_iso\_code Código ISO da moeda do documento. Não currency\_conversion\_rate Taxa de conversão para EUR (1 EUR = n USD Nãão retention Percentagem de retenção a aplicar sobre os serviços. Não retention\_type Tipo de retenção ("IRS" ou "IRC"). Por omissão, "IRS". Não apply\_retention\_when\_paid A retenção é feita logo no documento (false) ou apenas no recebimento (true). Por omissão, false. Não notes Notas ao documento. Não external\_reference Referência do documento externo. Não lines Lista de linhas do documento. Sim #### [hashtag](https://api-docs.toconline.pt/apis/vendas/documentos-de-venda#linha-de-documentos-de-venda) Linha de Documentos de Venda Atributo Descrição Obrigatório item\_type Tipo de item: "Service": serviços, "Product": produtos, "TaxDescriptor": descritores. Sim item\_id Identificador interno do item. Não item\_code Código do serviço/produto/descritor. Não description Descrição da linha. Por omissão é usada a descrição associada ao item, se este for indicado. Sim unit\_of\_measure\_id Identificador interno da unidade de medida. Não unit\_of\_measure Unidade de medida. Por omissão é a configurada no item (se for serviço ou produto). Não quantity Quantidade da linha. Sim unit\_price Preço unitário da linha. Sim settlement\_expression Desconto de linha, em percentagem. Não tax\_id Identificador interno da taxa de IVA. Não tax\_code Tipo de IVA associado ao item. Não tax\_percentage Percentagem de IVA a usar. Não tax\_country\_region Região do IVA. Não circle-info **Nota 1 -** A série associada ao documento tem já que existir, e o seu "id" interno pode ser obtido por um: `GET /commercial_document_series?filter[document_type]=&filter[prefix]=` circle-info **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: `GET /customers?filter[tax_registration_number]=` circle-info **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: `GET /countries?filter[iso_alpha_2]=` circle-info **Nota 4 -** O "id" interno da conta bancária da empresa deve ser obtido por um: `GET /company_bank_accounts?filter[iban]=` `ou` `GET /company_bank_accounts?filter[name]=` circle-info **Nota 5** \- O "id" interno da conta de caixa da empresa deve ser obtido por um `GET /cash_accounts?filter[name]=` circle-info **Nota 6** - O "id" interno do motivo de isenção deve ser obtido por um `GET /tax_exemption_reasons?filter[code]=` circle-info **Nota 7** - O "id" interno da moeda deve ser obtido por um `GET /currencies?filter[iso_code]=` circle-info **Nota 8:** O item (serviço, produto ou descritor) tem já que existir, e o seu "id" interno pode ser obtido por um `GET /services?filter[item_code]=` `ou` `GET /products?filter[item_code]=` `ou` `GET /tax_descriptors?filter[notation]=` circle-info **Nota 9**: A unidade de medida tem já que existir, e o seu "id" interno pode ser obtido por um `GET /units_of_measure?filter[unit_of_measure]=un|` circle-info **Nota 10**: O "id" interno da taxa de IVA deve ser obtido por um `GET /taxes?filter[tax_code]= &filter[tax_country_region]=` `ou` `GET /taxes?filter[tax_code]= &filter[tax_country_region]=PT|&filter[tax_percentage]=` circle-info **Nota 11:** Para as faturas-recibos (FR), o recibo associado é criado automaticamente quando a FR é finalizada. circle-check Ao submenter o documento de venda fica automaticamente **finalizado**! [hashtag](https://api-docs.toconline.pt/apis/vendas/documentos-de-venda#alteracao-do-documento-de-venda) Alteração do Documento de Venda --------------------------------------------------------------------------------------------------------------------------------------------- triangle-exclamation Após a criação de um documento de venda este fica automaticamente finalizado, se pretender criar documentos sem finalizar pode consultar a versão anterior desta API:[Documentos de Venda](https://api-docs.toconline.pt/apis/vendas/documentos-de-venda) Quando um documento é criado em um estado finalizado, torna-se impossível executar as seguintes operações em documentos de venda: * Finalização do Documento de Venda * Anulação do Documento de Venda * Atualizar Documento de Venda * Eliminação do Documento de Venda * * * [hashtag](https://api-docs.toconline.pt/apis/vendas/documentos-de-venda#obter-documento-de-venda-por-id) Obter Documento de Venda por Id --------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://api-docs.toconline.pt/apis/vendas/documentos-de-venda#get-api-v1-commercial_sales_documents-salesdocumentid) Obter Todos os Documentos de Venda por Id get {{base\_url}}/api/v1/commercial\_sales\_documents/{salesDocumentId} Obter Todos os Documentos de Venda por Id chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Path parameters salesDocumentIdstringRequired Responses chevron-right 200Success No content get /api/v1/commercial\_sales\_documents/{salesDocumentId} HTTPchevron-down HTTPcURLJavaScriptPython Test it 200Success No content [hashtag](https://api-docs.toconline.pt/apis/vendas/documentos-de-venda#obter-todos-os-documentos-de-venda) Obter Todos os Documentos de Venda --------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://api-docs.toconline.pt/apis/vendas/documentos-de-venda#get-api-v1-commercial_sales_documents) Obter Todos os Documentos de Venda get {{base\_url}}/api/v1/commercial\_sales\_documents/ Obter Todos os Documentos de Venda chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Responses chevron-right 200Success No content get /api/v1/commercial\_sales\_documents/ HTTPchevron-down HTTPcURLJavaScriptPython Test it 200Success No content [PreviousVendaschevron-left](https://api-docs.toconline.pt/apis/vendas) [NextDocumentos Retificativos chevron-right](https://api-docs.toconline.pt/apis/vendas/documentos-retificativos) Last updated 1 year ago * [Criar Documento de Venda](https://api-docs.toconline.pt/apis/vendas/documentos-de-venda#criar-documento-de-venda) * [POSTCriar Documento de Venda](https://api-docs.toconline.pt/apis/vendas/documentos-de-venda#post-api-v1-commercial_sales_documents) * [Alteração do Documento de Venda](https://api-docs.toconline.pt/apis/vendas/documentos-de-venda#alteracao-do-documento-de-venda) * [Obter Documento de Venda por Id](https://api-docs.toconline.pt/apis/vendas/documentos-de-venda#obter-documento-de-venda-por-id) * [GETObter Todos os Documentos de Venda por Id](https://api-docs.toconline.pt/apis/vendas/documentos-de-venda#get-api-v1-commercial_sales_documents-salesdocumentid) * [Obter Todos os Documentos de Venda](https://api-docs.toconline.pt/apis/vendas/documentos-de-venda#obter-todos-os-documentos-de-venda) * [GETObter Todos os Documentos de Venda](https://api-docs.toconline.pt/apis/vendas/documentos-de-venda#get-api-v1-commercial_sales_documents) sun-brightdesktopmoon Copy POST /api/v1/commercial_sales_documents HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Content-Type: application/json Accept: */* Content-Length: 640 { "apply_retention_when_paid": true, "currency_conversion_rate": 1.21, "currency_iso_code": "EUR", "customer_address_detail": "Praceta da Liberdade n5", "customer_business_name": "Ricardo Ribeiro", "customer_city": "Lisboa", "customer_country": "PT", "customer_postcode": "1000-101", "customer_tax_registration_number": "229659179", "date": "2023-01-01", "document_type": "FT", "due_date": "2023-02-01", "external_reference": "Referência do documento externo", "finalize": 0, "lines": [\ {}\ ], "notes": "Notas ao documento", "operation_country": "PT-MA", "payment_mechanism": "MO", "retention": 7.5, "retention_type": "IRS", "settlement_expression": "7.5", "vat_included_prices": false } Copy GET /api/v1/commercial_sales_documents/{salesDocumentId} HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Accept: */* Copy GET /api/v1/commercial_sales_documents/ HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Accept: */* sun-brightdesktopmoon --- # Documentos Retificativos | TOConline - Documentação API [hashtag](https://api-docs.toconline.pt/apis/vendas/documentos-retificativos#criar-documento-retificativo) Criar Documento Retificativo -------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://api-docs.toconline.pt/apis/vendas/documentos-retificativos#post-api-v1-commercial_sales_documents) Criar Documento de Venda post {{base\_url}}/api/v1/commercial\_sales\_documents Criar Documento de Venda chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Body application/jsonchevron-down application/json apply\_retention\_when\_paidbooleanOptionalExample: `true` currency\_conversion\_ratenumberOptionalExample: `1.21` currency\_iso\_codestringOptionalExample: `EUR` customer\_address\_detailstringOptionalExample: `Praceta da Liberdade n5` customer\_business\_namestringOptionalExample: `Ricardo Ribeiro` customer\_citystringOptionalExample: `Lisboa` customer\_countrystringOptionalExample: `PT` customer\_postcodestringOptionalExample: `1000-101` customer\_tax\_registration\_numberstringOptionalExample: `229659179` datestringOptionalExample: `2023-01-01` document\_typestringOptionalExample: `FT` due\_datestringOptionalExample: `2023-02-01` external\_referencestringOptionalExample: `Referência do documento externo` finalizenumberOptionalExample: `0` linesobject\[\]OptionalExample: `[{}]` notesstringOptionalExample: `Notas ao documento` operation\_countrystringOptionalExample: `PT-MA` payment\_mechanismstringOptionalExample: `MO` retentionnumberOptionalExample: `7.5` retention\_typestringOptionalExample: `IRS` settlement\_expressionstringOptionalExample: `7.5` vat\_included\_pricesbooleanOptionalExample: `false` Responses chevron-right 200Success No content post /api/v1/commercial\_sales\_documents HTTPchevron-down HTTPcURLJavaScriptPython Test it 200Success No content #### [hashtag](https://api-docs.toconline.pt/apis/vendas/documentos-retificativos#cabecalho-documentos-de-venda) Cabeçalho Documentos de Venda Atributo Descrição Obrigatório document\_type Tipo de documento. "NC": Nota de Crédito, "ND": Nota de Débito. Sim parent\_documents\_ids Identificador interno do documento ao qual o documento retificativo está associado. Não (mas é recomendado) parent\_document\_reference Identificador externo do documento ao qual o documento retificativo está associado. Não (mas é recomendado) date Data do documento. Por omissão, a data do pedido. Não document\_series\_id Identificador interno da série. Não document\_series\_prefix Prefixo da série. Não customer\_id Identificador interno do cliente. Não customer\_tax\_registration\_number NIF do cliente. Não customer\_business\_name Nome do cliente. Sim customer\_address\_detail Morada do cliente. Não customer\_postcode Código postal do cliente, no formato 0000-000. Não customer\_city Cidade/Localidade do cliente. Não customer\_country País do cliente. Por omissão, "PT". Não due\_date Data de vencimento. Por omissão, a data do documento, ou a referente ao prazo de pagamento configurado no cliente. Não settlement\_expression Desconto no cabeçalho, em percentagem. São suportados descontos compostos, como "3+5". Não payment\_mechanism Modo de pagamento. Não bank\_account\_id Identificador interno da conta bancária da empresa para onde o recebimento é feito. Não cash\_account\_id Identificador interno da conta de caixa da empresa para onde o recebimento é feito. Não vat\_included\_prices Os preços nas linhas são com IVA incluído? Por omissão, não (false). Não tax\_exemption\_reason\_id Motivo de isenção de IVA. Não operation\_country A região de operação para efeitos de IVA. Não currency\_id Identificador interno da moeda. Não currency\_iso\_code Código ISO da moeda do documento. Não currency\_conversion\_rate Taxa de conversão para EUR (1 EUR = n USD Nãão retention Percentagem de retenção a aplicar sobre os serviços. Não retention\_type Tipo de retenção ("IRS" ou "IRC"). Por omissão, "IRS". Não apply\_retention\_when\_paid A retenção é feita logo no documento (false) ou apenas no recebimento (true). Por omissão, false. Não notes Notas ao documento. Não external\_reference Referência do documento externo. Não lines Lista de linhas do documento. Sim #### [hashtag](https://api-docs.toconline.pt/apis/vendas/documentos-retificativos#linha-de-documentos-de-venda) Linha de Documentos de Venda Atributo Descrição Obrigatório item\_type Tipo de item: "Service": serviços, "Product": produtos, "TaxDescriptor": descritores. Sim item\_id Identificador interno do item. Não item\_code Código do serviço/produto/descritor. Não description Descrição da linha. Por omissão é usada a descrição associada ao item, se este for indicado. Sim unit\_of\_measure\_id Identificador interno da unidade de medida. Não unit\_of\_measure Unidade de medida. Por omissão é a configurada no item (se for serviço ou produto). Não quantity Quantidade da linha. Sim unit\_price Preço unitário da linha. Sim settlement\_expression Desconto de linha, em percentagem. Não tax\_id Identificador interno da taxa de IVA. Não tax\_code Tipo de IVA associado ao item. Não tax\_percentage Percentagem de IVA a usar. Não tax\_country\_region Região do IVA. Não circle-info **Nota 1 -** A série associada ao documento tem já que existir, e o seu "id" interno pode ser obtido por um: `GET /commercial_document_series?filter[document_type]=&filter[prefix]=` circle-info **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: `GET /customers?filter[tax_registration_number]=` circle-info **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: `GET /countries?filter[iso_alpha_2]=` circle-info **Nota 4 -** O "id" interno da conta bancária da empresa deve ser obtido por um: `GET /company_bank_accounts?filter[iban]=` `ou` `GET /company_bank_accounts?filter[name]=` circle-info **Nota 5** \- O "id" interno da conta de caixa da empresa deve ser obtido por um `GET /cash_accounts?filter[name]=` circle-info **Nota 6** - O "id" interno do motivo de isenção deve ser obtido por um `GET /tax_exemption_reasons?filter[code]=` circle-info **Nota 7** - O "id" interno da moeda deve ser obtido por um `GET /currencies?filter[iso_code]=` circle-info **Nota 8:** O item (serviço, produto ou descritor) tem já que existir, e o seu "id" interno pode ser obtido por um `GET /services?filter[item_code]=` `ou` `GET /products?filter[item_code]=` `ou` `GET /tax_descriptors?filter[notation]=` circle-info **Nota 9**: A unidade de medida tem já que existir, e o seu "id" interno pode ser obtido por um `GET /units_of_measure?filter[unit_of_measure]=un|` circle-info **Nota 10**: O "id" interno da taxa de IVA deve ser obtido por um `GET /taxes?filter[tax_code]= &filter[tax_country_region]=` `ou` `GET /taxes?filter[tax_code]= &filter[tax_country_region]=PT|&filter[tax_percentage]=` circle-info **Nota 11:** Para as faturas-recibos (FR), o recibo associado é criado automaticamente quando a FR é finalizada. circle-check Ao submenter o documento de venda fica automaticamente **finalizado**! [hashtag](https://api-docs.toconline.pt/apis/vendas/documentos-retificativos#alteracao-do-documento-de-venda) Alteração do Documento de Venda -------------------------------------------------------------------------------------------------------------------------------------------------- triangle-exclamation Após a criação de um documento de venda este fica automaticamente finalizado, se pretender criar documentos sem finalizar pode consultar a versão anterior desta API:[Documentos de Venda](https://api-docs.toconline.pt/apis/vendas/documentos-de-venda) Quando um documento é criado em um estado finalizado, torna-se impossível executar as seguintes operações em documentos de venda: * Finalização do Documento de Venda * Anulação do Documento de Venda * Atualizar Documento de Venda * Eliminação do Documento de Venda * * * [hashtag](https://api-docs.toconline.pt/apis/vendas/documentos-retificativos#obter-documentos-retificativos-por-id) Obter Documentos Retificativos por Id -------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://api-docs.toconline.pt/apis/vendas/documentos-retificativos#get-api-v1-commercial_sales_documents-salesdocumentid) Obter Todos os Documentos de Venda por Id get {{base\_url}}/api/v1/commercial\_sales\_documents/{salesDocumentId} Obter Todos os Documentos de Venda por Id chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Path parameters salesDocumentIdstringRequired Responses chevron-right 200Success No content get /api/v1/commercial\_sales\_documents/{salesDocumentId} HTTPchevron-down HTTPcURLJavaScriptPython Test it 200Success No content [hashtag](https://api-docs.toconline.pt/apis/vendas/documentos-retificativos#obter-todos-os-documentos-retificativos) Obter Todos os Documentos Retificativos ------------------------------------------------------------------------------------------------------------------------------------------------------------------ ### [hashtag](https://api-docs.toconline.pt/apis/vendas/documentos-retificativos#get-api-v1-commercial_sales_documents) Obter Todos os Documentos de Venda get {{base\_url}}/api/v1/commercial\_sales\_documents/ Obter Todos os Documentos de Venda chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Responses chevron-right 200Success No content get /api/v1/commercial\_sales\_documents/ HTTPchevron-down HTTPcURLJavaScriptPython Test it 200Success No content [PreviousDocumentos de Vendachevron-left](https://api-docs.toconline.pt/apis/vendas/documentos-de-venda) [NextRecibos de Vendachevron-right](https://api-docs.toconline.pt/apis/vendas/recibos-de-venda) Last updated 1 year ago * [Criar Documento Retificativo](https://api-docs.toconline.pt/apis/vendas/documentos-retificativos#criar-documento-retificativo) * [POSTCriar Documento de Venda](https://api-docs.toconline.pt/apis/vendas/documentos-retificativos#post-api-v1-commercial_sales_documents) * [Alteração do Documento de Venda](https://api-docs.toconline.pt/apis/vendas/documentos-retificativos#alteracao-do-documento-de-venda) * [Obter Documentos Retificativos por Id](https://api-docs.toconline.pt/apis/vendas/documentos-retificativos#obter-documentos-retificativos-por-id) * [GETObter Todos os Documentos de Venda por Id](https://api-docs.toconline.pt/apis/vendas/documentos-retificativos#get-api-v1-commercial_sales_documents-salesdocumentid) * [Obter Todos os Documentos Retificativos](https://api-docs.toconline.pt/apis/vendas/documentos-retificativos#obter-todos-os-documentos-retificativos) * [GETObter Todos os Documentos de Venda](https://api-docs.toconline.pt/apis/vendas/documentos-retificativos#get-api-v1-commercial_sales_documents) sun-brightdesktopmoon Copy POST /api/v1/commercial_sales_documents HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Content-Type: application/json Accept: */* Content-Length: 640 { "apply_retention_when_paid": true, "currency_conversion_rate": 1.21, "currency_iso_code": "EUR", "customer_address_detail": "Praceta da Liberdade n5", "customer_business_name": "Ricardo Ribeiro", "customer_city": "Lisboa", "customer_country": "PT", "customer_postcode": "1000-101", "customer_tax_registration_number": "229659179", "date": "2023-01-01", "document_type": "FT", "due_date": "2023-02-01", "external_reference": "Referência do documento externo", "finalize": 0, "lines": [\ {}\ ], "notes": "Notas ao documento", "operation_country": "PT-MA", "payment_mechanism": "MO", "retention": 7.5, "retention_type": "IRS", "settlement_expression": "7.5", "vat_included_prices": false } Copy GET /api/v1/commercial_sales_documents/{salesDocumentId} HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Accept: */* Copy GET /api/v1/commercial_sales_documents/ HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Accept: */* sun-brightdesktopmoon --- # Família de Itens | TOConline - Documentação API ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/familia-de-itens#criar-familias-de-item) Criar Famílias de Item ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/familia-de-itens#post-api-item_families) Criar Família de Item post {{base\_url}}/api/item\_families Criar Família de Item chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Body application/jsonchevron-down application/json dataobjectOptional Show propertiesplus Responses chevron-right 200 Sucesso application/json Headersobject Show Headersplus Responseobject Show propertiesplus post /api/item\_families HTTPchevron-down HTTPcURLJavaScriptPython Test it 200 Sucesso ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/familia-de-itens#undefined) ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/familia-de-itens#obter-familia-de-item-por-id) Obter Família de Item por Id ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/familia-de-itens#get-api-item_families-id) Obter Família de Item por ID get {{base\_url}}/api/item\_families/{id} Obter Família de Item por ID chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Path parameters idstringRequired TODO Example: `2` Responses chevron-right 200 Sucesso application/json Headersobject Show Headersplus Responseobject Show propertiesplus get /api/item\_families/{id} HTTPchevron-down HTTPcURLJavaScriptPython Test it 200 Sucesso ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/familia-de-itens#remover-familia-de-item) Remover Família de Item ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/familia-de-itens#delete-api-item_families-id) Remover Família de Item delete {{base\_url}}/api/item\_families/{id} Remover Família de Item chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Path parameters idstringRequired TODO Example: `2` Responses chevron-right 200 Sucesso application/json Headersobject Show Headersplus Responseobject Show propertiesplus delete /api/item\_families/{id} HTTPchevron-down HTTPcURLJavaScriptPython Test it 200 Sucesso ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/familia-de-itens#obter-todas-as-familias-de-item) Obter Todas as Famílias de Item ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/familia-de-itens#get-api-item_families) Obter Todas as Família de Item get {{base\_url}}/api/item\_families Obter Todas as Família de Item chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Responses chevron-right 200Success No content get /api/item\_families HTTPchevron-down HTTPcURLJavaScriptPython Test it 200Success No content [PreviousDescritores de Taxachevron-left](https://api-docs.toconline.pt/apis/apis-auxiliares/descritores-de-taxa) [NextPaíseschevron-right](https://api-docs.toconline.pt/apis/apis-auxiliares/paises) Last updated 1 year ago * [Criar Famílias de Item](https://api-docs.toconline.pt/apis/apis-auxiliares/familia-de-itens#criar-familias-de-item) * [POSTCriar Família de Item](https://api-docs.toconline.pt/apis/apis-auxiliares/familia-de-itens#post-api-item_families) * [](https://api-docs.toconline.pt/apis/apis-auxiliares/familia-de-itens#undefined) * [Obter Família de Item por Id](https://api-docs.toconline.pt/apis/apis-auxiliares/familia-de-itens#obter-familia-de-item-por-id) * [GETObter Família de Item por ID](https://api-docs.toconline.pt/apis/apis-auxiliares/familia-de-itens#get-api-item_families-id) * [Remover Família de Item](https://api-docs.toconline.pt/apis/apis-auxiliares/familia-de-itens#remover-familia-de-item) * [DELETERemover Família de Item](https://api-docs.toconline.pt/apis/apis-auxiliares/familia-de-itens#delete-api-item_families-id) * [Obter Todas as Famílias de Item](https://api-docs.toconline.pt/apis/apis-auxiliares/familia-de-itens#obter-todas-as-familias-de-item) * [GETObter Todas as Família de Item](https://api-docs.toconline.pt/apis/apis-auxiliares/familia-de-itens#get-api-item_families) sun-brightdesktopmoon Copy POST /api/item_families HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Content-Type: application/json Accept: */* Content-Length: 64 { "data": { "attributes": { "name": "Frutas" }, "type": "item_families" } } Copy { "data": { "attributes": { "name": "Frutas" }, "id": "6", "relationships": { "company": { "data": { "id": "800000046", "type": "current_company" } } }, "type": "item_families" } } Copy GET /api/item_families/{id} HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Accept: */* Copy { "data": { "attributes": { "name": "FamiliaDeServiço1" }, "id": "5", "relationships": { "company": { "data": { "id": "800000046", "type": "current_company" } } }, "type": "item_families" } } Copy DELETE /api/item_families/{id} HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Accept: */* Copy { "meta": {} } Copy GET /api/item_families HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Accept: */* sun-brightdesktopmoon --- # Recibos de Venda | TOConline - Documentação API ### [hashtag](https://api-docs.toconline.pt/apis/vendas/recibos-de-venda#criacao-de-cabecalhos-e-linhas) Criar Cabeçalho Recibo de Venda ### [hashtag](https://api-docs.toconline.pt/apis/vendas/recibos-de-venda#post-api-v1-commercial_sales_receipts) Criar Cabeçalho Recibo de Venda post {{base\_url}}/api/v1/commercial\_sales\_receipts Criar Cabeçalho Recibo de Venda chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Body application/jsonchevron-down application/json cash\_account\_idnumberOptionalExample: `2` check\_numberany | nullableOptional company\_idnumberOptionalExample: `800000046` country\_idnumberOptionalExample: `1` created\_atstringOptionalExample: `2024-02-23 11:49:25.209661` currency\_conversion\_ratenumberOptionalExample: `1` currency\_idnumberOptionalExample: `1` customer\_idnumberOptionalExample: `57` datestringOptionalExample: `2024-02-24` deletedbooleanOptionalExample: `true` gross\_totalnumberOptionalExample: `10.69` internal\_observationsstringOptional linesobject\[\]OptionalExample: `[{"cashed_vat_amount":null,"gross_total":11.38,"net_total":9.25,"receivable_id":12,"receivable_type":"Document","received_value":10.69,"retention_total":0.69,"settlement_amount":0,"settlement_percentage":0}]` Show propertiesplus manual\_registration\_numberany | nullableOptional manual\_registration\_seriesany | nullableOptional manual\_registration\_typeany | nullableOptional net\_totalnumberOptionalExample: `9.25` observationsstringOptional payment\_mechanismstringOptionalExample: `MO` saft\_import\_idany | nullableOptional standalonebooleanOptionalExample: `true` third\_party\_idany | nullableOptional third\_party\_typeany | nullableOptional updated\_atstringOptionalExample: `2024-02-28 14:04:52.678033` user\_idnumberOptionalExample: `800000863` Responses chevron-right 200Success No content post /api/v1/commercial\_sales\_receipts HTTPchevron-down HTTPcURLJavaScriptPython Test it 200Success No content Copy { "date": "2020-06-01", // [OPCIONAL] Data do recibo; por omissão, a data do pedido "payment_mechanism": "MO", // [OPCIONAL] Por omissão, "MO". Meios de pagamento aceites: "MO": Numerário, "CH": Cheque, "DC": Cartão de débito, "CC": Cartão de crédito, "TR": Transferência bancária, "DDA": Débito direto autorizado, "MB": Referências de pagamento Multibanco. // [OPCIONAL] Recursos associados ao recibo. Caso nenhum seja indicado, os restantes devem atributos devem ser omitidos. Caso contrário, todos os atributos devem ser preenchidos. "commercial_document_series_id": 1, // [OBRIGATÓRIO] Série de recibos associada. Não precisa de ser indicada; por omissão o recibo é criado na série por omissão associada ao tipo de documento. Vd. NOTA 1 "bank_account_id": 2, // [OBRIGATÓRIO] Conta bancária da empresa para onde o recebimento é feito. Usado apenas quando o meio de pagamento é "DC", "CC", "TR" ou "DDA", e apenas se for necessário indicar uma conta bancária específica. Vd. NOTA 2 "cash_account_id": 3, // [OBRIGATÓRIO] Conta de caixa da empresa para onde o recebimento é feito. Usado apenas quando o meio de pagamento é "MO", e apenas se for necessário indicar uma conta de caixa específica. Vd. NOTA 3 "lines": [\ {\ "receivable_type": "Document", // [OBRIGATÓRIO]\ "receivable_id": "", // [OBRIGATÓRIO] Vd. NOTA 1\ "received_value": 50, // [OBRIGATÓRIO] Valor total a receber (não é necessário receber a totalidade do documento, pode fazer-se um recebimento parcial)\ "settlement_percentage": "3" // [OPCIONAL] Desconto de pagamento, em percentagem; são suportados descontos compostos, como "3+5"\ }\ ] } circle-info **Nota 1:** A série associada ao recibo tem já que existir, e o seu "id" interno deve ser obtido por um circle-info **Nota 2:** O "id" interno da conta bancária da empresa deve ser obtido por um circle-info **Nota 3:** O "id" interno da conta de caixa da empresa deve ser obtido por um ### [hashtag](https://api-docs.toconline.pt/apis/vendas/recibos-de-venda#criacao-de-cabecalhos-e-linhas-1) Criar Linhas de Recibo de Venda ### [hashtag](https://api-docs.toconline.pt/apis/vendas/recibos-de-venda#post-api-commercial_sales_receipt_lines) Adicionar Linha a Recibo de Venda post {{base\_url}}/api/commercial\_sales\_receipt\_lines Adicionar Linha a Recibo de Venda chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Body application/jsonchevron-down application/json dataobjectOptional Show propertiesplus Responses chevron-right 200Success No content post /api/commercial\_sales\_receipt\_lines HTTPchevron-down HTTPcURLJavaScriptPython Test it 200Success No content ### [hashtag](https://api-docs.toconline.pt/apis/vendas/recibos-de-venda#anulacao-de-um-recibo-caso-seja-preciso) Anular Recibo de Venda ### [hashtag](https://api-docs.toconline.pt/apis/vendas/recibos-de-venda#patch-api-v1-commercial_sales_receipts-salesreceiptid-void) Anular Recibo de Venda patch {{base\_url}}/api/v1/commercial\_sales\_receipts/{salesReceiptId}/void Anular Recibo de Venda chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Path parameters salesReceiptIdstringRequired Responses chevron-right 200Success No content patch /api/v1/commercial\_sales\_receipts/{salesReceiptId}/void HTTPchevron-down HTTPcURLJavaScriptPython Test it 200Success No content No pedido acima, o corresponde ao token de acesso válido devolvido pelo serviço de OAuth circle-info **Nota 1:** O "id" interno do recibo a anular deve ser obtido por um `GET /api/commercial_sales_receipts?filter[document_no]=` É na linha do recibo que se indica qual o documento (FT, ou outro) que foi pago. Se necessário, pode criar-se mais do que uma linha (e nesse caso o recibo é emitido de uma só vez para todos os documentos referenciados) ### [hashtag](https://api-docs.toconline.pt/apis/vendas/recibos-de-venda#edicao-do-recibo-apos-criacao) Edição do recibo, após criação O seguinte pedido pode ser realizado, após a criação do recibo, e permite alterar informações sobre o mesmo. A estrutura do payload é a mesma do POST de criação. Neste, deverá enviar no id do pedido o id do recibo a alterar. Os atributos enviados no body irão substituir os guardados no momento, e cada linha enviada dentro de lines irá substituir os dados guardados na linha com id especificado em receipt\_line\_id ### [hashtag](https://api-docs.toconline.pt/apis/vendas/recibos-de-venda#patch-api-v1-commercial_sales_receipts-salesreceiptid) Atualizar Recibo de Venda patch {{base\_url}}/api/v1/commercial\_sales\_receipts/{salesReceiptId} Atualizar Recibo de Venda chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Path parameters salesReceiptIdstringRequired Body application/jsonchevron-down application/json cash\_account\_idnumberOptionalExample: `2` check\_numberany | nullableOptional company\_idnumberOptionalExample: `800000046` country\_idnumberOptionalExample: `1` created\_atstringOptionalExample: `2024-02-23 11:49:25.209661` currency\_conversion\_ratenumberOptionalExample: `1` currency\_idnumberOptionalExample: `1` customer\_idnumberOptionalExample: `57` datestringOptionalExample: `2024-02-24` deletedbooleanOptionalExample: `true` document\_nostringOptionalExample: `RC 2023/1` document\_series\_idnumberOptionalExample: `66` gross\_totalnumberOptionalExample: `10.69` idnumberOptionalExample: `2` internal\_observationsstringOptional linesobject\[\]OptionalExample: `[{"cashed_vat_amount":null,"gross_total":11.38,"id":2,"net_total":9.25,"receipt_id":2,"receivable_id":12,"receivable_type":"Document","received_value":10.69,"retention_total":0.69,"settlement_amount":0,"settlement_percentage":0}]` Show propertiesplus manual\_registration\_numberany | nullableOptional manual\_registration\_seriesany | nullableOptional manual\_registration\_typeany | nullableOptional net\_totalnumberOptionalExample: `9.25` observationsstringOptional payment\_mechanismstringOptionalExample: `MO` saft\_import\_idany | nullableOptional standalonebooleanOptionalExample: `true` third\_party\_idany | nullableOptional third\_party\_typeany | nullableOptional updated\_atstringOptionalExample: `2024-02-27 11:19:15.761393` user\_idnumberOptionalExample: `800000863` Responses chevron-right 200Success No content patch /api/v1/commercial\_sales\_receipts/{salesReceiptId} HTTPchevron-down HTTPcURLJavaScriptPython Test it 200Success No content #### [hashtag](https://api-docs.toconline.pt/apis/vendas/recibos-de-venda#exemplo) Exemplo: Payload Response ### [hashtag](https://api-docs.toconline.pt/apis/vendas/recibos-de-venda#adicao-de-linhas) Adição de Linha em Documento de Recibo de Venda Caso pretenda adicionar novas linhas ao recibo, após a sua criação, pode utilizar a seguinte rota, que utiliza o mesmo payload das lines do pedido POST de criação. ### [hashtag](https://api-docs.toconline.pt/apis/vendas/recibos-de-venda#post-api-commercial_sales_receipt_lines-1) Adicionar Linha a Recibo de Venda post {{base\_url}}/api/commercial\_sales\_receipt\_lines Adicionar Linha a Recibo de Venda chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Body application/jsonchevron-down application/json dataobjectOptional Show propertiesplus Responses chevron-right 200Success No content post /api/commercial\_sales\_receipt\_lines HTTPchevron-down HTTPcURLJavaScriptPython Test it 200Success No content No pedido acima, o corresponde ao token de acesso válido devolvido pelo serviço de OAuth, e o deverá ter o seguinte formato circle-info **Nota 1:** O "id" interno do documento (fatura, nota) a receber deve ser obtido por um circle-check É na linha do recibo que se indica qual o documento (FT, ou outro) que foi pago. Se necessário, pode criar-se mais do que uma linha (e nesse caso o recibo é emitido de uma só vez para todos os documentos referenciados) ### [hashtag](https://api-docs.toconline.pt/apis/vendas/recibos-de-venda#remover-linha-do-recibo-de-venda) Remover Linha do Recibo de Venda Do mesmo modo, caso pretenda remover linhas de um recibo, pode utilizar a seguinte rota, onde apenas tem de indicar o id da linha a remover, no path. `DELETE` `/v1/commercial_sales_receipt_lines/{id}` #### [hashtag](https://api-docs.toconline.pt/apis/vendas/recibos-de-venda#path-parameters) Path Parameters Name Type Description id\* Integer id of the receipt line to delete 200: OK OK ### [hashtag](https://api-docs.toconline.pt/apis/vendas/recibos-de-venda#consultar-recibo) Obter Recibo de Venda por ID Por fim, se pretender obter informações sobre um dado recibo pode utilizar a seguinte rota, onde deverá especificar o id do documento a analisar no path. `GET` `/v1/commercial_sales_receipts/{id}` #### [hashtag](https://api-docs.toconline.pt/apis/vendas/recibos-de-venda#path-parameters-1) Path Parameters Name Type Description id\* integer id of the receipt to get the information of 200: OK OK [PreviousDocumentos Retificativos chevron-left](https://api-docs.toconline.pt/apis/vendas/documentos-retificativos) [NextDescarregar PDF de Documentos de Vendachevron-right](https://api-docs.toconline.pt/apis/vendas/descarregar-pdf-de-documentos-de-venda) Last updated 1 year ago * [Criar Cabeçalho Recibo de Venda](https://api-docs.toconline.pt/apis/vendas/recibos-de-venda#criacao-de-cabecalhos-e-linhas) * [POSTCriar Cabeçalho Recibo de Venda](https://api-docs.toconline.pt/apis/vendas/recibos-de-venda#post-api-v1-commercial_sales_receipts) * [Criar Linhas de Recibo de Venda](https://api-docs.toconline.pt/apis/vendas/recibos-de-venda#criacao-de-cabecalhos-e-linhas-1) * [POSTAdicionar Linha a Recibo de Venda](https://api-docs.toconline.pt/apis/vendas/recibos-de-venda#post-api-commercial_sales_receipt_lines) * [Anular Recibo de Venda](https://api-docs.toconline.pt/apis/vendas/recibos-de-venda#anulacao-de-um-recibo-caso-seja-preciso) * [PATCHAnular Recibo de Venda](https://api-docs.toconline.pt/apis/vendas/recibos-de-venda#patch-api-v1-commercial_sales_receipts-salesreceiptid-void) * [Edição do recibo, após criação](https://api-docs.toconline.pt/apis/vendas/recibos-de-venda#edicao-do-recibo-apos-criacao) * [PATCHAtualizar Recibo de Venda](https://api-docs.toconline.pt/apis/vendas/recibos-de-venda#patch-api-v1-commercial_sales_receipts-salesreceiptid) * [Adição de Linha em Documento de Recibo de Venda](https://api-docs.toconline.pt/apis/vendas/recibos-de-venda#adicao-de-linhas) * [POSTAdicionar Linha a Recibo de Venda](https://api-docs.toconline.pt/apis/vendas/recibos-de-venda#post-api-commercial_sales_receipt_lines-1) * [Remover Linha do Recibo de Venda](https://api-docs.toconline.pt/apis/vendas/recibos-de-venda#remover-linha-do-recibo-de-venda) * [Obter Recibo de Venda por ID](https://api-docs.toconline.pt/apis/vendas/recibos-de-venda#consultar-recibo) sun-brightdesktopmoon Copy POST /api/v1/commercial_sales_receipts HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Content-Type: application/json Accept: */* Content-Length: 789 { "cash_account_id": 2, "check_number": null, "company_id": 800000046, "country_id": 1, "created_at": "2024-02-23 11:49:25.209661", "currency_conversion_rate": 1, "currency_id": 1, "customer_id": 57, "date": "2024-02-24", "deleted": true, "gross_total": 10.69, "internal_observations": "", "lines": [\ {\ "cashed_vat_amount": null,\ "gross_total": 11.38,\ "net_total": 9.25,\ "receivable_id": 12,\ "receivable_type": "Document",\ "received_value": 10.69,\ "retention_total": 0.69,\ "settlement_amount": 0,\ "settlement_percentage": 0\ }\ ], "manual_registration_number": null, "manual_registration_series": null, "manual_registration_type": null, "net_total": 9.25, "observations": "", "payment_mechanism": "MO", "saft_import_id": null, "standalone": true, "third_party_id": null, "third_party_type": null, "updated_at": "2024-02-28 14:04:52.678033", "user_id": 800000863 } Copy GET /commercial_document_series?filter[document_type]=o tipo de documento> &filter[prefix]= &filter[number]= Copy GET /company_bank_accounts?filter[iban]= ou GET /company_bank_accounts?filter[name]= Copy GET /cash_accounts?filter[name]= Copy POST /api/commercial_sales_receipt_lines HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Content-Type: application/json Accept: */* Content-Length: 285 { "data": { "attributes": { "cashed_vat_amount": null, "gross_total": 10.69, "net_total": 9.27, "receipt_id": 13, "receivable_id": 12, "receivable_type": "Document", "received_value": 10.69, "retention_total": 0.72, "settlement_amount": 0, "settlement_percentage": 0 }, "type": "commercial_sales_receipt_lines" } } Copy PATCH /api/v1/commercial_sales_receipts/{salesReceiptId}/void HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Accept: */* Copy PATCH /api/v1/commercial_sales_receipts/{salesReceiptId} HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Content-Type: application/json Accept: */* Content-Length: 868 { "cash_account_id": 2, "check_number": null, "company_id": 800000046, "country_id": 1, "created_at": "2024-02-23 11:49:25.209661", "currency_conversion_rate": 1, "currency_id": 1, "customer_id": 57, "date": "2024-02-24", "deleted": true, "document_no": "RC 2023/1", "document_series_id": 66, "gross_total": 10.69, "id": 2, "internal_observations": "", "lines": [\ {\ "cashed_vat_amount": null,\ "gross_total": 11.38,\ "id": 2,\ "net_total": 9.25,\ "receipt_id": 2,\ "receivable_id": 12,\ "receivable_type": "Document",\ "received_value": 10.69,\ "retention_total": 0.69,\ "settlement_amount": 0,\ "settlement_percentage": 0\ }\ ], "manual_registration_number": null, "manual_registration_series": null, "manual_registration_type": null, "net_total": 9.25, "observations": "", "payment_mechanism": "MO", "saft_import_id": null, "standalone": true, "third_party_id": null, "third_party_type": null, "updated_at": "2024-02-27 11:19:15.761393", "user_id": 800000863 } Exemplo de Payload Copy { "date": "2024-02-24", "document_no": "RC 2023/1", "document_series_id": 66, "payment_mechanism": "MO", "gross_total": 10.69, "net_total": 9.25, "third_party_type": null, "third_party_id": null, "check_number": null, "currency_conversion_rate": 1, "internal_observations": "", "observations": "", "standalone": true, "saft_import_id": null, "deleted": true, "manual_registration_type": null, "manual_registration_series": null, "manual_registration_number": null, "created_at": "2024-02-23 11:49:25.209661", "updated_at": "2024-02-27 11:19:15.761393", "id": 2, "cash_account_id": 2, "company_id": 800000046, "country_id": 1, "currency_id": 1, "customer_id": 57, "user_id": 800000863, "lines": [\ {\ "receipt_id": 2,\ "receivable_type": "Document",\ "receivable_id": 12,\ "received_value": 10.69,\ "settlement_percentage": 0,\ "cashed_vat_amount": null,\ "gross_total": 11.38,\ "settlement_amount": 0.0,\ "net_total": 9.25,\ "retention_total": 0.69,\ "id": 2\ }\ ] } Exemplo de Response Copy { "date": "2024-02-24", "document_no": "RC 2023/1", "document_series_id": 66, "payment_mechanism": "MO", "gross_total": 10.69, "net_total": 9.25, "third_party_type": null, "third_party_id": null, "check_number": null, "currency_conversion_rate": 1, "internal_observations": "", "observations": "", "standalone": true, "saft_import_id": null, "deleted": true, "manual_registration_type": null, "manual_registration_series": null, "manual_registration_number": null, "created_at": "2024-02-23 11:49:25.209661", "updated_at": "2024-02-27 14:03:24.085399", "id": 2, "cash_account_id": 2, "company_id": 800000046, "country_id": 1, "currency_id": 1, "customer_id": 57, "user_id": 800000863, "lines": [\ {\ "receipt_id": 2,\ "receivable_type": "Document",\ "receivable_id": 12,\ "received_value": 10.69,\ "settlement_percentage": 0,\ "cashed_vat_amount": null,\ "gross_total": 11.38,\ "settlement_amount": 0.0,\ "net_total": 9.25,\ "retention_total": 0.69,\ "id": 2\ }\ ] } Copy POST /api/commercial_sales_receipt_lines HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Content-Type: application/json Accept: */* Content-Length: 285 { "data": { "attributes": { "cashed_vat_amount": null, "gross_total": 10.69, "net_total": 9.27, "receipt_id": 13, "receivable_id": 12, "receivable_type": "Document", "received_value": 10.69, "retention_total": 0.72, "settlement_amount": 0, "settlement_percentage": 0 }, "type": "commercial_sales_receipt_lines" } } Payload Copy { "data": { "type": "commercial_sales_receipt_lines", // [OBRIGATÓRIO] "attributes": { "receivable_type": "Document", // [OBRIGATÓRIO] "receivable_id": "", // [OBRIGATÓRIO] Vd. Nota 1 "received_value": 50, // [OBRIGATÓRIO] Valor total a receber (não é necessário receber a totalidade do documento, pode fazer-se um recebimento parcial) "settlement_percentage": "3" // [OPCIONAL] Desconto de pagamento, em percentagem; são suportados descontos compostos, como "3+5" "receipt_id" : "" // [OBRIGATÓRIO] Recibo a que esta linha pertence. Este "id" é o devolvido na resposta ao pedido de criação do cabeçalho, ver acima } } } Copy GET /commercial_sales_documents?filter[document_no]= sun-brightdesktopmoon --- # Caixa Associada | TOConline - Documentação API ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/caixa-associada#obter-todas-as-caixas-associadas) Obter Todas as Caixas Associadas De modo a obter informações sobre um dado descritor, poderá realizar o seguinte pedido ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/caixa-associada#get-api-cash_accounts) Obter Todas as Contas de Caixa get {{base\_url}}/api/cash\_accounts Obter Todas as Contas de Caixa chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Responses chevron-right 200Success No content get /api/cash\_accounts HTTPchevron-down HTTPcURLJavaScriptPython Test it 200Success No content chevron-rightExemplo de Response[hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/caixa-associada#exemplo-de-response) ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/caixa-associada#obter-caixas-associadas-por-id) Obter Caixas Associadas por ID ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/caixa-associada#get-api-cash_accounts-id) Obter Contas de Caixa por ID get {{base\_url}}/api/cash\_accounts/{id} Obter Contas de Caixa por ID chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Path parameters idstringRequired TODO Example: `2` Responses chevron-right 200 Obter Contas de Caixa por ID application/json Headersobject Show Headersplus Responseobject Show propertiesplus get /api/cash\_accounts/{id} HTTPchevron-down HTTPcURLJavaScriptPython Test it 200 Obter Contas de Caixa por ID Endpoint Response ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/caixa-associada#criar-caixas-associadas) Criar Caixas Associadas ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/caixa-associada#post-api-cash_accounts) Criar Contas de Caixa post {{base\_url}}/api/cash\_accounts Criar Contas de Caixa chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Body application/jsonchevron-down application/json dataobjectOptional Show propertiesplus Responses chevron-right 200 Sucesso application/json Headersobject Show Headersplus Responseobject Show propertiesplus post /api/cash\_accounts HTTPchevron-down HTTPcURLJavaScriptPython Test it 200 Sucesso ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/caixa-associada#remover-caixas-associadas) Remover Caixas Associadas ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/caixa-associada#delete-api-bank_accounts-bankaccountid) Remover Contas Bancárias delete {{base\_url}}/api/bank\_accounts/{bankAccountId} Remover Contas Bancárias chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Path parameters bankAccountIdstringRequired Id da conta bancária Example: `5` Responses chevron-right 200 Sucesso application/json Headersobject Show Headersplus Responseobject Show propertiesplus delete /api/bank\_accounts/{bankAccountId} HTTPchevron-down HTTPcURLJavaScriptPython Test it 200 Sucesso [PreviousContas Bancáriaschevron-left](https://api-docs.toconline.pt/apis/apis-auxiliares/contas-bancarias) [NextUnidade Monetáriachevron-right](https://api-docs.toconline.pt/apis/apis-auxiliares/unidade-monetaria) Last updated 1 year ago * [Obter Todas as Caixas Associadas](https://api-docs.toconline.pt/apis/apis-auxiliares/caixa-associada#obter-todas-as-caixas-associadas) * [GETObter Todas as Contas de Caixa](https://api-docs.toconline.pt/apis/apis-auxiliares/caixa-associada#get-api-cash_accounts) * [Obter Caixas Associadas por ID](https://api-docs.toconline.pt/apis/apis-auxiliares/caixa-associada#obter-caixas-associadas-por-id) * [GETObter Contas de Caixa por ID](https://api-docs.toconline.pt/apis/apis-auxiliares/caixa-associada#get-api-cash_accounts-id) * [Criar Caixas Associadas](https://api-docs.toconline.pt/apis/apis-auxiliares/caixa-associada#criar-caixas-associadas) * [POSTCriar Contas de Caixa](https://api-docs.toconline.pt/apis/apis-auxiliares/caixa-associada#post-api-cash_accounts) * [Remover Caixas Associadas](https://api-docs.toconline.pt/apis/apis-auxiliares/caixa-associada#remover-caixas-associadas) * [DELETERemover Contas Bancárias](https://api-docs.toconline.pt/apis/apis-auxiliares/caixa-associada#delete-api-bank_accounts-bankaccountid) sun-brightdesktopmoon Copy GET /api/cash_accounts HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Accept: */* Copy { "data": [\ {\ "type": "cash_accounts",\ "id": "2",\ "attributes": {\ "name": "Caixa Teste 1"\ },\ "relationships": {\ "company": {\ "data": {\ "type": "current_company",\ "id": "800000046"\ }\ }\ }\ }\ ] } Copy GET /api/cash_accounts/{id} HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Accept: */* Copy { "data": { "attributes": { "name": "Caixa Teste 1" }, "id": "2", "relationships": { "company": { "data": { "id": "800000046", "type": "current_company" } } }, "type": "cash_accounts" } } Copy GET /api/bank_accounts/2 Copy { "data": { "type": "bank_accounts", "id": "2", "attributes": { "entity_type": "User", "description": null, "name": "BANCO BPI, SA", "nib": "001049282327079673218", "swift": "BBPIPTPL", "iban": "PT50001049282327079673218", "initial_balance": null, "sub_type": "ticket_account", "card_number": "", "account_type": "DO", "only_one_payment": null, "is_connected": false, "consent_until": null }, "relationships": { "supplier": { "data": null }, "user": { "data": { "type": "current_company_users", "id": "800000863" } } } } } Copy POST /api/cash_accounts HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Content-Type: application/json Accept: */* Content-Length: 71 { "data": { "attributes": { "name": "Caixa Teste 2" }, "type": "cash_accounts" } } Copy { "data": { "attributes": { "name": "Caixa Teste 2" }, "id": "3", "relationships": { "company": { "data": { "id": "800000046", "type": "current_company" } } }, "type": "cash_accounts" } } Copy DELETE /api/bank_accounts/{bankAccountId} HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Accept: */* Copy { "meta": {} } sun-brightdesktopmoon --- # Descritores de Taxa | TOConline - Documentação API ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/descritores-de-taxa#obter-todos-os-descritores-de-taxa) Obter Todos os Descritores de Taxa ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/descritores-de-taxa#get-api-tax_descriptors) Obter Todos os Descritores de Taxa get {{base\_url}}/api/tax\_descriptors Obter Todos os Descritores de Taxa chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Responses chevron-right 200Success No content get /api/tax\_descriptors HTTPchevron-down HTTPcURLJavaScriptPython Test it 200Success No content ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/descritores-de-taxa#criar-descritores) Criar Descritores ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/descritores-de-taxa#post-api-tax_descriptors) Criar Descritores de Taxa post {{base\_url}}/api/tax\_descriptors Criar Descritores de Taxa chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Body application/jsonchevron-down application/json dataobjectOptional Show propertiesplus Responses chevron-right 200 Sucesso application/json Headersobject Show Headersplus Responseobject Show propertiesplus post /api/tax\_descriptors HTTPchevron-down HTTPcURLJavaScriptPython Test it 200 Sucesso [PreviousAPIs Auxiliareschevron-left](https://api-docs.toconline.pt/apis/apis-auxiliares) [NextFamília de Itenschevron-right](https://api-docs.toconline.pt/apis/apis-auxiliares/familia-de-itens) Last updated 1 year ago * [Obter Todos os Descritores de Taxa](https://api-docs.toconline.pt/apis/apis-auxiliares/descritores-de-taxa#obter-todos-os-descritores-de-taxa) * [GETObter Todos os Descritores de Taxa](https://api-docs.toconline.pt/apis/apis-auxiliares/descritores-de-taxa#get-api-tax_descriptors) * [Criar Descritores](https://api-docs.toconline.pt/apis/apis-auxiliares/descritores-de-taxa#criar-descritores) * [POSTCriar Descritores de Taxa](https://api-docs.toconline.pt/apis/apis-auxiliares/descritores-de-taxa#post-api-tax_descriptors) sun-brightdesktopmoon Copy GET /api/tax_descriptors HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Accept: */* Copy POST /api/tax_descriptors HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Content-Type: application/json Accept: */* Content-Length: 221 { "data": { "attributes": { "allow_negative": false, "description": "Teste descritor", "notation": ">TEST1", "other_tax_code": false, "saft_import_id": null, "suggested_tax_code": null, "supports_tax_code": true }, "type": "tax_descriptors" } } Copy { "data": { "attributes": { "allow_negative": false, "company_id": 800000046, "description": "Teste descritor", "notation": "A1", "other_tax_code": false, "saft_import_id": null, "suggested_tax_code": "NOR", "supports_tax_code": true }, "id": "1003", "relationships": { "company": { "data": { "id": "800000046", "type": "current_company" } }, "tax_exemption_reasons": { "data": null } }, "type": "tax_descriptors" } } sun-brightdesktopmoon --- # Contas Bancárias | TOConline - Documentação API ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/contas-bancarias#obter-todas-as-contas-bancarias) Obter Todas as Contas Bancárias ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/contas-bancarias#get-api-bank_accounts) Obter Todas as Contas Bancárias get {{base\_url}}/api/bank\_accounts Obter Todas as Contas Bancárias chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Responses chevron-right 200Success No content get /api/bank\_accounts HTTPchevron-down HTTPcURLJavaScriptPython Test it 200Success No content chevron-rightExemplo de Response[hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/contas-bancarias#exemplo-de-response) Copy { "data": [\ {\ "type": "bank_accounts",\ "id": "2",\ "attributes": {\ "entity_type": "User",\ "description": null,\ "name": "BANCO BPI, SA",\ "nib": "001049282327079673218",\ "swift": "BBPIPTPL",\ "iban": "PT50001049282327079673218",\ "initial_balance": null,\ "sub_type": "ticket_account",\ "card_number": "",\ "account_type": "DO",\ "only_one_payment": null,\ "is_connected": false,\ "consent_until": null\ },\ "relationships": {\ "supplier": {\ "data": null\ },\ "user": {\ "data": {\ "type": "current_company_users",\ "id": "800000863"\ }\ }\ }\ },\ \ (...)\ \ ] } ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/contas-bancarias#obter-contas-bancaria-por-id) Obter Contas Bancária por ID ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/contas-bancarias#get-api-bank_accounts-bankaccountid) Obter Conta Bancária por Id get {{base\_url}}/api/bank\_accounts/{bankAccountId} Obter Conta Bancária por Id chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Path parameters bankAccountIdstringRequired Id da conta bancária Example: `5` Responses chevron-right 200 Sucesso application/json Headersobject Show Headersplus Responseobject Show propertiesplus get /api/bank\_accounts/{bankAccountId} HTTPchevron-down HTTPcURLJavaScriptPython Test it 200 Sucesso ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/contas-bancarias#criar-conta-bancaria) Criar Conta Bancária ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/contas-bancarias#post-api-bank_accounts) Criar Contas Bancárias de Utilizador post {{base\_url}}/api/bank\_accounts Criar Contas Bancárias de Utilizador chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Body application/jsonchevron-down application/json dataobjectOptional Show propertiesplus Responses chevron-right 200 Sucesso / Sucesso application/json Headersobject Show Headersplus Responseobject Show propertiesplus post /api/bank\_accounts HTTPchevron-down HTTPcURLJavaScriptPython Criar Contas Bancárias de Fornecedorchevron-down Criar Contas Bancárias de FornecedorCriar Contas Bancárias de Utilizador Test it 200 Sucesso / Sucesso ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/contas-bancarias#remover-conta-bancaria) Remover Conta Bancária ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/contas-bancarias#delete-api-bank_accounts-bankaccountid) Remover Contas Bancárias delete {{base\_url}}/api/bank\_accounts/{bankAccountId} Remover Contas Bancárias chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Path parameters bankAccountIdstringRequired Id da conta bancária Example: `5` Responses chevron-right 200 Sucesso application/json Headersobject Show Headersplus Responseobject Show propertiesplus delete /api/bank\_accounts/{bankAccountId} HTTPchevron-down HTTPcURLJavaScriptPython Test it 200 Sucesso [PreviousUnidades de Medidachevron-left](https://api-docs.toconline.pt/apis/apis-auxiliares/unidades-de-medida) [NextCaixa Associadachevron-right](https://api-docs.toconline.pt/apis/apis-auxiliares/caixa-associada) Last updated 1 year ago * [Obter Todas as Contas Bancárias](https://api-docs.toconline.pt/apis/apis-auxiliares/contas-bancarias#obter-todas-as-contas-bancarias) * [GETObter Todas as Contas Bancárias](https://api-docs.toconline.pt/apis/apis-auxiliares/contas-bancarias#get-api-bank_accounts) * [Obter Contas Bancária por ID](https://api-docs.toconline.pt/apis/apis-auxiliares/contas-bancarias#obter-contas-bancaria-por-id) * [GETObter Conta Bancária por Id](https://api-docs.toconline.pt/apis/apis-auxiliares/contas-bancarias#get-api-bank_accounts-bankaccountid) * [Criar Conta Bancária](https://api-docs.toconline.pt/apis/apis-auxiliares/contas-bancarias#criar-conta-bancaria) * [POSTCriar Contas Bancárias de Utilizador](https://api-docs.toconline.pt/apis/apis-auxiliares/contas-bancarias#post-api-bank_accounts) * [Remover Conta Bancária](https://api-docs.toconline.pt/apis/apis-auxiliares/contas-bancarias#remover-conta-bancaria) * [DELETERemover Contas Bancárias](https://api-docs.toconline.pt/apis/apis-auxiliares/contas-bancarias#delete-api-bank_accounts-bankaccountid) sun-brightdesktopmoon Copy GET /api/bank_accounts HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Accept: */* Copy GET /api/bank_accounts/{bankAccountId} HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Accept: */* Copy { "data": { "attributes": { "account_type": "DO", "card_number": "", "consent_until": null, "description": null, "entity_type": "User", "iban": "PT50001049282327079673218", "initial_balance": null, "is_connected": false, "name": "BANCO BPI, SA", "nib": "001049282327079673218", "only_one_payment": null, "sub_type": "ticket_account", "swift": "BBPIPTPL" }, "id": "2", "relationships": { "supplier": { "data": null }, "user": { "data": { "id": "800000863", "type": "current_company_users" } } }, "type": "bank_accounts" } } Copy POST /api/bank_accounts HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Content-Type: application/json Accept: */* Content-Length: 395 { "data": { "attributes": { "account_type": "DO", "card_number": "", "consent_until": null, "description": "Descrição de Conta Bancária", "entity_id": 4, "entity_type": "Supplier", "iban": "PT50001049282327079673219", "initial_balance": null, "is_connected": false, "name": "BANCO BPI, SA", "nib": "001049282327079673219", "only_one_payment": null, "sub_type": "ticket_account", "swift": "BBPIPTPL" }, "type": "bank_accounts" } } Copy { "data": { "attributes": { "account_type": "DO", "card_number": "", "consent_until": null, "description": "Descrição de Conta Bancária", "entity_type": "Supplier", "iban": "PT50001049282327079673219", "initial_balance": null, "is_connected": false, "name": "BANCO BPI, SA", "nib": "001049282327079673219", "only_one_payment": null, "sub_type": "ticket_account", "swift": "BBPIPTPL" }, "id": "7", "relationships": { "supplier": { "data": null }, "user": { "data": null } }, "type": "bank_accounts" } } Copy DELETE /api/bank_accounts/{bankAccountId} HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Accept: */* Copy { "meta": {} } sun-brightdesktopmoon --- # Pagamentos | TOConline - Documentação API ### [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/pagamentos#criacao-de-pagamentos) Criação de pagamentos Tal como no caso dos recibos, as compras são constituídas por: 1. Um cabeçalho 2. Umas ou mais linhas ### [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/pagamentos#id-1.-criacao-do-cabecalho) 1\. Criação do cabeçalho De modo a criar uma compra, deverá inicialmente criar o cabeçalho do documento. Para este efeito, deverá realizar o seguinte pedido: ### [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/pagamentos#post-api-v1-commercial_purchases_payments) Criar Cabeçalho de Pagamentos post {{base\_url}}/api/v1/commercial\_purchases\_payments Criar Cabeçalho de Pagamentos chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Body application/jsonchevron-down application/json cash\_account\_idnumberOptionalExample: `2` check\_numberany | nullableOptional company\_idnumberOptionalExample: `800000046` country\_idnumberOptionalExample: `1` currency\_conversion\_ratenumberOptionalExample: `1` currency\_idnumberOptionalExample: `1` datestringOptionalExample: `2024-02-29` document\_series\_idnumberOptionalExample: `12` gross\_totalnumberOptionalExample: `11.3` internal\_observationsstringOptionalExample: `Comentário interno` net\_totalnumberOptionalExample: `0` observationsstringOptionalExample: `Comentários visíveis` payment\_mechanismstringOptionalExample: `MO` supplier\_idnumberOptionalExample: `9` third\_party\_idany | nullableOptional third\_party\_typeany | nullableOptional Responses chevron-right 200Success No content post /api/v1/commercial\_purchases\_payments HTTPchevron-down HTTPcURLJavaScriptPython Test it 200Success No content No pedido acima, o corresponde ao token de acesso válido devolvido pelo serviço de OAuth O deverá vir no seguinte formato Após criar o cabeçalho, a resposta TEM QUE ser consultada para obtenção do identificador interno ("id") da compra criada. Este identificador será necessário para a criação de todas as linhas. ### [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/pagamentos#id-2.-criacao-de-linha-de-pagamento) 2\. Criação de Linha de Pagamento Em todos os pedidos seguintes, é necessário saber qual o id do documento de compra. Este id pode ser guardado a partir da resposta (JSON) ao pedido de criação anterior, ou pode ser consultado via API. Via API, o id do documento pode ser obtido por um De modo a inserir linhas na compra criada, deverá realizar o seguinte pedido ### [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/pagamentos#post-api-commercial_purchases_payment_lines) Adicionar Linha a Pagamentos post {{base\_url}}/api/commercial\_purchases\_payment\_lines Adicionar Linha a Pagamentos chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Body application/jsonchevron-down application/json dataobjectOptional Show propertiesplus Responses chevron-right 200Success No content post /api/commercial\_purchases\_payment\_lines HTTPchevron-down HTTPcURLJavaScriptPython Adicionar Linha a Pagamentoschevron-down Adicionar Linha a PagamentosCriar Linhas de Pagamento Test it 200Success No content No pedido acima, o corresponde ao token de acesso válido devolvido pelo serviço de OAuth. O payload JSON deverá vir no seguinte formato, dependendo se se trata de um produto, ou categoria de despesa NOTA: É na linha que se indica qual o documento de compra (FC ou DSP) a pagar. Se necessário, podem criar-se mais do que uma linha (e nesse caso o pagamento é feito de uma só vez para todos os documentos) #### [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/pagamentos#linha-de-pagamento) Linha de pagamento ### [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/pagamentos#undefined) [PreviousDocumentos de Comprachevron-left](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/documentos-de-compra) [NextAPIs Auxiliareschevron-right](https://api-docs.toconline.pt/apis/apis-auxiliares) Last updated 1 year ago * [Criação de pagamentos](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/pagamentos#criacao-de-pagamentos) * [1\. Criação do cabeçalho](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/pagamentos#id-1.-criacao-do-cabecalho) * [POSTCriar Cabeçalho de Pagamentos](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/pagamentos#post-api-v1-commercial_purchases_payments) * [2\. Criação de Linha de Pagamento](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/pagamentos#id-2.-criacao-de-linha-de-pagamento) * [POSTAdicionar Linha a Pagamentos](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/pagamentos#post-api-commercial_purchases_payment_lines) * [](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/pagamentos#undefined) sun-brightdesktopmoon Copy POST /api/v1/commercial_purchases_payments HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Content-Type: application/json Accept: */* Content-Length: 374 { "cash_account_id": 2, "check_number": null, "company_id": 800000046, "country_id": 1, "currency_conversion_rate": 1, "currency_id": 1, "date": "2024-02-29", "document_series_id": 12, "gross_total": 11.3, "internal_observations": "Comentário interno", "net_total": 0, "observations": "Comentários visíveis", "payment_mechanism": "MO", "supplier_id": 9, "third_party_id": null, "third_party_type": null } Copy { "data": { "type": "commercial_purchases_payments", "attributes": { "date": "2017-06-01", // Data do pagamento "payment_mechanism": "MO|CH|DC|CC|TR|DDA|MB|OU|..." // Por omissão, MO. Modo de pagamento: MO (numerário), CH (cheque), DC (cartão de débito), CC (cartão de crédito), TR (transferência), DDA (débito directo), MB (referência MB), OU (outro) }, "relationships": { "commercial_document_series": { // Associação à série de pagamentos. Pode ser omitida, se for para usar a série por omissão "data": { "type": "commercial_document_series", "id": "" // Este id pode ser obtido por um GET /commercial_document_series?filter[document_type]=PF&filter[prefix]=2020|ou outro qualquer... } }, "bank_accounts": { // SÓ NECESSÁRIO se o meio de pagamento for DC,CC,TR,CH, e se for para indicar uma conta bancária específica. Associação à conta bancária da empresa de onde o pagamento foi feito "data": { "type": "bank_accounts", "id": "" // Este id pode ser obtido por um GET /company_bank_accounts?filter[iban]=, ou GET /company_bank_accounts?filter[name]= } }, "cash_accounts": { // SÓ NECESSÁRIO se o meio de pagamento for MO, e se for para indicar uma conta de caixa específica. Associação à conta de caixa da empresa de onde o pagamento foi feito "data": { "type": "cash_accounts", "id": "" // Este id pode ser obtido por um GET /cash_accounts?filter[name]= } } } } } Copy GET /commercial_purchases_payments?filter[document_no]= Copy POST /api/commercial_purchases_payment_lines HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Content-Type: application/json Accept: */* Content-Length: 163 { "data": { "attributes": { "paid_value": 50, "payable_id": 2, "payable_type": "Purchases::Document", "settlement_percentage": 3 }, "type": "commercial_purchases_payment_lines" } } Copy { "data": { "type": "commercial_purchases_payment_lines", "attributes": { "payment_id": "", // NOTA: quando a API estiver concluída, isto vai ser também uma "relationship", mas por agora indica-se aqui, nos atributos "payable_type": "Purchases::Document", "payable_id": "", "paid_value": 50, // Valor total a pagar (não é necessário pagar a totalidade do documento, ou pode pagar-se mais do que um documento) // Indicar o atributo seguinte apenas se existir desconto no pagamento (3%, neste exemplo) "settlement_percentage": 3 "commercial_purchases_documents_id":"" } } } sun-brightdesktopmoon --- # Taxas | TOConline - Documentação API ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/taxas#obter-todas-as-taxas) Obter Todas as Taxas ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/taxas#get-api-taxes) Obter Todas as Taxas get {{base\_url}}/api/taxes Obter Todas as Taxas chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Query parameters filter\[tax\_country\_region\]stringOptionalExample: `BE` filter\[tax\_code\]stringOptionalExample: `NOR` filter\[tax\_percentage\]stringOptionalExample: `21` Responses chevron-right 200 / Sucesso / Sucesso Headersobject Show Headersplus get /api/taxes HTTPchevron-down HTTPcURLJavaScriptPython Test it 200 / Sucesso / Sucesso No content ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/taxas#filtro-por-codigo-de-taxa-e-pelo-codigo-da-regiao) Filtro por Código de Taxa e pelo Código da Região **Exemplo:** Endpoint Response ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/taxas#filtro-por-codigo-de-taxa-e-pela-regiao-e-percentagem-de-taxa) Filtro por Código de Taxa e pela Região e Percentagem de Taxa **Exemplo:** Endpoint Response ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/taxas#obter-todas-as-taxas-de-oss-one-stop-shop) Obter Todas as Taxas de OSS (One Stop Shop) ### [hashtag](https://api-docs.toconline.pt/apis/apis-auxiliares/taxas#get-api-oss_taxes) Obter Todas as Taxas de OSS get {{base\_url}}/api/oss\_taxes Obter Todas as Taxas de OSS chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Responses chevron-right 200 Sucesso application/json Headersobject Show Headersplus Responseobject Show propertiesplus get /api/oss\_taxes HTTPchevron-down HTTPcURLJavaScriptPython Test it 200 Sucesso [PreviousUnidade Monetáriachevron-left](https://api-docs.toconline.pt/apis/apis-auxiliares/unidade-monetaria) [NextCategorias de Despesachevron-right](https://api-docs.toconline.pt/apis/apis-auxiliares/categorias-de-despesa) Last updated 1 year ago * [Obter Todas as Taxas](https://api-docs.toconline.pt/apis/apis-auxiliares/taxas#obter-todas-as-taxas) * [GETObter Todas as Taxas](https://api-docs.toconline.pt/apis/apis-auxiliares/taxas#get-api-taxes) * [Filtro por Código de Taxa e pelo Código da Região](https://api-docs.toconline.pt/apis/apis-auxiliares/taxas#filtro-por-codigo-de-taxa-e-pelo-codigo-da-regiao) * [Filtro por Código de Taxa e pela Região e Percentagem de Taxa](https://api-docs.toconline.pt/apis/apis-auxiliares/taxas#filtro-por-codigo-de-taxa-e-pela-regiao-e-percentagem-de-taxa) * [Obter Todas as Taxas de OSS (One Stop Shop)](https://api-docs.toconline.pt/apis/apis-auxiliares/taxas#obter-todas-as-taxas-de-oss-one-stop-shop) * [GETObter Todas as Taxas de OSS](https://api-docs.toconline.pt/apis/apis-auxiliares/taxas#get-api-oss_taxes) sun-brightdesktopmoon Copy GET /api/taxes HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Accept: */* Endpoint Copy GET /taxes?filter[tax_code]= &filter[tax_country_region]= Exemplo de Endpoint Copy GET /api/taxes?filter[tax_code]=NOR&filter[tax_country_region]=BE Exemplo de Response Copy { "data": [\ {\ "type": "taxes",\ "id": "103",\ "attributes": {\ "tax_country_region": "BE",\ "tax_code": "NOR",\ "description": "Normal",\ "tax_percentage": "21",\ "tax_expiration_date": null,\ "vat_tax_id": null\ }\ }\ ] } Endpoint Copy GET /taxes?filter[tax_code]= &filter[tax_country_region]=&filter[tax_percentage]= Exemplo de Endpoint Copy {{base_url}}/api/taxes?filter[tax_code]=NOR&filter[tax_country_region]=BE&filter[tax_percentage]=21 Exemplo de Response Copy { "data": [\ {\ "type": "taxes",\ "id": "103",\ "attributes": {\ "tax_country_region": "BE",\ "tax_code": "NOR",\ "description": "Normal",\ "tax_percentage": "21",\ "tax_expiration_date": null,\ "vat_tax_id": null\ }\ }\ ] } Copy GET /api/oss_taxes HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Accept: */* Copy { "data": [\ {\ "attributes": {\ "code": "AT",\ "country_name": "Áustria",\ "int": [\ "13#1"\ ],\ "nor": [\ "20#1"\ ],\ "red": [\ "10#1"\ ],\ "tax_country_region": "AT"\ },\ "id": "AT",\ "type": "oss_taxes"\ },\ {\ "attributes": {\ "code": "BE",\ "country_name": "Bélgica",\ "int": [\ "12#1"\ ],\ "nor": [\ "21#1"\ ],\ "red": [\ "6#1"\ ],\ "tax_country_region": "BE"\ },\ "id": "BE",\ "type": "oss_taxes"\ },\ {\ "attributes": {\ "code": "BG",\ "country_name": "Bulgária",\ "int": [\ "9#1"\ ],\ "nor": [\ "20#1"\ ],\ "red": [],\ "tax_country_region": "BG"\ },\ "id": "BG",\ "type": "oss_taxes"\ },\ {\ "attributes": {\ "code": "CY",\ "country_name": "Chipre",\ "int": [\ "9#1"\ ],\ "nor": [\ "19#1"\ ],\ "red": [\ "5#1"\ ],\ "tax_country_region": "CY"\ },\ "id": "CY",\ "type": "oss_taxes"\ },\ {\ "attributes": {\ "code": "CZ",\ "country_name": "República Checa",\ "int": [\ "15#1"\ ],\ "nor": [\ "21#1"\ ],\ "red": [\ "10#1"\ ],\ "tax_country_region": "CZ"\ },\ "id": "CZ",\ "type": "oss_taxes"\ },\ {\ "attributes": {\ "code": "DE",\ "country_name": "Alemanha",\ "int": [],\ "nor": [\ "19#1"\ ],\ "red": [\ "7#1"\ ],\ "tax_country_region": "DE"\ },\ "id": "DE",\ "type": "oss_taxes"\ },\ {\ "attributes": {\ "code": "DK",\ "country_name": "Dinamarca",\ "int": [],\ "nor": [\ "25#1"\ ],\ "red": [],\ "tax_country_region": "DK"\ },\ "id": "DK",\ "type": "oss_taxes"\ },\ {\ "attributes": {\ "code": "EE",\ "country_name": "Estónia",\ "int": [],\ "nor": [\ "20#1"\ ],\ "red": [\ "9#1"\ ],\ "tax_country_region": "EE"\ },\ "id": "EE",\ "type": "oss_taxes"\ },\ {\ "attributes": {\ "code": "EL",\ "country_name": "Grécia",\ "int": [\ "13#1"\ ],\ "nor": [\ "24#1"\ ],\ "red": [\ "6#1"\ ],\ "tax_country_region": "EL"\ },\ "id": "EL",\ "type": "oss_taxes"\ },\ {\ "attributes": {\ "code": "ES",\ "country_name": "Espanha",\ "int": [\ "10#1"\ ],\ "nor": [\ "21#1"\ ],\ "red": [\ "4#1"\ ],\ "tax_country_region": "ES"\ },\ "id": "ES",\ "type": "oss_taxes"\ },\ {\ "attributes": {\ "code": "FI",\ "country_name": "Finlândia",\ "int": [\ "14#1"\ ],\ "nor": [\ "24#1"\ ],\ "red": [\ "10#1"\ ],\ "tax_country_region": "FI"\ },\ "id": "FI",\ "type": "oss_taxes"\ },\ {\ "attributes": {\ "code": "FR",\ "country_name": "França",\ "int": [\ "5.5#1",\ "10#2"\ ],\ "nor": [\ "20#1"\ ],\ "red": [\ "2.1#1"\ ],\ "tax_country_region": "FR"\ },\ "id": "FR",\ "type": "oss_taxes"\ },\ {\ "attributes": {\ "code": "HR",\ "country_name": "Croácia",\ "int": [\ "13#1"\ ],\ "nor": [\ "25#1"\ ],\ "red": [\ "5#1"\ ],\ "tax_country_region": "HR"\ },\ "id": "HR",\ "type": "oss_taxes"\ },\ {\ "attributes": {\ "code": "HU",\ "country_name": "Hungria",\ "int": [\ "18#1"\ ],\ "nor": [\ "27#1"\ ],\ "red": [\ "5#1"\ ],\ "tax_country_region": "HU"\ },\ "id": "HU",\ "type": "oss_taxes"\ },\ {\ "attributes": {\ "code": "IE",\ "country_name": "Irlanda",\ "int": [\ "9#1",\ "13.5#2"\ ],\ "nor": [\ "23#1"\ ],\ "red": [\ "4.8#1"\ ],\ "tax_country_region": "IE"\ },\ "id": "IE",\ "type": "oss_taxes"\ },\ {\ "attributes": {\ "code": "IT",\ "country_name": "Itália",\ "int": [\ "5#1",\ "10#2"\ ],\ "nor": [\ "22#1"\ ],\ "red": [\ "4#1"\ ],\ "tax_country_region": "IT"\ },\ "id": "IT",\ "type": "oss_taxes"\ },\ {\ "attributes": {\ "code": "LT",\ "country_name": "Lituânia",\ "int": [\ "9#1"\ ],\ "nor": [\ "21#1"\ ],\ "red": [\ "5#1"\ ],\ "tax_country_region": "LT"\ },\ "id": "LT",\ "type": "oss_taxes"\ },\ {\ "attributes": {\ "code": "LU",\ "country_name": "Luxemburgo",\ "int": [\ "7#1",\ "13#2"\ ],\ "nor": [\ "16#1"\ ],\ "red": [\ "3#1"\ ],\ "tax_country_region": "LU"\ },\ "id": "LU",\ "type": "oss_taxes"\ },\ {\ "attributes": {\ "code": "LV",\ "country_name": "Letónia",\ "int": [\ "12#1"\ ],\ "nor": [\ "21#1"\ ],\ "red": [\ "5#1"\ ],\ "tax_country_region": "LV"\ },\ "id": "LV",\ "type": "oss_taxes"\ },\ {\ "attributes": {\ "code": "MC",\ "country_name": "Mónaco",\ "int": [\ "5.5#1",\ "10#2"\ ],\ "nor": [\ "20#1"\ ],\ "red": [],\ "tax_country_region": "MC"\ },\ "id": "MC",\ "type": "oss_taxes"\ },\ {\ "attributes": {\ "code": "MT",\ "country_name": "Malta",\ "int": [\ "7#1"\ ],\ "nor": [\ "18#1"\ ],\ "red": [\ "5#1"\ ],\ "tax_country_region": "MT"\ },\ "id": "MT",\ "type": "oss_taxes"\ },\ {\ "attributes": {\ "code": "NL",\ "country_name": "Países Baixos",\ "int": [],\ "nor": [\ "21#1"\ ],\ "red": [\ "9#1"\ ],\ "tax_country_region": "NL"\ },\ "id": "NL",\ "type": "oss_taxes"\ },\ {\ "attributes": {\ "code": "PL",\ "country_name": "Polónia",\ "int": [\ "8#1"\ ],\ "nor": [\ "23#1"\ ],\ "red": [\ "5#1"\ ],\ "tax_country_region": "PL"\ },\ "id": "PL",\ "type": "oss_taxes"\ },\ {\ "attributes": {\ "code": "PT",\ "country_name": "Portugal",\ "int": [\ "13#1"\ ],\ "nor": [\ "23#1"\ ],\ "red": [\ "6#1"\ ],\ "tax_country_region": "PT"\ },\ "id": "PT",\ "type": "oss_taxes"\ },\ {\ "attributes": {\ "code": "PT-AC",\ "country_name": "Portugal - Açores",\ "int": [\ "9#1"\ ],\ "nor": [\ "16#1"\ ],\ "red": [\ "4#1"\ ],\ "tax_country_region": "PT-AC"\ },\ "id": "PT-AC",\ "type": "oss_taxes"\ },\ {\ "attributes": {\ "code": "PT-MA",\ "country_name": "Portugal - Madeira",\ "int": [\ "12#1"\ ],\ "nor": [\ "22#1"\ ],\ "red": [\ "5#1"\ ],\ "tax_country_region": "PT-MA"\ },\ "id": "PT-MA",\ "type": "oss_taxes"\ },\ {\ "attributes": {\ "code": "RO",\ "country_name": "Roménia",\ "int": [\ "9#1"\ ],\ "nor": [\ "19#1"\ ],\ "red": [\ "5#1"\ ],\ "tax_country_region": "RO"\ },\ "id": "RO",\ "type": "oss_taxes"\ },\ {\ "attributes": {\ "code": "SE",\ "country_name": "Suécia",\ "int": [\ "12#1"\ ],\ "nor": [\ "25#1"\ ],\ "red": [\ "6#1"\ ],\ "tax_country_region": "SE"\ },\ "id": "SE",\ "type": "oss_taxes"\ },\ {\ "attributes": {\ "code": "SI",\ "country_name": "Eslovénia",\ "int": [\ "9.5#1"\ ],\ "nor": [\ "22#1"\ ],\ "red": [\ "5#1"\ ],\ "tax_country_region": "SI"\ },\ "id": "SI",\ "type": "oss_taxes"\ },\ {\ "attributes": {\ "code": "SK",\ "country_name": "Eslováquia",\ "int": [\ "10#1"\ ],\ "nor": [\ "20#1"\ ],\ "red": [],\ "tax_country_region": "SK"\ },\ "id": "SK",\ "type": "oss_taxes"\ }\ ] } sun-brightdesktopmoon --- # Clientes, Morada e E-mail | TOConline - Documentação API [hashtag](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email#cliente) Cliente -------------------------------------------------------------------------------------------------- O TOC Online disponibiliza as seguintes rotas que permitem operações sobre clientes (customers) da empresa: GET – obter informação de cliente POST – criar novos clientes PATCH – Alterar um cliente DELETE – Apagar um cliente (atenção, o uso desta operação não permite a recuperação do identificador inicial) ### [hashtag](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email#obter-todos-os-clientes) Obter Todos os Clientes Ao realizar um pedido para a rota `https://apiv1.toconline.com/customers` irá receber uma resposta semelhante à descrita de seguida, com uma lista de elementos 'data', onde cada elemento corresponde a um cliente associado à sua empresa. Esta rota não requer qualquer tipo de parâmetros. ### [hashtag](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email#get-api-customers) Obter Todos os Clientes get {{base\_url}}/api/customers Obter Todos os Clientes chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Responses chevron-right 200Success No content chevron-right 400 Autorização em falta application/json chevron-right 401 Sessão inválida application/json get /api/customers HTTPchevron-down HTTPcURLJavaScriptPython Test it 200Successchevron-down No content ### [hashtag](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email#obter-cliente-por-id) Obter Cliente por Id À semelhança do pedido anterior, se este for realizado para a rota irá obter como resposta apenas as informações de um único cliente, em vez de receber uma lista de todos os clientes existentes. ### [hashtag](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email#get-api-customers-clientid) Obter Cliente por ID get {{base\_url}}/api/customers/{clientId} Obter Cliente por ID chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Path parameters clientIdstringRequired Id do cliente Example: `60` Responses chevron-right 200 Sucesso application/json Headersobject Show Headersplus Responseobject Show propertiesplus chevron-right 404 Recurso não encontrado application/json get /api/customers/{clientId} HTTPchevron-down HTTPcURLJavaScriptPython Test it 200 Sucesso chevron-down ### [hashtag](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email#criar-cliente) Criar Cliente A seguinte rota permite a criação de novas instâncias de clientes, associados à sua empresa. De modo a realizar um pedido para esta rota, terá de enviar alguns parâmetros no body do pedido. Tal como está descrito no pedido em baixo. circle-info Para associar uma morada ao cliente deverá já ter inserido um cliente [Criar Cliente](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email#criar-cliente) e efectuar o seguinte passo [Associar morada a Cliente](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email#associar-morada-a-cliente) ### [hashtag](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email#post-api-customers) Criar Clientes post {{base\_url}}/api/customers Criar Clientes chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Body application/jsonchevron-down application/json dataobjectOptional Show propertiesplus Responses chevron-right 200 Sucesso application/json Headersobject Show Headersplus Responseobject Show propertiesplus chevron-right 400 NIF Inválido application/json chevron-right 403 Recurso já existe application/json post /api/customers HTTPchevron-down HTTPcURLJavaScriptPython Test it 200 Sucesso chevron-down [hashtag](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email#associar-morada-a-cliente) Associar morada a Cliente -------------------------------------------------------------------------------------------------------------------------------------- A sequência de passos delineada no diagrama proporciona uma compreensão do processo, desde a criação do cliente até a sua associação com uma morada. ![](https://api-docs.toconline.pt/~gitbook/image?url=https%3A%2F%2F1863668386-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fk7sif7BY0rPzivMcj1HB%252Fuploads%252FWK9QGTMZuW5WyvnWzJAf%252FDiagramas%2520de%2520Documentac%25CC%25A7a%25CC%2583o-Associar%2520Cliente%2520a%2520Morada.jpg%3Falt%3Dmedia%26token%3D9af6a197-189a-47c6-8556-226089045c26&width=768&dpr=4&quality=100&sign=e67fbbd6&sv=2) circle-exclamation Quando um cliente é criado, uma morada principal fica associada ao cliente. Esta morada por default vem vazia e é necessário atualizar com os dados da nova morada do cliente. Através do `id` obtido pela response do [Criar Cliente](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email#criar-cliente) este deverá ser usado para obter o id da morada ao fazer um `GET /customers/{id}` [Obter Cliente por Id](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email#obter-cliente-por-id) O `id` da morada obtido anteriormente, será usado para atualizar os dados da morada através de um `PATCH / addresses`. #### [hashtag](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email#atualizar-morada) Atualizar Morada ### [hashtag](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email#patch-api-addresses) Atualizar Morada patch {{base\_url}}/api/addresses Atualizar Morada chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Body application/jsonchevron-down application/json dataobjectOptional Show propertiesplus Responses chevron-right 200 Atualizar Morada / Atualizar Morada application/json Headersobject Show Headersplus Responseobject Show propertiesplus patch /api/addresses HTTPchevron-down HTTPcURLJavaScriptPython Test it 200 Atualizar Morada / Atualizar Morada O body deste pedido (payload JSON) deverá conter as informações de cliente que se pretende atualizar nos respetivos atributos. Payload Response Atributo Descrição Obrigatório type Tipo de entidade associada ao endereço (ex: Customer). Sim id ID da entidade associada ao endereço. Sim address\_detail Detalhes do endereço (ex: rua, número). Não city Cidade. Não postcode Código postal. Não region Região ou província. Não ### [hashtag](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email#remover-cliente) Remover Cliente A seguinte rota permite a remoção de um dado cliente. Esta rota deve ser utilizada de forma cautelosa dado que é irreversível, e mesmo que este cliente volte a ser criado, o seu id nunca será o mesmo que teria anteriormente. Utilizando o id do cliente que quer eliminar, que poderá fazer utilizando a primeira rota desta página, por exemplo, terá simplesmente de fazer um pedido para https://apiv1.toconline.com/customers/{id}. Este irá retornar OK em caso de sucesso.\\ ### [hashtag](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email#delete-api-customers-clientid) Remover Cliente delete {{base\_url}}/api/customers/{clientId} Remover Cliente chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Path parameters clientIdstringRequired Id do cliente Example: `60` Responses chevron-right 200 Sucesso application/json Headersobject Show Headersplus Responseobject Show propertiesplus chevron-right 400 Pedido Inválido application/json chevron-right 404 Recurso não existente application/json delete /api/customers/{clientId} HTTPchevron-down HTTPcURLJavaScriptPython Test it 200 Sucesso chevron-down ### [hashtag](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email#atualizar-cliente) Atualizar Cliente A rota PATCH permite a edição de um cliente existente. O body deste pedido deverá ser igual ao descrito na rota POST, contendo todas as informações obrigatórias do cliente, atualizadas para os valores que tenciona alterar, além do campo "id" no "data" do "body". Álem disto, o pedido deverá ser feito a https://apiv1.toconline.com/customers/{id}, sendo que {id} é o identificador do cliente que tenciona atualizar. No exemplo que se segue poderá observar todos os campos dentro dos atributos que são possiveis de editar. Request Response * * * [hashtag](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email#morada) Morada ------------------------------------------------------------------------------------------------ ### [hashtag](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email#criar-morada) Criar Morada Quando um Cliente é criado este já tem uma morada vazia associada, mas é possível adicionar mais do que uma morada ao Cliente. De modo a associar uma morada a um cliente, deverá realizar o seguinte pedido ### [hashtag](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email#post-api-addresses) Criar Morada post {{base\_url}}/api/addresses Criar Morada chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Body application/jsonchevron-down application/json dataobjectOptional Show propertiesplus Responses chevron-right 200 Criar Morada / Criar Morada application/json Headersobject Show Headersplus Responseobject Show propertiesplus post /api/addresses HTTPchevron-down HTTPcURLJavaScriptPython Test it 200 Criar Morada / Criar Morada No pedido acima, o corresponde ao token de acesso válido devolvido pelo serviço de OAuth, e o deverá ter o seguinte formato Atributo Descrição Obrigatório type Tipo de entidade associada ao endereço (ex: Customer). Sim addressable\_type Tipo de entidade associada ao endereço (ex: Customer). Sim addressable\_id ID da entidade associada ao endereço (ex: ID do Cliente). Sim address\_detail Detalhes do endereço (ex: rua, número). Não city Cidade. Não postcode Código postal. Não region Região ou província. Não country\_id ID do país. Não circle-info "addressable\_id" - corresponde ao id da morada do cliente obtido da relação entre cliente e morada, através do [Clientes, Morada e E-mail](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email#obter-cliente) circle-info Para usar outro país que não seja Portugal, poderá consultar mais informação em: [Países](https://api-docs.toconline.pt/apis/apis-auxiliares/paises) * * * [hashtag](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email#e-mail) E-mail ------------------------------------------------------------------------------------------------ ### [hashtag](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email#criar-e-mail-de-cliente) Criar E-mail de Cliente Para proceder à criação do E-mail de um cliente pela primeira vez deverá utilizar a `POST / contacts`. ### [hashtag](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email#post-api-contacts) Criar email de Cliente post {{base\_url}}/api/contacts Criar email de Cliente chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Body application/jsonchevron-down application/json dataobjectOptional Show propertiesplus Responses chevron-right 200 Sucesso / Suceso / Criar Novo Contacto application/json Headersobject Show Headersplus Responseobject Show propertiesplus post /api/contacts HTTPchevron-down HTTPcURLJavaScriptPython Criar Novo Contactochevron-down Criar Novo ContactoCriar email de ClienteCriar email de Cliente Copy Test it 200 Sucesso / Suceso / Criar Novo Contacto Criar Novo Contactochevron-down O body deste pedido () deverá conter as informações de cliente que se pretende atualizar, sendo obrigatório campo "**contactable\_id**" identificador do cliente que tenciona atualizar e o "**contactable\_type**" sendo este do tipo "**Customer**" Payload Response ![](https://api-docs.toconline.pt/~gitbook/image?url=https%3A%2F%2F1863668386-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fk7sif7BY0rPzivMcj1HB%252Fuploads%252FybzSDSrvzyUUdO4pU7JW%252FDiagramas%2520de%2520Documentac%25CC%25A7a%25CC%2583o%2520TOCOnline%2520API-Criar%2520Email%2520de%2520Cliente.jpg%3Falt%3Dmedia%26token%3D570f2275-3c1e-44cf-914b-0a3fbf33afa5&width=768&dpr=4&quality=100&sign=e88e22fe&sv=2) Exemplo de Criação de E-mail para Cliente ![](https://api-docs.toconline.pt/~gitbook/image?url=https%3A%2F%2F1863668386-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fk7sif7BY0rPzivMcj1HB%252Fuploads%252FuEfiA3uAe0tQ1cOTh7qO%252FDiagramas%2520de%2520Documentac%25CC%25A7a%25CC%2583o%2520TOCOnline%2520API-Criar%2520Email%2520de%2520Cliente.jpg%3Falt%3Dmedia%26token%3D14c06c66-14d3-4dae-80ea-d2cbdd515412&width=768&dpr=4&quality=100&sign=300fc789&sv=2) Exemplo de Criação de E-mail para Cliente ### [hashtag](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email#atualizar-e-mail-de-cliente) Atualizar E-mail de Cliente circle-exclamation Já deve ter realizado [Clientes, Morada e E-mail](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email#criar-email-de-cliente) Usando o `GET / customer{id}` deverá obter o id correspondente ao contacto do cliente, que se encontra localizado na área de relationships-> main\_contact, como pode observar no exemplo de response abaixo. chevron-rightExemplo de response de um GET/customer/{id}[hashtag](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email#exemplo-de-response-de-um-get-customer-id) Para proceder à atualização do E-mail de um cliente deverá utilizar a `PATCH / contacts` usando o id obtido do main\_contact obtido do cliente pretendido. ### [hashtag](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email#patch-api-contacts) Atualizar email de Cliente patch {{base\_url}}/api/contacts Atualizar email de Cliente chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Body application/jsonchevron-down application/json dataobjectOptional Show propertiesplus Responses chevron-right 200 Sucesso / Sucesso application/json Headersobject Show Headersplus Responseobject Show propertiesplus patch /api/contacts HTTPchevron-down HTTPcURLJavaScriptPython Atualizar email de Clientechevron-down Atualizar email de ClienteAtualizar email de Fornecedor Test it 200 Sucesso / Sucesso O body deste pedido () deverá conter as informações de cliente que se pretende atualizar, sendo obrigatório campo "`id`" id do contacto correspondente ao utilizador que tenciona atualizar e o "`email`" novo a ser alterado. Payload Response ![](https://api-docs.toconline.pt/~gitbook/image?url=https%3A%2F%2F1863668386-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fk7sif7BY0rPzivMcj1HB%252Fuploads%252Fy8ltXAcAv79CnNEiHaAs%252FDiagramas%2520de%2520Documentac%25CC%25A7a%25CC%2583o%2520TOCOnline%2520API-Atualizar%2520Email%2520de%2520Cliente.jpg%3Falt%3Dmedia%26token%3D818e93b5-ed7f-4fc4-8d2c-583ba1c6af17&width=768&dpr=4&quality=100&sign=10dd9a61&sv=2) Exemplo de Atualização de E-mail para Cliente [PreviousEmpresachevron-left](https://api-docs.toconline.pt/apis/empresa) [NextFornecedores, Morada e E-mailchevron-right](https://api-docs.toconline.pt/apis/empresa/fornecedores) Last updated 1 year ago * [Cliente](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email#cliente) * [Obter Todos os Clientes](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email#obter-todos-os-clientes) * [GETObter Todos os Clientes](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email#get-api-customers) * [Obter Cliente por Id](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email#obter-cliente-por-id) * [GETObter Cliente por ID](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email#get-api-customers-clientid) * [Criar Cliente](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email#criar-cliente) * [POSTCriar Clientes](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email#post-api-customers) * [Associar morada a Cliente](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email#associar-morada-a-cliente) * [PATCHAtualizar Morada](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email#patch-api-addresses) * [Remover Cliente](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email#remover-cliente) * [DELETERemover Cliente](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email#delete-api-customers-clientid) * [Atualizar Cliente](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email#atualizar-cliente) * [Morada](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email#morada) * [Criar Morada](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email#criar-morada) * [POSTCriar Morada](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email#post-api-addresses) * [E-mail](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email#e-mail) * [Criar E-mail de Cliente](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email#criar-e-mail-de-cliente) * [POSTCriar email de Cliente](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email#post-api-contacts) * [Atualizar E-mail de Cliente](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email#atualizar-e-mail-de-cliente) * [PATCHAtualizar email de Cliente](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email#patch-api-contacts) sun-brightdesktopmoon Copy GET /api/customers HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Accept: */* Copy GET /api/customers/{clientId} HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Accept: */* Copy { "data": { "attributes": { "business_name": "Empresa de Testes", "cashed_vat": false, "contact_name": "Testes", "country_iso_alpha_2": "PT", "data": {}, "email": "[email protected]", "internal_observations": "Empresa de teste", "is_tax_exempt": false, "mobile_number": "939038342", "not_final_customer": false, "observations": "Empresa de teste", "phone_number": "309867004", "saft_import_id": null, "tax_country_region": "PT", "tax_registration_number": "221976302", "website": "http://testes.pt" }, "id": "62", "relationships": { "addresses": { "data": [\ {\ "id": "68",\ "type": "addresses"\ }\ ] }, "company": { "data": { "id": "800000046", "type": "current_company" } }, "defaults": { "data": { "id": "32", "type": "customers_defaults" } }, "email_addresses": { "data": [\ {\ "id": "19",\ "type": "email_addresses"\ }\ ] }, "main_address": { "data": { "id": "68", "type": "addresses" } }, "main_email_address": { "data": { "id": "19", "type": "email_addresses" } }, "tax_exemption_reason": { "data": null } }, "type": "customers" } } Copy POST /api/customers HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Content-Type: application/json Accept: */* Content-Length: 338 { "data": { "attributes": { "business_name": "Empresa de Contabilidade", "contact_name": "Utilizador", "email": "[email protected]", "internal_observations": "Empresa de teste", "mobile_number": 939038342, "observations": "Empresa de teste", "phone_number": 309867004, "tax_registration_number": "221976302", "website": "https://toconline.pt" }, "type": "customers" } } Copy { "data": { "attributes": { "business_name": "Empresa de Contabilidade", "cashed_vat": false, "contact_name": "Utilizador", "country_iso_alpha_2": "PT", "data": {}, "email": "[email protected]", "internal_observations": "Empresa de teste", "is_tax_exempt": false, "mobile_number": "939038342", "not_final_customer": false, "observations": "Empresa de teste", "phone_number": "309867004", "saft_import_id": null, "tax_country_region": "PT", "tax_registration_number": "221976302", "website": "http://testes.pt" }, "id": "62", "relationships": { "addresses": { "data": [] }, "company": { "data": { "id": "800000046", "type": "current_company" } }, "defaults": { "data": null }, "email_addresses": { "data": [] }, "main_address": { "data": null }, "main_email_address": { "data": null }, "tax_exemption_reason": { "data": null } }, "type": "customers" } } Copy PATCH /api/addresses HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Content-Type: application/json Accept: */* Content-Length: 168 { "data": { "attributes": { "address_detail": "Avenida Principal", "city": "Setúbal", "country_id": "3", "postcode": "2910-099", "region": "Setúbal" }, "id": "45", "type": "addresses" } } Copy { "data": { "attributes": { "address_detail": "Avenida Principal", "city": "Setúbal", "code": null, "for_charge": false, "for_discharge": false, "is_national_holidays_workday": false, "is_primary": true, "is_saturday_workday": false, "is_sunday_workday": false, "name": "Sede", "payroll_enumerations_tax_office_id": null, "postcode": "2910-099", "region": "Setúbal", "subtype": null }, "id": "45", "relationships": { "company": { "data": null }, "country": { "data": { "id": "3", "type": "countries" } }, "customer": { "data": null }, "supplier": { "data": null }, "user": { "data": null } }, "type": "addresses" } } Payload Copy { "data": { "type": "addresses", //OBRIGATÓRIO "id": [ID ADRESS], //OBRIGATÓRIO provém do id da address obtido no get anterio "attributes": { "address_detail": "string", "city": "string", "postcode": "string", "region": "string" } } } Response Copy { "data": { "type": "addresses", "id": "45", "attributes": { "is_primary": true, "address_detail": "Avenida Principal", "city": "Setúbal", "postcode": "2910-099", "region": "Setúbal", "name": "Sede", "for_discharge": false, "for_charge": false, "subtype": null, "is_saturday_workday": false, "is_sunday_workday": false, "is_national_holidays_workday": false, "code": null, "payroll_enumerations_tax_office_id": null }, "relationships": { "company": { "data": null }, "country": { "data": { "type": "countries", "id": "3" } }, "customer": { "data": null }, "supplier": { "data": null }, "user": { "data": null } } } } Copy DELETE /api/customers/{clientId} HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Accept: */* Copy { "meta": {} } Request Copy { "data": { "type": "customers", "id": "31", "attributes": { "tax_registration_number": "146081692", "business_name": "Isso mesmo", "contact_name": "Bruno Cascais", "website": "http://issomesmo.pt", "phone_number": "21344444", "mobile_number": "935678999", "email": "[email protected]", "observations": "observções do cliente", "internal_observations": "observações internas" } } } Response Copy { "data": { "type": "customers", "id": "31", "attributes": { "tax_registration_number": "146081692", "business_name": "Isso mesmo", "contact_name": "Bruno Cascais", "website": "http://issomesmo.pt", "phone_number": "21344444", "mobile_number": "935678999", "email": "[email protected]", "observations": "observções do cliente", "internal_observations": "observações internas", "not_final_customer": false, "cashed_vat": false, "tax_country_region": "PT", "country_iso_alpha_2": "PT", "saft_import_id": null, "is_tax_exempt": false, "tax_exemption_reason_id": null, "accounting_number": null, "data": {}, "credit_limit_value": null, "credit_limit_days": null, "has_credit_limit_override": false }, "relationships": { "addresses": { "data": [] }, "company": { "data": { "type": "current_company", "id": "800000046" } }, "contacts": { "data": [] }, "defaults": { "data": null }, "email_addresses": { "data": [] }, "main_address": { "data": null }, "main_email_address": { "data": null }, "tax_exemption_reason": { "data": null } } } } Copy POST /api/addresses HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Content-Type: application/json Accept: */* Content-Length: 180 { "data": { "attributes": { "address_detail": "teste 3", "addressable_id": 7, "addressable_type": "Supplier", "city": "Setúbal", "postcode": "2910-099", "region": "Setúbal" }, "type": "addresses" } } Copy { "data": { "attributes": { "address_detail": "teste 3", "city": "Setúbal", "code": null, "for_charge": false, "for_discharge": false, "is_national_holidays_workday": false, "is_primary": false, "is_saturday_workday": false, "is_sunday_workday": false, "name": null, "payroll_enumerations_tax_office_id": null, "postcode": "2910-099", "region": "Setúbal", "subtype": null }, "id": "74", "relationships": { "company": { "data": null }, "country": { "data": null }, "customer": { "data": null }, "supplier": { "data": null }, "user": { "data": null } }, "type": "addresses" } } Payload Copy { "data": { "type": "addresses", "attributes": { "addressable_type": "Customer", //OBRIGATÓRIO "addressable_id": 47, //OBRIGATÓRIO - ID da morada do Cliente "address_detail": "morada teste 2", "city": "Setúbal", "postcode": "2910-099", "region": "Setúbal" "country_id" : 1 // 1 = PT (Portugal Continental); //2 = PT_MA (Madeira); //3 = PT_AC (Açores)...Ver Get/countries } } } Copy POST /api/contacts HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Content-Type: application/json Accept: */* Content-Length: 204 { "data": { "attributes": { "contactable_id": 29, "contactable_type": "Supplier", "email": "[email protected]", "is_primary": true, "mobile_number": null, "name": null, "phone_number": null, "position": null }, "type": "contacts" } } Copy { "data": { "attributes": { "email": "[email protected]", "is_primary": true, "mobile_number": null, "name": null, "phone_number": null, "position": null }, "id": "22", "relationships": { "supplier": { "data": null } }, "type": "contacts" } } Exemplo de Payload Copy { "data": { "type": "contacts", "attributes": { "is_primary": true, "name": "teste_cmo", "position": null, "phone_number": null, "mobile_number": null, "email": "[email protected]", "categories": [\ "general"\ ], "contactable_id": 61, "contactable_type": "Customer" } } } Exemplo de Response Copy { "data": { "type": "contacts", "id": "27", "attributes": { "is_primary": true, "name": "teste_cmo", "position": null, "phone_number": null, "mobile_number": null, "email": "[email protected]" }, "relationships": { "supplier": { "data": null } } } } Copy { "data": { "type": "customers", "id": "61", "attributes": { "tax_registration_number": "229659179", "business_name": "Manuel Ricardo Ribeiro", "contact_name": null, "website": null, "phone_number": null, "mobile_number": null, "email": null, "observations": null, "internal_observations": null, "not_final_customer": false, "cashed_vat": false, "tax_country_region": "PT", "country_iso_alpha_2": "PT", "saft_import_id": null, "is_tax_exempt": false, "data": {} }, "relationships": { "addresses": { "data": [\ {\ "type": "addresses",\ "id": "67"\ }\ ] }, "company": { "data": { "type": "current_company", "id": "800000046" } }, "defaults": { "data": { "type": "customers_defaults", "id": "31" } }, "email_addresses": { "data": [\ {\ "type": "email_addresses",\ "id": "24"\ }\ ] }, "main_address": { "data": { "type": "addresses", "id": "67" } }, "main_email_address": { "data": { "type": "email_addresses", "id": "24" } }, "tax_exemption_reason": { "data": null } } } } Copy PATCH /api/contacts HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Content-Type: application/json Accept: */* Content-Length: 81 { "data": { "attributes": { "email": "[email protected]" }, "id": "24", "type": "contacts" } } Copy { "data": { "attributes": { "email": "[email protected]", "is_primary": true, "mobile_number": null, "name": "teste_cmo", "phone_number": null, "position": null }, "id": "24", "relationships": { "supplier": { "data": null } }, "type": "contacts" } } Exemplo de Payload Copy { "data": { "type": "contacts", "id": "24", "attributes": { "email": "[email protected]" } } } Exemplo de Response Copy { "data": { "type": "contacts", "id": "24", "attributes": { "is_primary": true, "name": "teste", "position": null, "phone_number": null, "mobile_number": null, "email": "[email protected]" }, "relationships": { "supplier": { "data": null } } } } sun-brightdesktopmoon --- # Fornecedores, Morada e E-mail | TOConline - Documentação API ### [hashtag](https://api-docs.toconline.pt/apis/empresa/fornecedores#obter-todos-os-fornecedores) Obter Todos os Fornecedores Esta primeira rota permite obter a informação de todos os fornecedores disponíveis. Para tal, deve apenas realizar o seguinte pedido: ### [hashtag](https://api-docs.toconline.pt/apis/empresa/fornecedores#get-api-suppliers) Obter Todos os Fornecedores get {{base\_url}}/api/suppliers Obter Todos os Fornecedores chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Responses chevron-right 200Success No content get /api/suppliers HTTPchevron-down HTTPcURLJavaScriptPython Test it 200Success No content Endpoint cURL ### [hashtag](https://api-docs.toconline.pt/apis/empresa/fornecedores#obter-fornecedor-por-id) Obter Fornecedor por Id Se pretender obter a informação de um fornecedor específico, deverá realizar o mesmo pedido, especificando o id do fornecedor que deseja consultar ### [hashtag](https://api-docs.toconline.pt/apis/empresa/fornecedores#get-api-addresses-id) Obter Morada por Id get {{base\_url}}/api/addresses/{id} Obter Morada por Id chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Path parameters idstringRequired id da morada Example: `45` Responses chevron-right 200 Obter Todas as Moradas Copy / Obter Todas as Moradas Copy application/json Headersobject Show Headersplus Responseobject Show propertiesplus get /api/addresses/{id} HTTPchevron-down HTTPcURLJavaScriptPython Test it 200 Obter Todas as Moradas Copy / Obter Todas as Moradas Copy chevron-rightExemplo de Resposta[hashtag](https://api-docs.toconline.pt/apis/empresa/fornecedores#exemplo-de-resposta) ### [hashtag](https://api-docs.toconline.pt/apis/empresa/fornecedores#criar-fornecedor) Criar Fornecedor Permite a criação de novas instâncias de fornecedores. De modo a realizar um pedido para esta rota, terá de enviar alguns parâmetros no body do pedido. Tal como está descrito no pedido em baixo. Dentro de data, deverá colocar todos os parâmetros obrigatórios e poderá também colocar os restantes parâmetros, se for do seu interesse. O tipo dos parâmetros está também especificado. ### [hashtag](https://api-docs.toconline.pt/apis/empresa/fornecedores#post-api-suppliers) Criar Fornecedor post {{base\_url}}/api/suppliers Criar Fornecedor chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Body application/jsonchevron-down application/json dataobjectOptional Show propertiesplus Responses chevron-right 200 Criar Fornecedor application/json Headersobject Show Headersplus Responseobject Show propertiesplus post /api/suppliers HTTPchevron-down HTTPcURLJavaScriptPython Test it 200 Criar Fornecedor Payload Response Atributo Descrição Obrigatório type Tipo de entidade (neste caso, fornecedor). Sim tax\_registration\_number Número de identificação fiscal do fornecedor. Sim business\_name Nome comercial ou razão social do fornecedor. Sim website Website do fornecedor (opcional). Não is\_taxable Indica se o fornecedor é tributável (opcional). Não is\_tax\_exempt Indica se o fornecedor está isento de impostos (opcional). Não self\_billing Indica se o fornecedor permite a autogestão de faturas (opcional). Não document\_series\_id ID da série de documentos associada ao fornecedor (opcional). Não internal\_observations Observações internas sobre o fornecedor (opcional). Não tax\_country\_region Região fiscal do fornecedor (opcional). Não is\_independent\_worker Indica se o fornecedor é um trabalhador independente (opcional). Não ### [hashtag](https://api-docs.toconline.pt/apis/empresa/fornecedores#associar-morada-a-fornecedor) Associar morada a Fornecedor A sequência de passos delineada no diagrama proporciona uma compreensão do processo, desde a criação do forncedor até a sua associação com uma morada. ![](https://api-docs.toconline.pt/~gitbook/image?url=https%3A%2F%2F1863668386-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fk7sif7BY0rPzivMcj1HB%252Fuploads%252FrNn6Th63xppQ6A3byg4W%252FDiagramas%2520de%2520Documentac%25CC%25A7a%25CC%2583o-Associar%2520Fornecedor%2520a%2520Morada.jpg%3Falt%3Dmedia%26token%3Df02a19d6-ebfc-47c7-a722-45c162ddb066&width=768&dpr=4&quality=100&sign=1e961b4c&sv=2) circle-exclamation Quando um forncedor é criado, uma morada principal fica associada ao fornecedor. Esta morada por default vem vazia e é necessário atualizar com os dados da nova morada do fornecedor. Através do `id` obtido pela response do [Criar Fornecedor](https://api-docs.toconline.pt/apis/empresa/fornecedores#criar-fornecedor) este deverá ser usado para obter o id da morada ao fazer um `GET /suppliers/{id}` chevron-rightExemplo de resposta de um GET Supplier por ID[hashtag](https://api-docs.toconline.pt/apis/empresa/fornecedores#exemplo-de-resposta-de-um-get-supplier-por-id) O `id` da morada obtido anteriormente, será usado para atualizar os dados da morada através de um `PATCH / addresses`. ### [hashtag](https://api-docs.toconline.pt/apis/empresa/fornecedores#patch-api-addresses) Atualizar Morada patch {{base\_url}}/api/addresses Atualizar Morada chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Body application/jsonchevron-down application/json dataobjectOptional Show propertiesplus Responses chevron-right 200 Atualizar Morada / Atualizar Morada application/json Headersobject Show Headersplus Responseobject Show propertiesplus patch /api/addresses HTTPchevron-down HTTPcURLJavaScriptPython Test it 200 Atualizar Morada / Atualizar Morada O body deste pedido (payload JSON) deverá conter as informações de cliente que se pretende atualizar nos respetivos atributos. Payload Response ### [hashtag](https://api-docs.toconline.pt/apis/empresa/fornecedores#remover-fornecedor) Remover Fornecedor A seguinte rota permite a remoção de um dado fornecedor. Esta rota deve ser utilizada de forma cautelosa dado que é irreversível, e mesmo que este cliente volte a ser criado, o seu id nunca será o mesmo que teria anteriormente. Utilizando o id do forncedor que quer eliminar, que poderá fazer utilizando a primeira rota desta página, por exemplo, terá simplesmente de fazer o pedido: ### [hashtag](https://api-docs.toconline.pt/apis/empresa/fornecedores#delete-api-suppliers-supplierid) Remover Fornecedor delete {{base\_url}}/api/suppliers/{supplierId} Remover Fornecedor chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Path parameters supplierIdstringRequired Responses chevron-right 200Success No content chevron-right 403 Erro Documentos Emitidos application/json delete /api/suppliers/{supplierId} HTTPchevron-down HTTPcURLJavaScriptPython Test it 200Successchevron-down No content ### [hashtag](https://api-docs.toconline.pt/apis/empresa/fornecedores#atualizar-fornecedor) Atualizar Fornecedor A rota PATCH permite a edição de um fornecedor existente. O body deste pedido deverá ser igual ao descrito na rota POST, contendo todas as informações obrigatórias do fornecedor, atualizadas para os valores que tenciona alterar, além do "id" do fornecedor. Álem disto, o pedido deverá ser feito a `https://apiv1.toconline.com/suppliers/{id}`, sendo que {id} é o identificador do fornecedor que tenciona atualizar. ### [hashtag](https://api-docs.toconline.pt/apis/empresa/fornecedores#patch-api-suppliers) Atualizar Fornecedor patch {{base\_url}}/api/suppliers Atualizar Fornecedor chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Body application/jsonchevron-down application/json dataobjectOptional Show propertiesplus Responses chevron-right 200 Sucesso application/json Headersobject Show Headersplus Responseobject Show propertiesplus patch /api/suppliers HTTPchevron-down HTTPcURLJavaScriptPython Test it 200 Sucesso chevron-rightExemplo de Payload[hashtag](https://api-docs.toconline.pt/apis/empresa/fornecedores#exemplo-de-payload) No exemplo que se segue foi atualizado o website da empresa chevron-rightExemplo de Response[hashtag](https://api-docs.toconline.pt/apis/empresa/fornecedores#exemplo-de-response) * * * [hashtag](https://api-docs.toconline.pt/apis/empresa/fornecedores#morada) Morada ------------------------------------------------------------------------------------- ### [hashtag](https://api-docs.toconline.pt/apis/empresa/fornecedores#criar-morada) Criar Morada Quando um Fornecedor é criado este já tem uma morada vazia associada, mas é possível adicionar mais do que uma morada ao Fornecedor. De modo a associar uma morada a um cliente, deverá realizar o seguinte pedido ### [hashtag](https://api-docs.toconline.pt/apis/empresa/fornecedores#post-api-addresses) Criar Morada post {{base\_url}}/api/addresses Criar Morada chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Body application/jsonchevron-down application/json dataobjectOptional Show propertiesplus Responses chevron-right 200 Criar Morada / Criar Morada application/json Headersobject Show Headersplus Responseobject Show propertiesplus post /api/addresses HTTPchevron-down HTTPcURLJavaScriptPython Test it 200 Criar Morada / Criar Morada No pedido acima, o corresponde ao token de acesso válido devolvido pelo serviço de OAuth, e o deverá ter o seguinte formato Atributo Descrição Obrigatório type Tipo de entidade (neste caso, endereço). Sim addressable\_type Tipo de entidade à qual o endereço está associado (neste caso, fornecedor). Sim addressable\_id ID do fornecedor associado ao endereço. Sim address\_detail Detalhes específicos do endereço, como rua e número. Não city Cidade do endereço. Não postcode Código postal do endereço. Não region Região do endereço (por exemplo, província, estado). Não country\_id ID do país do endereço (1 = Portugal Continental, 2 = Madeira, 3 = Açores). Não circle-info "addressable\_id" - corresponde ao id da morada do cliente obtido da relação entre fornecedor e morada, através do [Fornecedores, Morada e E-mail](https://api-docs.toconline.pt/apis/empresa/fornecedores#obter-fornecedor) circle-info Para usar outro país que não seja Portugal, poderá consultar mais informação em: [Países](https://api-docs.toconline.pt/apis/apis-auxiliares/paises) * * * [hashtag](https://api-docs.toconline.pt/apis/empresa/fornecedores#e-mail) E-mail ------------------------------------------------------------------------------------- ### [hashtag](https://api-docs.toconline.pt/apis/empresa/fornecedores#criar-e-mail-de-fornecedor) Criar E-mail de Fornecedor Para proceder à criação do E-mail de um fornecedor pela primeira vez deverá utilizar a `POST / contacts`. ### [hashtag](https://api-docs.toconline.pt/apis/empresa/fornecedores#post-api-contacts) Criar email de Cliente post {{base\_url}}/api/contacts Criar email de Cliente chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Body application/jsonchevron-down application/json dataobjectOptional Show propertiesplus Responses chevron-right 200 Sucesso / Suceso / Criar Novo Contacto application/json Headersobject Show Headersplus Responseobject Show propertiesplus post /api/contacts HTTPchevron-down HTTPcURLJavaScriptPython Criar Novo Contactochevron-down Criar Novo ContactoCriar email de ClienteCriar email de Cliente Copy Test it 200 Sucesso / Suceso / Criar Novo Contacto Criar Novo Contactochevron-down O body deste pedido () deverá conter as informações de fornecedor que se pretende atualizar, sendo obrigatório campo "**contactable\_id**" identificador do fornecedor que tenciona atualizar e o "**contactable\_type**" sendo este do tipo "**Supplier**" Payload Response ![](https://api-docs.toconline.pt/~gitbook/image?url=https%3A%2F%2F1863668386-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fk7sif7BY0rPzivMcj1HB%252Fuploads%252FUokrRzhYP0YYIyiDcYKg%252FDiagramas%2520de%2520Documentac%25CC%25A7a%25CC%2583o%2520TOCOnline%2520API-Criar%2520Email%2520de%2520Fornecedor.jpg%3Falt%3Dmedia%26token%3D10e5b4af-fcfd-44bd-848c-830b6dd35c1d&width=768&dpr=4&quality=100&sign=336187f1&sv=2) Exemplo de Criação de E-mail para Fornecedor ### [hashtag](https://api-docs.toconline.pt/apis/empresa/fornecedores#atualizar-e-mail-de-cliente) Atualizar E-mail de Cliente circle-exclamation Já deve ter realizado [Criar E-mail de Fornecedor](https://api-docs.toconline.pt/apis/empresa/fornecedores#criar-e-mail-de-fornecedor) Usando o `GET / supplier{id}` deverá obter o id correspondente ao contacto do fornecedor, que se encontra localizado na área de relationships-> main\_contact, como pode observar no exemplo de response abaixo. chevron-rightExemplo de response de um GET/supplier/{id}[hashtag](https://api-docs.toconline.pt/apis/empresa/fornecedores#exemplo-de-response-de-um-get-supplier-id) Para proceder à atualização do E-mail de um fornecedor deverá utilizar a `PATCH / contacts` usando o id obtido do main\_contact obtido do fornecedor pretendido. ### [hashtag](https://api-docs.toconline.pt/apis/empresa/fornecedores#patch-api-contacts) Atualizar email de Cliente patch {{base\_url}}/api/contacts Atualizar email de Cliente chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Body application/jsonchevron-down application/json dataobjectOptional Show propertiesplus Responses chevron-right 200 Sucesso / Sucesso application/json Headersobject Show Headersplus Responseobject Show propertiesplus patch /api/contacts HTTPchevron-down HTTPcURLJavaScriptPython Atualizar email de Clientechevron-down Atualizar email de ClienteAtualizar email de Fornecedor Test it 200 Sucesso / Sucesso O body deste pedido () deverá conter as informações de cliente que se pretende atualizar, sendo obrigatório campo "`id`" id do contacto correspondente ao utilizador que tenciona atualizar e o "`email`" novo a ser alterado. Payload Response ![](https://api-docs.toconline.pt/~gitbook/image?url=https%3A%2F%2F1863668386-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252Fk7sif7BY0rPzivMcj1HB%252Fuploads%252FaoocVkvYtXJIfXpFHF9Y%252FDiagramas%2520de%2520Documentac%25CC%25A7a%25CC%2583o%2520TOCOnline%2520API-Atualizar%2520Email%2520de%2520Fornecedor.jpg%3Falt%3Dmedia%26token%3Dd9b634a6-a5a3-42b1-bba5-3c5ae7057aa0&width=768&dpr=4&quality=100&sign=8b3416da&sv=2) Exemplo de Criação de E-mail para Fornecedor [PreviousClientes, Morada e E-mailchevron-left](https://api-docs.toconline.pt/apis/empresa/clientes-morada-e-email) [NextProdutos e Serviçoschevron-right](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos) Last updated 1 year ago * [Obter Todos os Fornecedores](https://api-docs.toconline.pt/apis/empresa/fornecedores#obter-todos-os-fornecedores) * [GETObter Todos os Fornecedores](https://api-docs.toconline.pt/apis/empresa/fornecedores#get-api-suppliers) * [Obter Fornecedor por Id](https://api-docs.toconline.pt/apis/empresa/fornecedores#obter-fornecedor-por-id) * [GETObter Morada por Id](https://api-docs.toconline.pt/apis/empresa/fornecedores#get-api-addresses-id) * [Criar Fornecedor](https://api-docs.toconline.pt/apis/empresa/fornecedores#criar-fornecedor) * [POSTCriar Fornecedor](https://api-docs.toconline.pt/apis/empresa/fornecedores#post-api-suppliers) * [Associar morada a Fornecedor](https://api-docs.toconline.pt/apis/empresa/fornecedores#associar-morada-a-fornecedor) * [PATCHAtualizar Morada](https://api-docs.toconline.pt/apis/empresa/fornecedores#patch-api-addresses) * [Remover Fornecedor](https://api-docs.toconline.pt/apis/empresa/fornecedores#remover-fornecedor) * [DELETERemover Fornecedor](https://api-docs.toconline.pt/apis/empresa/fornecedores#delete-api-suppliers-supplierid) * [Atualizar Fornecedor](https://api-docs.toconline.pt/apis/empresa/fornecedores#atualizar-fornecedor) * [PATCHAtualizar Fornecedor](https://api-docs.toconline.pt/apis/empresa/fornecedores#patch-api-suppliers) * [Morada](https://api-docs.toconline.pt/apis/empresa/fornecedores#morada) * [Criar Morada](https://api-docs.toconline.pt/apis/empresa/fornecedores#criar-morada) * [POSTCriar Morada](https://api-docs.toconline.pt/apis/empresa/fornecedores#post-api-addresses) * [E-mail](https://api-docs.toconline.pt/apis/empresa/fornecedores#e-mail) * [Criar E-mail de Fornecedor](https://api-docs.toconline.pt/apis/empresa/fornecedores#criar-e-mail-de-fornecedor) * [POSTCriar email de Cliente](https://api-docs.toconline.pt/apis/empresa/fornecedores#post-api-contacts) * [Atualizar E-mail de Cliente](https://api-docs.toconline.pt/apis/empresa/fornecedores#atualizar-e-mail-de-cliente) * [PATCHAtualizar email de Cliente](https://api-docs.toconline.pt/apis/empresa/fornecedores#patch-api-contacts) sun-brightdesktopmoon Copy GET /api/suppliers HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Accept: */* Endpoint Copy https://api/v1.toconline.com/api/suppliers cURL Copy curl -v -X GET -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer ' '/api/suppliers' Copy GET /api/addresses/{id} HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Accept: */* Copy { "data": { "attributes": { "address_detail": "", "city": "", "code": null, "for_charge": false, "for_discharge": false, "is_national_holidays_workday": false, "is_primary": true, "is_saturday_workday": false, "is_sunday_workday": false, "name": "Main Address", "payroll_enumerations_tax_office_id": null, "postcode": "", "region": null, "subtype": null }, "id": "3", "relationships": { "company": { "data": null }, "country": { "data": { "id": "1", "type": "countries" } }, "customer": { "data": null }, "supplier": { "data": null }, "user": { "data": { "id": "800000863", "type": "current_company_users" } } }, "type": "addresses" } } Response Copy { "data": { "type": "suppliers", "id": "7", "attributes": { "tax_registration_number": "533186331", "business_name": "A Empresa", "website": "www.a_empresa.pt", "is_taxable": false, "is_tax_exempt": false, "tax_exemption_reason_id": null, "self_billing": null, "document_series_id": null, "internal_observations": null, "tax_country_region": "PT-AC", "is_independent_worker": false, "country_iso_alpha_2": "PT-AC", "saft_import_id": null, "accounting_number": null, "trusted_email_source": false }, "relationships": { "addresses": { "data": [\ {\ "type": "addresses",\ "id": "45"\ }\ ] }, "bank_accounts": { "data": [\ {\ "type": "bank_accounts",\ "id": "4"\ }\ ] }, "company": { "data": { "type": "current_company", "id": "800000046" } }, "contacts": { "data": [\ {\ "type": "contacts",\ "id": "17"\ }\ ] }, "defaults": { "data": { "type": "suppliers_defaults", "id": "4" } }, "main_address": { "data": { "type": "addresses", "id": "45" } }, "main_contact": { "data": { "type": "contacts", "id": "17" } }, "tax_exemption_reason": { "data": null } } } } Copy POST /api/suppliers HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Content-Type: application/json Accept: */* Content-Length: 448 { "data": { "attributes": { "accounting_number": null, "business_name": "A Empresa 3", "country_iso_alpha_2": "PT", "document_series_id": null, "internal_observations": null, "is_independent_worker": false, "is_tax_exempt": false, "is_taxable": false, "saft_import_id": null, "self_billing": null, "tax_country_region": "PT", "tax_exemption_reason_id": null, "tax_registration_number": "533186331", "trusted_email_source": false, "website": "www.a_empresa3.pt" }, "type": "suppliers" } } Copy { "data": { "attributes": { "business_name": "A Empresa 3", "country_iso_alpha_2": "PT", "document_series_id": null, "internal_observations": null, "is_independent_worker": false, "is_tax_exempt": false, "is_taxable": false, "saft_import_id": null, "self_billing": null, "tax_country_region": "PT", "tax_registration_number": "533186331", "website": "www.a_empresa3.pt" }, "id": "29", "relationships": { "addresses": { "data": [] }, "bank_accounts": { "data": [] }, "company": { "data": { "id": "800000046", "type": "current_company" } }, "contacts": { "data": [] }, "defaults": { "data": null }, "main_address": { "data": null }, "main_contact": { "data": null }, "tax_exemption_reason": { "data": null } }, "type": "suppliers" } } Payload Copy { "data": { "type": "suppliers", "attributes": { "tax_registration_number": 533186331, //OBRIGATÓRIO "business_name": "A Empresa", //OBRIGATÓRIO "website": null, "is_taxable": null, "is_tax_exempt": null, "self_billing": null, "document_series_id": null, "internal_observations": null, "tax_country_region": null, "is_independent_worker": null } } } Response Copy { "data": { "type": "suppliers", "id": "7", "attributes": { "tax_registration_number": "533186331", "business_name": "A Empresa", "website": null, "is_taxable": false, "is_tax_exempt": false, "tax_exemption_reason_id": null, "self_billing": null, "document_series_id": null, "internal_observations": null, "tax_country_region": "PT", "is_independent_worker": false, "country_iso_alpha_2": "PT", "saft_import_id": null, "accounting_number": null, "trusted_email_source": false }, "relationships": { "addresses": { "data": [] }, "bank_accounts": { "data": [] }, "company": { "data": { "type": "current_company", "id": "800000046" } }, "contacts": { "data": [] }, "defaults": { "data": null }, "main_address": { "data": null }, "main_contact": { "data": null }, "tax_exemption_reason": { "data": null } } } } Response Copy { "data": { "type": "suppliers", "id": "7", "attributes": { "tax_registration_number": "533186331", "business_name": "A Empresa", "website": "www.a_empresa.pt", "is_taxable": false, "is_tax_exempt": false, "tax_exemption_reason_id": null, "self_billing": null, "document_series_id": null, "internal_observations": null, "tax_country_region": "PT-AC", "is_independent_worker": false, "country_iso_alpha_2": "PT-AC", "saft_import_id": null, "accounting_number": null, "trusted_email_source": false }, "relationships": { "addresses": { "data": [\ {\ "type": "addresses",\ "id": "45"\ }\ ] }, "bank_accounts": { "data": [\ {\ "type": "bank_accounts",\ "id": "4"\ }\ ] }, "company": { "data": { "type": "current_company", "id": "800000046" } }, "contacts": { "data": [\ {\ "type": "contacts",\ "id": "17"\ }\ ] }, "defaults": { "data": { "type": "suppliers_defaults", "id": "4" } }, "main_address": { "data": { "type": "addresses", "id": "45" } }, "main_contact": { "data": { "type": "contacts", "id": "17" } }, "tax_exemption_reason": { "data": null } } } } Copy PATCH /api/addresses HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Content-Type: application/json Accept: */* Content-Length: 168 { "data": { "attributes": { "address_detail": "Avenida Principal", "city": "Setúbal", "country_id": "3", "postcode": "2910-099", "region": "Setúbal" }, "id": "45", "type": "addresses" } } Copy { "data": { "attributes": { "address_detail": "Avenida Principal", "city": "Setúbal", "code": null, "for_charge": false, "for_discharge": false, "is_national_holidays_workday": false, "is_primary": true, "is_saturday_workday": false, "is_sunday_workday": false, "name": "Sede", "payroll_enumerations_tax_office_id": null, "postcode": "2910-099", "region": "Setúbal", "subtype": null }, "id": "45", "relationships": { "company": { "data": null }, "country": { "data": { "id": "3", "type": "countries" } }, "customer": { "data": null }, "supplier": { "data": null }, "user": { "data": null } }, "type": "addresses" } } Payload Copy { "data": { "type": "addresses", "id": "45", "attributes": { "address_detail": "Avenida Principal", "city": "Setúbal", "postcode": "2910-099", "region": "Setúbal", "country_id": "3" } } } Response Copy { "data": { "type": "addresses", "id": "45", "attributes": { "is_primary": true, "address_detail": "Avenida Principal", "city": "Setúbal", "postcode": "2910-099", "region": "Setúbal", "name": "Sede", "for_discharge": false, "for_charge": false, "subtype": null, "is_saturday_workday": false, "is_sunday_workday": false, "is_national_holidays_workday": false, "code": null, "payroll_enumerations_tax_office_id": null }, "relationships": { "company": { "data": null }, "country": { "data": { "type": "countries", "id": "3" } }, "customer": { "data": null }, "supplier": { "data": null }, "user": { "data": null } } } } Copy DELETE /api/suppliers/{supplierId} HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Accept: */* Copy PATCH /api/suppliers HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Content-Type: application/json Accept: */* Content-Length: 454 { "data": { "attributes": { "accounting_number": null, "business_name": "A Empresa", "country_iso_alpha_2": "PT", "document_series_id": null, "internal_observations": null, "is_independent_worker": false, "is_tax_exempt": false, "is_taxable": false, "saft_import_id": null, "self_billing": null, "tax_country_region": "PT", "tax_exemption_reason_id": null, "tax_registration_number": "533186331", "trusted_email_source": false, "website": "www.a_empresa.pt" }, "id": "7", "type": "suppliers" } } Copy { "data": { "attributes": { "business_name": "A Empresa", "country_iso_alpha_2": "PT", "document_series_id": null, "internal_observations": null, "is_independent_worker": false, "is_tax_exempt": false, "is_taxable": false, "saft_import_id": null, "self_billing": null, "tax_country_region": "PT", "tax_registration_number": "533186331", "website": "www.a_empresa.pt" }, "id": "7", "relationships": { "addresses": { "data": [] }, "bank_accounts": { "data": [] }, "company": { "data": { "id": "800000046", "type": "current_company" } }, "contacts": { "data": [] }, "defaults": { "data": null }, "main_address": { "data": null }, "main_contact": { "data": null }, "tax_exemption_reason": { "data": null } }, "type": "suppliers" } } Payload Copy { "data": { "type": "suppliers", "id": "7", "attributes": { "tax_registration_number": "533186331", "business_name": "A Empresa", "website": "www.a_empresa.pt", "is_taxable": false, "is_tax_exempt": false, "tax_exemption_reason_id": null, "self_billing": null, "document_series_id": null, "internal_observations": null, "tax_country_region": "PT", "is_independent_worker": false, "country_iso_alpha_2": "PT", "saft_import_id": null, "accounting_number": null, "trusted_email_source": false } } } Copy { "data": { "type": "suppliers", "id": "7", "attributes": { "tax_registration_number": "533186331", "business_name": "A Empresa", "website": null, "is_taxable": false, "is_tax_exempt": false, "tax_exemption_reason_id": null, "self_billing": null, "document_series_id": null, "internal_observations": null, "tax_country_region": "PT", "is_independent_worker": false, "country_iso_alpha_2": "PT", "saft_import_id": null, "accounting_number": null, "trusted_email_source": false }, "relationships": { "addresses": { "data": [] }, "bank_accounts": { "data": [] }, "company": { "data": { "type": "current_company", "id": "800000046" } }, "contacts": { "data": [] }, "defaults": { "data": null }, "main_address": { "data": null }, "main_contact": { "data": null }, "tax_exemption_reason": { "data": null } } } } Copy POST /api/addresses HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Content-Type: application/json Accept: */* Content-Length: 180 { "data": { "attributes": { "address_detail": "teste 3", "addressable_id": 7, "addressable_type": "Supplier", "city": "Setúbal", "postcode": "2910-099", "region": "Setúbal" }, "type": "addresses" } } Copy { "data": { "attributes": { "address_detail": "teste 3", "city": "Setúbal", "code": null, "for_charge": false, "for_discharge": false, "is_national_holidays_workday": false, "is_primary": false, "is_saturday_workday": false, "is_sunday_workday": false, "name": null, "payroll_enumerations_tax_office_id": null, "postcode": "2910-099", "region": "Setúbal", "subtype": null }, "id": "74", "relationships": { "company": { "data": null }, "country": { "data": null }, "customer": { "data": null }, "supplier": { "data": null }, "user": { "data": null } }, "type": "addresses" } } Payload Copy { "data": { "type": "addresses", "attributes": { "addressable_type": "Supplier", //OBRIGATÓRIO "addressable_id": 7, //OBRIGATÓRIO - ID da morada do Fornecedor "address_detail": "teste 3", "city": "Setúbal", "postcode": "2910-099", "region": "Setúbal", "country_id" : 1 // 1 = PT (Portugal Continental); 2 = PT_MA (Madeira); //3 = PT_AC (Açores)...Ver Get/countries } } } Copy POST /api/contacts HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Content-Type: application/json Accept: */* Content-Length: 204 { "data": { "attributes": { "contactable_id": 29, "contactable_type": "Supplier", "email": "[email protected]", "is_primary": true, "mobile_number": null, "name": null, "phone_number": null, "position": null }, "type": "contacts" } } Copy { "data": { "attributes": { "email": "[email protected]", "is_primary": true, "mobile_number": null, "name": null, "phone_number": null, "position": null }, "id": "22", "relationships": { "supplier": { "data": null } }, "type": "contacts" } } Exemplo de Payload Copy { "data": { "type": "contacts", "attributes": { "is_primary": true, "name": "teste_cmo", "position": null, "phone_number": null, "mobile_number": null, "email": "[email protected]", "categories": [\ "general"\ ], "contactable_id": 61, "contactable_type": "Customer" } } } Exemplo de Response Copy { "data": { "type": "contacts", "id": "29", "attributes": { "is_primary": true, "name": "teste_supplier", "position": null, "phone_number": null, "mobile_number": null, "email": "[email protected]" }, "relationships": { "supplier": { "data": null } } } } ``` Copy { "data": { "type": "customers", "id": "61", "attributes": { "tax_registration_number": "229659179", "business_name": "Manuel Ricardo Ribeiro", "contact_name": null, "website": null, "phone_number": null, "mobile_number": null, "email": null, "observations": null, "internal_observations": null, "not_final_customer": false, "cashed_vat": false, "tax_country_region": "PT", "country_iso_alpha_2": "PT", "saft_import_id": null, "is_tax_exempt": false, "data": {} }, "relationships": { "addresses": { "data": [\ {\ "type": "addresses",\ "id": "67"\ }\ ] }, "company": { "data": { "type": "current_company", "id": "800000046" } }, "defaults": { "data": { "type": "customers_defaults", "id": "31" } }, "email_addresses": { "data": [\ {\ "type": "email_addresses",\ "id": "24"\ }\ ] }, "main_address": { "data": { "type": "addresses", "id": "67" } }, "main_email_address": { "data": { "type": "email_addresses", "id": "24" } }, "tax_exemption_reason": { "data": null } } } } Copy PATCH /api/contacts HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Content-Type: application/json Accept: */* Content-Length: 81 { "data": { "attributes": { "email": "[email protected]" }, "id": "24", "type": "contacts" } } Copy { "data": { "attributes": { "email": "[email protected]", "is_primary": true, "mobile_number": null, "name": "teste_cmo", "phone_number": null, "position": null }, "id": "24", "relationships": { "supplier": { "data": null } }, "type": "contacts" } } Exemplo de Payload Copy { "data": { "type": "contacts", "id": "24", "attributes": { "email": "[email protected]" } } } Exemplo de Response Copy { "data": { "type": "contacts", "id": "24", "attributes": { "is_primary": true, "name": "teste", "position": null, "phone_number": null, "mobile_number": null, "email": "[email protected]" }, "relationships": { "supplier": { "data": null } } } } sun-brightdesktopmoon --- # Documentos de Compra | TOConline - Documentação API [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/documentos-de-compra#criacao-de-documentos-de-compra) Criação de Documentos de Compra ------------------------------------------------------------------------------------------------------------------------------------------------------------------ Para a criação de compras no sistema, é necessário seguir dois passos principais: a criação do cabeçalho e a inserção de uma ou mais linhas correspondentes aos itens adquiridos. 1. **Cabeçalho da Compra**: O cabeçalho contém informações gerais sobre a compra, como data, fornecedor e condições de pagamento. 2. **Linhas da Compra**: Cada linha detalha um item específico comprado, incluindo a descrição, quantidade e preço. 3. **Finalização de Documento de Compra** ### [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/documentos-de-compra#id-1.-criar-cabecalho-de-documentos-de-compra) 1\. Criar Cabeçalho de Documentos de Compra De modo a criar uma compra, deverá inicialmente criar o cabeçalho do documento. Para este efeito, deverá realizar o seguinte pedido: ### [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/documentos-de-compra#post-api-commercial_sales_document_lines) Criar Linha de Documentos de Venda para um Produto post {{base\_url}}/api/commercial\_sales\_document\_lines Criar Linha de Documentos de Venda para um Produto chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Body application/jsonchevron-down application/json dataobjectOptional Show propertiesplus Responses chevron-right 200 Sucesso / Criar Linha de Documentos de Venda para um Serviço / Criar Linha de Documentos de Venda para um Descritor / Criar Linha de Documento de Venda para uma Descrição Sem Valor application/json Headersobject Show Headersplus Responseobject Show propertiesplus post /api/commercial\_sales\_document\_lines HTTPchevron-down HTTPcURLJavaScriptPython Criar Linha de Documento de Venda para uma Descrição Sem Valorchevron-down Criar Linha de Documento de Venda para uma Descrição Sem ValorCriar Linha de Documentos de Venda para um DescritorCriar Linha de Documentos de Venda para um ProdutoCriar Linha de Documentos de Venda para um Serviço Test it 200 Sucesso / Criar Linha de Documentos de Venda para um Serviço / Criar Linha de Documentos de Venda para um Descritor / Criar Linha de Documento de Venda para uma Descrição Sem Valor Criar Linha de Documento de Venda para uma Descrição Sem Valorchevron-down No pedido acima, o corresponde ao token de acesso válido devolvido pelo serviço de OAuth Caso a compra seja realizada em euros, o deverá vir de acordo com os exemplos seguintes: #### [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/documentos-de-compra#id-1.1-criar-cabecalho-de-documento-de-venda-para-uma-nova-empresa) 1.1 Criar Cabeçalho de Documento de Venda para uma Nova Empresa circle-exclamation Após criar o cabeçalho, a resposta TEM QUE ser consultada para obtenção do identificador interno ("id") da compra criada. Este identificador será necessário para a criação de todas as linhas. #### [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/documentos-de-compra#id-1.2-criar-cabecalho-de-documento-de-venda-para-uma-empresa-existente) 1.2 Criar Cabeçalho de Documento de Venda para uma Empresa Existente ### [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/documentos-de-compra#id-2.-criar-linhas-de-documentos-de-compra) 2\. Criar Linhas de Documentos de Compra Em todos os pedidos seguintes, é necessário saber qual o id do documento de compra. Este id pode ser guardado a partir da resposta (JSON) ao pedido de criação anterior, ou pode ser consultado via API. Via API, o id do documento pode ser obtido por um filtro a todos os Documentos de Compra usando o número do documento (finalizado). Se o documento ainda não estiver finalizado (fechado), então ainda não tem número atribuído, e o GET anterior não poderá ser feito! Em alternativa pode realizado um filtro a todos os Documentos de Compra usando o estado do documento e número de registro fiscal do fornecedor. De modo a inserir linhas na compra criada, deverá realizar o seguinte pedido ### [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/documentos-de-compra#post-api-commercial_purchases_payment_lines) Adicionar Linha a Pagamentos post {{base\_url}}/api/commercial\_purchases\_payment\_lines Adicionar Linha a Pagamentos chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Body application/jsonchevron-down application/json dataobjectOptional Show propertiesplus Responses chevron-right 200Success No content post /api/commercial\_purchases\_payment\_lines HTTPchevron-down HTTPcURLJavaScriptPython Adicionar Linha a Pagamentoschevron-down Adicionar Linha a PagamentosCriar Linhas de Pagamento Test it 200Success No content No pedido acima, o corresponde ao token de acesso válido devolvido pelo serviço de OAuth. O payload JSON deverá vir no seguinte formato, dependendo se se trata de um produto, ou categoria de despesa. circle-exclamation Nos documentos de despesas (tipo de documento DSP), só são aceites linhas de Categorias de Despesa, não de Produtos. #### [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/documentos-de-compra#id-2.1-criar-linha-para-produto) 2.1 Criar Linha para Produto #### [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/documentos-de-compra#id-2.2-criar-linha-para-categoria-de-despesas) 2.2 Criar Linha para Categoria de Despesas circle-info Para mais informações acerca de Categorias de Despesa visite a página: [Categorias de Despesa](https://api-docs.toconline.pt/apis/apis-auxiliares/categorias-de-despesa) ### [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/documentos-de-compra#id-3.-finalizacao-de-um-documento-de-compra) 3\. Finalização de um Documento de Compra ### [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/documentos-de-compra#patch-api-v1-commercial_purchases_documents-id-finalize) Finalizar Documentos de Compra patch {{base\_url}}/api/v1/commercial\_purchases\_documents/{id}/finalize Finalizar Documentos de Compra chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Path parameters idstringRequiredExample: `41` Body application/jsonchevron-down application/json objectOptional Responses chevron-right 200 Finalizar Documentos de Compra application/json Headersobject Show Headersplus Responseobject Show propertiesplus patch /api/v1/commercial\_purchases\_documents/{id}/finalize HTTPchevron-down HTTPcURLJavaScriptPython Test it 200 Finalizar Documentos de Compra circle-info NOTA: o documento e as linhas podem continuar a ser alterados mesmo depois de finalizados (fechados) ### [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/documentos-de-compra#undefined) [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/documentos-de-compra#alteracao-de-documento-de-compra) Alteração de Documento de Compra -------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/documentos-de-compra#anulacao-do-documento-de-compra) Anulação do Documento de Compra ### [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/documentos-de-compra#patch-api-v1-commercial_purchases_documents-id-void) Anular Documentos de Compra patch {{base\_url}}/api/v1/commercial\_purchases\_documents/{id}/void Anular Documentos de Compra chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Path parameters idstringRequiredExample: `41` Responses chevron-right 200Success No content patch /api/v1/commercial\_purchases\_documents/{id}/void HTTPchevron-down HTTPcURLJavaScriptPython Test it 200Success No content ### [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/documentos-de-compra#obter-todos-os-documentos-de-compra-finalizados) Obter Todos os Documentos de Compra Finalizados * * * [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/documentos-de-compra#linhas-de-documento-de-compra) Linhas de Documento de Compra -------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/documentos-de-compra#remover-linha-de-documento) Remover Linha de Documento ### [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/documentos-de-compra#delete-api-commercial_purchases_payment_lines) Remover Linhas de Pagamento delete {{base\_url}}/api/commercial\_purchases\_payment\_lines Remover Linhas de Pagamento chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Responses chevron-right 200Success No content delete /api/commercial\_purchases\_payment\_lines HTTPchevron-down HTTPcURLJavaScriptPython Test it 200Success No content [PreviousCompraschevron-left](https://api-docs.toconline.pt/apis/versoes-anteriores/compras) [NextPagamentoschevron-right](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/pagamentos) Last updated 1 year ago * [Criação de Documentos de Compra](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/documentos-de-compra#criacao-de-documentos-de-compra) * [1\. Criar Cabeçalho de Documentos de Compra](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/documentos-de-compra#id-1.-criar-cabecalho-de-documentos-de-compra) * [POSTCriar Linha de Documentos de Venda para um Produto](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/documentos-de-compra#post-api-commercial_sales_document_lines) * [2\. Criar Linhas de Documentos de Compra](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/documentos-de-compra#id-2.-criar-linhas-de-documentos-de-compra) * [POSTAdicionar Linha a Pagamentos](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/documentos-de-compra#post-api-commercial_purchases_payment_lines) * [3\. Finalização de um Documento de Compra](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/documentos-de-compra#id-3.-finalizacao-de-um-documento-de-compra) * [PATCHFinalizar Documentos de Compra](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/documentos-de-compra#patch-api-v1-commercial_purchases_documents-id-finalize) * [](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/documentos-de-compra#undefined) * [Alteração de Documento de Compra](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/documentos-de-compra#alteracao-de-documento-de-compra) * [Anulação do Documento de Compra](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/documentos-de-compra#anulacao-do-documento-de-compra) * [PATCHAnular Documentos de Compra](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/documentos-de-compra#patch-api-v1-commercial_purchases_documents-id-void) * [Obter Todos os Documentos de Compra Finalizados](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/documentos-de-compra#obter-todos-os-documentos-de-compra-finalizados) * [Linhas de Documento de Compra](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/documentos-de-compra#linhas-de-documento-de-compra) * [Remover Linha de Documento](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/documentos-de-compra#remover-linha-de-documento) * [DELETERemover Linhas de Pagamento](https://api-docs.toconline.pt/apis/versoes-anteriores/compras/documentos-de-compra#delete-api-commercial_purchases_payment_lines) sun-brightdesktopmoon Copy POST /api/commercial_sales_document_lines HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Content-Type: application/json Accept: */* Content-Length: 120 { "data": { "attributes": { "description": "Descrição da linha", "document_id": 66 }, "type": "commercial_sales_document_lines" } } Copy { "data": { "attributes": { "amount": null, "amount_with_header_settlement": null, "base_currency_amount": null, "base_currency_net_amount": null, "base_currency_net_unit_price": null, "base_currency_settlement_with_tax": null, "base_currency_settlement_without_tax": null, "base_currency_tax_amount": null, "base_currency_unit_price": null, "created_at": "2024-03-05 14:27:22.265972", "date": null, "description": "Descrição da linha", "exemption_reason": null, "imported_quantity": null, "item_code": "", "item_id": null, "item_type": "", "item_unit_price_includes_vat": false, "locked": null, "net_amount": null, "net_amount_with_header_settlement": null, "net_settlement_amount": null, "net_tax_amount": null, "net_unit_price": null, "original_document_no": null, "pending_quantity": null, "pending_retention_value": null, "pending_total": null, "quantity": null, "retention_value": null, "settlement_amount": null, "settlement_expression": null, "settlement_percentage": 0, "settlement_with_tax": null, "settlement_without_tax": null, "tax_amount": null, "tax_code": null, "tax_country_region": "PT-MA", "tax_descriptor_id": null, "tax_percentage": null, "unit_price": null, "updated_at": "2024-03-05 14:27:22.265972" }, "id": "136", "relationships": { "document": { "data": { "id": "66", "type": "commercial_sales_documents" } }, "product": { "data": null }, "service": { "data": null }, "tax": { "data": null }, "tax_descriptor": { "data": null }, "unit_of_measure": { "data": null } }, "type": "commercial_sales_document_lines" }, "meta": { "observed": { "lines": 1, "scalar": 0 } } } Copy { "data": { "type": "commercial_purchases_documents", "attributes": { "document_type": "FC", //[OBRIGATÓRIO] Pode ser FC (fatura de compra), NCF (nota de crédito), NDF (nota de débito), DSP (fatura de despesaa) "date": "2020-05-25", // Por omissão, a data de hoje "due_date": "2020-05-25", // Por omissão, a data do documento "currency_conversion_rate": 0.813 // Obrigatório quando a moeda não é EUR. Taxa de conversão da moeda para EUR (1 EUR = x) "supplier_tax_registration_number": "888888880", // Por omissão, o fornecedor indiferenciado (999999990) //**** Para uma empresa que já existe "company_id": 2, //id da moeda usada "currency_id" :2 //id de um fornecedor "supplier_id": 2, // Indicar o atributo seguinte, com o valor true, apenas se os preços indicados nas linhas forem preços com IVA incluído "external_reference": "Texto livre, referente ao campo Vossa Ref.", // "vat_included_prices": true, // Indicar o atributo seguinte apenas se existir desconto de cabeçalho (7,5%, neste exemplo) "settlement_expression": "7.5", // Indicar o atributo seguinte apenas se existir retenção (10€, neste exemplo) "retention_total": 10 // Associação à série de documentos. Pode ser omitida, se for para usar a série por omissão "commercial_document_series_id": "" // Este id pode ser obtido por um GET /commercial_document_series?filter[document_type]=FC|NCF|...&filter[prefix]=2020|ou outro qualquer... } } } Copy { "data": { "type": "commercial_purchases_documents", "attributes": { "document_type": "FC", //[OBRIGATÓRIO] Pode ser FC (fatura de compra), NCF (nota de crédito), NDF (nota de débito), DSP (fatura de despesaa) "date": "2020-05-25", // Por omissão, a data de hoje "due_date": "2020-05-25", // Por omissão, a data do documento "currency_conversion_rate": 0.813 // Obrigatório quando a moeda não é EUR. Taxa de conversão da moeda para EUR (1 EUR = x) "supplier_tax_registration_number": "888888880", // Por omissão, o fornecedor indiferenciado (999999990) //**** Para uma empresa que já existe "company_id": 2, // Indicar o atributo seguinte, com o valor true, apenas se os preços indicados nas linhas forem preços com IVA incluído "external_reference": "Texto livre, referente ao campo Vossa Ref.", // "vat_included_prices": true, // Indicar o atributo seguinte apenas se existir desconto de cabeçalho (7,5%, neste exemplo) "settlement_expression": "7.5", // Indicar o atributo seguinte apenas se existir retenção (10€, neste exemplo) "retention_total": 10 // Associação à série de documentos. Pode ser omitida, se for para usar a série por omissão "commercial_document_series_id": "" // Este id pode ser obtido por um GET /commercial_document_series?filter[document_type]=FC|NCF|...&filter[prefix]=2020|ou outro qualquer... } } } Copy GET /commercial_purchases_documents?filter[document_no]= Copy GET /commercial_purchases_documents?filter[status]=0&filter[supplier_tax_registration_number]= Copy POST /api/commercial_purchases_payment_lines HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Content-Type: application/json Accept: */* Content-Length: 163 { "data": { "attributes": { "paid_value": 50, "payable_id": 2, "payable_type": "Purchases::Document", "settlement_percentage": 3 }, "type": "commercial_purchases_payment_lines" } } Copy { "data": { "type": "commercial_purchases_document_lines", "attributes": { "quantity": 1, "unit_price": 20, "item_type": "Product", "item_code": "PTEST", // NOTA: já tem que existir o produto com este código // Indicar o atributo seguinte apenas se existir desconto de linha (3%, neste exemplo) "settlement_expression":"3", "document_id": 2, // Associação ao documento de compra "tax_id":1 // O id da taxa de IVA pode ser obtido por um GET /taxes?filter[tax_code]=NOR|INT|RED|ISE } } } Copy { "data": { "type": "commercial_purchases_document_lines", "attributes": { "quantity": 1, "unit_price": 20, "item_type": "Purchases::ExpenseCategory", "item_code": "ETEST", // NOTA: já tem que existir a categoria de despesa com este código "documet_id": 2, "tax_id": 2 } } } Copy PATCH /api/v1/commercial_purchases_documents/{id}/finalize HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Content-Type: application/json Accept: */* Content-Length: 2 {} Copy { "acts_as_shipment_document": null, "apply_retention_when_paid": null, "base_currency_gross_total": null, "base_currency_net_total": null, "base_currency_pending_total": null, "base_currency_retention_total": null, "base_currency_settlement_total": null, "base_currency_vat_incidence_int": null, "base_currency_vat_incidence_ise": null, "base_currency_vat_incidence_nor": null, "base_currency_vat_incidence_red": null, "base_currency_vat_total_int": null, "base_currency_vat_total_nor": null, "base_currency_vat_total_red": null, "cashed_vat": null, "child_documents_ids": null, "communication_code": null, "communication_code_source": null, "communication_status": null, "company_id": 800000046, "created_at": "2024-03-06 10:52:52.637757", "currency_conversion_rate": 1, "currency_id": 1, "currency_iso_code": "EUR", "date": "2024-03-06", "document_area": "FC", "document_hash_sum": null, "document_no": "FC 2023/4", "document_series_id": 125, "document_series_prefix": "2023", "document_type": "FC", "due_date": "2024-03-06", "emailed": null, "external_reference": "", "gross_total": 0, "hash_control": null, "id": 41, "is_third_party": null, "line_settlement_with_tax": 0, "line_settlement_with_tax_unrounded": 0, "line_settlement_without_tax": 0, "line_settlement_without_tax_unrounded": 0, "lines": [\ {\ "amount": 0,\ "amount_with_header_settlement": 0,\ "base_currency_amount": null,\ "base_currency_net_amount": null,\ "base_currency_net_unit_price": null,\ "base_currency_settlement_with_tax": null,\ "base_currency_settlement_without_tax": null,\ "base_currency_tax_amount": null,\ "base_currency_unit_price": null,\ "created_at": "2024-03-06 11:05:50.019855",\ "date": null,\ "description": "Impostos Sobre o Rendimento",\ "document_id": 41,\ "expense_category_id": 2,\ "id": 41,\ "imported_quantity": null,\ "item_code": "241",\ "item_id": 2,\ "item_type": "Purchases::ExpenseCategory",\ "item_unit_price_includes_vat": false,\ "net_amount": 0,\ "net_amount_with_header_settlement": 0,\ "net_unit_price": 0,\ "original_document_no": null,\ "pending_quantity": null,\ "pending_retention_value": null,\ "pending_total": null,\ "quantity": null,\ "retention_value": null,\ "settlement_amount": null,\ "settlement_expression": null,\ "settlement_percentage": 0,\ "settlement_with_tax": 0,\ "settlement_without_tax": 0,\ "tax_amount": 0,\ "tax_code": "NOR",\ "tax_country_region": "PT",\ "tax_id": 1,\ "tax_percentage": 23,\ "unit_of_measure_id": 2,\ "unit_price": 0,\ "updated_at": "2024-03-06 11:05:50.019855"\ }\ ], "net_total": 0, "notes": "", "operation_country": null, "parent_document_area": null, "parent_documents_ids": null, "payments_ids": null, "pending_retention_value": 0, "pending_total": 0, "printed": null, "public_link": "", "retention": null, "retention_type": null, "retention_value": 0, "retention_value_unrounded": 0, "settlement_expression": null, "settlement_percentage": 0, "settlement_total": 0, "settlement_with_tax": 0, "settlement_with_tax_unrounded": 0, "settlement_without_tax": 0, "settlement_without_tax_unrounded": 0, "shipment_country": null, "shipment_loading_address_detail": null, "shipment_loading_city": null, "shipment_loading_country": null, "shipment_loading_postcode": null, "shipment_loading_time": null, "shipment_unloading_address_detail": null, "shipment_unloading_city": null, "shipment_unloading_country": null, "shipment_unloading_postcode": null, "shipment_unloading_time": null, "status": 1, "supplier_address_detail": "", "supplier_business_name": "Fornecedor Indiferenciado", "supplier_city": "", "supplier_country": "PT", "supplier_id": 9, "supplier_postcode": "", "supplier_tax_country_region": "PT", "supplier_tax_registration_number": "999999990", "system_entry_date": "2024-03-06 11:06:17.132657", "tax_payable": 0, "third_party_type": null, "total_pending_quantity": null, "updated_at": "2024-03-06 11:06:17.132657", "user_id": 800000863, "vat_incidence_int": 0, "vat_incidence_int_unrounded": 0, "vat_incidence_ise": 0, "vat_incidence_ise_unrounded": 0, "vat_incidence_nor": 0, "vat_incidence_nor_unrounded": 0, "vat_incidence_red": 0, "vat_incidence_red_unrounded": 0, "vat_included_prices": false, "vat_percentage_int": null, "vat_percentage_nor": 23, "vat_percentage_red": null, "vat_total_int": 0, "vat_total_int_unrounded": 0, "vat_total_nor": 0, "vat_total_nor_unrounded": 0, "vat_total_red": 0, "vat_total_red_unrounded": 0, "vehicle_registration": null, "voided_reason": null } Payload Copy { "type": "commercial_purchases_documents", "id": "", "data": { "attributes": { "status": 1 } } } Copy PATCH /api/v1/commercial_purchases_documents/{id}/void HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Accept: */* Payload Copy { "data": { "type": "commercial_purchases_documents", "id": "", "attributes": { "status": 4, "voided_reason": "Texto livre com o motivo pelo qual se está a anular o documento" // Opcional, não precisa de ser indicada } } } Endpoint Copy {{base_url}}/api/commercial_purchases_documents?filter[status]=1 Copy DELETE /api/commercial_purchases_payment_lines HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Accept: */* sun-brightdesktopmoon --- # Documentos de Venda | TOConline - Documentação API [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/documentos-de-venda#criacao-do-documento-de-venda) 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. * * * ### [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/documentos-de-venda#id-1.-criar-cabecalho-de-documento-de-venda) 1\. Criar Cabeçalho de Documento de Venda ### [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/documentos-de-venda#post-api-commercial_sales_documents) Criar Cabeçalho de Documentos de Venda post {{base\_url}}/api/commercial\_sales\_documents | Atributo | Descrição | Opcional | | --- | --- | --- | | document\_type | Tipo de documento. "FT": fatura, "FS": fatura simplificada, "FR": fatura-recibo. | Não | | date | Data do documento; por omissão, a data do pedido. | Sim | | document\_series\_prefix | Em alternativa ao campo "document\_series\_id". | Sim | | customer\_tax\_registration\_number | NIF do cliente. se o cliente com o NIF indicado não existir, será criado automaticamente. | Sim | | customer\_business\_name | Nome do cliente. | Não | | customer\_address\_detail | Morada do cliente. | Sim | | customer\_postcode | Código postal do cliente, no formato 0000-000. | Sim | | customer\_city | Cidade/Localidade do cliente. | Sim | | customer\_country | País do cliente. Por omissão, "PT"; é o código ISO alpha-2 do país do cliente. | Sim | | customer\_id | No caso do cliente já existir e não pretender criar um novo. | Sim | | due\_date | Data de vencimento; por omissão, a data do documento, ou a referente ao prazo de pagamento configurado no cliente. | Sim | | settlement\_expression | Desconto no cabeçalho, em percentagem; são suportados descontos compostos, como "3+5" | Sim | | payment\_mechanism | Modos de pagamento aceites. | Sim | | vat\_included\_prices | Os preços nas linhas são com IVA incluído? Por omissão, não (false). | Sim | | operation\_country | A região de operação para efeitos de IVA. | Sim | | currency\_iso\_code | É o código ISO da moeda do documento. | Sim | | currency\_conversion\_rate | É a taxa de conversão para EUR. | Sim | | retention | Percentagem de retenção a aplicar sobre os serviços. | Sim | | retention\_type | Tipo de retenção ("IRS" ou "IRC"). Por omissão, "IRS". | Sim | | apply\_retention\_when\_paid | A retenção é feita logo no documento (false) ou apenas no recebimento (true). Por omissão, false. | Sim | | notes | Notas ao documento. | Sim | | external\_reference | Referência do documento externo. | Sim | chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Body application/jsonchevron-down application/json dataobjectOptional Show propertiesplus Responses chevron-right 200 Sucesso application/json Headersobject Show Headersplus Responseobject Show propertiesplus post /api/commercial\_sales\_documents HTTPchevron-down HTTPcURLJavaScriptPython Test it 200 Sucesso 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: Atributo Descrição Obrigatório document\_type Tipo de documento. "FT": fatura, "FS": fatura simplificada, "FR": fatura-recibo. Sim date Data do documento; por omissão, a data do pedido. Não document\_series\_prefix Em alternativa ao campo "document\_series\_id". Não customer\_tax\_registration\_number NIF do cliente. Se o cliente com o NIF indicado não existir, será criado automaticamente. Não customer\_business\_name Nome do cliente. Sim customer\_address\_detail Morada do cliente. Não customer\_postcode Código postal do cliente, no formato 0000-000. Não customer\_city Cidade/Localidade do cliente. Não customer\_country País do cliente. Por omissão, "PT"; é o código ISO alpha-2 do país do cliente. Não customer\_id No caso do cliente já existir e não pretender criar um novo. Não due\_date Data de vencimento; por omissão, a data do documento, ou a referente ao prazo de pagamento configurado no cliente. Não settlement\_expression Desconto no cabeçalho, em percentagem; são suportados descontos compostos, como "3+5" Não payment\_mechanism Modos de pagamento aceites. Não vat\_included\_prices Os preços nas linhas são com IVA incluído? Por omissão, não (false). Não operation\_country A região de operação para efeitos de IVA. Não currency\_iso\_code É o código ISO da moeda do documento. Não currency\_conversion\_rate É a taxa de conversão para EUR. Não retention Percentagem de retenção a aplicar sobre os serviços. Não retention\_type Tipo de retenção ("IRS" ou "IRC"). Por omissão, "IRS". Não apply\_retention\_when\_paid A retenção é feita logo no documento (false) ou apenas no recebimento (true). Por omissão, false. Não notes Notas ao documento. Não external\_reference Referência do documento externo. Não circle-info **Nota 1 -** A série associada ao documento tem já que existir, e o seu "id" interno pode ser obtido por um: circle-info **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: circle-info **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: circle-info **Nota 4 -** O "id" interno da conta bancária da empresa deve ser obtido por um: circle-info **Nota 5** - O "id" interno da conta de caixa da empresa deve ser obtido por um circle-info **Nota 6** - O "id" interno do motivo de isenção deve ser obtido por um circle-info **Nota 7** - O "id" interno da moeda deve ser obtido por um ### [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/documentos-de-venda#id-2.-criacao-da-s-linha-s) 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. ### [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/documentos-de-venda#post-api-commercial_sales_receipt_lines) Adicionar Linha a Recibo de Venda post {{base\_url}}/api/commercial\_sales\_receipt\_lines Adicionar Linha a Recibo de Venda chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Body application/jsonchevron-down application/json dataobjectOptional Show propertiesplus Responses chevron-right 200Success No content post /api/commercial\_sales\_receipt\_lines HTTPchevron-down HTTPcURLJavaScriptPython Test it 200Success No content 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 #### [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/documentos-de-venda#id-2.1.-criar-linha-de-documento-de-venda-para-um-produto) 2.1. Criar Linha de Documento de Venda para um Produto Atributo Descrição Obrigatório document\_id ID do documento ao qual esta linha está associada. Sim item\_type Tipo de item: "Product" para produto. Sim quantity Quantidade do item. Por omissão, 1. Não unit\_price Preço unitário do item. Por omissão, é usado o PVP associado ao produto. Não settlement\_expression Desconto de linha, em percentagem; são suportados descontos compostos, como "3+5". Não item\_id ID do produto. Não unit\_of\_measure\_id ID da unidade de medida. Por omissão, é a configurada no produto ou a padrão da empresa. Não tax\_id ID do imposto associado ao item. Por omissão, é aplicado o IVA associado ao produto ou a taxa normal da empresa. Não #### [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/documentos-de-venda#id-2.2.-criar-linha-de-documento-de-venda-para-um-servico) 2.2. Criar Linha de Documento de Venda para um Serviço circle-exclamation Já deve ter um Serviço criado previamente. Pode consultar mais informação em [Criar Serviços](https://api-docs.toconline.pt/apis/empresa/produtos-e-servicos#criar-servicos) Atributo Descrição Obrigatório type Tipo de linha de documento. Sim document\_id ID do documento ao qual esta linha está associada. Sim item\_type Tipo de item: "Service" (serviço). Sim quantity Quantidade do serviço. Não unit\_price Preço unitário do serviço. Não settlement\_expression Expressão de liquidação, em percentagem. Não item\_id ID do serviço associado à linha. Não unit\_of\_measure\_id ID da unidade de medida. Não tax\_id ID do imposto sobre o valor acrescentado (IVA) aplicado ao serviço. Não #### [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/documentos-de-venda#id-2.3.-criar-linha-de-documento-de-venda-para-um-descritor) 2.3. Criar Linha de Documento de Venda para um Descritor circle-exclamation Já deve ter um Descritor criado previamente. Pode consultar mais informação em [Criar Descritores](https://api-docs.toconline.pt/apis/apis-auxiliares/descritores-de-taxa#criar-descritores) Atributo Descrição Obrigatório document\_id ID do documento ao qual esta linha está associada. Sim item\_type Tipo de item: "Service" para serviço. Sim quantity Quantidade do serviço. Por omissão, 1. Não unit\_price Preço unitário do serviço. Por omissão, é usado o PVP associado ao serviço. Não settlement\_expression Desconto de linha, em percentagem; são suportados descontos compostos, como "3+5". Não item\_id ID do serviço. Não unit\_of\_measure\_id ID da unidade de medida. Por omissão, é a configurada no serviço ou a padrão da empresa. Não tax\_id ID do imposto associado ao serviço. Por omissão, é aplicado o IVA associado ao serviço ou a taxa normal da empresa. Não #### [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/documentos-de-venda#id-2.5.-criar-linha-de-documento-de-venda-para-uma-descricao-sem-valor) 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: Atributo Descrição Obrigatório description Descrição da linha do documento. Sim document\_id ID do documento ao qual a linha pertence. Sim ### [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/documentos-de-venda#id-3.-finalizacao-do-documento) 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. triangle-exclamation 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: Atributo Descrição Obrigatório type Tipo de documento. Sim id Identificador interno do documento (cabeçalho). Este "id" é devolvido na resposta ao pedido de criação do cabeçalho. Sim status Identificação do estado do documento. 1: documento finalizado. Sim chevron-rightExemplo de Response[hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/documentos-de-venda#exemplo-de-response) circle-info 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. * * * [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/documentos-de-venda#alteracao-do-documento-de-venda) 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)**). ### [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/documentos-de-venda#atualizar-linha-de-documento-de-venda) Atualizar Linha de Documento de Venda ### [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/documentos-de-venda#patch-api-commercial_sales_document_lines) Atualizar Linha de Documentos de Venda patch {{base\_url}}/api/commercial\_sales\_document\_lines Atualizar Linha de Documentos de Venda chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Body application/jsonchevron-down application/json dataobjectOptional Show propertiesplus Responses chevron-right 200 Sucesso application/json Headersobject Show Headersplus Responseobject Show propertiesplus patch /api/commercial\_sales\_document\_lines HTTPchevron-down HTTPcURLJavaScriptPython Test it 200 Sucesso 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). circle-info 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)](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/documentos-de-venda#id-2.-criacao-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. Atributo Descrição type Tipo de linha de documento. id Identificador interno da linha do documento. item\_id ID do item associado à linha. item\_code Código do item. description Descrição da linha. amount Valor total da linha. unit\_price Preço unitário do item. quantity Quantidade do item. tax\_code Tipo de IVA aplicado. tax\_percentage Percentagem de IVA. tax\_amount Valor do IVA aplicado. settlement\_amount Valor de liquidação da linha. settlement\_percentage Percentagem de liquidação da linha. exemption\_reason Motivo da isenção de imposto. created\_at Data e hora de criação da linha. updated\_at Data e hora da última atualização da linha. tax\_country\_region Região do IVA aplicado. item\_unit\_price\_includes\_vat Indica se o preço unitário do item inclui IVA. net\_amount Valor líquido da linha. net\_unit\_price Preço unitário líquido do item. net\_tax\_amount Valor líquido do IVA. date Data associada à linha. retention\_value Valor de retenção. pending\_total Total pendente. pending\_retention\_value Valor de retenção pendente. locked Indica se a linha está bloqueada. base\_currency\_amount Valor total da linha na moeda base. base\_currency\_unit\_price Preço unitário do item na moeda base. base\_currency\_tax\_amount Valor do IVA na moeda base. base\_currency\_net\_unit\_price Preço unitário líquido do item na moeda base. base\_currency\_net\_amount Valor líquido da linha na moeda base. base\_currency\_settlement\_without\_tax Valor de liquidação sem IVA na moeda base. original\_document\_no Número do documento original associado à linha. net\_settlement\_amount Valor líquido de liquidação. net\_amount\_with\_header\_settlement Valor líquido da linha com liquidação no cabeçalho. amount\_with\_header\_settlement Valor total da linha com liquidação no cabeçalho. settlement\_with\_tax Valor de liquidação com IVA. settlement\_without\_tax Valor de liquidação sem IVA. base\_currency\_settlement\_with\_tax Valor de liquidação com IVA na moeda base. item\_type Tipo de item: "Product" (produto), "Service" (serviço) ou "TaxDescriptor" (descritor de imposto). pending\_quantity Quantidade pendente. imported\_quantity Quantidade importada. settlement\_expression Expressão de liquidação. tax\_descriptor\_id ID do descritor de imposto associado à linha. 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. circle-info **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 [Documentos de Venda](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/documentos-de-venda#id-1.-criacao-do-cabecalho) para mais detalhes. circle-info **Nota 2 -** O item (serviço, produto ou descritor) já deve existir, e o seu "`id"` interno pode ser obtido por um circle-info **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: circle-info **Nota 4 -** A unidade de medida deve existir previamente, e seu identificador `"id"` interno pode ser obtido através de um circle-info **Nota 5** - O "id" interno da taxa de IVA deve ser obtido por um ### [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/documentos-de-venda#remover-linha-de-documento-de-venda) Remover Linha de Documento de Venda ### [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/documentos-de-venda#delete-api-commercial_sales_document_lines-salesdocumentlineid) Remover Linhas de Documentos de Venda delete {{base\_url}}/api/commercial\_sales\_document\_lines/{salesDocumentLineId} Remover Linhas de Documentos de Venda chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Path parameters salesDocumentLineIdstringRequired Id da Linha do Documento de Venda Example: `131` Responses chevron-right 200 Sucesso application/json Headersobject Show Headersplus Responseobject Show propertiesplus chevron-right 404 Not Found application/json delete /api/commercial\_sales\_document\_lines/{salesDocumentLineId} HTTPchevron-down HTTPcURLJavaScriptPython Test it 200 Sucesso chevron-down 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)**). * * * [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/documentos-de-venda#anulacao-do-documento) Anulação do documento -------------------------------------------------------------------------------------------------------------------------------------------- Após a sua finalização, o documento deixa de poder ser eliminado, podendo apenas ser anulado. ### [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/documentos-de-venda#patch-api-v1-commercial_sales_receipts-salesreceiptid-void) Anular Recibo de Venda patch {{base\_url}}/api/v1/commercial\_sales\_receipts/{salesReceiptId}/void Anular Recibo de Venda chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Path parameters salesReceiptIdstringRequired Responses chevron-right 200Success No content patch /api/v1/commercial\_sales\_receipts/{salesReceiptId}/void HTTPchevron-down HTTPcURLJavaScriptPython Test it 200Success No content 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: triangle-exclamation Após a sua anulação, o documento deixa de poder ser alterado. Esta operação é irreversível. * * * [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/documentos-de-venda#remover-documento-de-venda) Remover Documento de Venda ------------------------------------------------------------------------------------------------------------------------------------------------------ circle-check Enquanto estiver em preparação, o documento pode ser eliminado. triangle-exclamation 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](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/documentos-de-venda#id-3.-finalizacao-do-documento) ### [hashtag](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/documentos-de-venda#delete-api-commercial_sales_documents-id) Remover Documentos de Venda delete {{base\_url}}/api/commercial\_sales\_documents/{id} Remover Documentos de Venda chevron-right lockRequired scopes This endpoint requires the following scopes: * `commercial`: commercial Authorizations oauth2chevron-down oauth2 OAuth2authorizationCodeRequired Authorization URL: {{base\_url\_oauth}}/authToken URL: {{base\_url\_oauth}}/token Path parameters idstringRequiredExample: `66` Responses chevron-right 200 Remover Documentos de Venda application/json Headersobject Show Headersplus Responseobject Show propertiesplus chevron-right 403 Id de Documento Finalizado application/json delete /api/commercial\_sales\_documents/{id} HTTPchevron-down HTTPcURLJavaScriptPython Test it 200 Remover Documentos de Venda chevron-down 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**). circle-exclamation Esta operação é irreversível. [PreviousVendaschevron-left](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas) [NextRecibos de Vendachevron-right](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/recibos-de-venda) Last updated 1 year ago * [Criação do Documento de Venda](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/documentos-de-venda#criacao-do-documento-de-venda) * [1\. Criar Cabeçalho de Documento de Venda](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/documentos-de-venda#id-1.-criar-cabecalho-de-documento-de-venda) * [POSTCriar Cabeçalho de Documentos de Venda](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/documentos-de-venda#post-api-commercial_sales_documents) * [2\. Criação da(s) linha(s)](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/documentos-de-venda#id-2.-criacao-da-s-linha-s) * [POSTAdicionar Linha a Recibo de Venda](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/documentos-de-venda#post-api-commercial_sales_receipt_lines) * [3\. Finalização do documento](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/documentos-de-venda#id-3.-finalizacao-do-documento) * [Alteração do Documento de Venda](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/documentos-de-venda#alteracao-do-documento-de-venda) * [Atualizar Linha de Documento de Venda](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/documentos-de-venda#atualizar-linha-de-documento-de-venda) * [PATCHAtualizar Linha de Documentos de Venda](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/documentos-de-venda#patch-api-commercial_sales_document_lines) * [Remover Linha de Documento de Venda](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/documentos-de-venda#remover-linha-de-documento-de-venda) * [DELETERemover Linhas de Documentos de Venda](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/documentos-de-venda#delete-api-commercial_sales_document_lines-salesdocumentlineid) * [Anulação do documento](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/documentos-de-venda#anulacao-do-documento) * [PATCHAnular Recibo de Venda](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/documentos-de-venda#patch-api-v1-commercial_sales_receipts-salesreceiptid-void) * [Remover Documento de Venda](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/documentos-de-venda#remover-documento-de-venda) * [DELETERemover Documentos de Venda](https://api-docs.toconline.pt/apis/versoes-anteriores/vendas/documentos-de-venda#delete-api-commercial_sales_documents-id) sun-brightdesktopmoon Copy POST /api/commercial_sales_documents HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Content-Type: application/json Accept: */* Content-Length: 468 { "data": { "attributes": { "apply_retention_when_paid": true, "currency_conversion_rate": 1.21, "currency_iso_code": "EUR", "customer_id": 2, "date": "2023-01-01", "document_type": "FT", "due_date": "2023-02-01", "external_reference": "Referência do documento externo", "notes": "Notas ao documento", "operation_country": "PT-MA", "payment_mechanism": "MO", "retention": 7.5, "retention_type": "IRS", "settlement_expression": "7.5", "vat_included_prices": false }, "type": "commercial_sales_documents" } } Copy { "data": { "attributes": { "acts_as_shipment_document": false, "apply_retention_when_paid": true, "base_currency_conversion_difference": null, "base_currency_gross_total": null, "base_currency_net_total": null, "base_currency_other_retentions": null, "base_currency_other_taxes_total": null, "base_currency_pending_total": null, "base_currency_retention_aware_gross_total": null, "base_currency_retention_total": null, "base_currency_settlement_total": null, "base_currency_tax_payable": null, "base_currency_vat_incidence_int": null, "base_currency_vat_incidence_ise": null, "base_currency_vat_incidence_nor": null, "base_currency_vat_incidence_red": null, "base_currency_vat_total_int": null, "base_currency_vat_total_nor": null, "base_currency_vat_total_red": null, "cashed_vat": false, "child_documents_ids": null, "communication_code": null, "communication_code_source": "webservice", "communication_status": "unsent", "created_at": "2024-03-05 14:24:53.318028", "currency_amount": null, "currency_conversion_rate": 1, "currency_iso_code": "EUR", "customer_address_detail": "", "customer_business_name": "Gabriel", "customer_city": "", "customer_country": "PT", "customer_postcode": "", "customer_tax_country_region": "PT", "customer_tax_registration_number": "123456789", "date": "2023-01-01", "description": null, "document_area": "FT", "document_hash_sum": null, "document_no": null, "document_series_no": null, "document_series_prefix": "2023", "document_type": "FT", "due_date": "2023-02-01", "due_days": null, "email_readed": false, "emailed": null, "end_date": null, "expected_shipment_unloading_time": null, "expired": null, "external_reference": "Referência do documento externo", "fulfilled_mask": 0, "gross_total": 0, "hash_control": null, "invoice_counter": null, "is_active": null, "is_document_to_self": false, "is_invoice_receipt": null, "is_receipt": null, "is_third_party": false, "issue_finalized": null, "line_settlement_with_tax": 0, "line_settlement_with_tax_unrounded": 0, "line_settlement_without_tax": 0, "line_settlement_without_tax_unrounded": 0, "made_available_to": true, "manual_registration_number": "", "manual_registration_series": "", "manual_registration_type": null, "net_settlement_total": null, "net_total": 0, "notes": "Notas ao documento", "operation_country": "PT-MA", "other_retentions": 0, "other_taxes_total": 0, "parent_document_area": null, "parent_document_reference": "", "parent_document_type": null, "parent_documents_ids": null, "payment_mechanism": "MO", "pending_retention_value": 0, "pending_total": 0, "periodicity": null, "periodicity_type": null, "printed": null, "public_link": "", "receipts_ids": null, "reference": null, "reference_document_type": null, "required_mask": 0, "retention": 7.5, "retention_aware_gross_total": 0, "retention_type": "IRS", "retention_value": 0, "retention_value_unrounded": 0, "scheduled_description": null, "scheduled_end_date": null, "scheduled_interval": null, "scheduled_invoice_id": null, "scheduled_start_date": null, "send_email": null, "settlement": null, "settlement_expression": "7.5", "settlement_percentage": 7.5, "settlement_total": 0, "settlement_with_tax": 0, "settlement_with_tax_unrounded": 0, "settlement_without_tax": 0, "settlement_without_tax_unrounded": 0, "shipment_address_detail": null, "shipment_city": null, "shipment_country": null, "shipment_from_address_detail": null, "shipment_from_city": null, "shipment_from_country": null, "shipment_from_postcode": null, "shipment_loading_time": null, "shipment_postcode": null, "sort_status": 0, "start_date": null, "status": 0, "system_entry_date": null, "tax_payable": 0, "third_party_type": 0, "total_pending_quantity": null, "updated_at": "2024-03-05 14:24:53.318028", "vat_incidence_int": 0, "vat_incidence_int_unrounded": 0, "vat_incidence_ise": 0, "vat_incidence_ise_unrounded": 0, "vat_incidence_nor": 0, "vat_incidence_nor_unrounded": 0, "vat_incidence_red": 0, "vat_incidence_red_unrounded": 0, "vat_included_prices": false, "vat_percentage_int": null, "vat_percentage_nor": null, "vat_percentage_red": null, "vat_total_int": 0, "vat_total_int_unrounded": 0, "vat_total_nor": 0, "vat_total_nor_unrounded": 0, "vat_total_red": 0, "vat_total_red_unrounded": 0, "vehicle_registration": null, "voided_reason": null }, "id": "66", "relationships": { "bank_accounts": { "data": null }, "cash_accounts": { "data": null }, "commercial_document_series": { "data": { "id": "72", "type": "commercial_document_series" } }, "company": { "data": { "id": "800000046", "type": "current_company" } }, "currency": { "data": { "id": "1", "type": "currencies" } }, "customer": { "data": { "id": "2", "type": "customers" } }, "lines": { "data": [] }, "tax_exemption_reasons": { "data": null }, "user": { "data": { "id": "800000863", "type": "current_company_users" } } }, "type": "commercial_sales_documents" }, "meta": { "observed": { "scalar": 1 } } } Copy GET /commercial_document_series?filter[document_type]=&filter[prefix]= Copy GET /customers?filter[tax_registration_number]= Copy GET /countries?filter[iso_alpha_2]= Copy GET /company_bank_accounts?filter[iban]= ou GET /company_bank_accounts?filter[name]= Copy GET /cash_accounts?filter[name]= Copy GET /tax_exemption_reasons?filter[code]= Copy GET /currencies?filter[iso_code]= Copy POST /api/commercial_sales_receipt_lines HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Content-Type: application/json Accept: */* Content-Length: 285 { "data": { "attributes": { "cashed_vat_amount": null, "gross_total": 10.69, "net_total": 9.27, "receipt_id": 13, "receivable_id": 12, "receivable_type": "Document", "received_value": 10.69, "retention_total": 0.72, "settlement_amount": 0, "settlement_percentage": 0 }, "type": "commercial_sales_receipt_lines" } } Copy { "meta": { "observed": { "scalar": 1 } }, "data": { "type": "commercial_sales_documents", "id": "12", "attributes": { "document_no": "FT 2023/3", "status": 1, "date": "2023-01-01", "payment_mechanism": null, "gross_total": 11.38, "notes": "Notas ao documento", "document_type": "FT", "pending_total": 11.38, "retention": 7.5, "settlement": null, "settlement_total": 0.75, "due_date": "2023-01-01", "emailed": null, "tax_payable": 2.13, "net_total": 9.25, "document_hash_sum": "k8FEN8/xf+GErWsPiATVpAWd5jM64132yWVldc6qg7XNxpjt+JCJTwgqQ5fswUsXw0MbbtBzHpN/aZozPiiiRHiHAR+TM4hJ8u5XnAe5hiss2Tn//QiCxbvolLywCqRw4cIt1UcbhMEP97YYj0FdLgzrPTF1amU+Xk81EkBzq54=", "hash_control": "1", "reference": null, "customer_tax_registration_number": "229659179", "customer_business_name": "Ricardo Ribeiro", "customer_address_detail": "Praceta da Liberdade n5", "customer_postcode": "1000-101", "customer_city": "Lisboa", "created_at": "2024-02-21 16:41:50.588385", "updated_at": "2024-02-22 18:21:13.512872", "is_receipt": null, "vehicle_registration": null, "shipment_address_detail": null, "shipment_postcode": null, "shipment_city": null, "vat_incidence_ise": 0, "vat_incidence_red": 0, "vat_incidence_int": 0, "vat_incidence_nor": 9.25, "vat_total_red": 0, "vat_total_int": 0, "vat_total_nor": 2.13, "customer_tax_country_region": "PT", "currency_amount": null, "customer_country": "PT", "printed": null, "currency_conversion_rate": 1, "currency_iso_code": "EUR", "system_entry_date": "2024-02-22 18:21:13.512872", "retention_value": 0.69, "parent_document_reference": "", "acts_as_shipment_document": false, "manual_registration_series": "", "manual_registration_number": "", "shipment_loading_time": null, "expected_shipment_unloading_time": null, "apply_retention_when_paid": true, "retention_aware_gross_total": 10.69, "pending_retention_value": 0.69, "communication_status": "unsent", "shipment_country": null, "is_invoice_receipt": null, "due_days": null, "scheduled_start_date": null, "scheduled_end_date": null, "scheduled_description": null, "scheduled_interval": null, "base_currency_gross_total": null, "base_currency_net_total": null, "base_currency_pending_total": null, "base_currency_settlement_total": null, "base_currency_retention_total": null, "base_currency_retention_aware_gross_total": null, "base_currency_tax_payable": null, "base_currency_vat_incidence_nor": null, "base_currency_vat_total_nor": null, "base_currency_vat_incidence_int": null, "base_currency_vat_total_int": null, "base_currency_vat_incidence_red": null, "base_currency_vat_total_red": null, "base_currency_vat_incidence_ise": null, "base_currency_conversion_difference": null, "start_date": null, "end_date": null, "periodicity": null, "description": null, "reference_document_type": null, "is_active": null, "scheduled_invoice_id": null, "issue_finalized": null, "periodicity_type": null, "invoice_counter": null, "expired": null, "send_email": null, "communication_code": null, "shipment_from_address_detail": null, "shipment_from_postcode": null, "shipment_from_city": null, "shipment_from_country": null, "is_third_party": false, "is_document_to_self": false, "manual_registration_type": null, "third_party_type": 0, "document_area": "FT", "parent_document_type": null, "parent_document_area": null, "communication_code_source": "webservice", "cashed_vat": false, "made_available_to": true, "other_taxes_total": 0, "base_currency_other_taxes_total": null, "other_retentions": 0, "base_currency_other_retentions": null, "retention_type": null, "net_settlement_total": null, "external_reference": "Referência do documento externo", "document_series_prefix": "2023", "document_series_no": 3, "email_readed": false, "vat_included_prices": false, "voided_reason": null, "settlement_with_tax": 0.92, "settlement_without_tax": 0.75, "line_settlement_with_tax": 0, "line_settlement_without_tax": 0, "total_pending_quantity": null, "child_documents_ids": null, "parent_documents_ids": null, "receipts_ids": null, "operation_country": "PT", "sort_status": 1, "settlement_percentage": 7.500000000000000000000, "settlement_expression": "7.5", "vat_percentage_red": null, "vat_percentage_int": null, "vat_percentage_nor": 23.0, "vat_incidence_ise_unrounded": 0, "vat_incidence_red_unrounded": 0, "vat_incidence_int_unrounded": 0, "vat_incidence_nor_unrounded": 0, "vat_total_red_unrounded": 0, "vat_total_int_unrounded": 0, "vat_total_nor_unrounded": 0, "settlement_with_tax_unrounded": 0, "settlement_without_tax_unrounded": 0, "line_settlement_with_tax_unrounded": 0, "line_settlement_without_tax_unrounded": 0, "retention_value_unrounded": 0, "required_mask": 10, "fulfilled_mask": 0, "public_link": "https://app.toconline.pt/public_links/link/uDdZazxttzBsJwrne83w6kSUwkbM2a8vlYIiXztqKlYhRRdNIR8hFfDLi0sxw98g-0CWzNyMJ0RlBfRMbjBomsK-QOysT0Gm3D7poBTOivqjzCsRTIPTbcs3s3lN3LyGQoILoexjjctqpvK6CBSjOA" }, "relationships": { "bank_accounts": { "data": null }, "cash_accounts": { "data": null }, "commercial_document_series": { "data": { "type": "commercial_document_series", "id": "72" } }, "company": { "data": { "type": "current_company", "id": "800000046" } }, "currency": { "data": { "type": "currencies", "id": "1" } }, "customer": { "data": { "type": "customers", "id": "57" } }, "lines": { "data": [] }, "tax_exemption_reasons": { "data": null }, "user": { "data": { "type": "current_company_users", "id": "800000863" } } } } } Copy PATCH /api/commercial_sales_document_lines HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Content-Type: application/json Accept: */* Content-Length: 1182 { "data": { "attributes": { "amount": 0, "amount_with_header_settlement": 0, "base_currency_amount": null, "base_currency_net_amount": null, "base_currency_net_unit_price": null, "base_currency_settlement_with_tax": null, "base_currency_settlement_without_tax": null, "base_currency_tax_amount": null, "base_currency_unit_price": null, "created_at": "2024-03-05 14:25:28.275949", "date": null, "description": "Isto é uma NOVA breve descrição", "exemption_reason": null, "imported_quantity": null, "item_code": "1000", "item_id": 2, "item_type": "Product", "item_unit_price_includes_vat": false, "locked": null, "net_amount": 0, "net_amount_with_header_settlement": 0, "net_settlement_amount": null, "net_tax_amount": null, "net_unit_price": 2, "original_document_no": null, "pending_quantity": null, "pending_retention_value": null, "pending_total": null, "quantity": null, "retention_value": null, "settlement_amount": null, "settlement_expression": null, "settlement_percentage": 0, "settlement_with_tax": 0, "settlement_without_tax": 0, "tax_amount": 0, "tax_code": "INT", "tax_country_region": "PT", "tax_descriptor_id": null, "tax_percentage": 13, "unit_price": 2, "updated_at": "2024-03-05 14:25:28.275949" }, "id": "131", "type": "commercial_sales_document_lines" } } Copy { "data": { "attributes": { "amount": 2.09, "amount_with_header_settlement": 2.26, "base_currency_amount": null, "base_currency_net_amount": null, "base_currency_net_unit_price": null, "base_currency_settlement_with_tax": null, "base_currency_settlement_without_tax": null, "base_currency_tax_amount": null, "base_currency_unit_price": null, "created_at": "2024-03-05 14:25:28.275949", "date": null, "description": "Isto é uma NOVA breve descrição", "exemption_reason": null, "imported_quantity": null, "item_code": "1000", "item_id": 2, "item_type": "Product", "item_unit_price_includes_vat": false, "locked": null, "net_amount": 1.85, "net_amount_with_header_settlement": 2, "net_settlement_amount": null, "net_tax_amount": null, "net_unit_price": 1.85, "original_document_no": null, "pending_quantity": null, "pending_retention_value": null, "pending_total": null, "quantity": 1, "retention_value": null, "settlement_amount": null, "settlement_expression": null, "settlement_percentage": 0, "settlement_with_tax": 0, "settlement_without_tax": 0, "tax_amount": 0.24, "tax_code": "INT", "tax_country_region": "PT", "tax_descriptor_id": null, "tax_percentage": 13, "unit_price": 2, "updated_at": "2024-03-05 14:43:46.935053" }, "id": "131", "relationships": { "document": { "data": { "id": "66", "type": "commercial_sales_documents" } }, "product": { "data": null }, "service": { "data": null }, "tax": { "data": { "id": "2", "type": "taxes" } }, "tax_descriptor": { "data": null }, "unit_of_measure": { "data": { "id": "5", "type": "units_of_measure" } } }, "type": "commercial_sales_document_lines" }, "meta": { "observed": { "lines": 1, "scalar": 1 } } } Copy GET /services?filter[item_code]= ou GET /products?filter[item_code]= ou GET /tax_descriptors?filter[notation]= Copy GET /countries?filter[iso_alpha_2]= Copy GET /units_of_measure?filter[unit_of_measure]= Copy GET /taxes?filter[tax_code]=&filter[tax_country_region]= ou GET /taxes?filter[tax_code]=&filter[tax_country_region]=&filter[tax_percentage]= Copy DELETE /api/commercial_sales_document_lines/{salesDocumentLineId} HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Accept: */* Copy { "meta": { "observed": { "lines": 5, "scalar": 1 } } } Copy PATCH /api/v1/commercial_sales_receipts/{salesReceiptId}/void HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Accept: */* Copy { "data": { "type": "commercial_sales_documents", // [OBRIGATÓRIO] "id": "1", // [OBRIGATÓRIO] Identificador interno do documento (cabeçalho). Este "id" é o devolvido na resposta ao pedido de criação do cabeçalho, ver acima. "attributes": { // [OBRIGATÓRIO] Os atributos do documento "status": 4, // [OBRIGATÓRIO] Identificação do estado do documento. 4: documento anulado. "voided_reason": "Motivo pelo qual se anula o documento" // [OBRIGATÓRIO] } } } Copy DELETE /api/commercial_sales_documents/{id} HTTP/1.1 Host: {{base_url}} Authorization: Bearer YOUR_OAUTH2_TOKEN Accept: */* Copy { "meta": { "observed": { "scalar": 1 } } } sun-brightdesktopmoon --- # Email Protection | Cloudflare Please enable cookies. Email Protection ================ You are unable to access this email address api-docs.toconline.pt ----------------------------------------------------------------- The website from which you got to this page is protected by Cloudflare. Email addresses on that page have been hidden in order to keep them from being accessed by malicious bots. **You must enable Javascript in your browser in order to decode the e-mail address**. If you have a website and are interested in protecting it in a similar way, you can [sign up for Cloudflare](https://www.cloudflare.com/sign-up?utm_source=email_protection) . * [How does Cloudflare protect email addresses on website from spammers?](https://developers.cloudflare.com/waf/tools/scrape-shield/email-address-obfuscation/) * [Can I sign up for Cloudflare?](https://developers.cloudflare.com/fundamentals/setup/account/create-account/) Cloudflare Ray ID: **9be6c2abce92d6e5** • Your IP: Click to reveal 54.237.218.47 • Performance & security by [Cloudflare](https://www.cloudflare.com/5xx-error-landing) ---